LRUQueryCache.clearQuery and clearCoreCacheKey say "Remove all cache entries", but on main they only mark the entries for cleanUp()

LRUQueryCache.clearQuery(query) and clearCoreCacheKey(key) are documented as "Remove all cache entries for the given query" and "... for the given core cache key" (LRUQueryCache.java:450, :442). Up to 10.6.0 they did exactly that before returning. #15558 (2026-04-14, not backported to 10.x) made removal deferred on purpose: both methods now only add the query or segment key to a pending set, and cleanUp() removes the marked entries later, on a background schedule if the cache was built with CacheCleanUpParameters, otherwise only when the application calls it. #15558 described this in the class javadoc ("Stale cache entries (from closed segments or cleared queries) are not removed inline"), but left the two method one-liners as they were.

So on main, after a clear call returns, the entry is still counted by getCacheSize(), still accounted in ramBytesUsed(), still returned by lookups and counted as a hit, and its eviction callback has not fired. MIGRATE.md, whose 11.0 recipe enables the cache with the 2-argument constructor (no automatic cleanup), never mentions cleanUp() or CacheCleanUpParameters. Search results stay correct. The fix is text only: reword the two javadocs and add a MIGRATE.md note.

// LRUQueryCache.java:442-455
/** Remove all cache entries for the given core cache key. */
public void clearCoreCacheKey(IndexReader.CacheKey coreKey) {
  this.registeredClosedListeners.remove(coreKey);
  synchronized (keysToClean) {
    keysToClean.add(coreKey);                    // only marks the key
  }
}

/** Remove all cache entries for the given query. */
public void clearQuery(Query query) {
  for (int i = 0; i < numberOfPartitions; i++) {
    this.lruQueryCachePartition[i].clearQuery(query);   // :1250-1257: queriesToClean.add(query)
  }
}

1. Both methods only mark. Neither removes a cache entry, fires an eviction callback or lowers ramBytesUsed() inside the call; clearCoreCacheKey also drops the segment's closed-listener registration (:443).
2. Lookups ignore the marks. LRUQueryCachePartition.get (:1060-1083) returns the cached entry and calls onHit (:1077) without looking at keysToClean or queriesToClean.
3. Only cleanUp() drains the marks (:1392-1413, the only code that drains the two sets); until it runs, a marked entry stays unless LRU eviction (:1214-1246) or clear() (:457-463) removes it first. It runs on a scheduler only when the 6-argument constructor got CacheCleanUpParameters with an executor (:197-207); the 4-argument constructor passes null (:150) and the 2-argument one delegates to it (:252).
4. Closed segments take the same path. The close listener registered for each cached segment is clearCoreCacheKey itself (:1135).
5. Results stay correct. Only SegmentCacheable queries are cached, which depend only on segment-immutable structures (SegmentCacheable.java:27-36), so a still-served entry holds the documents the query would compute again. The study's model-based test found 0 cached-vs-uncached mismatches.

MIGRATE.md has no occurrence of cleanUp or CacheCleanUpParameters.

For both clearQuery and clearCoreCacheKey, on one document: cached size=1; right after the call size=1, ramBytesUsed() unchanged, 0 evictions; next identical search size=1, hits=1, 1 document; after cleanUp() size=0, 1 eviction, ramBytesUsed() 0. With the 2-argument constructor and a 10,000-document segment, closing the reader leaves the entry counted with no eviction until cleanUp(): cached=1 afterReaderClose=1 evictedAfterClose=0 afterCleanUp=0 evicted=1.

