CompletionScorer ignores the BulkScorer [min, max) window, so a CompletionQuery run through IndexSearcher#search with a TopSuggestDocsCollector and a timeout or intra-segment partitions repeats some suggestions and drops others

CompletionScorer is the BulkScorer of every CompletionQuery in the document suggester (lucene/suggest). BulkScorer#score(collector, acceptDocs, min, max) must collect only the matches in [min, max) (BulkScorer.java:42-43, :72-73), but CompletionScorer.score never reads min or max: every call runs suggester.lookup over the whole segment, a score-ordered top-N walk of its suggestion FST, and returns max (CompletionScorer.java:68-75 on main 645d4fe14a20). The documented entry point, SuggestIndexSearcher#suggest, makes one whole-range call per segment, so it is correct. Through the generic IndexSearcher#search with a TopSuggestDocsCollector it is correct only without a timeout and without intra-segment partitions. With setTimeout, even a timeout that never fires, TimeLimitingBulkScorer scores each segment in up to 40 growing windows (TimeLimitingBulkScorer.java:70-86), so the same top suggestions are collected again until the collector's queue overflows: 500 suggestions, n = 5 give docs [499, 499, 498, 498, 497] instead of [499, 498, 497, 496, 495], with an EQUAL_TO total and timedOut() false; one document with one suggestion comes back 5 times. With intra-segment partitions every partition collects the whole segment and TopSuggestDocs.merge keeps the copies: [499 x5]. Every hit still passes the query's filter, contexts and live docs. The scorer has ignored the window since it was written (LUCENE-6459, 5.3.0); it turned silent through IndexSearcher in 9.4.0 (#996) and gained the partition leg in 10.0.0 (#13542), whose migration notes say such Weights "need updating". Running the lookup only for the window that starts at doc 0 and returning NO_MORE_DOCS fixes both paths; throwing for any other window, as DrillSidewaysScorer does, is the loud alternative.

• CompletionQuery (PrefixCompletionQuery, RegexCompletionQuery, FuzzyCompletionQuery, ContextQuery): the queries of the document (NRT) suggester; CompletionWeight's ScorerSupplier#bulkScorer() returns a CompletionScorer (CompletionWeight.java:102-130). The module says: "Use SuggestIndexSearcher#suggest(CompletionQuery, int, boolean) to execute any query" (CompletionQuery.java:36-37).
• BulkScorer window: "min is the minimum document to be considered for matching. All documents strictly before this value must be ignored" (BulkScorer.java:42-43); "@param max Score up to, but not including, this doc" (:72-73); the return value is NO_MORE_DOCS "if there are no more matches" (:34-40).
• Timeout windows: with a QueryTimeout, IndexSearcher#searchLeaf wraps the scorer in TimeLimitingBulkScorer (IndexSearcher.java:846-848), which calls it for [min, min + interval) with an interval of 100 that grows by 50% per call, checking the timeout before each, and continues from the returned value (TimeLimitingBulkScorer.java:70-86). An entire segment is the range [0, NO_MORE_DOCS) (IndexSearcher.java:1096-1100).
• Partitions: with an executor and slices(leaves, maxDocs, maxSegments, true), a segment is split into doc-ID ranges searched with different collectors (MIGRATE.md:1668-1684).

1. CompletionScorer.score(collector, acceptDocs, min, max) checks the collector type, calls suggester.lookup(this, acceptDocs, (TopSuggestDocsCollector) collector) and returns max (CompletionScorer.java:68-75). min and max are never read; the class javadoc still says score "is called for each leaf reader" (:30).
2. Under a timeout, the returned max sends TimeLimitingBulkScorer on to the next window, so the loop walks the whole int range: up to 40 calls per segment, each running the full lookup into the same collector.
3. TopSuggestDocsCollector keeps a top-n queue and throws CollectionTerminatedException at the first insert that overflows, on the assumption that every later hit of the segment scores lower (TopSuggestDocsCollector.java:123-135). searchLeaf catches it and moves on (IndexSearcher.java:853-855), so the search succeeds.
4. With partitions, each partition's call runs the whole lookup into its own collector, and TopSuggestDocs.merge merges them into a top n with no de-duplication and an EQUAL_TO total (TopSuggestDocs.java:115-132).

