LateInteractionFloatValuesSource always reports itself cacheable, so after an in-place update a cached filter on a late-interaction score keeps its old matches

LateInteractionFloatValuesSource scores documents by reading their multi-vectors from binary doc values (LateInteractionField is a BinaryDocValuesField), but its isCacheable always returns true. SegmentCacheable says doc-values-based objects should return DocValues#isCacheable, which turns false once the field is updated in place, because the query cache keys entries on the segment core and a doc-values update keeps that core. So when the source is used in a cached, non-scoring filter (FunctionMatchQuery, or the facet module's DoubleRange#getQuery) and a document's multi-vector is replaced with updateBinaryDocValue or updateDocValues, the reopened searcher keeps serving the match set computed from the old multi-vector: 5 hits instead of 4 in a 20-document repro. On 10.3.0 to 10.6.0 (10.6.0 by reading) the default IndexSearcher cache is enough; main needs an installed cache. Re-ranking with LateInteractionRescorer or RescoreTopNQuery, the documented use, is not affected. The fix changes one line (plus an import): return DocValues.isCacheable(ctx, fieldName);.

• Late-interaction multi-vector: LateInteractionField (10.3.0) stores a document's token vectors as one binary doc value; it extends BinaryDocValuesField. LateInteractionFloatValuesSource scores a document against a query multi-vector (default: COSINE similarity, SUM_MAX_SIM), and is a DoubleValuesSource, so any query that takes a values source can use it.
• Query cache: LRUQueryCache stores the matching doc ids of a non-scoring query per segment, keyed by the query and the segment's core cache key. That key deliberately ignores deletions and doc-values updates.
• SegmentCacheable: every cacheable weight or values source says whether its result may be cached for a segment. Objects that read doc values should answer DocValues.isCacheable(ctx, field), which turns false once the field has been updated in place, so the cache evaluates them fresh.

1. getValues reads the multi-vectors with ctx.reader().getBinaryDocValues(fieldName) (LateInteractionFloatValuesSource.java:84 on main a9779ef3c193).
2. isCacheable returns true unconditionally (:145-148).
3. FunctionMatchQuery (FunctionMatchQuery.java:111-114) and the facet module's DoubleRange#getQuery (the weight of the ValueSourceQuery it builds, DoubleRange.java:209-211; a fromSingleValued multi-valued source is unwrapped into the same query, :351-357) pass that answer on as their Weight#isCacheable.
4. LRUQueryCache trusts it (LRUQueryCache.java:816, and :903 in count) and looks the entry up by query plus getCoreCacheHelper() (:827-834, :914-924). The core key is the same after updateBinaryDocValue or updateDocValues (LeafReader.java:66-70: readers with "different sets of deleted documents or doc values updates may be considered equal").
5. So the entry filled before the update is found and served. DocValues.isCacheable would have said false (fi.getDocValuesGen() > -1, DocValues.java:339-346), as it does for DoubleValuesSource.fromLongField and fromDoubleField (DoubleValuesSource.java:609-611).

20 documents in one segment; docs 0-4 hold {{1, 0}} (score 1.0 against the query {{1, 0}}), docs 5-19 hold {{0, 1}} (score 0.5); filter score > 0.75. Before the update: 5 hits, cached. After updateBinaryDocValue of doc 0 to {{0, 1}} and openIfChanged: uncached 4, cached 5; isCacheable on the updated segment is true while DocValues.isCacheable(ctx, "mv") is false. The same sequence with a fromLongField filter and updateNumericDocValue gives 4. A probe confirms the stale answer goes both ways and only for updated documents: doc 0 (updated out of the filter) is still returned, doc 7 (updated into it) is missing.

