WordBreakSpellChecker.suggestWordCombinations applies minSuggestionFrequency under SUGGEST_MORE_POPULAR, although its setter says the minimum does not apply there

WordBreakSpellChecker (lucene-suggest) suggests joining terms a user typed apart (suggestWordCombinations, sun flower -> sunflower) and splitting one term into indexed words (suggestWordBreaks). Its setMinSuggestionFrequency javadoc says the minimum is "Not applicable when used with SUGGEST_MORE_POPULAR". suggestWordBreaks follows that: in that mode it replaces the minimum with the term's own docFreq (at least 1). suggestWordCombinations does not: after its more-popular rule it still requires combinedTermFreq >= minSuggestionFrequency, in every mode. With setMinSuggestionFrequency(2), an index holding only sunflower (docFreq 1) and SUGGEST_MORE_POPULAR, suggestWordCombinations([sun, flower]) returns nothing instead of sunflower, while on an index with sun and flower suggestWordBreaks("sunflower") returns [sun, flower] under the same settings. The default minimum (1) and the other modes are unaffected, nothing throws, and the only effect is a missing suggestion. It dates from the class's first commit (LUCENE-3523, 2012) and reproduces on every version run, 4.0.0-ALPHA to 10.6.0 and main. A one-line change that mirrors suggestWordBreaks fixes it; maintainers may prefer to narrow the javadoc instead.

• WordBreakSpellChecker (lucene-suggest, org.apache.lucene.search.spell): suggestWordCombinations(terms, ...) joins adjacent query terms into one indexed word; suggestWordBreaks(term, ...) splits one term into indexed words.
• SuggestMode.SUGGEST_MORE_POPULAR: "Return only suggested words that are as frequent or more frequent than the searched word" (SuggestMode.java:28). For joins the method javadoc says "each suggestion will have the same, or better frequency than the most-popular included term" (WordBreakSpellChecker.java:142-143).
• minSuggestionFrequency (default 1, one field read by both methods): "The minimum frequency a term must have to be included as part of a suggestion. Default=1 Not applicable when used with SUGGEST_MORE_POPULAR" (:413-416).

1. suggestWordBreaks keeps the promise: under SUGGEST_MORE_POPULAR, useMinSuggestionFrequency = (origFreq == 0 ? 1 : origFreq) (:104-107), so the configured minimum is not used.
2. suggestWordCombinations checks the more-popular rule combinedTermFreq >= maxFreq (:206), where maxFreq is the docFreq of the most popular included term, and then combinedTermFreq >= minSuggestionFrequency in every mode (:208).
3. So in more-popular mode a join that passes the method's other checks (separators, maxChanges, word length, evaluation and result limits) is dropped exactly when maxFreq <= combinedTermFreq < minSuggestionFrequency: the joined word and all its parts are rarer than the minimum. The default minimum (1) and the other two modes behave the same with and without the fix.

One document, field f, stock main, assertions on (the last column: the same run with the fix):

Row 4 is the setter's promise kept by word breaks (each part has docFreq 1 < 2, yet the split is offered); row 2 is the same promise broken by word joins. The fix changes exactly one cell.

