docs: one engine plan — fold in the representation-selection campaign

[proggeramlug]

There were five documents and issues describing parts of the same effort, plus a 55 KB working plan that existed only as an uncommitted file on one machine. If that laptop died, the campaign's reasoning died with it. This makes docs/engine-plan.md the single entry point; detail stays in the linked RFCs.

What got folded in

The representation-selection campaign's durable results, which were nowhere in the repo:

• The framing: Perry does not NaN-box eagerly by choice — it is the fallback, and the proofs that would let us stop almost never succeed. The fix is in the proofs, not the value representation.
• Step 0: −19.4% is the defensible per-site win; coverage, not sharpening, is the binding constraint.
• The null result (repsel: the coverage work converted exactly as predicted, and almost none of it is faster (one −4.1% win, one +14.9% regression) #7128): coverage work measured net ~0%, and the only real win was canonical Str at −4.12% from deleting two opaque runtime calls per iteration.
• The scoreboard change: count opaque js_* calls removed from hot paths, never promotion counts — the metric that would have predicted that null in advance.
• The three ways a promotion goes unconsumed, and why object hashes and counters both lie.

Why now

2026-08-03's measurements confirm the framing precisely. The three worst benchmarks lose on a missing proof, not a missing representation:

benchmark	perry	node	with lever
matrix_multiply	631 ms	32 ms	59 ms — 10.7×
prime_sieve	107 ms	5 ms	27 ms — 4.0×

And the proof that is missing is not "is this an i32" — (i*size+k)|0 produces genuine i32 and buys nothing, because |0 has min < 0. What is missing is non-negativity plus an upper bound (#7286).

The plan also records #7287, which contradicts our own scoreboard: method_calls has zero js_* calls in its hot loop and is 7.9× behind — it is guard-bound. A metric we adopted for good reasons is necessary but not sufficient, and it is better to write that down than to keep scoring a win on that workload class.

Structure

engine-plan.md carries sequencing and rationale. Detail lives in
src/internals/rfc-rooting-by-construction.md (three rooting layers + the in-process-LLVM enabler, #7292) and src/internals/gc-rooting-invariant.md (the invariant and the checker's three blind spots, #7289).

Docs only. The 55 KB local file is superseded and can be deleted.

Summary by CodeRabbit

• Documentation
  • Added a single, consolidated engine plan covering garbage-collection correctness, performance findings, prerequisites, active work tracks, and implementation sequencing.
  • Documented benchmark measurements, proof and heap-access gaps, instrumentation needs, build non-determinism, and planned optimization areas.
  • Added a changelog entry describing the consolidated engine-plan documentation and its key findings.

[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: c401df23-2561-4da0-acfb-b0c0381de75d

📥 Commits

Reviewing files that changed from the base of the PR and between b2ef415 and cb7d6e6.

📒 Files selected for processing (2)

• changelog.d/7293-one-engine-plan.md
• docs/engine-plan.md

---

📝 Walkthrough

Walkthrough

Added a consolidated engine plan and changelog entry. The plan covers GC rooting, statepoints, LLVM requirements, RSS measurements, benchmark findings, representation analysis, active work tracks, and implementation sequencing.

Changes

Engine planning documentation

Layer / File(s)	Summary
GC correctness plan docs/engine-plan.md	Documents GC rooting failure modes, statepoints, LLVM requirements, measured costs, RSS findings, and replacement planning documents.
Performance measurements and findings docs/engine-plan.md	Documents benchmark methods, representation coverage, promotion-consumption cases, heap access, range proofs, guarded calls, and build variability.
Active tracks and sequencing docs/engine-plan.md, changelog.d/7293-one-engine-plan.md	Documents active proof and dependency-analysis tracks, implementation sequencing, excluded interim work, and the consolidated plan entry.

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

Possibly related PRs

• PerryTS/perry#7216: Implements GC-rooting fixes covered by the documented GC correctness effort.
• PerryTS/perry#7292: Documents the same GC correctness roadmap, including rooting layers and statepoints.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/7293-one-engine-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.}