perf(gc): negative-cache the page classes the map does not hold — reach is 52.8-62.1% of remaining misses, not #9852's 90.7%

[proggeramlug]

DRAFT, and deliberately unpriced. The counter that decides this change is
in hand and is in the body; the rig A/B is not, and the honest ceiling says a
rig A/B may never resolve it (see "What this is worth"). It is opened so the
measurement and the correction to #9852 are not lost, not because it is ready
to land. Take it out of draft only after a quiet-host pair.

Stacked on #9853 (perf/page-class-table), which itself carries #9827
(fork-only base), so GitHub shows several commits. The change under review
here is the last commit only, a52922346 — arena/page_meta.rs plus a
changelog fragment.

The counter came first, and it corrects the issue this closes

#9852 says the "unregistered" miss population is 90.7 % of every remaining
miss after #9853's table, and that all of it is negative-cacheable. The first
half is close; the second is wrong, and nothing had measured it, because
pages.get(&key).and_then(|slot| slot.find(addr)) collapses two cases into one
None:

• pages.get(&key) is itself None — no registered range covers this 1 MiB
  class. Sound to remember at class granularity.
• the class exists, but no range in it contains addr — remembering the
  class as absent would answer wrongly for the addresses it really covers.

So this change adds the two counters that split them before it adds the
cache. Measured on the compiled claude-code TUI, table arm, three 3300-char
runs and two at 400. neg_absent + neg_present == miss_unregistered exactly in
all five, and registered + unregistered == misses exactly, so the split is
complete by construction:

run	remaining misses	absent (cacheable)	present (not cacheable)	registered (first touch)
3300 r1	26,387,799	52.78 %	27.37 %	19.85 %
3300 r2	28,145,127	55.59 %	16.25 %	28.15 %
3300 r3	24,434,760	62.12 %	21.41 %	16.47 %
400 r1	8,302,678	41.51 %	28.71 %	29.78 %
400 r2	7,892,866	66.17 %	15.94 %	17.89 %

Reach is 52.8–62.1 % of remaining misses at 3300 and 41.5–66.2 % at 400 — not
90.7 %. Of the population #9852 counted as one thing, only 65.9–80.6 % is
a class the map does not hold; the other 19–34 % is the unsound case. The
share is quoted as a range, not a point, because it varies that much between
runs of one binary — two runs before a number is quoted, three before a target
is built on it.

Why the unsound case is common rather than a corner: a registered block is
BLOCK_SIZE = 1 << GENERATION_CLASS_SHIFT, so one block is one class only
when its base is class-aligned. A block at an unaligned base covers the tail
of one class and the head of the next, and every address in the uncovered
halves lands here.

What the change is

A negative is an ordinary table entry carrying the current epoch, with the
sentinel range base = usize::MAX, end = 0. contains() is false for every
address, so:

• the hit arm is byte-for-byte what it was — the marker test is reached only
  after contains() has already failed, i.e. on the miss path, never on a hit;
• lookup becomes a tri-state, and KnownAbsent returns exactly what the
  fall-through would have returned (HeapGeneration::Unknown for the generation
  classifier, None for classify_heap_space_in_range) without asking the map.

Invalidation needs no new rule — and that is the whole correctness argument

All three PageGenerationMap mutation sites already end with
invalidate_generation_cache(), which bumps the epoch and makes every entry —
positive and negative alike — stale at once. A registration into this class is
precisely the event that would make a negative wrong, and precisely the event
that kills it. A stale negative is the worst answer this structure can give:
the collector is told "not a GC page" about a live young object and declines to
trace it. The equivalence above is what makes that unreachable, and
a_negative_entry_is_killed_by_a_later_registration_in_that_class is the
standing guard.

Two further preconditions, each a way this could be wrong rather than merely
slow:

• the table arm only — the 4-way set has no negative concept and its
  lookup does not test for one;
• never the insert that allocates the table — the base is derived from the
  first key stored, and only a registered key is guaranteed to sit inside the
  arena's eventual span. An unregistered candidate address can be anywhere.

PERRY_GC_PAGE_CLASS_NEGATIVE=0 restores the previous behaviour in the same
binary, mirroring PERRY_GC_PAGE_CLASS_TABLE, so an A/B has no build
difference to confound it.

Tests, with the sabotage named at each

cargo test --release -p perry-runtime --lib -- gc:: arena:: --test-threads=1
— 1,142 passed, 0 failed, all eight page-class tests included.

test	sabotage that makes it fail
a_class_with_no_registered_range_is_answered_from_the_negative_entry	drop the insert_negative call — the second classification misses again
a_partially_registered_class_is_never_remembered_as_absent	call insert_negative unconditionally instead of under class_absent
a_negative_entry_is_killed_by_a_later_registration_in_that_class	stamp a constant epoch instead of self.epoch
a_negative_never_fixes_the_tables_base	drop the table.is_empty() guard in insert_negative

The first asserts on the neg_hits counter, not on the returned value: the
value is Unknown whether or not the negative was consulted, so a test that
checked only the answer would pass with the whole feature deleted.

What this is worth, stated before anyone measures it

Small, and this PR does not promise a rig delta. After #9853 the two pure-miss
leaf symbols are 0.59 % of active main-thread samples, so removing ~53–62 %
of what is left bounds the win at roughly 0.3 % of the turn — under this
campaign's measured n=1 noise floor. The ground this stands on is work
permanently removed — ~13.9 M failing hash lookups per 3300-char reply — proved
by a counter, not by a stopwatch. Anyone reading a flat rig table here is
reading the expected outcome.

Counters are load-independent, so the table above is quotable; no CPU or memory
number is claimed at all.

Closes #9852 as measured, with its 90.7 % headline corrected to 52.8–62.1 %.

https://claude.ai/code/session_014knX724SYDogwzsXybCGxp

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[jdalton]

Review of a529223465ef8c0db72219ee91e1e14c6f8570f2 (2026-09-07).

The negative cache correctly distinguishes a wholly absent class from an address gap inside a registered class. Please retain a regression that first caches absence, then registers a range in that same class and immediately classifies it, plus unregister/re-register and multiple-range gap cases. The independent PERRY_GC_PAGE_CLASS_NEGATIVE=0 switch also needs an exercised OFF arm per CLAUDE.md's GC-knob policy, rather than only a manual campaign comparison. Separately, the declaration-count TLS ratchet is a useful correction; please keep that self-test when rebasing the page-meta split onto current main.

Validation scope: source/diff inspection; I have not run this PR's build or test suite locally.