On main, LRUQueryCache's entry callbacks report a shared query's RAM with only one entry, but their javadoc still says "the total RAM cost of this entry"

LRUQueryCache invites subclasses to keep "per-index or per-query-class statistics" through its callbacks and to prefer the unified onCacheEntryInserted / onCacheEntryEvicted, "which provide the full context (segment key, query, total RAM)". Both callbacks' javadoc says ramBytesUsed is "the total RAM cost of this entry" (of "the evicted entry"), "including both the query key overhead and the cached DocIdSet value". That matched the code when #15558 wrote it, because every entry's amount then included the query's bytes (double-counting a query shared by several entries, which #16657 fixed).

#16657 made all entries of a query share one canonical query object and count its RAM once. The query's bytes now come with the insertion of its first entry and with the eviction of its last entry, often entries of different segments or indices. So one entry is inserted with 344 bytes and evicted with 160, and with two indices sharing one cache a per-index ledger kept through the callbacks ends at +184 for one index and -184 for the other while the cache reports 0. The count-once accounting is intended and every amount is the exact change of the cache's own ramBytesUsed(); the defect is that the javadoc still describes one fixed amount per entry, and the MIGRATE.md advice added after #16657, which points to these callbacks, says nothing about shared bytes. Search results, cache contents, hit counts, ramBytesUsed(), getCacheSize() and the memory bound are correct.

onCacheEntryInserted (LRUQueryCache.java:385-386, :390 at 645d4fe14a20): "The ramBytesUsed parameter reflects the total RAM cost of this entry, including both the query key overhead and the cached DocIdSet value." / "@param ramBytesUsed total RAM bytes used by this cache entry". onCacheEntryEvicted (:402-403): "the total RAM cost of the evicted entry, including both the query key overhead and the cached DocIdSet value"; its @param (:407) says "total RAM bytes freed by this eviction". The class javadoc (:91-99) offers the callbacks for "per-index or per-query-class statistics" and says to prefer the unified ones, "which provide the full context (segment key, query, total RAM)". MIGRATE.md:521-522: "Prefer onCacheEntryInserted / onCacheEntryEvicted."

1. A query goes to partition query.hashCode() & (numberOfPartitions - 1) (:1277-1278), so all its entries share one partition, whose uniqueQueries map holds one canonical instance per distinct query (:954).
2. putIfAbsent (:1085-1137): the per-entry amount is QueryCacheKey.ramBytesUsed(), "Per-entry overhead only" (:1096, :1346-1350). "Account the query object only on the first entry that references it in this partition": queryBytes = perEntryBytes + (firstReference ? ref.queryBytes : 0) (:1111, :1120-1121), then onCacheEntryInserted(cacheKey, canonical, queryBytes + cachedValueBytesUsed) (:1126-1127).
3. remove (:1155-1189): "reclaim the query bytes on the last reference" (:1176-1177); releaseQuery returns the query's bytes only when its count drops to 0, else 0 (:1001-1017); then onCacheEntryEvicted(..., queryBytes + docIdSetBytes) (:1183-1184).

344 = 48 (key) + 112 (doc id set with its table slot) + 184 (query); 160 = 48 + 112. With #16657's parent shadowed, every event is 344 and the cache holds 688 with both entries. Two indices A and B sharing one cache, the same filter, readers closed in turn: the unified-callback ledger ends at A = +184, B = -184 with ramBytesUsed() = 0 and getCacheSize() = 0; the deprecated per-core onDocIdSetCache / onDocIdSetEviction ledger ends at A = 0, B = 0. The drift depends on order: with segment 1 cleared before segment 0 (the query's first and last entry in the same segment) the events are 344, 160, 160, 344 and both ledgers end at 0.

