docs(gc): one GC correctness plan — three layers, and the enabler they depend on

[proggeramlug]

We have five documents and issues that each describe part of the same defect, and no single place that says how they relate. This makes rfc-rooting-by-construction.md that place, rather than adding a sixth.

The motivating evidence

40 GC/rooting commits landed in three days, and the blocking bug (#7280) still measures red 0/30. Every one of those fixes was correct. None ended the class. That is what fixing instances instead of the shape looks like.

What the plan says

The shape, stated once: a GC-managed pointer exists somewhere the collector does not know about, across a point where the collector can run.

"Somewhere it does not know about" has had three homes, needing three different mechanisms — and conflating them is why this felt endless:

layer	home	example bugs	mechanism
1	perry-codegen's lowering code	#7192, #7206, #7211	this RFC (Raw/Rooted)
2	emitted machine code's liveness	#7280, #7271, #7252, #7243	statepoints (#7108/#7174)
3	perry-runtime's hand-written Rust	#7249, #7239, #7226, #7231	RuntimeHandleScope, non-optional

Layer 0 is the enabler. #7108 measured statepoints viable but concluded "the text-IR-plus-stock-clang architecture is what rules the cheapest design out" — Perry emits textual .ll to a user-supplied clang, controlling neither the pass pipeline nor stackmap emission. #7241's Phase 0 removes exactly that, and independently verified gc "statepoint-example" constructs, verifies and emits. Dependency order is 0 → 2, with 1 and 3 independent.

The finding worth reading even if you skip the rest

Adopting statepoints deletes three of this RFC's own "cannot catch" entries rather than mitigating them — shadow-frame correctness, side-table-rooted values, and the SlotIdx companion change — because the shadow frame stops existing. Layers 1 and 2 are complements: layer 2 makes emitted code correct by construction, layer 1 makes the compiler's own code hard to write incorrectly.

Costs, recorded so they are decided rather than discovered

• Stack maps: 438,848 B hot text saved for 4.5–16.6 MB cold metadata (10–38×, exceeding the app's whole code section). Cold, so the RSS cost is far below the file-size cost. Safepoint density is a direct lever — but that lever is expected, not measured, and is the first thing layer 2 must prove.
• In-process LLVM: ~171 MB static-linked when enabled, LLVM 22 dev libs, zero cost by default.
• Stack maps vs the codegen shadow stack: viability experiment (Q1 passes; 0.44 MB text saved for 4.5-16.6 MB metadata) #7108's prototype has a known deep-stack-walker gap.

RSS interaction

The −65% (320 MB → 111 MB) comes from the 16 MB nursery cap, not the copying — they merely share a flag. So the memory win has a route that avoids the risky path. Sequenced last deliberately: measuring it while "minors" fall back to a conservative full scan (#7255) would bake that cost in and make it look inherent.

Docs only. No behaviour change.

Summary by CodeRabbit

• Documentation
  • Expanded the rooting-by-construction RFC with the three-layer GC correctness plan and dependencies between its components.
  • Documented how LLVM statepoints address previously uncovered rooting cases.
  • Added details on performance costs, an outstanding deep-stack-walker limitation, and the planned sequencing of RSS optimizations.
  • Added a changelog entry consolidating related garbage-collection correctness improvements.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 56d8efce-2b76-4752-94f5-e512343027b8

📥 Commits

Reviewing files that changed from the base of the PR and between fc9db05 and 8ea4acf.

📒 Files selected for processing (2)

• changelog.d/7290-one-gc-plan.md
• docs/src/internals/rfc-rooting-by-construction.md

---

📝 Walkthrough

Walkthrough

The PR documents a three-layer GC correctness plan covering codegen rooting, LLVM statepoints, and runtime Rust rooting. It also records statepoint effects, measured costs, known limitations, RSS sequencing, and the related changelog entry.

Changes

GC correctness plan

Layer / File(s)	Summary
Three-layer rooting plan docs/src/internals/rfc-rooting-by-construction.md, changelog.d/7290-one-gc-plan.md	The RFC and changelog define the codegen, statepoint, and runtime Rust rooting layers, their dependency order, and related GC correctness work.
Statepoint implications and measurements docs/src/internals/rfc-rooting-by-construction.md	The RFC explains statepoint effects on shadow-frame limitations, records stack-map and in-process LLVM costs, documents a deep-stack-walker gap, and sequences RSS evaluation after collector and measurement work.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related issues

• gc: RewriteStatepointsForGC over managed-pointer SSA — the measured-only road to native-root file-size parity #7174: The RFC discusses LLVM statepoints in relation to the issue’s RewriteStatepointsForGC proposal.

Possibly related PRs

• PerryTS/perry#7212: Extends the same rooting RFC with GC-rooting strategy and statepoint context.
• PerryTS/perry#7226: Implements concrete rooting fixes that this PR documents as part of the broader plan.
• PerryTS/perry#7291: Fixes optional-parameter and runtime-construction rooting defects covered by the documented plan.

Suggested reviewers: jdalton

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/7290-one-gc-plan

---

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