• Who. Users of WordBreakSpellChecker who call setMinSuggestionFrequency with 2 or more and ask suggestWordCombinations for SUGGEST_MORE_POPULAR suggestions, directly or through a downstream word-break spell-check component.
• Not affected. The default minimum (1), and the modes SUGGEST_ALWAYS and SUGGEST_WHEN_NOT_IN_INDEX.
• Effect. A valid join suggestion is silently missing. No exception, no index change, no change to search hits.
• Scale. Deterministic, with assertions on and off: the condition depends only on the docFreqs of the parts and the joined word, not on index size (the method's other limits apply as usual). The window is narrow: the joined word and all its parts must be rarer than the configured minimum, with the joined word at least as frequent as its most popular part, so it concerns words that are rare relative to the floor the caller chose.
• How likely. Rare: it needs a non-default minimum and the more-popular mode; the recorded searches found no public report since 4.0 (2012). Plain setter calls suffice, so it is not contrived.

The test asserts the number of suggestions (the comment names the expected word, sunflower). It is the hunt's minimal repro with one comment line shortened so the module's format check passes; the code is unchanged. It uses public API only; this exact file compiles and fails unchanged on 9.1.0, 9.12.3, 10.6.0 and main (run); on 9.0.0 and older LuceneTestCase is in org.apache.lucene.util. The same test is the suggested regression test.

# gradle, main 645d4fe14a20, seed DEADBEEF, -Ptests.asserts=true (the same with -Ptests.asserts=false)
TestWordBreakCombineMorePopularMinFreq > testMinSuggestionFrequencyNotAppliedWithMorePopular FAILED
    java.lang.AssertionError: expected:<1> but was:<0>
        at org.apache.lucene.search.spell.TestWordBreakCombineMorePopularMinFreq.testMinSuggestionFrequencyNotAppliedWithMorePopular(TestWordBreakCombineMorePopularMinFreq.java:44)
TestWordBreakSpellChecker (upstream): tests=5 failures=0

# release jars 10.6.0, 9.12.3 and 9.1.0, standalone runner, this exact file, assertions on: 1 of 1 fails, same message

# with the fix: the whole :lucene:suggest:test plus the repro, 32 classes, 237 tests, 0 failures (7 skipped by the module), assertions on and off

• Contract. setMinSuggestionFrequency: "The minimum frequency a term must have to be included as part of a suggestion. Default=1 Not applicable when used with SUGGEST_MORE_POPULAR" (WordBreakSpellChecker.java:413-416). Nothing limits the sentence to one method.
• Sibling method. suggestWordBreaks replaces the minimum with origFreq == 0 ? 1 : origFreq in that mode (:104-107), written in the same commit by the same author (642b882d5a5). That code can even go below the configured minimum, so "not applicable" was meant literally.
• The method's own rule. "When suggestMode equals SUGGEST_MORE_POPULAR, each suggestion will have the same, or better frequency than the most-popular included term" (:142-143); SuggestMode says "as frequent or more frequent than the searched word" (SuggestMode.java:28). Neither mentions a minimum.
• Tests and history. Upstream TestWordBreakSpellChecker never uses SUGGEST_MORE_POPULAR (its suggestWordCombinations calls use SUGGEST_ALWAYS and SUGGEST_WHEN_NOT_IN_INDEX); no CHANGES, MIGRATE or issue entry found in the recorded searches discusses the rule. In SOLR-2993, the Solr integration of this class, its author describes the only-more-popular join rule as "a document frequency that is greater or equal than the highest document frequency between "spell" and "check"", with no minimum.

The strongest works-as-designed case (the cross-model lenses rated it moderate; the credibility audit leans on it): minSuggestionFrequency is a global quality floor and more-popular an extra relative rule. DirectSpellChecker in the same package keeps its thresholdFrequency floor under SUGGEST_MORE_POPULAR (DirectSpellChecker.java:350-356). The join javadoc gives a necessary condition, not a promise to return every qualifying word. The behaviour is 14 years old with no public complaint found, SuggestMode is experimental, and Solr's reference guide presents the minimum as a plain floor, so a user who sets 2 may expect it to apply.

Why it fails as a defence of the current code: DirectSpellChecker's threshold javadoc makes no "not applicable" promise, while this class's setter does, in so many words; the sibling method of the same checker implements the promise; and nothing found endorses applying the minimum to joins only. What the case does show is that the fix direction (code, javadoc, or the minimum in both methods) is the maintainers' choice, which is why the bug ranks Low. Verdict: not intended; one setting, two meanings in a checker.

Option A was built and run in a scratch worktree at 645d4fe14a20; B and C are listed as alternatives. A is recommended because it makes the code match its documentation and the two methods agree, with no change for the default minimum.

In suggestWordCombinations, compute the minimum once before the loop and use it in the check at WordBreakSpellChecker.java:208. A joined word then has to exist and be at least as frequent as its most popular part, the rule suggestWordBreaks applies.

// minSuggestionFrequency is "not applicable" with SUGGEST_MORE_POPULAR (see its setter), and
// suggestWordBreaks replaces it in that mode. Here, in that mode, a combined term only has to
// exist and be at least as frequent as the most popular included term
int useMinSuggestionFrequency =
    suggestMode == SuggestMode.SUGGEST_MORE_POPULAR ? 1 : minSuggestionFrequency;
...
            if (combinedTermFreq >= useMinSuggestionFrequency) {

Trade-offs

• No change for the default minimum (1) or for the other two modes.
• Callers who relied on a minimum of 2 or more for joins in more-popular mode get more suggestions: a behaviour change for them.
• For a minimum of 0 or below, A also stops suggesting a joined word that is not in the index (docFreq 0) in more-popular mode, as suggestWordBreaks already does (its replacement never goes below 1). Today 0 >= 0 lets such a word through; that face is not claimed as a bug.
• Open PR #16847 changes docFreq variables in this file (including combinedTermFreq) from int to long; A applies cleanly on top of it and still compiles (the int floor is widened when compared with the long docFreq); a reviewer may prefer long for the new local.

What the checks validated

Gradle in a scratch worktree at 645d4fe14a20, seed DEADBEEF, OpenJDK 25.0.3: on stock the repro fails 1 of 1 and upstream TestWordBreakSpellChecker passes 5 of 5, assertions on and off; with A the whole :lucene:suggest:test plus the repro, 32 classes, 237 tests, 0 failures (7 skipped by the module), assertions on and off; :lucene:suggest:check -x test with A and the repro added passes (google-java-format, ecj lint, forbidden APIs). After the fact check the patch's three comment lines were reworded (code lines unchanged) and the patch re-run: check, and the whole module with assertions on and off, same results. In the hunt's bounded-exhaustive comparison A changes exactly the 99,791 calls that differ from the setter-following reference (73,819 claimed drops at a minimum of 2 or 3, 25,972 minimum-0 calls) and no other call, and the same change in 4.0.0 makes the history probe pass.

Say that the minimum is not applicable to suggestWordBreaks in more-popular mode and that suggestWordCombinations applies it in every mode.

Trade-offs

No behaviour change, but one setting keeps two meanings within one request. Not run (no code change).

Let suggestWordBreaks keep the configured minimum in more-popular mode (for example Math.max(minSuggestionFrequency, origFreq)) and drop the "Not applicable" sentence.

Trade-offs

Consistent, and matches Solr's reference-guide wording, but it changes word-break results for existing users (row 4 of the table becomes "none"). Not run.

Method: bounded-exhaustive translation validation (the hunt's "semi-formal" tier): the stock suggestWordCombinations compared with four executable references, one faithful to the code and others that follow the documentation, through the public API.

• Scope: 40 random 3-document indexes over the strings of length 1-6 over {a, b} in two fields, all 2,379 term arrays of length 1-3 over the separator and a, b, aa, ab, ba, bb in fields f and g, 3 modes, minimum 0-3, maxChanges 1-2: 2,283,840 calls.
• Result: the jar equals the code-faithful reference on every call and differs from the setter-following reference on 99,791 calls (73,819 calls drop joins at a minimum of 2 or 3, 21,013 at 2 and 52,806 at 3; the other 25,972 suggest docFreq-0 joins at a minimum of 0, which is not claimed). With the one-line fix alone it equals that reference on every call and changes no other call. The comparison also separates a different bug in the same method (the joined word is looked up in the first term's field), which has its own fix. The model is exhaustive over these term arrays and settings, not over all indexes.
• An earlier pass had built a reference for this method, had to make it apply the minimum to match the code, noticed that the setter says the opposite and set the lead aside as likely a javadoc fix of low value. A later pass re-ran it on main and reduced it to a public-API JUnit test, later minimized to a one-word index.