PointInSetIncludingScoreQuery.ramBytesUsed() leaves out its per-value score list, so scoring numeric joins under-report their heap

JoinUtil.createJoinQuery(fromField, multipleValuesPerDocument, toField, numericType, fromQuery, fromSearcher, scoreMode) with ScoreMode Max, Min, Avg or Total returns a package-private PointInSetIncludingScoreQuery. It keeps the join values as packed points and one float score per value in aggregatedJoinScores, as JoinUtil's javadoc says ("a float value per unique join value is kept in memory"). Its ramBytesUsed() adds the base object, the field name, the from query and the packed points, but not the score list.

With 5,000 join values it reports 16,504 bytes, only 976 more than the ScoreMode.None join of the same values (15,528), while it holds 37,224; the missing list alone is 21,368 bytes. LRUQueryCache charges this number for the query object of each cached join, so a cache holding such joins as filters holds more heap than its budget: from 9.11.0 on at most about 2.5 times, on 8.11.0 to 9.10.0 about 6 times. The string-key twin TermsIncludingScoreQuery counts its scores; both sums were written in the same commit (LUCENE-8855, first released in 8.2.0). The fix is one more term in the sum.

1. Which class you get. The numeric overload (JoinUtil.java:142-150) returns new PointInSetIncludingScoreQuery(...) when scoreMode != ScoreMode.None (:155, :405-413), else a PointInSetQuery (:414-420).
2. What it keeps. The constructor appends each value to a PrefixCodedTerms.Builder and its score to a new FloatArrayList (PointInSetIncludingScoreQuery.java:107-137; :134 the value, :135 the score). Both are final fields (:76, :81). Every search reads the list again (MergePointVisitor, :259), so it lives as long as the query, also while the query is a cache key.
3. What it reports. The constructor then caches BASE_RAM_BYTES + sizeOfObject(field) + sizeOfObject(originalQuery, QUERY_DEFAULT_RAM_BYTES_USED) + sizeOfObject(sortedPackedPoints) (:141-146), which ramBytesUsed() returns (:380-383). aggregatedJoinScores is not in the sum.
4. Counting it would be O(1). FloatArrayList is Accountable (FloatArrayList.java:37, ramBytesUsed() at :388-390), and RamUsageEstimator.sizeOfObject returns ramBytesUsed() for any Accountable (RamUsageEstimator.java:413).
5. Who consumes the number. LRUQueryCache charges each distinct cached query RamUsageEstimator.sizeOf(query, 32) (LRUQueryCache.java:465-471, :994), which is ramBytesUsed() for an Accountable query (RamUsageEstimator.java:378-381). The weight is always cacheable (PointInSetIncludingScoreQuery.java:235-236), and UsageTrackingQueryCachingPolicy caches the class after 2 uses as a costly point query (UsageTrackingQueryCachingPolicy.java:33-53, :122-124).
6. No score-free path. TermsIncludingScoreQuery switches to a TermsQuery when scores are not needed (TermsIncludingScoreQuery.java:132-139); this class always returns its own weight (PointInSetIncludingScoreQuery.java:156-160), so a scoring numeric join used as a filter stays this object, with its list.

With the fix the score list is counted too: 37,872 reported for 37,224 held (the 1.7% excess comes mostly from the 1,024-byte default estimate for the MatchAllDocsQuery from query, which holds 16 bytes, partly offset by the packed values being counted 312 bytes low).

