AfterEffectB's explanation prints totalTermFreq and docFreq under labels that say "+ 1", so its own formula does not give its value (scores are correct)

AfterEffectB scores with F = totalTermFreq + 1 and n = docFreq + 1, and its explanation node says so: "AfterEffectB, computed as (F + 1) / (n * (tfn + 1)) from:", with children labelled "F, total number of occurrences of term across all documents + 1" and "n, number of documents containing term + 1". But the children are the raw stats.getTotalTermFreq() and stats.getDocFreq(), and tfn is listed twice. For a term with totalTermFreq 6 and docFreq 3 the children show 6 and 3 where the labels promise 7 and 4, and the formula on the printed children gives 0.71897 while the node correctly shows 0.61626 (DFR I(n)B2). Scores, ranking and the node value are correct. It came in with LUCENE-8011 (8.0.0), which added the formula text and the "+ 1" labels but kept the raw values; 7.7.3 printed accurate raw labels. A fix that changes three lines (+2/-3) prints the + 1 and drops the duplicate child.

• scoreTimes1pTfn (:32-36): long F = stats.getTotalTermFreq() + 1; long n = stats.getDocFreq() + 1; return (F + 1.0) / n;
• explain(BasicStats stats, double tfn) (:39-49):
  • node value scoreTimes1pTfn(stats) / (1 + tfn) (:41): right;
  • description "AfterEffectB, computed as (F + 1) / (n * (tfn + 1)) from:" (:42);
  • child tfn (:43);
  • child stats.getTotalTermFreq() labelled "F, total number of occurrences of term across all documents + 1" (:44-46): the raw value;
  • child stats.getDocFreq() labelled "n, number of documents containing term + 1" (:47): the raw value;
  • child tfn again (:48).
• DFRSimilarity.explain (DFRSimilarity.java:134-145) adds this node (:144) to every explanation of a DFRSimilarity built with AfterEffectB, whatever the basic model and normalization. Scoring (:127-131) uses only scoreTimes1pTfn, so the score is not involved.

Five documents a b c a a, a d e, f g h, a a b, x y z; term a: docFreq 3, totalTermFreq 6. Document 0 has a 3 times in 5 terms; NormalizationH2 gives tfn = 3 x log2(1 + 3.4 / 5) = 2.2453837.

1. Node: (6 + 1 + 1) / ((3 + 1) x (2.2453837 + 1)) = 8 / 12.98 = 0.61626, printed 0.61625993: right.
2. Printed children: 6 = F, ... + 1, 3 = n, ... + 1.
3. The printed formula on the printed children: (6 + 1) / (3 x 3.2453837) = 7 / 9.74 = 0.71897.
4. Score: 1.7460274 (BasicModelIn) x 0.61625993 = 1.0760068: right, the same on 7.7.3, 8.0.0, main and main with the fix.

CheckHits.verifyExplanation accepts a node whose description matches .*, computed as .* from: (CheckHits.java:375, :437-438) by setting combined = value (:494-496), so it never checks such a node against its children. The test framework's RandomSimilarity does use AfterEffectB (RandomSimilarity.java:96, :131), so Lucene's tests explain with it, but nothing compares the children with their labels.

• Who. Users of DFRSimilarity built with AfterEffectB (public constructors, @lucene.experimental, not the default similarity) who read IndexSearcher.explain output, for example to tune or debug relevance. Lucene ships two after effects, B and L; L's explanation is consistent.
• What they see. On every explained hit, F and n one lower than their labels say, and tfn twice. Recomputing the node from its printed inputs gives 0.719 instead of the 0.616 shown in the example, which can make a reader suspect the score.
• Not affected. Scores, ranking, matching, the node's own value and the top explanation value; nothing throws; assertions on and off behave the same.
• Downstream (by reading, not run): Elasticsearch and OpenSearch expose a DFR similarity with after effect b and an explain API, so their explain output would show the same numbers.
• Likelihood: plausible. Every explained hit is affected, but only a reader who checks children against labels notices; no report since 8.0.0 (2019).

One test class, one method, nothing random (the seed only satisfies LuceneTestCase). It uses public API only (BasicStats constructor and setters, AfterEffectB.explain, Explanation.getDetails); it sits in the similarities package like Lucene's other similarity tests but needs nothing package-private. children[1] is the F child and children[2] the n child; with tfn = 1 the node itself is (7 + 1) / (4 x 2) = 1.0.

The test pins the recommended fix. With the alternative fix (relabel instead of adding 1), its expected string would change to F=6, n=3 and it would check the new labels instead.

Regression test: this same test. It fails on stock main and passes with the fix.

