ProtectedTermFilterFactory does not pass its luceneMatchVersion to the filters it builds from wrappedFilters

ProtectedTermFilterFactory runs other filters on every token that is not protected. You can name them with CustomAnalyzer's when()/endwhen() or with the factory's own wrappedFilters and filterName.argName parameters (the Solr-style spelling); the class javadoc shows both, each wrapping truncate prefixLength=4. In the wrappedFilters form the factory builds each wrapped filter from the filterName.* arguments only, and its own luceneMatchVersion, already consumed by AbstractAnalysisFactory, is never passed on, so every wrapped factory without its own filterName.luceneMatchVersion runs at Version.LATEST. Since 10.5.0 (#15900) truncate's deprecated prefixLength keeps N UTF-16 chars below version 10.5 and N code points from 10.5, so with luceneMatchVersion=10.4.0 the token ab😀😀cd becomes ab😀 unwrapped and in the when() form, but ab😀😀 in the wrappedFilters form. A document indexed on 10.4.0 with this configuration is found by the when() form on main (1 hit) but not by the wrappedFilters form (0 hits). The missing forwarding is in every release since 7.4.0; with stock filters it silently changes terms since 10.5.0. A one-line putIfAbsent in populateInnerFilters fixes it; the analysis module's tests pass with it.

• luceneMatchVersion: every analysis factory reads it from its arguments (AbstractAnalysisFactory) and uses Version.LATEST when there is none. Pinning it to an older version keeps that version's analysis after an upgrade. CustomAnalyzer.Builder.withDefaultMatchVersion adds it to every factory it builds.
• Two spellings of a protected chain: CustomAnalyzer.builder()...when("protectedTerm", ...) + addTokenFilter("truncate", "prefixLength", "4") + endwhen(), or one factory with wrappedFilters=truncate and truncate.prefixLength=4 (the Solr-style spelling). The class javadoc shows both (ProtectedTermFilterFactory.java:38-61).
• truncate prefixLength (deprecated): since 10.5.0 (#15900) it keeps N UTF-16 chars when the version is below 10.5 and N code points from 10.5 (TruncateTokenFilterFactory.java:93-97). With no length parameter at all it takes the same path with N = 5 (:81-82).

1. The constructor's super(args) takes luceneMatchVersion out of the argument map into the factory's own field (AbstractAnalysisFactory.java:94-109).
2. handleWrappedFilterArgs makes a fresh map per wrapped filter and moves only the filterName.argName entries into it (ProtectedTermFilterFactory.java:116-152).
3. populateInnerFilters calls TokenFilterFactory.forName(filterName, filterArgs) with that map (:154-165, the call at :162). Unless the configuration gave that filter its own filterName.luceneMatchVersion, the map has no version, so the wrapped factory takes Version.LATEST (AbstractAnalysisFactory.java:98-99).
4. The when() form does not have this gap: ConditionBuilder.addTokenFilter adds the default version to each wrapped filter (CustomAnalyzer.java:646-650, through applyDefaultParams, :596-602).

Token ab😀😀cd = 8 UTF-16 chars, 6 code points. The legacy no-length result splits a surrogate pair: that is the pre-10.5 behaviour the pinned version asks for. The table shows the analyzer's term text; when such a term is indexed, the UTF-16 to UTF-8 conversion writes the lone surrogate as U+FFFD, so an index built before 10.5 holds ab😀 followed by U+FFFD for that token (CharTermAttributeImpl.java:92-94, UnicodeUtil.java:172-176). The same on 10.5.2. Upgrade scenario: one document written with the 10.4.0 jars and this configuration holds the term ab😀; searching it on 10.5.2 or main with the same configuration finds 0 hits in the wrappedFilters form and 1 in the when() form (1 and 1 with the fix).

• Who is exposed. The wrappedFilters form of ProtectedTermFilterFactory (SPI name protectedTerm): factory arguments, Solr-style schemas, or CustomAnalyzer.addTokenFilter("protectedTerm", ..., "wrappedFilters", ...). The when()/endwhen() form is not affected.
• What it takes. Lucene 10.5.0 or later, luceneMatchVersion pinned below 10.5.0, a wrapped truncate with the deprecated prefixLength (or no length parameter), and a supplementary character (emoji, many CJK extension characters) in the first prefixLength chars of a token that is not protected.
• What changes. Such tokens get the 10.5+ code-point prefix (at most 2 * prefixLength chars) instead of the pinned legacy one. Queries miss documents indexed with the legacy analysis (before an upgrade, or by the when() form): 0 hits instead of 1 in the upgrade probe. Mixed index generations analyse the same text differently. No error and no exception; the extra work is bounded (the code-point branch scans at most prefixLength code points, TruncateTokenFilter.java:97-112).
• What does not change. BMP-only text, protected terms, unpinned configurations, versions pinned to 10.5.0 or later, and the when() form.
• Beyond truncate. On main, truncate is the only stock factory whose output reads the version, but any application factory used inside wrappedFilters that reads luceneMatchVersion has received Version.LATEST since 7.4.0, unless it was given its own filterName.luceneMatchVersion. From 8.4.0 to 9.12.3 the only stock consequence was loud: a wrapped concatenateGraph rejected preserveSep under a version below 8.4.0.
• How likely. Rare: each ingredient is ordinary (the class javadoc's Solr example is this configuration, and pinning the version is how users keep an old index after an upgrade), but all together they are uncommon in direct Lucene use today.

# Lucene main 645d4fe14a20, assertions on (-ea), seed DEADBEEF: 1 test(s) run, 1 failed
    => org.junit.ComparisonFailure: term 0 expected:<ab😀[]> but was:<ab😀[😀]>
       org.junit.Assert.assertEquals(Assert.java:117)
       org.apache.lucene.tests.analysis.BaseTokenStreamTestCase.assertTokenStreamContents(BaseTokenStreamTestCase.java:262)
       org.apache.lucene.tests.analysis.BaseTokenStreamTestCase.assertTokenStreamContents(BaseTokenStreamTestCase.java:513)
       org.apache.lucene.tests.analysis.BaseTokenStreamTestCase.assertTokenStreamContents(BaseTokenStreamTestCase.java:598)
       org.apache.lucene.tests.analysis.BaseTokenStreamTestCase.assertTokenStreamContents(BaseTokenStreamTestCase.java:622)
       org.apache.lucene.tests.analysis.BaseTokenStreamTestCase.assertTokenStreamContents(BaseTokenStreamTestCase.java:689)
       org.apache.lucene.analysis.miscellaneous.TestProtectedTermWrappedFiltersMatchVersion.testWrappedTruncateUsesFactoryMatchVersion(TestProtectedTermWrappedFiltersMatchVersion.java:36)

• CustomAnalyzer's contract. withDefaultMatchVersion's javadoc: "This match version is passed as default to all tokenizers or filters. It is used unless you pass the parameter {code luceneMatchVersion} explicitly." (CustomAnalyzer.java:242-243, verbatim; {code ...} is a malformed tag in the source). The wrapped truncate is a filter of that analyzer and does not get it; in the when() form it does (:648). TestCustomAnalyzer.testVersionAwareFilter (:111-127) checks that version-aware filters receive the default; it checks a top-level filter only, not a filter inside when() or wrappedFilters.
• truncate's back-compat purpose. prefixLength "is still supported" "for backwards compatibility" and "its behaviour depends on the luceneMatchVersion parameter" (TruncateTokenFilterFactory.java:32-37). In the #15900 review, uschindler wrote "Old indexes and schemas then use old behaviour". Pinning the version is how a schema keeps the old terms; the wrappedFilters path defeats it.
• The two spellings disagree. The class javadoc shows the when() form and the wrappedFilters form next to each other, both wrapping truncate prefixLength=4; under the same pinned version they give different terms (the two examples also differ in tokenizer and in how they name the factory; the repro removes those differences). The javadoc does not call them equivalent, and nothing promises that wrapped filters inherit the version.
• Precedent. SOLR-4251 (fixed in 4.1, 2013): SynonymFilterFactory's delegate "is not propagating the LUCENE_MATCH_VERSION"; its fix (a973191f2de) forwarded the version to the delegate. Today both Synonym factories forward their version to the tokenizer factory they build, through lines from later commits (SynonymFilterFactory.java:112, SOLR-4813, 2013; SynonymGraphFilterFactory.java:109, LUCENE-6664, 2016). They put the version first and then copy the tokenizerFactory.* arguments, so an explicit tokenizerFactory.luceneMatchVersion still wins (executed): the same semantics as the recommended putIfAbsent fix.
• Nothing pins the current behaviour. The introducing commit and the 87 comments of #9320 never mention the version. TestProtectedTermFilterFactory wraps truncate.prefixLength (testMultipleWrappedFiltersWithParams, :83-99), but only with ASCII text at Version.LATEST. #15900 never mentions ProtectedTermFilterFactory.

The checkers built the strongest case for "works as designed": (a) no javadoc line says wrapped filters inherit the version; (b) luceneMatchVersion is an ordinary factory argument, so truncate.luceneMatchVersion=10.4.0 is a valid filterName.argName setting, and it works; (c) each component meets its own contract read literally (AbstractAnalysisFactory defaults to LATEST, CustomAnalyzer does pass the version to the factory it builds, truncate follows the version it gets); (d) prefixLength is deprecated, and truncateAfterChars (a parameter since 10.5.0) gives the legacy result at any luceneMatchVersion.

Why it fails: no documentation mentions filterName.luceneMatchVersion for wrapped filters (the class javadoc describes filterName.argName in general), and Solr fills in the schema's default version for every factory that does not set its own, so users normally set it once per schema; withDefaultMatchVersion promises the version to "all tokenizers or filters", and the when() form delivers it; #15900 kept prefixLength so that pinned schemas keep their old terms; the Synonym factories pass their version on to the tokenizer factory they build, and SOLR-4251 fixed the same kind of defect in 2013 by forwarding the version. No test, commit or PR says the gap is deliberate. The strongest remaining reading is that withDefaultMatchVersion covers only the factories CustomAnalyzer builds itself; the when() form and the Synonym factories show that Lucene otherwise passes the version on to child factories. The remaining pushback is about severity (narrow), not validity. Every checker rejected the works-as-designed case.

The recommended fix was applied in a scratch worktree of main a9779ef3c193 and run through gradle with assertions on and off; the worktree was removed afterwards. A put variant was run to check that the new guard test catches it.

In populateInnerFilters (ProtectedTermFilterFactory.java:154-165), before forName, add the outer factory's version to each wrapped filter's arguments with putIfAbsent, as CustomAnalyzer does for the when() form (applyDefaultParams, CustomAnalyzer.java:599) and as the Synonym factories in effect do for their tokenizer factory (version first, then the tokenizerFactory.* arguments, so an explicit per-tokenizer version wins). +3 lines, 2 of them comments. It is the hunt's sketch with a different comment.

New output. Every row of the table equals the when() form: ab😀 for prefixLength=4 and the javadoc's Solr example, the legacy 5-char result with no length; the workarounds and the unpinned configuration are unchanged; the upgrade probe finds the 10.4.0 document (1 hit).

           if (idSuffixPos != -1) { // Strip '-id' suffix, if any, prior to SPI lookup
             filterName = filterName.substring(0, idSuffixPos);
           }
+          // wrapped filters use this factory's luceneMatchVersion, unless they were given their own
+          // (filterName.luceneMatchVersion)
+          filterArgs.putIfAbsent(LUCENE_MATCH_VERSION_PARAM, getLuceneMatchVersion().toString());
           innerFilters.add(TokenFilterFactory.forName(filterName, filterArgs));

Trade-offs

• A configuration pinned below 10.5 that ran on 10.5.0-10.5.2 indexed code-point terms for affected tokens; after the fix it produces the legacy terms again, so such an index needs a reindex, or the user keeps the code points with truncate.luceneMatchVersion=10.5.0 or truncateAfterCodePoints; that only avoids a reindex when all affected terms were written on 10.5.0-10.5.2, and an index that mixes pre-10.5 and 10.5.x terms needs a reindex either way. Worth a CHANGES line (none drafted).
• An application factory inside wrappedFilters that reads luceneMatchVersion now sees the configured version instead of LATEST: the point of the fix, but a behaviour change since 7.4.0.
• The wrapped factories' getOriginalArgs() now include luceneMatchVersion; the wrapped factories are not reachable from outside (ConditionalTokenFilterFactory.innerFilters is private).

What the checks validated

• The 5 new tests and the closest upstream suites (TestProtectedTermFilterFactory, TestProtectedTermFilter, TestTruncateTokenFilterFactory, TestTruncateTokenFilter, TestConditionalTokenFilter, TestCustomAnalyzer) pass with assertions on and off: 59 of 59; stock: the 2 bug tests fail.
• All of :lucene:analysis:common:test with assertions on: 340 classes, 1,914 tests, 18 skipped, 0 failures.
• :lucene:analysis:common:check -x test passes (google-java-format, ecjLint, forbiddenApis).
• Through the repro harness with the fix shadowed: the new test 5 of 5; the hunt's runs of the same line: the finder's JUnit 4 of 4, the reproducer's 6 of 6, and the version-neutral history probe on 7.4.0 and main.
• The module-wide run used the test file before a comment-only javadoc reflow (the first check flagged only that); the final file then ran with check and the six suites (assertions on).
• Coverage gap: no dedicated test covers a wrapped filter with an -id suffix or a conditional factory nested in wrappedFilters; the fact check's probe ran a truncate-x child, which gets 10.4.0 with the fix and 11.0.0 without it.

Uses an unconditional put after the per-filter arguments are collected (the Synonym factories also call put, but before they copy the tokenizerFactory.* arguments, so an explicit per-tokenizer version still wins there).

Trade-offs

So it overrides an explicit truncate.luceneMatchVersion with the outer version, which breaks the filterName.argName mechanism for this one argument. With it the guard test testWrappedFilterOwnVersionWins fails (expected:<ab😀[😀]> but was:<ab😀[]>), the other 4 pass.

Document that wrapped filters need filterName.luceneMatchVersion, and point to truncateAfterChars / truncateAfterCodePoints.

Trade-offs

Leaves withDefaultMatchVersion's "all tokenizers or filters" broken and the two spellings inconsistent; not validated.

A small protected helper (for example in AbstractAnalysisFactory) that copies the version into a child factory's arguments, used by ProtectedTermFilterFactory and the Synonym factories.

Trade-offs

A broader API change for a one-line bug; only if a reviewer asks. Not validated.

• Method (non-formal): code reading in the hunt's unit on analysis factory/constructor equivalence: every place that builds an inner analysis factory (forName, getConstructor(Map.class) in src/java) was read while modelling how factory arguments reach constructors. luceneMatchVersion is the one argument AbstractAnalysisFactory consumes for every factory, and TruncateTokenFilterFactory (since #15900) is the one stock factory whose output depends on it.
• Confirmation. A public-API JUnit comparing the wrappedFilters form with the when() form and an unwrapped truncate (2 of 4 fail on main and 10.5.2, assertions on and off), then the checks below.