• Who is hit. Applications using the numeric JoinUtil overload (Integer, Long, Float or Double keys) with a scoring ScoreMode, when they read ramBytesUsed() or run the join where scores are not needed on a searcher with a query cache, often enough to be cached. The default LRUQueryCache(maxSize, maxRamBytesUsed) caches only segments of at least 10,000 documents that also hold more than half the average segment's documents (LRUQueryCache.java:251-253, :277-295). ScoreMode.None joins and string-key joins are counted correctly.
• Default vs opt-in. The wrong number appears for every scoring numeric join. The IndexSearcher default cache is on in the 8.x, 9.x and 10.x lines and charges ramBytesUsed() since 8.11.0 (10.6.0: LRUQueryCache(1000, min(32 MB, max heap / 20))); on main it is off by default (GITHUB#14187, IndexSearcher.java:82-84), so there it needs an application-installed cache. JoinUtil is @lucene.experimental.
• Scale. For large lists about 4 to 4.5 omitted bytes per join value (a float plus up to 1/8 growth slack; 21,368 bytes for 5,000 values, 4.27 per value). The under-count depends on how compactly the keys prefix-code: 2.26x for 5,000 sequential Integer keys, 2.43x for 20,000, 1.89x for 20,000 random Integer keys, 1.49x for 20,000 random Long keys. In 8.2.0 to 9.10.0 the list held boxed Floats and the gap was larger (5.8x for the 5,000-value join on 9.10.0).
• Fixed bound, from 9.11.0 on. For large lists each join value adds at least 3 counted bytes to the packed points and at most about 4.5 omitted bytes to the score list, so the omission alone lets a query hold at most about 2.5 times what it reports (the from query's own estimate is a separate matter), and a cache full of such keys hold at most about 2.5 times its budget in them, however many queries pass through it. The hunt's probe measured 2.29x the budget at worst on main and 2.39x on 10.5.2; the ScoreMode.None control held 1.01x what it was charged (at most 0.99x the budget).
• Larger before 9.11.0. In 8.11.0 to 9.10.0 the list held boxed Floats and the cache already charged ramBytesUsed(): on 8.11.0 the whole cache reports 64,240 bytes after caching a 20,000-value join that holds 381,712 (5.9x), so a cache full of such joins could hold about 6 times its budget.
• Not affected. Which documents match and how they score: cached and uncached joins return the same hits.

# Lucene main 645d4fe14a20, assertions on (-ea), seed DEADBEEF: 1 test(s) run, 1 failed
    => java.lang.AssertionError: expected:<37224.0> but was:<16504.0>
       org.junit.Assert.fail(Assert.java:89)
       org.junit.Assert.failNotEquals(Assert.java:835)
       org.junit.Assert.assertEquals(Assert.java:555)
       org.junit.Assert.assertEquals(Assert.java:685)
       org.apache.lucene.search.join.TestNumericScoreJoinRamBytesUsed.testRamBytesUsed(TestNumericScoreJoinRamBytesUsed.java:56)

• The contract. Accountable#ramBytesUsed: "Returns an estimate of the JVM heap memory used by this object in bytes" (Accountable.java:35-40). The list is on the heap, created by the constructor, referenced only by the query, and its largest structure (21,368 of 37,224 bytes here; 32-59% in the measured cases).
• The class's own docs say the floats exist. "when the scoreMode isn't set to ScoreMode#None a float value per unique join value is kept in memory for computing scores" (JoinUtil.java:76-79); the numeric overload adds that "memory consumption might be higher" (:121-125).
• The twin, same commit. TermsIncludingScoreQuery sums sizeOfObject(scores) (TermsIncludingScoreQuery.java:81-89). Both sums were added in a76c962ee61f (LUCENE-8855): the string join got its scores, the numeric join did not.
• Precedent. GITHUB#16405, "PointInSetQuery#ramBytesUsed now accounts for the retained lowerPoint and upperPoint bounds arrays" (CHANGES.txt:761-762, Lucene 10.6.0), with a regression test (TestPointQueries.java:2636-2651) next to the 5% RamUsageTester test (:2653-2668).
• Tests and history. No join test mentions ramBytesUsed; the sum has not changed since 2019 except for the LUCENE-9570 reformat (7f8b7ffbcad2); no comment, test, CHANGES or MIGRATE entry says the scores are left out on purpose.

The intended-behaviour verifier built the strongest case: ramBytesUsed() is only an estimate and LUCENE-8855 accepted rough numbers; Accountable is @lucene.internal and JoinUtil @lucene.experimental; the join package tells users to choose ScoreMode.None when they do not need scores; and the open #16113 shows that Lucene has no settled rule for what an Accountable should count.

Why it fails: the LUCENE-8855 tolerance was about JVM layout differences and default sizes for unknown objects, and the same discussion asked to over-estimate rather than under-estimate for caches; here a whole owned structure, the largest one, is missing. Under any ownership rule #16113 proposes, a list the constructor allocates and only the query references belongs to the query. @lucene.experimental allows API changes, not wrong numbers, and the ScoreMode.None advice is about speed and memory, not a precondition. Both reading-only reviews rated the intended argument weak and the intended-behaviour check rejected each argument it tested; the later read-only fact check rated it moderate: enough for low priority and no backport, not enough to make the omission intended.

One fix was built and checked; the other two items are an optional extra and a change that is not a fix.

One file, +2/-1 (the same change as the finder's): add the list as a fifth term of the sum the constructor caches.

    this.ramBytesUsed =
        BASE_RAM_BYTES
            + RamUsageEstimator.sizeOfObject(this.field)
            + RamUsageEstimator.sizeOfObject(
                this.originalQuery, RamUsageEstimator.QUERY_DEFAULT_RAM_BYTES_USED)
            + RamUsageEstimator.sizeOfObject(this.sortedPackedPoints)
            + RamUsageEstimator.sizeOfObject(this.aggregatedJoinScores);

Trade-offs

No correctness downside found; the cache charge for such joins grows to their real size, so a cache evicts them sooner, which is the point. sizeOfObject returns FloatArrayList.ramBytesUsed() once, in the constructor. The estimate includes the list's growth slack, which is real heap: 37,872 reported for 37,224 held with 5,000 values (1.7% over, within the 5% margin of upstream's RamUsageTester tests); 149,400 for 149,456 with 20,000 values.

What the checks validated

In a scratch worktree of 645d4fe14a20 with the test added and this change applied (seed DEADBEEF): the test passes with assertions on and off (stock: fails both); TestJoinUtil passes (16 tests); the whole :lucene:join:test passes with assertions on (17 classes, 105 tests, 0 failures, 3 skipped), where the same run without the fix has 1 failure, the test; :lucene:join:checkGoogleJavaFormat passes. The standalone runner with the fixed class passes with -ea and -da.

Call aggregatedJoinScores.trimToSize() (FloatArrayList.java:303) after the constructor's loop, so the query keeps exactly 4 bytes per value.

Trade-offs

Saves the growth slack: 332 of the 5,332 slots with 5,000 values, up to about 1/8 of the size for large lists and proportionally more for lists of a few values, where ArrayUtil.oversize adds at least 3 slots. Not needed for correct accounting. Not run.

A needsScores() == false path like TermsIncludingScoreQuery's (TermsIncludingScoreQuery.java:132-139) would return another query's weight when scores are not needed. The cache keys on the returned weight's query (IndexSearcher.java:976-982, LRUQueryCache.java:834-841), so this would likely keep this class and its list out of the cache.

Trade-offs

ramBytesUsed() would stay wrong for every caller that reads it: a possible separate change, not a substitute for the fix. Not run.

Method: semi-formal (the hunt's tier for a systematic differential harness, short of model checking or proof).

• Differential. The harness built 26 public-API constructions of Accountable queries (12 query classes) from core, join and spatial3d and compared each ramBytesUsed() with the RamUsageTester walk, before and after a search through an always-caching LRUQueryCache, with a known AutomatonQuery under-count (LFV-192) as positive control. 11 constructions were flagged more than 2x under; one was "JoinUtil numeric ScoreMode.Max" (61,560 vs 149,440, 2.4x) while "JoinUtil numeric ScoreMode.None" was 1.0x.
• Trace. Reading PointInSetIncludingScoreQuery's constructor showed the score list missing from the sum, next to the twin TermsIncludingScoreQuery that counts its scores.
• Confirmation. A JUnit on the stock jars (100,000 values) failed on main with assertions on and off, on 10.5.2 and on 9.12.3; the one-term fix made it pass. Independent verifiers then reproduced it with their own tests, and a 2026-10-29 minimisation cut it to 5,000 values.