docs(gc-rooting): #7211 is fixed, and add the runtime-cache class

[jdalton]

docs/src/internals/gc-rooting-invariant.md teaches contributors the rooting invariant using real bugs as case studies, and it had drifted from reality in two ways that matter.

#7211 is closed, not open. The page carried a section titled "And the one that is still open (#7211)". It was fixed by #7226, and the checker's allowlist is now empty (scripts/gc_root_dominance_allowlist.json reads "entries": [], annotated "EMPTY IS THE GOAL AND IT IS CURRENTLY MET"). The stale section is removed and the hazard-2 paragraph now cites #7226.

The runtime-cache class was missing from the taxonomy. It is added as a named class with its tell — a thread-local or static cell holding a GC pointer that no registered scanner rewrites — citing #7226 (the interned typeof result strings and the rawJSON key) and #7239 (ten runtime caches: CACHED_ENV, CACHED_PERMISSION, CACHED_REPORT, ERROR_CONSTRUCTOR_PTR, INPUT_HANDLER, RESIZE_CALLBACK, FRAME_CALLBACKS, CURRENT_NEW_TARGET, ACCESSOR_RECEIVER_OVERRIDE, PENDING_FETCH_SIGNAL).

This one is worth naming explicitly because it is invisible to the static checker by construction: the checker reads emitted IR, and a runtime-side cache never appears there. It was also the hardest instance of the class to find.

The "rules of thumb" cross-reference was renumbered to match, and CLAUDE.md:253 was checked for consistency (it already describes the runtime cache as a sibling class and points here for the full writeup).

Docs only — one file, 25 insertions, 31 deletions.

Summary by CodeRabbit

• Documentation
  • Updated garbage-collection rooting guidance to cover five failure modes, including runtime-cache hazards.
  • Clarified detection characteristics, checker limitations, and mutable-root scanner registration requirements.
  • Removed outdated ClassExprFresh allowlist guidance following predicate fixes.
  • Added guidance connecting root-before-call practices with emitted field-setting operations.

[coderabbitai]

📝 Walkthrough

Walkthrough

The GC-rooting invariant documentation now describes five failure modes, including unscanned runtime caches. It also updates gate-promotion status and explains the ClassExprFresh root-before-call issue.

Changes

GC-rooting invariant documentation

Layer / File(s)	Summary
Rooting failure modes and validation guidance docs/src/internals/gc-rooting-invariant.md	The guide adds runtime-cache hazards, scanner registration requirements, checker limitations, updated gate-promotion status, and explicit guidance for js_object_set_field_by_name calls.

Estimated code review effort: 1 (Trivial) | ~4 minutes

Possibly related issues

• GC: enumerate the unrooted runtime-side caches — the population no static checker can see #7231 — Covers runtime-side GC caches and mutable-root scanner registration, matching the new documented failure mode.

Possibly related PRs

• PerryTS/perry#7226 — Implements GC-rooting fixes for runtime caches and ClassExprFresh, which this documentation describes.
• PerryTS/perry#7227 — Updates related GC-rooting documentation and runtime-cache scanner guidance.
• PerryTS/perry#7212 — Updates the same GC-rooting invariant documentation.

Suggested reviewers: proggeramlug

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies both primary documentation changes: closing #7211 and adding the runtime-cache class.
Description check	✅ Passed	The description clearly explains the documentation changes, related issues, rationale, examples, scope, and consistency check.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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.}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/src/internals/gc-rooting-invariant.md`:
- Around line 115-119: Revise the next section’s description of
scripts/gc_root_dominance_check.py to state that it detects only emitted-LLVM
rooting hazards, not runtime-table cache issues. Keep PERRY_GC_ZEAL,
PERRY_GC_PROTECT_FROMSPACE, and PERRY_GC_PROTECT_FROMSPACE_DEPTH as the checks
for runtime caches, and preserve the existing guidance to register mutable
roots.
- Around line 98-103: Update the “Runtime-cache class” description to avoid
claiming failure always occurs at collection `#0`. Explain that the pointer
becomes stale at the first moving collection after the cache is populated and
remains stale until code rewrites the cache, while preserving the distinction
from register-class bugs.
- Line 53: Run perry-doc-tests against docs/src and update all 13 untagged
TypeScript code fences in the documentation: mark illustrative fences with the
typescript,no-test tags, or replace them with {%#include ...%} directives where
the content should be sourced from a file.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: ece7df8c-adfc-4980-8643-99ab98cd6f80

📥 Commits

Reviewing files that changed from the base of the PR and between 97c6921 and 1e73fdb.

📒 Files selected for processing (1)

• docs/src/internals/gc-rooting-invariant.md