cp $REPRO/TestAfterEffectBExplain.java $LUCENE/lucene/core/src/test/org/apache/lucene/search/similarities/
cd $LUCENE && ./gradlew :lucene:core:test --tests org.apache.lucene.search.similarities.TestAfterEffectBExplain -Ptests.seed=DEADBEEF -Ptests.asserts=true
# same failure with -Ptests.asserts=false

# gradle, main 645d4fe14a20, seed DEADBEEF, -Ptests.asserts=true
TestAfterEffectBExplain > testPlusOneChildren FAILED
    org.junit.ComparisonFailure: expected:<F=[7, n=4]> but was:<F=[6, n=3]>
        at __randomizedtesting.SeedInfo.seed([DEADBEEF:14CF3C90051FC187]:0)
        at app//org.junit.Assert.assertEquals(Assert.java:117)
        at app//org.junit.Assert.assertEquals(Assert.java:146)
        at app//org.apache.lucene.search.similarities.TestAfterEffectBExplain.testPlusOneChildren(TestAfterEffectBExplain.java:30)
BUILD FAILED

# -Ptests.asserts=false: the same ComparisonFailure; 10.6.0 and 10.5.2 (-ea and -da): the same
# with the recommended fix: 1 test, 0 failures, both ways

# explain probe, main 645d4fe14a20, DFR I(n)B2, term a (docFreq 3, totalTermFreq 6), doc 0
1.0760068 = weight(f:a in 0) [DFRSimilarity], result of:
  1.0760068 = score(DFRSimilarity, freq=3.0), computed as boost * basicModel.score(stats, tfn) * afterEffect.score(stats, tfn) from:
    2.2453837 = NormalizationH2, computed as tf * log2(1 + c * avgfl / fl) from:
      3.0 = tf, number of occurrences of term in the document
      1.0 = c, hyper-parameter
      3.4 = avgfl, average length of field across all documents
      5.0 = fl, field length of the document
    1.7460274 = BasicModelIn, computed as tfn * log2((N + 1) / (n + 0.5)) from:
      2.2453837 = tfn, normalized term frequency
      5 = N, total number of documents with field
      3 = n, number of documents containing term
    0.61625993 = AfterEffectB, computed as (F + 1) / (n * (tfn + 1)) from:
      2.2453837 = tfn, normalized term frequency
      6 = F, total number of occurrences of term across all documents + 1
      3 = n, number of documents containing term + 1
      2.2453837 = tfn, normalized term frequency

# the same probe with the fix: the AfterEffectB children become
      2.2453837 = tfn, normalized term frequency
      7 = F, total number of occurrences of term across all documents + 1
      4 = n, number of documents containing term + 1

# the same probe on 7.7.3 (before LUCENE-8011)
    0.6162599 = AfterEffectB, computed from: 
      2.245384 = tfn
      6.0 = totalTermFreq
      3.0 = docFreq