• Who. Users of LateInteractionFloatValuesSource (10.3.0+, @lucene.experimental) in a non-scoring, cacheable query, that is a filter or a range-facet drill-down on the late-interaction score, who also replace LateInteractionField multi-vectors in place (for example when re-embedding documents) and keep a query cache across NRT reopens.
• Default vs opt-in. On 10.3.0 to 10.5.2 a plain new IndexSearcher(reader) shares the default LRUQueryCache with UsageTrackingQueryCachingPolicy, whose policy caches a query like this one after 5 uses, on a segment of at least 10,000 documents that holds more than half of the index's average documents per segment: zero configuration is enough (executed on 10.3.0 and 10.5.2). Main has had no default query cache since GITHUB#14187 (11.0.0, unreleased), so it is hit only with an installed cache (executed). branch_10_6 still installs the default cache.
• Query reuse. The stale entry is found only by an equal query. DoubleRange#getQuery compares by value, so it goes stale even when rebuilt for every request (executed). FunctionMatchQuery compares its predicate object, so it needs the same query object or a predicate that compares equal. Equality covers the whole source (field name, similarity, score function and the query multi-vector, LateInteractionFloatValuesSource.java:121-130) and, for DoubleRange, the range and the fast-match query.
• Not affected. Re-ranking (LateInteractionRescorer, RescoreTopNQuery) reads the values per hit and never puts the source in the query cache; scoring searches are not cached either.
• Effect and reach. Silent wrong results for the updated documents only, in both directions; deletes after the update are still applied, the tested restriction clause (an exact query on another updated doc-values field) is evaluated fresh, and a query not equal to any entry cached before the update is computed from the current values (until the field's next in-place update). Nothing is written to disk. The stale answer lasts until the entry is evicted, the cache is cleared or the segment core goes away (closed after a merge, or a reader opened afresh from the directory); a later deletion does not end it (executed). Deterministic at every size tried: 6 to 20 documents with an explicit cache, 12,000 with the default one.
• How likely. Rare: the source is documented for re-ranking, and filtering on a late-interaction threshold plus in-place multi-vector updates is an unusual combination.

# Lucene main 645d4fe14a20, assertions on (-ea), seed DEADBEEF: 1 test(s) run, 1 failed
    => java.lang.AssertionError: expected:<false> but was:<true>
       org.junit.Assert.fail(Assert.java:89)
       org.junit.Assert.failNotEquals(Assert.java:835)
       org.junit.Assert.assertEquals(Assert.java:120)
       org.junit.Assert.assertEquals(Assert.java:146)
       org.apache.lucene.search.TestLateInteractionValuesSourceCacheable.testNotCacheableAfterDocValuesUpdate(TestLateInteractionValuesSourceCacheable.java:46)

• The contract. SegmentCacheable.java:27-32: "Objects that depend only on segment-immutable structures such as Points or postings lists can just return true ... Objects that depend on doc values should return DocValues#isCacheable(LeafReaderContext, String...), which will check to see if the doc values fields have been updated. Updated doc values fields are not suitable for caching." DoubleValuesSource implements SegmentCacheable (DoubleValuesSource.java:48).
• Siblings follow it. DoubleValuesSource's field sources (:609-611) and LongValuesSource (:269-271) return DocValues.isCacheable. In a bytecode scan of all 123 classes that declare isCacheable, this is the only SegmentCacheable that returns a constant true while reading doc values; the other constant-true implementations read only segment-immutable data (postings, points or vectors) or nothing from the index at all (for example the constant sources).
• Tests. TestLRUQueryCache#testDocValuesUpdatesDontBreakCache ("second segment no longer cached due to DV update") and TestSegmentCacheables#testMultipleDocValuesDelegates ("after field3 is updated, all composites referring to it should be uncacheable") assert the contract for other classes. The late-interaction tests never update the field and never call isCacheable.
• History. The line has not changed since #14729 (d9618080b340). No comment or review in the PR discusses whether the new source is cacheable or what a doc-values update does to it; caching comes up once, when the PR author compares FunctionScoreQuery with a Rescorer ("I believe we only cache hits (disi) and not scores"), which is about choosing a re-ranking API. The constant matches VectorSimilarityValuesSource#isCacheable (VectorSimilarityValuesSource.java:67-70), which is right there because vector values cannot be updated in place.
• Precedent. LUCENE-8017 (#9065, "FunctionRangeQuery and FunctionMatchQuery can pollute the QueryCache") and LUCENE-8042 (#9090), 2017, created this contract for function queries over doc values.
• Legal trigger. IndexWriter#updateBinaryDocValue: "You can only update fields that were indexed only with doc values" (IndexWriter.java:1982-1984), which a LateInteractionField is. No javadoc, CHANGES or MIGRATE entry restricts the source to re-ranking or forbids in-place updates.

The intended-behaviour verifier and a works-as-designed review by a model from another family built the strongest case: the class javadoc calls the source "useful re-ranking query results using late interaction models", it is @lucene.experimental, its own re-ranking paths never consult isCacheable, and main has no default query cache, so a cached filter over it is off-label.

Why it fails: "useful for" is not "only for". The class is a public DoubleValuesSource, and true is a positive claim that its values never change for a segment core, which is false for a doc-values field; if caching was not meant, false would be the safe answer. @lucene.experimental is about API stability, not correctness, and the missing default cache on main only lowers exposure (10.3.0 to 10.5.2 cache by default, and MIGRATE.md shows main users how to turn caching back on). No reviewer or verifier rated the intended argument better than weak.

One fix was applied in a scratch worktree at a9779ef3c193 and run through gradle (seed DEADBEEF); the other options were not run.

In LateInteractionFloatValuesSource, replace return true; with return DocValues.isCacheable(ctx, fieldName); and import org.apache.lucene.index.DocValues (+2/-1). This is the recipe SegmentCacheable gives for doc-values-based objects and what fromLongField and fromDoubleField do. A second diff adds the repro as a regression test in lucene/queries.

@Override
public boolean isCacheable(LeafReaderContext ctx) {
  return DocValues.isCacheable(ctx, fieldName);
}

Trade-offs

• A segment stays cacheable until its multi-vector field gets its first in-place update, then is evaluated fresh until it is merged away: the same trade-off every doc-values source already makes.
• No change for the re-ranking paths, which never consult isCacheable.
• A core-only unit test could also assert isCacheable after updateBinaryDocValue next to the existing late-interaction tests.

What the checks validated

• Stock main a9779ef3c193: the repro fails 2 of 3 with assertions on and off (expected:<4> but was:<5>; isCacheable true); the control passes. The facet range variant fails 1 of 2.
• With the fix: the repro passes 3 of 3 with assertions on and with assertions off; the facet range variant passes 2 of 2.
• With the fix, the closest suites pass: in core TestLateInteractionFloatValuesSource, TestLateInteractionRescorer, TestLateInteractionField, TestRescoreTopNQuery*, TestLRUQueryCache, TestSegmentCacheables and TestDoubleValuesSource; all of org.apache.lucene.queries.function; all of org.apache.lucene.facet.range: 27 classes, 220 tests, 5 skipped, 0 failures.
• ecjLint and checkGoogleJavaFormat pass for core and queries (the queries run includes the repro test); both diffs apply cleanly to a clean a9779ef3c193 tree.
• Earlier, with the fix shadowed in: the finder's, the independent reproducer's and the devil's advocate's tests pass, and the stale-set tests of the reach probe fail as expected.
• Not run: the full lucene/core, queries and facet suites; no benchmark (the change only removes cache hits on segments whose multi-vector field was updated in place).

Never cache filters over this source.

Trade-offs

Always correct and simplest, but broader than necessary: it also stops caching for segments whose field was never updated (the performance effect was not measured), and it departs from the contract's recipe for doc-values sources.

State that the source must not be used in cached filters when the field is updated in place.

Trade-offs

No code change, but the silent stale results stay for anyone who misses the sentence, and true remains a false claim.

A test that updates the field of every doc-values-based DoubleValuesSource and asserts isCacheable turns false. The hunt found two other SegmentCacheable violations with separate one-site fixes (the shape doc-values queries, and DoubleRange/LongRange#getQuery ignoring the fast-match query's cacheability).

Trade-offs

More work; each violation still needs its own fix.

Method: a static scan plus differential testing on the real jars (semi-formal tier), in a hunt unit on query-cache correctness.

• A ClassFile-API scan of every class in the module jars that declares isCacheable (123 classes) classified each implementation (for example a constant true, or a DocValues.isCacheable check) and listed the doc-values reads in its class family. LateInteractionFloatValuesSource was the only constant true next to a LeafReader.getBinaryDocValues read.
• A differential sweep ran 35 doc-values query cases on main's jars: each query cached, the field updated in place with the same segment core, then cached versus uncached. It returned STALE for FunctionMatchQuery and DoubleRange#getQuery over this source (32 cached versus 31 uncached).
• A TLA+ model of the LRUQueryCache path, written right after, violates its SearchCorrect invariant with a 5-state counterexample when isCacheable is a constant true, and holds for the correct shapes.
• Found 2026-10-26 on main ea57360912ed; then checked by an independent reproducer, an intended-behaviour devil's advocate, reading-only reviews by a model from another family (OpenAI GPT-5.6) and an adjudication.