• Who is hit. Applications on 11.0 (main and branch_11x today) that subclass LRUQueryCache and keep per-segment, per-index or per-shard RAM from onCacheEntryInserted / onCacheEntryEvicted. Their ledgers drift silently: one index stays positive with no entries left, another goes negative, and the error grows with every shared filter whose first and last entries are in different segments or indices (the devil's-advocate verifier ran 50 shared filters: index A ended above its live RAM by the sum of their query sizes and index B below it by the same sum, at a negative value; the fact check's probe, searching A then B and closing A first, got A = +9200 and B = -9200). When a filter's first and last entries are in the same segment, its ledger balances.
• Default vs opt-in. Opt-in: the query cache is off by default on main (IndexSearcher.java:84, DEFAULT_QUERY_CACHE = null), and only a subclass that overrides these protected @lucene.experimental callbacks is affected. No in-tree subclass outside the tests overrides them, and a GitHub code search (indexed public code) found no implementer outside apache/lucene.
• Scale. The most ordinary trigger, one cached filter on an index with two segments, already makes the per-segment amounts differ; no concurrency, no clear(), no unusual parameters.
• Not affected. Search results, cache contents, hit and miss counts, ramBytesUsed(), getCacheSize(), the memory bound (eviction uses the partition's own accounting, LRUQueryCache.java:1128), and every release, 10.6.0 included.
• Workarounds for subclass authors. Remember each entry's inserted amount and subtract that at eviction: it balances per index, but while a shared query is still held the per-index sum is below ramBytesUsed() by the query's size. Or keep the deprecated per-core onDocIdSetCache / onDocIdSetEviction, which still balance per core on main but "will be removed in a future release" (:361, :373).

The test asserts the per-entry reading of the current javadoc (one entry, one amount), so its failure shows that the javadoc no longer matches the code. It is not a regression test: the documentation fix changes no code and leaves it failing, by design.

Only segment 0 is cleared, so the outcome does not depend on the order in which cleanUp() removes entries. NoMergePolicy keeps the two segments; the always-cache policy caches the filter on both. Controls, executed: with #16657's parent LRUQueryCache.java (shadowed, or as an exact-commit build) it passes; on 10.5.2 and 10.6.0 it does not compile, because the callbacks and the public cleanUp() do not exist there.

cp $REPRO/TestLRUQueryCacheEntryCallbackBytes.java $LUCENE/lucene/core/src/test/org/apache/lucene/search/
cd $LUCENE && ./gradlew :lucene:core:test --tests TestLRUQueryCacheEntryCallbackBytes -Ptests.seed=DEADBEEF -Ptests.asserts=true
# assertions off fail the same way: -Ptests.asserts=false

TestLRUQueryCacheEntryCallbackBytes > testEvictedEntryReportsItsInsertedBytes FAILED
    java.lang.AssertionError: segment 0 entry: onCacheEntryInserted vs onCacheEntryEvicted ramBytesUsed expected:<344> but was:<160>
        at __randomizedtesting.SeedInfo.seed([DEADBEEF:2D824F39DC672]:0)
        at org.junit.Assert.fail(Assert.java:89)
        at org.junit.Assert.failNotEquals(Assert.java:835)
        at org.junit.Assert.assertEquals(Assert.java:120)
        at org.apache.lucene.search.TestLRUQueryCacheEntryCallbackBytes.testEvictedEntryReportsItsInsertedBytes(TestLRUQueryCacheEntryCallbackBytes.java:79)

1 test completed, 1 failed

# the same with -Ptests.asserts=false, and with the documentation fix applied (by design)

• The contract text names one per-entry quantity with two components, at both events (LRUQueryCache.java:385-386, :390, :402-403). On main the 184-byte query object is neither component: QueryCacheKey.ramBytesUsed() is "Per-entry overhead only" (:1347), 48 bytes, and a structurally identical second entry reports 160.
• History. #15558 (d50fb36d9af3, 2026-04-14) wrote the text when each entry's key included the query's bytes; all five LRUQueryCache.java versions from #15558 to #16657's parent pass the repro (assertions on). #16657 (fadd63e0eb4e) left the javadoc and the class javadoc byte-identical (the class javadoc's per-index sentence, :91-93, is older, 2d6ad2fee6df, 2020; :94-99 is from #15558); its PR body and 13 comments never discuss what the callbacks report. CHANGES.txt:281-282 says only that a query's RAM is accounted once.
• The class javadoc offers the callbacks for per-index statistics (:91-93), and it and MIGRATE.md point to the unified pair (:97-99; MIGRATE.md:521-522, #16756), while the deprecated per-core pair, the only one that still balances per index, is marked for removal.
• Tests. No upstream test checks per-entry or per-segment amounts: testUnifiedCacheEntryCallbacks (TestLRUQueryCache.java:2725) forces one segment, where a query's first and last entry coincide, and checks aggregate balance; testFineGrainedStats (:954) keeps RAM only cache-wide.
• Precedent (weaker than it reads). #12614 (2023) fixed an earlier, different insert/evict amount mismatch in the predecessor onQueryCache / onQueryEviction pair as a bug; there it also broke the cache's own total, here it does not.

The strongest case for "works as designed" (the executing refute review by OpenAI GPT-5.6, verdict not real, high confidence, and the devil's-advocate verifier): each amount is the actual cache-wide RAM change of its event, and the eviction @param says exactly that ("total RAM bytes freed by this eviction"); nothing promises that an entry's two amounts are equal; a shared query's RAM cannot be split per index without double counting; upstream tests pin the aggregate balance and the count-once accounting (testQueryRamAccountedOncePerDistinctQuery, testCanonicalQueryInstanceSharedAcrossSegments); in 10.x onQueryCache also reported a query's RAM once per distinct query, so folding it into one insertion is the faithful sum of the pair the unified callback replaces; the hooks are experimental and unreleased.

Why it fails: it defeats a code-bug claim, which is why none is made. It does not make the text right. The insertion javadoc has no "added by this insertion" wording at all, and its two named components do not cover the 184 bytes the first insertion carries. The eviction sentence repeats the per-entry wording, and its "freed by this eviction" @param fits the per-event reading, but was written when that was the same number as the per-entry total, so it does not show that one entry's two amounts were meant to differ. The class javadoc offers the callbacks for per-index statistics, and it and MIGRATE.md point to the unified pair, with no word on shared bytes. The reviewer itself wrote that "a clarification could make the javadoc less susceptible to this interpretation". Verdict (tie-break): a documentation defect, not a code bug. The cache-wide-delta reading is the cross-model reviewer's and the intended-behaviour check's; their correct points belong in the fix text. The second cross-model fact check (OpenAI GPT-5.6) also rates the intended-behaviour case strong and calls "clarify the attribution" the strongest version of the claim.

One option was built and checked (A); B is a question for maintainers; C should be avoided.

The finder's wording with the adjudication's corrections: both callbacks, the class javadoc's "total RAM" sentence and one paragraph in the #15558 section of MIGRATE.md (+26/-8 lines). The finder's sentence "the sum of all inserted amounts minus all evicted amounts equals ramBytesUsed()" is dropped, because it fails when an insertion runs concurrently with clear() (LFV-991). After the fact checks one sentence was added to the eviction javadoc and to MIGRATE.md: entries dropped by clear() are not reported as evictions, clear() calls onClear() instead (LRUQueryCache.java:455-460, :1191-1201).

// onCacheEntryInserted
 * <p>The {@code ramBytesUsed} parameter is the RAM that this insertion added to the cache: the
 * per-entry key overhead and the cached {@link DocIdSet} value, plus the RAM of the query object
 * itself when no other entry of the same query is cached. All entries of a query share one query
 * object, which is accounted once: its RAM is reported with the insertion of the query's first
 * entry and with the eviction of its last entry (see {@link #onCacheEntryEvicted}), and these
 * often belong to different segments. The amounts reported for one entry at insertion and at
 * eviction can therefore differ, and sums of these amounts kept per segment or per index need not
 * return to zero once that segment's or index's entries are gone.
 * @param ramBytesUsed RAM bytes added to this cache by this insertion
// onCacheEntryEvicted: "the RAM that this eviction freed ... plus the RAM of the query object itself
// when this was the last cached entry of the same query"; "Entries dropped by {@link #clear()} are not
// reported here; {@link #clear()} calls {@link #onClear()} instead."; class javadoc: "RAM added or freed";
// MIGRATE.md: the same note in the #15558 section

Trade-offs

• Documents the intended accounting instead of changing it: no runtime cost, #16657's count-once design stays.
• It does not give subclasses balanced per-index numbers; it tells them why they are not balanced. The workarounds (remember each entry's inserted amount, or the deprecated per-core pair) could be added if maintainers want.
• The class-javadoc sentence is the one LFV-1000's fix also rewrites ("under a lock"), and LFV-1000's fix also inserts a MIGRATE.md paragraph at the same place, so the two edits overlap. The eviction @param ("total RAM bytes freed by this eviction") is accurate and stays.
• A leaves the class javadoc's other stale sentence, :66-68 (one query's entries "may reside in different partitions"; since #16657 they share one), which is LFV-054's documentation point.

What the checks validated

• Stock 645d4fe14a20: the minimal test fails with assertions on and off, 344 vs 160.
• With A (v1, before the clear() sentence was added), in a scratch worktree with gradle: :lucene:core:checkGoogleJavaFormat, ecjLintMain and renderJavadoc pass; TestLRUQueryCache passes (40 tests, 3 skipped, 0 failures, seed DEADBEEF, assertions on; the log's "eclint tool location is not set" line is the separate editorconfig lint, not ecjLintMain). With assertions off (seed C0FFEE), TestLRUQueryCache plus the minimal test: 41 tests, 1 failure, the minimal test, as expected, because A changes no code.
• The current diff (v2, comment text added): git apply --check on pristine 645d4fe14a20 files, google-java-format 1.37.0 (Lucene's version and options) leaves it unchanged, and javac -Xdoclint:all/protected -Werror passes (a broken {@link} fails it). Gradle was not re-run for this version; the change is comment-only.
• The diff applies cleanly to a pristine 645d4fe14a20 (git apply --check). No regression test: a documentation fix has nothing to assert.

Give the unified callbacks a stable per-entry amount (key overhead plus doc id set) and report the query object's RAM through a separate per-query notification or an extra parameter.

Trade-offs

Per-entry and per-index sums would balance and a subclass could still rebuild ramBytesUsed(), but it adds API surface to hooks that are new in 11.0. Not built.

Restore the pre-#16657 accounting, so every event of one entry carries the query's bytes.

Trade-offs

Makes the javadoc true again (shadowed parent: every event 344) but counts the query twice, 688 instead of 504 bytes for one filter on two segments, which is the bug #16657 fixed. The devil's-advocate verifier showed that no per-entry split of a shared query's bytes balances both per entry and cache-wide.

Method: semi-formal, bounded-exhaustive checking of the real jar. A probe enumerated every operation sequence up to a small bound against the stock main LRUQueryCache and checked per-entry and per-core callback balance: 12,819 of 46,650 sequences violated on a9779ef3c193 with assertions off; on 645d4fe14a20 15,089 with assertions off and 12,819 with them on (the count varies with identity-hash order in cleanUp()).

The finder (a hunt unit) then ran an independent reference model of the partitioned cache in lockstep with the real one: every sequence of length 1-6 over 8 operations and 9 configurations, 2,696,328 sequences and 16,353,259 event checks, 0 model mismatches; per-entry balance failed in 1,511,830 sequences and per-core balance in 973,900, the other six properties held. It read the root cause off putIfAbsent / remove and wrote a public-API JUnit. It was then reduced to the one test above.

The independent cross-model reviewer (OpenAI GPT-5.6) and the devil's-advocate verifier then framed it as stale documentation rather than a code bug.