500 documents in one segment, suggestion apple<i> with weight i + 1, PrefixCompletionQuery("apple"), n = 5, skipDuplicates false. suggest(): docs [499, 498, 497, 496, 495]. IndexSearcher#search with a TopSuggestDocsCollector per slice and no timeout: the same. With setTimeout(() -> false): window 1 fills the queue with 499 to 495; window 2 adds 499 and 498 again, which push out 495 and 496; 497 then overflows and the segment ends: [499, 499, 498, 498, 497], total 5 EQUAL_TO, timedOut() false. One document with one suggestion: the same hit 5 times. 5 partitions of 100 documents: [499, 499, 499, 499, 499]. A direct bulkScorer.score(collector, null, 0, 100) collects 400 documents outside [0, 100).

• Needs: a CompletionQuery executed through IndexSearcher#search with a TopSuggestDocsCollector (a hand-written CollectorManager, or the deprecated search(Query, Collector), which SuggestIndexSearcher inherits), plus any QueryTimeout on that searcher or intra-segment partitions.
• The shortest trigger: suggestSearcher.setTimeout(() -> false) and then suggestSearcher.search(query, new TopSuggestDocsCollector(5, false)); on 20 suggestions it gives [19, 19, 18, 18, 17], while suggest() with the same timeout gives [19, 18, 17, 16, 15].
• Not affected: SuggestIndexSearcher#suggest (SuggestIndexSearcher.java:69-76: one score(..., 0, NO_MORE_DOCS) call per segment); the generic path without a timeout or partitions. Scope: on 10.x the generic path also throws NullPointerException on a segment with no document with the suggest field, or where the query's filter matches no document (sibling LFV-967), so these statements assume segments where CompletionWeight hands out a CompletionScorer, as in the repro.
• What stays right: every hit passes the filter and the live docs (NRTSuggester.java:207, CompletionScorer.java:89-92), and contexts are part of the same lookup. The lists are wrong, never foreign.
• With skipDuplicates=true the timeout leg happens to stay correct (the collector's set of seen surface forms survives across windows); the partition leg does not (the finder's model: 0 and 128 of 240 grid points differ).
• Other generic calls already fail loudly: search(q, n) throws IllegalArgumentException ("collector is not of type TopSuggestDocsCollector", CompletionScorer.java:71), count(q) throws, explain returns null.
• Side observation: suggest() itself never applies setTimeout; with an expired timeout it still returns every hit and timedOut() stays false.

• Who is hit. Code that executes completion suggestions like any other query: a CollectorManager of TopSuggestDocsCollector, or the inherited search(Query, Collector) on a SuggestIndexSearcher, on a searcher that has a timeout or intra-segment partitions. A developer who wants to bound suggest latency has a reason to try setTimeout, because suggest() ignores it.
• Default or opt-in. Opt-in: the module documents SuggestIndexSearcher#suggest (CompletionQuery.java:36-37, SuggestField.java:45-46); the generic path, the timeout and the partitions are the application's choices.
• Effect. Silent wrong suggestion lists: copies of the best suggestions, lower ones missing, an EQUAL_TO total, timedOut() false, no exception. No filtered-out or deleted document comes back.
• Releases. Silent under a timeout from 9.4.0 (9.3.0 throws CollectionTerminatedException), with partitions from 10.0.0, through 10.6.0 and main.
• Scale. Ordinary: one document under a timeout, one 500-document segment in 5 partitions.
• How likely: rare. No upstream test and no downstream user of the generic path was found; on 10.x that path also throws NullPointerException on any segment without the suggest field (LFV-967).

# Lucene main 645d4fe14a20, assertions on (-ea), seed DEADBEEF: 1 test(s) run, 1 failed
    => java.lang.AssertionError: expected:<1> but was:<5>
       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.suggest.document.TestCompletionQueryUnderTimeout.testNeverFiringTimeoutReturnsSuggestionOnce(TestCompletionQueryUnderTimeout.java:49)