• The node defines its operands. "computed as (F + 1) / (n * (tfn + 1)) from:" and the "+ 1" labels (AfterEffectB.java:42-47) match the scoring code (:33-34); only the printed values differ.
• What a description means. Explanation.match: "@param description how {@code value} was computed", "@param details sub explanations that contributed to this explanation" (Explanation.java:42-47).
• Lucene's own test writes the + 1. TestSimilarityBase.testIFB (:449-453) computes the after effect as B = (TOTAL_TERM_FREQ + 1 + 1) / ((DOC_FREQ + 1) * (FREQ + 1)). On LUCENE-8020 (#9068), rmuir described the code as using (F + 1 + 1) / ((n + 1) * (tfn + 1)).
• Same family. BasicModelG.explain computes F = stats.getTotalTermFreq() + 1 (BasicModelG.java:55) and prints it under "F, total number of occurrences of term across all docs + 1" (:62-63). BasicModelIn prints the raw docFreq under "n, number of documents containing term", without "+ 1".
• History. Before LUCENE-8011 the node read "AfterEffectB, computed from:" with 6.0 = totalTermFreq and 3.0 = docFreq: accurate (7.7.3, executed). LUCENE-8011 (8.0.0 CHANGES "Improved similarity explanations", CHANGES.txt:6825) added the formula, the "+ 1" labels and a second tfn, and kept the raw values. Its issue (#9059) and review (apache/lucene-solr#280) do not discuss the values.
• Precedent. 9.12.0 Bug Fixes: "GITHUB#13691: Fix incorrect exponent value in explain of SigmoidFunction." (CHANGES.txt:2705), a wrong explain value with a correct score.

The strongest case for "not a bug": IndexSearcher.explain "is intended to be used in developing Similarity implementations" (IndexSearcher.java:934-940); AfterEffectB, AfterEffect and DFRSimilarity are @lucene.experimental; no javadoc promises that a "computed as" node can be rebuilt from its children, and CheckHits treats such nodes as opaque; the strings have stood for about nine years without a complaint; and the open LUCENE-8023 (#9071) proposes dropping the "+ 1" terms from the scores, so one could call the raw counts the real F and n.

Why it fails: under any reading, a child whose label says "+ 1" and whose value has no + 1 contradicts itself. If the raw counts were meant, the label and the formula would say so, as 7.7.3's did and as BasicModelIn's n child does today. The duplicated tfn child reads as a copy slip. The rest (expert API, experimental class, no complaints) argues for Low priority, which is how it is classed, not for intent. LUCENE-8023 would change scores; it does not make today's explanation right. The independent verifier, the devil's-advocate check and the cross-model reviews (OpenAI GPT-5.6) all rated the works-as-designed case weak.

One fix was validated through gradle in a scratch worktree of 645d4fe14a20; the alternative keeps the raw values and fixes the text instead; changing the scores (LUCENE-8023) is a separate decision.

AfterEffectB.java +2/-3:

@@ -42,10 +42,9 @@ public class AfterEffectB extends AfterEffect {
         getClass().getSimpleName() + ", computed as (F + 1) / (n * (tfn + 1)) from:",
         Explanation.match((float) tfn, "tfn, normalized term frequency"),
         Explanation.match(
-            stats.getTotalTermFreq(),
+            stats.getTotalTermFreq() + 1,
             "F, total number of occurrences of term across all documents + 1"),
-        Explanation.match(stats.getDocFreq(), "n, number of documents containing term + 1"),
-        Explanation.match((float) tfn, "tfn, normalized term frequency"));
+        Explanation.match(stats.getDocFreq() + 1, "n, number of documents containing term + 1"));
   }

Trade-offs

• The explanation then matches its own formula and BasicModelG's "F, ... + 1" child; the probe tree with the fix shows 7 = F, 4 = n, one tfn, and the same score 1.0760068.
• Explain text changes for anyone who parses it: two numbers go up by 1 and one child goes away.

What the checks validated

• Scratch worktree of 645d4fe14a20, gradle --offline, OpenJDK 25.0.3, seed DEADBEEF. Stock: the repro fails with assertions on and off.
• With the fix: the repro passes both ways; the whole org.apache.lucene.search.similarities package plus TestSimpleExplanations* and TestComplexExplanations* pass with assertions on and off (32 suites, 353 tests, 0 failures, 2 skipped by the suite's own assumption); :lucene:core:checkGoogleJavaFormat, ecjLintMain, ecjLintTest, forbiddenApisMain and forbiddenApisTest pass with the fix and the test in place.
• Earlier runs: the finder's, the independent reproducer's and the cross-model reviewers' tests pass with it; 118 of 118 lucene/core similarity tests passed with it on a9779ef3c193.

Labels "F, total number of occurrences of term across all documents" and "n, number of documents containing term", formula "(F + 2) / ((n + 1) * (tfn + 1))", and drop the second tfn.

Trade-offs

The tree shows raw index statistics, as 7.7.3 did and as BasicModelIn's n child does, but the formula moves away from the F and n of the scoring code; the regression test would check the new labels instead.

What the checks validated

Not run.

The open LUCENE-8023 (#9071, since 2017) proposes removing divide-by-zero "+ 1" terms across similarities.

Trade-offs

Changes scores and needs its own discussion; it is related context, not a fix for the explanation.

What the checks validated

Not run.

Method: semi-formal (a differential evaluation of explain trees against their own formula strings).

• Sweep. A test program ran IndexSearcher.explain over 79 similarity configurations x TermQuery, PhraseQuery, SynonymQuery and a 2-clause BooleanQuery x boosts 1 and 2.5, plus other scoring queries: 3,178 explained hits, 14,574 "computed as <formula> from:" nodes (14,554 evaluated on their own labelled children) and 3,806 labelled statistics checked against the index, with assertions on and off.
• Result. All 1,000 AfterEffectB formula nodes over the 20 DFR configurations that use after effect B disagreed with their formula, and 200 + 200 "F, ... + 1" / "n, ... + 1" children were 1 below the index statistic + 1; every other DFR node agreed.
• Oracle check. 10 of 10 injected mutants were detected, so the check is not vacuous.
• Then a public-API JUnit, a cross-model refute review (OpenAI GPT-5.6, with execution), an independent reproducer, a cross-model intended-behaviour review, a devil's-advocate check, an adjudication, the registration check, an audit, a repro minimization, the version-history runs and a prior-report search followed.