docs(gc): plan status after #7339/#7340/#7342 — the 0→2 spine is done

[proggeramlug]

Routine plan-status update against #7294, plus one substantive re-ordering.

Corrections

• Layer 3 said "not started"; RuntimeHandleScope has 675 uses across 169 files. What is missing is non-optional. Now says so, and carries gc(layer 3): from-space quarantine catches 55 stale dereferences across the gap suite — the instrument is in CI but aimed at one synthetic fixture #7341's 54-item worklist.
• Layer 2 is not just "landed opt-in" — it became reachable (fix(gc): route RS4GC through the in-process LLVM backend #7339, RS4GC on a stock toolchain) and selectable (fix(gc): split the precise-root analysis from its lowering #7340, analysis split from lowering).
• Sequencing said "Next: in-process LLVM → statepoints" about work that has landed.

The one substantive change

Reducing root density moves from a follow-up to a prerequisite for statepoint adoption. Measured on two 2000-function programs:

workload	delta	__text
root-free	+0 B	+12 B
root-dense	+18.95%	+4.20 MB

Statepoints have no fixed cost, and 97% of the growth is code, not metadata. So making them the default today regresses the stated goal of minimal binary size. The plan already named this lever but flagged it "expected, not measured. Layer 2 must prove it first" — layer 2 has now landed, so it is measurable. It is also the same lever #7296 proved worth 9.9× on matmul, so size and speed pull together rather than trading off.

Docs only.

Summary by CodeRabbit

• Documentation
  • Updated the garbage collection implementation plan to reflect completed statepoint work and current optional runtime handle scopes.
  • Clarified sequencing, prerequisites, platform considerations, and deferred memory-usage evaluation.
  • Documented measured binary-size impact associated with root-density reduction.

[coderabbitai]

📝 Walkthrough

Walkthrough

The GC engine plan updates status for statepoints and runtime handle scopes. It also revises sequencing to identify completed work, root-density prerequisites, independent layers, LLVM and x86-64 prerequisites, and deferred RSS evaluation.

Changes

GC roadmap documentation

Layer / File(s)	Summary
GC status and sequencing docs/engine-plan.md	The plan records landed and usable statepoints, an optional runtime handle-scope mechanism with 54 open catches, completed layers 0 and 2, root-density prerequisites, independent layers 1 and 3, platform and LLVM prerequisites, and deferred RSS evaluation.

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

Possibly related issues

• Engine plan tracker — GC correctness and performance (routing only; docs/engine-plan.md is authoritative) #7294 — Both changes update the authoritative GC roadmap and sequencing in docs/engine-plan.md.

Possibly related PRs

• PerryTS/perry#7292 — Both changes document GC correctness planning, statepoints, runtime handle scopes, and in-process LLVM prerequisites.
• PerryTS/perry#7314 — This change documents the statepoint and GC work associated with that PR.
• PerryTS/perry#7339 — This change records statepoint adoption prerequisites related to that PR.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the GC plan-status update and the completed layer 0→2 work.
Description check	✅ Passed	The description explains the changes, related issues, measured rationale, sequencing decision, and documentation-only scope.
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
• Commit unit tests in branch docs/7294-plan-status-after-7339-7342

---

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: 2

🤖 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/engine-plan.md`:
- Around line 345-349: Update the progress note in the documentation to refer to
“Step 1” instead of “Step 2,” matching the completed item currently marked in
the list; leave the surrounding ordering and completion details unchanged.
- Around line 31-32: Update the layer 3 status and the adoption-gate guidance to
use one consistent `RuntimeHandleScope` policy: either require its integration
before making statepoints the default, or explicitly define the safety boundary
that allows adoption while the 54 catches remain open. Ensure the entries around
the statepoints and `RuntimeHandleScope` rows, including the later
`llvm-inprocess` and x86-64 gates, reflect that policy without contradictory
“non-optional” and “still optional” statuses.

🪄 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: 2db963d8-33bb-4ad6-bc95-64f1ee90ed14

📥 Commits

Reviewing files that changed from the base of the PR and between 0632a77 and 832de5d.

📒 Files selected for processing (1)

• docs/engine-plan.md

[coderabbitai]

🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Make RuntimeHandleScope a real adoption gate.

Lines 31-32 use conflicting statuses: the mechanism is “non-optional”, but the status says “still optional”. Lines 362-364 then list only llvm-inprocess and x86-64 as adoption gates, although this document states that statepoints do not cover layer 3 and 54 catches remain.

Require RuntimeHandleScope integration before statepoints become the default, or define the safety boundary that permits adoption while those catches remain open.

Also applies to: 362-364

🤖 Prompt for 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.

In `@docs/engine-plan.md` around lines 31 - 32, Update the layer 3 status and the
adoption-gate guidance to use one consistent `RuntimeHandleScope` policy: either
require its integration before making statepoints the default, or explicitly
define the safety boundary that allows adoption while the 54 catches remain
open. Ensure the entries around the statepoints and `RuntimeHandleScope` rows,
including the later `llvm-inprocess` and x86-64 gates, reflect that policy
without contradictory “non-optional” and “still optional” statuses.

[coderabbitai]

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Fix the stale step reference.

Line 345 says “Step 2 below is complete”, but the current list marks item 1 as complete and item 2 as the root-density prerequisite. Change “Step 2” to “Step 1”, or remove the step number.

🤖 Prompt for 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.

In `@docs/engine-plan.md` around lines 345 - 349, Update the progress note in the
documentation to refer to “Step 1” instead of “Step 2,” matching the completed
item currently marked in the list; leave the surrounding ordering and completion
details unchanged.