• Contract. BulkScorer.java:42-43: "All documents strictly before this value must be ignored"; :72-73: "max Score up to, but not including, this doc". The direct violation is collecting matches outside the window. max is a legal return value in general (:45), but after a lookup of the whole segment it tells the caller to come back for the next window, which runs the lookup again; NO_MORE_DOCS is the value for "no more matches" (:34-40).
• Migration note (10.0). "Weight implementations that rely on the assumption that a scorer, bulk scorer or scorer supplier for a given LeafReaderContext is requested once per search need updating" (MIGRATE.md:1678-1684 on main; :851-857 in 10.0.0, added by #13542). CompletionScorer.java:30 ("is called for each leaf reader", 2015) reflects that per-leaf calling model, although it does not say "exactly once".
• Timeouts. setTimeout applies "for all searches that run through this IndexSearcher" (IndexSearcher.java:612); the test framework's newSearcher sets setTimeout(() -> false) at random on half of its concurrent searchers (LuceneTestCaseParent.java:2689-2691; the common overloads pick a concurrent searcher half the time, :2568, :2580-2583, so about a quarter of all searchers get it), treating "a timeout that never fires changes nothing" as an invariant. The suggest tests build SuggestIndexSearcher directly and never meet it.
• Precedent. DrillSidewaysScorer rejects windows: "min must be 0, got " + min and "maxDoc must be Integer.MAX_VALUE" (DrillSidewaysScorer.java:90-97); facet tests opt it out of the random timeout because it "requires the entire range of docs to be scored at once" (TestRangeFacetCounts.java:473); #12032 (open) treats that as a limitation to fix.
• History. The silent path was never designed: it appeared when timeouts (#927, #996) and partitions (#13542) began passing the user's collector through windows; none of those PRs changed CompletionScorer or discussed the suggest module (#13542 only switched SuggestIndexSearcher#suggest to the explicit whole-range score(..., 0, NO_MORE_DOCS) call).

The intended-behaviour checker and a reviewer from another model family (OpenAI GPT-5.6) built the strongest case: the module documents suggest() as the way to run "any query" (CompletionQuery.java:36-37) and a call for each leaf (CompletionScorer.java:30); the generic machinery is visibly unsupported (search(q, n), count(q) and a BooleanQuery clause throw, explain returns null); a score-ordered FST walk cannot honour doc-ID windows; SuggestIndexSearcher refuses an executor; whole-segment-only scorers are a tolerated limitation; the module is @lucene.experimental; and for partitions the 10.0 notes put per-segment logic on the CollectorManager ("Individual collectors don't need to be adapted", MIGRATE.md:1668-1676), so part of the partition handling falls on the application's hand-written manager.

Why it fails: "use suggest()" is guidance, not a prohibition, and nothing rejects the other path; SuggestIndexSearcher is an IndexSearcher and inherits both search(Query, Collector) and setTimeout, and the generic path is correct without a timeout. Where the module did decide against the generic machinery it fails loudly; here it fails silently, unlike the tolerated precedent DrillSideways. Experimental allows API changes, not silent wrong results. The collector note covers collectors, not scorers: the note right after it (MIGRATE.md:1678-1684) asks scorers to cope with several doc-ID ranges, and in the timeout leg one collector receives the copies within one leaf, out of the manager's reach. The adjudication kept the framing "silently ignores the window instead of rejecting it", a documentation and robustness bug.

One fix was built and validated; a loud alternative was built and run for comparison; two more options were not built.

A change in CompletionScorer.score (1 file, +9/-2; the finder's sketch, unchanged by tidy). Under a timeout, TimeLimitingBulkScorer checks the timeout, calls [0, 100) once, gets NO_MORE_DOCS and stops: one lookup per segment, as suggest() makes. With partitions, the one that starts at doc 0 collects the segment's suggestions and the others collect nothing. It is a mitigation for these two callers, not an implementation of the window contract.

// The lookup is a top-N search in score order, not in doc-ID order, so it cannot be split into
// doc-ID windows: run it once, on the window that starts the leaf, and report that this leaf
// has no more matches, so that callers that score in windows (IndexSearcher#setTimeout,
// intra-segment partitions) neither repeat it nor collect it again.
if (min == 0) {
  suggester.lookup(this, acceptDocs, ((TopSuggestDocsCollector) collector));
}
return DocIdSetIterator.NO_MORE_DOCS;

Trade-offs

• A direct windowed call is still not honoured: score(c, acceptDocs, 0, 100) collects the whole segment and a window that does not start at 0 collects nothing. The repro's direct-window test keeps failing with this fix by design; the PR version of the test leaves it out, and the class javadoc (CompletionScorer.java:30) should say so.
• It relies on one partition of each segment starting at doc 0, as the standard slices(..., true) creates (IndexSearcher.java:405); a custom slices override whose partitions leave out doc 0 would lose the segment's suggestions.
• The lookup runs as one block, so the timeout is checked once, before it. The stock loop checks again before window 2 (TimeLimitingBulkScorer.java:80), so a timeout that expires during the first lookup is reported today and no longer with the fix. Executed with a timeout that returns false on its first check and true afterwards: stock [499 ... 495] with timedOut() true, the fix the same hits with timedOut() false. The list is complete either way.
• With partitions, one partition does all of a segment's suggestion work: no intra-segment speed-up, and no repeated work.
• NO_MORE_DOCS is a legal return value (BulkScorer.java:38).

What the checks validated

• Scratch worktree of 645d4fe14a20, gradle, OpenJDK 25: the repro test fails 4 of 5 on the stock tree; with the fix 4 of 5 pass and only the direct-window test fails, with assertions on and off; the PR test passes 4 of 4.
• With the fix and the PR test, the whole lucene/suggest module passes with assertions on and off: 32 suites (31 upstream + the PR test), 240 tests, 7 skipped, 0 failures; the 6 upstream suggest.document suites (58 tests) among them.
• :lucene:suggest:check -x test (checkGoogleJavaFormat, ecjLint, forbiddenApis) passes after tidy joined one line of the test.
• Earlier, by the hunt: the finder's model grid drops from 448 to 0 points that differ from suggest() (timeout 0 of 480, partitions 0 of 480).
• Not run: nightly tests, a benchmark.

Throw IllegalArgumentException("CompletionScorer can only score a whole segment at once, got [" + min + ", " + max + ")") unless min == 0 && max == NO_MORE_DOCS, and return NO_MORE_DOCS (1 file, +8/-1). The repro's 4 bug tests then throw ... got [0, 100) instead of returning wrong lists; the control passes; the suggest module's 31 upstream suites (236 tests) pass with assertions on.

Trade-offs

Honest, but every CompletionQuery search through IndexSearcher with any timeout or with partitions then throws, including the inherited search(Query, Collector) on a SuggestIndexSearcher with a timeout: the DrillSideways state that #12032 keeps open as a limitation to fix.

A javadoc sentence on CompletionQuery, CompletionWeight or SuggestIndexSearcher (and that suggest() ignores setTimeout).

Trade-offs

Cheap, but on its own it leaves the silent copies for anyone who misses the note. Best combined with one of the two code options.

Collect only hits whose doc ID is inside the window.

Trade-offs

Satisfies the contract literally, but every window repeats a full score-ordered walk of the FST (up to 40 per segment under a timeout), and TopSuggestDocsCollector ends the whole segment at the first queue overflow on the assumption of one descending-score pass (TopSuggestDocsCollector.java:123, :128-134), which several windows break. More than a local change.

Method: non-formal first signal, then a model-based differential (the hunt's hunt unit for CompletionWeight and CompletionScorer outside SuggestIndexSearcher, 2026-10-28, main a9779ef3c193).

• Lead. A planning probe on the stock jars, built from the contract "every BulkScorer collects exactly the matches in [min, max)": under a timeout IndexSearcher returned 499 499 498 498 497 where suggest() returns 499 to 495. Its partition leg had no executor, so no partitions were used.
• Intent gate. Code, javadoc and history were read first, because the module documents suggest() as the entry point; the bug was filed as a documentation and robustness defect.
• Model. An explicit model of CompletionScorer under timeout windows and intra-segment partitions, checked against the stock jar on a bounded grid: 6 segment sizes x 4 match counts x 2 key layouts x 5 values of n x skipDuplicates on and off x {suggest(), never-firing timeout, 100-document partitions with an executor} = 1,440 points; 0 model disagreements after one model fix (the real windows run to NO_MORE_DOCS, not to maxDoc). 192 timeout points and 256 partition points differ from suggest(); 0 with the fix.
• JUnit. Reduced to a JUnit (public API, plus a protected IndexSearcher#slices override for the partition test): 4 of 5 fail with assertions on and off.