docs/test(gc): establish a current collector source of truth and remove deleted knobs from live gates

[proggeramlug]

Summary

The GC documentation no longer has a reliable current entry point, and a deleted collector knob remains in an executable CI stress script. After ~200 GC-heavy commits in four days, several documents present mutually exclusive states as current.

Concrete drift on main (79d2f59ed, v0.5.1473):

• docs/generational-gc-plan.md opens with “proposed, pre-implementation” but ends with all implementation phases complete. It still specifies nonexistent PERRY_NURSERY_MB and repeatedly uses deleted PERRY_GEN_GC_EVACUATE.
• docs/statepoint-gc-experiment.md opens with “Keep the shadow stack as the default” and later labels shadow as default, while docs/engine-plan.md and gc-rooting-invariant.md say target-aware native statepoints are the shipped default.
• docs/engine-plan.md calls itself authoritative, points at closed tracker Engine plan tracker — GC correctness and performance (routing only; docs/engine-plan.md is authoritative) #7294, and is synced only through v0.5.1350; the repository is now v0.5.1473. It still says the statepoint lowering has no static root-dominance checker even though gc: teach the root-dominance checker to read statepoint relocation bundles #7663 and the current workflow added one.
• CLAUDE.md points at crates/perry-runtime/src/gc.rs; GC is now the src/gc/ module tree.
• docs/src/testing/ci-gate-scheduling.md and scripts/gate_freshness.json say gate freshness runs hourly, while the workflow cron is every two hours.
• Most importantly, required CI still executes scripts/run_memory_stability_tests.sh, whose mode matrix and architecture workload environment contain PERRY_GEN_GC_EVACUATE=1/0. That knob was deleted in gc: PERRY_GEN_GC_EVACUATE=0 moves zero cells on all 12 gc-ratchet probes — the knob's off-state is unexercised #7611, so those tokens claim a mode distinction that no longer exists.

Evidence

• Contradictory status in the generational plan vs completion status
• Obsolete nursery knob and obsolete evacuation knob
• Statepoint experiment's obsolete top-level decision
• Current rooting doc says native/statepoint is the default
• “Authoritative” engine plan is 123 versions behind
• Deleted knob remains in live memory-stability modes and in the executable matrix

Proposed structure

Create one short, current GC architecture/operations page covering:

• shipped collector modes and actual env knobs;
• nursery/old-gen regions, copying vs fallback/full paths;
• root mechanism by target, barriers, weak processing, memory pressure, block pooling, and old-defrag status;
• the authoritative validation commands/workflows and which are required contexts;
• links to historical experiment journals clearly marked as historical/chronological evidence.

Do not rewrite valuable experiment history. Put a prominent dated supersession banner and a current conclusion at the top, then link to the current page.

Acceptance criteria

• A reader can identify the shipped GC/rooting defaults and supported knobs from one current page without reconciling chronological journals.
• Historical plans/experiments are labeled historical and no longer make an obsolete opening decision look current.
• Remove PERRY_GEN_GC_EVACUATE from executable test environments, source docs, and generated translation source; replace each test arm with the actual knob/subject it intends to exercise.
• Add a cheap stale-knob check: executable scripts/docs claiming GC env knobs must match an allowlisted runtime/codegen parser (with explicit historical-doc exemptions).
• Correct the GC source path and freshness cadence.
• Update or retire the “authoritative” claim/tracker in engine-plan.md.

[proggeramlug]

?Reopening after the v0.5.1473?v0.5.1481 re-audit: the new ?current source of truth? drifted in the same landing train that created it.

Current false/stale statements:

• docs/src/internals/garbage-collector.md says full/fallback weak processing still walks the whole arena atomically and cites perf(gc): full/fallback weak processing is an unsliced O(total heap) atomic pause #7874. perf(gc): slice full weak processing by holder #7892 replaced that with registry-scoped, holder-sliced processing and closed perf(gc): full/fallback weak processing is an unsliced O(total heap) atomic pause #7874.
• The same page says the block pool is a 64 MiB per-thread allowance that critical pressure and device budgets do not drain/resize, citing memory(gc): critical pressure and device budgets do not drain or bound the per-thread 64 MiB block pool #7875. fix(gc): bound and drain recycled block pool #7889 made the cap process-wide and budget-scaled and added sticky critical-pressure drains, then closed memory(gc): critical pressure and device budgets do not drain or bound the per-thread 64 MiB block pool #7875.
• docs/src/internals/memory-model.md still presents a fixed PROMOTION_AGE = 2 and describes tenured objects as initially remaining physically in nursery pending telemetry-driven evacuation. Current copying GC has an adaptive 1?4 survival threshold (gc/tenuring.rs), promote-on-first-copy locking, direct survivor promotion to old-gen, and whole-block in-place promotion including the optional untraced path.
• The current page does not document perf: shapes 0.139 -> 0.061 s (beats node) and pipeline 0.240 -> 0.175 s — a 2000-element array was born immortal, and this.vals[i]=v had no inline arm #7895's type-dependent born-old thresholds (16 KiB pointer-free vs 128 KiB pointer-bearing), even though that materially changes nursery/old-gen behavior and memory retention.
• The ratchet README still says js_arena_stats sums block offsets and labels that limitation ?UNCHANGED?; fix(gc): report live arena bytes after collection (#7879) #7886 routes it through the live census. That text now misdirects ratchet triage.

The new check_gc_env_knobs.py gate is working and all its self/live checks pass on Windows. The remaining gap is architectural claim drift: later GC PRs can update code and close the cited issue without being required to update the current page/ratchet semantics.

Suggested acceptance addition: add a PR checklist or cheap source-marker test for collector changes that touch weakref.rs, pool policy, tenuring/promotion, or heap accounting, and require the current GC page plus ratchet metric definitions to be reviewed in the same PR. At minimum, remove issue-status prose that silently becomes false when the issue closes.

One more concrete drift item: memory-model.md's entire Source map still points to the deleted monolithic crates/perry-runtime/src/gc.rs (including obsolete line numbers). The implementation is now src/gc/mod.rs plus the split module tree, so none of those source links identifies a real file on current main.