• Who. Applications on 11.0 (branch_11x) and later (main) that install an LRUQueryCache and call clearQuery or clearCoreCacheKey, and 10.x users who learned that these calls remove at once. The class is @lucene.experimental (LRUQueryCache.java:117).
• Default vs opt-in. Opt-in: the query cache is off by default on main (IndexSearcher.java:84, DEFAULT_QUERY_CACHE = null, #14187). Among those who turn it on, MIGRATE.md's own recipe builds a cache with no automatic cleanup.
• What they see. After a clear call: the entries in getCacheSize(), ramBytesUsed(), hit counts and onHit; memory not freed; onCacheEntryEvicted / onDocIdSetEviction only at the next cleanUp(), LRU eviction or clear().
• Scale. Every call, deterministically. If the application never calls cleanUp(), the study's 1,000-round near-real-time run ended with 996 pending keys and 402 of 434 entries belonging to closed segments (432,704 accounted bytes, against 32 entries and 206,400 bytes with cleanUp() every round), and a Query passed to clearQuery stayed strongly reachable after LRU had evicted its entries. Entry count and accounted memory stay within maxSize and maxRamBytesUsed, and that run's hit and miss counts matched a run with cleanUp() every round, so no hit-rate loss is claimed. The PR author wrote that without cleanup "it will affect cache hit rates pretty badly", about stale segment entries piling up until LRU evicts them (sgup432 on #15558, 2026-04-22); one synthetic run settles neither way, so no hit-rate claim is made either way.
• Not affected. Search results; the cache's size and memory bounds; every release up to 10.6.0.
• Migration impact is recognized (evidence that someone relied on the two summaries was not found). On #15558, msokolov warned that cleanups being disabled by default "could bite someone if they are relying on it"; elastic/elasticsearch#163523 (open) lists "Cleanup is now async: a scheduler, or cleanup(). Without either, stale keys sit until LRU evicts them." among its adaptations to Lucene 11.

# Lucene main 645d4fe14a20, assertions on (-ea), seed DEADBEEF: 1 test(s) run, 1 failed
    => org.junit.ComparisonFailure: cache size after clearQuery / after clearCoreCacheKey expected:<[0 / 0]> but was:<[1 / 1]>
       org.junit.Assert.assertEquals(Assert.java:117)
       org.apache.lucene.search.TestLRUQueryCacheClearRemovesEntries.testClearQueryAndClearCoreCacheKeyRemoveEntries(TestLRUQueryCacheClearRemovesEntries.java:68)

• The method text. "Remove all cache entries for the given core cache key." (LRUQueryCache.java:442) and "Remove all cache entries for the given query." (:450). The text dates from LUCENE-6077 (2014) and LUCENE-6303 (2015); in 10.6.0 it sits over bodies that remove under the write lock (10.6.0 LRUQueryCache.java:373-404).
• The same file disagrees. "Stale cache entries (from closed segments or cleared queries) are not removed inline during cache operations." (:103-104). After the call the entries are not even logically removed: they are still returned and counted as hits.
• #15558 updated everything around them. The squash commit d50fb36d9af3 wrote the class paragraph, the 6-argument constructor, CacheCleanUpParameters and cleanUp() javadocs; in TestLRUQueryCache it inserted cleanUp() between existing clear calls and their assertions (e.g. :472-473, :762-769) and added a new test, testInvalidation (:2679-2722), whose clear calls are followed by cleanUp(). It left the two one-liners; no comment or review comment discusses them (the one inline review thread on the new clearCoreCacheKey body is about what it removes, not its javadoc).
• The migration guide is silent. MIGRATE.md's #15558 section (:514-542, added by #16756) shows a clearCoreCacheKey call and no cleanup note. Explaining why #15558 stayed off 10.x ("the query cache re-implementation introduced some breaking changes"), the PR author added: "we also changed the cleanup logic of the cache from sync to async flow" (sgup432, 2026-07-20).
• What is not claimed. That deferral is wrong (it is the design), that results are wrong, or that the hit rate drops.

Strongest case for "intended / noise" (the cross-model refute reviewer, OpenAI GPT-5.6, which ran its own failing two-segment test and voted not real with high confidence): the deferral is deliberate and documented four times (class, 6-argument constructor, CacheCleanUpParameters, cleanUp()); a test comment says "clearQuery() populates queriesToClean so that cleanUp() actually scans cache entries" (TestLRUQueryCache.java:272); the later fix #16212 kept the two-stage design; "Remove all" does not say "immediately"; the class is @lucene.experimental; no result is ever wrong.

Why it fails. It defeats a code-bug claim, which nobody makes. It does not make the method text true: on that reading "Remove all cache entries" would also fit a method that removes nothing until another method runs, and the class javadoc in the same file says these entries are "not removed inline". The reader most likely to trust the one-liner is the 10.x user, for whom the same words meant removal before return. The reviewer itself conceded that "MIGRATE.md and the method summaries could more explicitly repeat the cleanup requirement" and called the wording patch "a reasonable documentation enhancement". The objection fits the MIGRATE.md half better than the one-liners.

Two options. The deferral is #15558's design, so the recommended fix changes only text; a code option that restores removal-on-call for the two explicit methods is listed for upstream to weigh.

Both method javadocs: "Marks all cache entries for the given query (core cache key) for removal. Marked entries are removed by the next cleanUp(), which runs either on the background schedule configured through CacheCleanUpParameters or when the caller invokes it, unless LRU eviction or clear() removes them first. Until then they may still be returned by lookups and are counted by getCacheSize() and ramBytesUsed()."

MIGRATE.md, in the #15558 section: "clearQuery, clearCoreCacheKey and the segment close listener no longer remove entries right away: they mark them, and cleanUp() removes them. Either pass CacheCleanUpParameters with a ScheduledThreadPoolExecutor to the 6-argument constructor (and close() the cache when done), or call cleanUp() yourself. The 2- and 4-argument constructors configure no automatic cleanup."

Related nits: the class-javadoc example (LRUQueryCache.java:76-86) builds a cache with no cleanup, and :74 still says IndexSearcher uses a default query cache, although DEFAULT_QUERY_CACHE is null on main. LFV-1000 is another #15558 javadoc gap in the same file and MIGRATE.md section.

/**
 * Marks all cache entries for the given core cache key for removal. Marked entries are removed by
 * the next {@link #cleanUp()}, which runs either on the background schedule configured through
 * {@link CacheCleanUpParameters} or when the caller invokes it, unless LRU eviction or {@link
 * #clear()} removes them first. Until then they may still be returned by lookups and are counted
 * by {@link #getCacheSize()} and {@link #ramBytesUsed()}.
 */
public void clearCoreCacheKey(IndexReader.CacheKey coreKey) {
// clearQuery(Query): the same text, "for the given query"; MIGRATE.md: one paragraph, quoted in this option

Trade-offs

• No code or behaviour change, no risk; the deferral and its performance reasons stay.
• Callers still have to remember cleanUp(); the text only tells them. close() shuts down the executor passed in CacheCleanUpParameters (LRUQueryCache.java:271-275), so a shared executor needs care; the MIGRATE.md note could say so.
• "The next cleanUp()" strictly means the next one that starts after the call: a cleanUp() already running has taken its copy of the pending sets (LRUQueryCache.java:1393-1394).

What the checks validated

• Scratch worktree of 645d4fe14a20, OpenJDK 25.0.3, 2026-11-01, with the final wording (after the fact checks): the patch applies cleanly.
• ./gradlew :lucene:core:checkGoogleJavaFormat :lucene:core:renderJavadoc passes; the rendered javadoc of both methods shows the new text with working links to cleanUp(), clear(), LRUQueryCache.CacheCleanUpParameters, getCacheSize() and ramBytesUsed().
• ./gradlew :lucene:core:test --tests TestLRUQueryCache --tests TestLRUQueryCacheClearThenCleanUpRemovesEntries -Ptests.seed=DEADBEEF: 41 tests, 3 skipped, 0 failures.
• The change is comments and Markdown only: with the patch applied the repro still fails exactly as shown, which is now what the javadoc says; the cleanUp() control passes. MIGRATE.md was not rendered to HTML. An earlier wording without the eviction/clear() clause passed the same checks.

From the hunt: clearQuery removes the query's entries from its one partition under that partition's write lock (routing is by query alone); an explicit clearCoreCacheKey removes the segment's entries from every partition; the segment close listener moves to a private onCoreClosed that keeps the deferred path, so segment close stays cheap. The javadocs then stay true as written.

Trade-offs

• Reverses part of a deliberate #15558 design; the author moved cleanup off the calling thread on purpose.
• clearCoreCacheKey scans every partition on the calling thread (linear in the cache size); clearQuery scans one partition under its write lock.
• clearCoreCacheKey takes the partition locks one at a time, so it is not atomic with concurrent inserts (10.6.0's method held the cache's single write lock); it also replaces the public LRUQueryCachePartition.clearQuery(Query) (LRUQueryCache.java:1250, partitions public through getLruQueryCacheSegments(), :210) with a package-private removeIf. Neither point was stress-tested.
• With this option the minimal test is the regression test.

What the checks validated

• Scratch worktree of 645d4fe14a20, OpenJDK 25.0.3, 2026-11-01: ./gradlew :lucene:core:checkGoogleJavaFormat passes; ./gradlew :lucene:core:test --tests TestLRUQueryCacheClearRemovesEntries --tests TestLRUQueryCacheClearThenCleanUpRemovesEntries --tests TestLRUQueryCache -Ptests.seed=DEADBEEF: the repro passes, the control passes, TestLRUQueryCache 40 tests, 3 skipped, 0 failures.
• Earlier, in the study: the same file shadowed over the main jar passed the repro and upstream TestLRUQueryCache (37 of 37 then), and flipped the model-based test to conform to the method javadocs.
• Not benchmarked; concurrency of the new removal path was not stress-tested.

• Lead. A code-reading probe on main showed the entry still present and served after clearQuery and clearCoreCacheKey; clear() was the control.
• Intended or not. The hunt unit read #15558's body and comments and the class javadoc and concluded that the deferral is intended, so this is a documentation defect, not a code bug.
• Model-based test. It drove the real jar through every sequence of up to 6 operations (search q0/q1, clearQuery q0/q1, clearCoreCacheKey s0/s1, clear, cleanUp) on a 2-segment reader and compared it with two reference models, SYNC (the method javadocs and 10.x) and DEFERRED (the class javadoc). Main: 299,592 sequences, 165,496 diverge from SYNC (the first is [search q0, clearQuery q0]) and 0 from DEFERRED. 10.5.2 and 10.6.0: 137,256 sequences each, 0 diverge from SYNC. A result oracle (cached documents equal uncached documents) found 0 mismatches in all three.
• Reduction. The finding was reduced to a one-test public-API JUnit, then made portable to 10.x.