fix(gc): measure the moving-defer allowance from the deferral point so the copying minor is reachable under a heap budget

[proggeramlug]

Closes #7024. Closes #6993.

The defect

gc_check_trigger's deferral arm — the one that hands an allocation-point nursery trigger to the next precise-root safepoint, and therefore to the copying minor that #7019 made default-on — was guarded by an absolute committed-arena cap:

if gc_moving_loop_polls_enabled()
    && crate::arena::arena_total_bytes() < gc_moving_defer_hard_cap_dyn_bytes()

gc_moving_defer_hard_cap_dyn_bytes() was budget_scaled(128 MB, 1, 4, 2 MB) — byte-for-byte the formula behind gc_trigger_absolute_ceiling_bytes(). And gc_budgeted_due_trigger() reports the arena trigger due exactly when

crate::arena::arena_total_bytes() >= effective_next_arena_trigger()

Under any heap budget small enough for the ceiling to reach the 16 MB nursery cap — every PERRY_GC_HEAP_LIMIT ≤ 64, every device budget a small container or watch derives, every --pressure setting the GC stress matrix uses — the two collapse to the same number. "A trigger is due" and "the deferral is allowed" become exact complements: the deferral is refused at precisely the arena size that makes the trigger due. Control falls through to the alloc-point minor under ManualGcScanGuard::force_full_scan(), the collector reports [gc-copy-minor] eligible=false fallback=conservative_stack, and a heap-limited deployment silently runs the pre-#7019 non-moving collector.

Reproduced on e279b2d54 before touching anything, --pressure 8, pinned Node 26.5.0:

arm	collected	copy-minor
default	13/22	0/22
verify_evac	13/22	0/22
cons_scan_off	13/22	13/22
shipped_default	2/22	2/22

The fix — a formula change, no new knob

The allowance is now a slack measured from the deferral point, not an absolute arena size (GC_MOVING_DEFER_SLACK_BYTES / gc_moving_defer_slack_dyn_bytes(), budget_scaled(64 MB, 1, 3, 1 MB)):

• the first deferral of a cycle is unconditional — deferring is the sound path, and the alloc-point fallback exists only to bound growth when nothing drains it;
• the safety valve fires once the arena has grown one slack past the deferral point, and retires the pending request, so the baseline can never go stale and pin the deferral off for the rest of the process;
• a delta cannot collapse into an absolute trigger at any heap budget. The denominator is a third rather than a quarter so the deferral point (≈ ¼ of the budget) plus its slack still leaves headroom.

No env knob was added, so nothing new is owed an OFF arm under the GC knob kill-policy.

Proof the copying minor now runs

PERRY_GC_HEAP_LIMIT=8 PERRY_GC_DIAG=1 — the default arm's exact configuration, no other GC env:

test_gap_repsel_canonical_i32     cycles=1   copy-minor ran=1    copied_objects=3576      eligible=true fallback=none
test_gap_repsel_gc_stress         cycles=203 copy-minor ran=154  copied_objects=8604215   eligible=true fallback=none
test_gap_repsel_ptr_shape_locals  cycles=1   copy-minor ran=1    copied_objects=3654      eligible=true fallback=none
test_gap_typedarray_param_read    cycles=1   copy-minor ran=1    copied_objects=3608      eligible=true fallback=none

(In an auto-optimized link the runtime staticlib carries no diagnostics feature, so PERRY_GC_TRACE=1 emits only [gc] cycle (diagnostics feature disabled …) markers and the copy counter comes from PERRY_GC_DIAG. Both were set for every run below, exactly as the harness does.)

Matrix delta — --arms all --pressure 8, 440 cells

before   PASS=324  UNVER=91   XFAIL=1  FAIL=24
after    PASS=325  UNVER=100  XFAIL=1  FAIL=14

Liveness: default 0/22 → 12/22 copy-minor, verify_evac 0/22 → 12/22.

Every one of the 14 remaining FAILs is the same cell — test_gap_repsel_p4a3_numarray_barriers, exit=139 cycles=1 evacuated=0 scavenged=3594 — on the 14 arms that now run a copying minor. No corpus row broke that was not already red. The two rows that moved are the two pre-existing #6981 p4a3 rows:

cell	before	after
default × p4a3_numarray_barriers	PASS (cycles=1 scavenged=0)	FAIL (exit=139 scavenged=3594)
verify_evac × p4a3_numarray_barriers	PASS (cycles=1 scavenged=0)	FAIL (exit=139 scavenged=3594)
p4a3_ptr_numarray × 12 precise-root arms	FAIL (output-mismatch)	PASS

The two new reds are not softened, and they are the point: that SIGSEGV is #6981's, previously producible only by cons_scan_off and the %E% arms. It now reaches the arm named after the shipped configuration.

p4a3_ptr_numarray going green on 12 arms is a real behaviour change, not a mask: it now relocates at a safepoint (scavenged=3585) instead of at the register-imprecise allocation point, and its output matches the oracle byte-for-byte.

#6993 — the per-PR subset can now see the class

That is what default × p4a3_numarray_barriers flipping colour demonstrates. The whole "raw reference held across a relocating collection" class (#6951, #6972, #6982, #6991, #6992) was invisible to --arms pr because default/verify_evac ran the non-moving minor and cons_scan_off relocated only with incremental mode on. It is now reproducible per-PR, by the shipped configuration, without adding a red arm.

evac_minor / force_verify stay out of PR_ARMS for their original, unchanged reason (#6981), and the WHEN #6981 CLOSES note stays.

Gate teeth

• A scavenge liveness requirement, given to default, verify_evac, cons_scan_off, cons_scan_off_force — it reads the copying minor's own [gc-copy-minor] ran copied_objects= counter, never the sum that also counts the C4b mark-sweep evacuation (gc-matrix: the 'moved' liveness counter sums the C4b mark-sweep evacuation with the copying minor, so a move-arm can be green with zero scavenged objects #7025). A verifier arm that relocates nothing verifies nothing, and used to report PASS for it.
• Unit tests (gc/tests/triggers.rs) sweep every plausible heap budget and assert the deferral is satisfiable at the exact arena size that makes the trigger due, and that the safety valve still refuses past one slack. They also assert the collapse premise itself (due_at >= legacy_cap whenever the ceiling reaches the nursery cap), so the reason is recorded and not just the fix.
• crates/perry/tests/gc_copy_minor_under_heap_limit.rs pins the end-to-end observable: a compiled program under PERRY_GC_HEAP_LIMIT=8 must report copied_objects > 0. Exit 0 does not distinguish the two worlds — the broken build exited 0 and collected.

Measured consequences worth knowing

• test_gap_specabi_reassign stops collecting under the pressure knob (PASS → UNVER on every arm that used to take the alloc-point fallback). It is a 20-line program with no loop, so there is no back-edge poll to drain the deferral and it exits before reaching any safepoint. Previously the collapsed cap forced a non-moving minor at the allocation point. Growth stays bounded by the slack, and the harness reports it honestly as UNVER rather than green.
• Peak committed arena under a small budget can rise by up to one slack when a deferral does not drain (≈2.6 MB at PERRY_GC_HEAP_LIMIT=8). That is the price of the copying minor being reachable there at all; the previous behaviour bought its lower ceiling by never relocating.

Verification

Local box, pinned Node 26.5.0 (node --version asserted; the harness refuses to run otherwise), release profile, isolated CARGO_TARGET_DIR. Baseline and fixed runtimes were built from the same worktree by checking the three runtime files back and forth, so the A/B differs in nothing else; the auto-optimize archive is source-fingerprinted over perry-runtime, and was observed rebuilding on the switch.

Summary by CodeRabbit

• Bug Fixes

  • Fixed moving garbage collection deferral under tight heap limits.
  • Ensured copying minor collections run when nursery thresholds are reached.
  • Added a safety valve to prevent deferred collections from remaining stalled.

• Tests

  • Added regression coverage across heap-budget configurations.
  • Added verification that copying collections occur under explicit heap limits.
  • Improved GC stress-matrix checks to distinguish actual copying activity.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: a50d527f-8255-4f79-887b-445a15e92ea1

📥 Commits

Reviewing files that changed from the base of the PR and between 788a757 and 40d849a.

📒 Files selected for processing (6)

• changelog.d/7057-gc-moving-defer-slack.md
• crates/perry-runtime/src/gc/heap_budget.rs
• crates/perry-runtime/src/gc/policy.rs
• crates/perry-runtime/src/gc/tests/triggers.rs
• crates/perry/tests/gc_copy_minor_under_heap_limit.rs
• scripts/gc_repsel_matrix.sh

---

📝 Walkthrough

Walkthrough

Moving-GC deferral now uses a baseline-relative slack window instead of an absolute cap. Runtime tests, a heap-limited copying-minor regression test, and GC matrix gating updates verify that relocating minors execute and are measured independently.

Changes

Moving GC deferral and validation

Layer / File(s)	Summary
Baseline-relative deferral policy crates/perry-runtime/src/gc/heap_budget.rs, crates/perry-runtime/src/gc/policy.rs	Dynamic sizing and safepoint deferral now use a recorded arena baseline plus a slack allowance, with stale pending requests cleared after the allowance is exceeded.
Deferral behavior tests crates/perry-runtime/src/gc/tests/triggers.rs	Tests cover trigger reachability, slack boundaries, large arena values, and overflow-adjacent inputs.
Copying-minor regression and matrix gating crates/perry/tests/gc_copy_minor_under_heap_limit.rs, scripts/gc_repsel_matrix.sh, changelog.d/7057-gc-moving-defer-slack.md	The heap-limited integration test requires copied_objects > 0; matrix arms and classifications now require actual copying-minor evidence, with updated recorded results.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant gc_check_trigger
  participant moving_defer_within_slack
  participant gc_safepoint_moving_minor
  gc_check_trigger->>moving_defer_within_slack: evaluate arena growth against defer baseline
  moving_defer_within_slack-->>gc_check_trigger: allow or retire deferral
  gc_check_trigger->>gc_safepoint_moving_minor: route owed collection to moving minor

Loading

Possibly related issues

• gc: automatic (allocation-driven) collections in compiled programs are always full mark-sweeps under a forced conservative scan — PERRY_GC_FORCE_EVACUATE is inert there too #6950 — Addresses allocation-driven GC behavior by making copying minors reachable under heap limits.
• gc: a relocating minor with PRECISE roots breaks 14 of 20 representation-corpus files (5 crashes, 9 mismatches) — the conservative stack scan is load-bearing for correctness #6981 — Relates to exposing relocating-minor and precise-root failures in the GC matrix.
• gc: test_gap_repsel_gc_stress SIGSEGVs deterministically in 12 matrix arms under #7019's default-on moving minor (PASS -> FAIL) #7022 — Relates to making post-gc: default-on evacuating young-gen scavenge (moving minor at precise safepoints) #7019 relocating-minor failures observable under heap limits.
• gc: no reachable configuration exercises an evacuating minor with unpinned runtime locals — the #6655/#6935 bug class is untestable #6942 — Relates to unreachable automatic evacuating-minor paths and heap-limited copying-minor coverage.

Possibly related PRs

• PerryTS/perry#7019 — Introduced the moving/scavenge routing exercised by the updated deferral logic.
• PerryTS/perry#7020 — Adds test overrides affecting the deferral path exercised by moving-mode tests.
• PerryTS/perry#7040 — Separates copying-minor evidence from mark-sweep evacuation counters in matrix reporting.

Suggested labels: performance

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly describes the main fix: moving-defer slack now comes from the deferral point so copying minors run under heap pressure.
Description check	✅ Passed	The description is detailed and covers the defect, fix, related issues, and verification, even though it does not follow the template headings exactly.
Linked Issues check	✅ Passed	The changes address #7024 by making the copying minor reachable under heap limits and #6993 by adding liveness checks that expose the relocating path.
Out of Scope Changes check	✅ Passed	The diff stays focused on GC deferral logic, tests, matrix gating, and the changelog fragment, with no clear unrelated code changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/7024-decouple-defer-cap

---

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

[proggeramlug]

Filed granularly rather than smoothed over

• gc: a loop-free program never drains its deferred nursery trigger, so it now performs zero collections (test_gap_specabi_reassign went inert on 9 matrix cells) #7059 — test_gap_specabi_reassign stops collecting under the pressure knob. It is a 20-line program with no loop, so there is no back-edge poll to drain the deferral and it exits before any safepoint. Nine matrix cells went PASS → UNVER for this reason. Bounded by the slack, reported honestly, and now tracked.
• gc test: large_object_old_born_array_slot_write_keeps_young_child_alive asserts an exact whole-nursery copied_objects count and fails on macOS (4249 vs 1) — pre-existing on main #7060 — gc::tests::copying::large_object_old_born_array_slot_write_keeps_young_child_alive fails on macOS with copied_objects 4 249 vs an asserted exact 1. Verified byte-identical on a pristine build of e279b2d54, so it is pre-existing on main and not from this PR; the assertion is an exact equality against a whole-process quantity.
• gc: a relocating minor with PRECISE roots breaks 14 of 20 representation-corpus files (5 crashes, 9 mismatches) — the conservative stack scan is load-bearing for correctness #6981 — updated with the measurement: its p4a3_ptr_numarray half is now green on all 12 precise-root arms, and its p4a3_numarray_barriers half now reproduces in the shipped configuration.

One gate observation this PR does not fix

gc-stress — the job that runs this matrix — is not in main's branch-protection required contexts (lint, cargo-test, parity, compile-smoke, api-docs-drift, security-audit, conformance-smoke-complete). Its own comment in test.yml says so. So the arm subset can now reproduce the relocating-minor defect class, but reproducing it still cannot turn a merge red — variant (2) of the four documented ways a gate can be unable to fail. It also cannot be promoted as-is, because the job is genuinely red on main today: cons_scan_off × p4a3_numarray_barriers and cons_scan_off × p4a3_ptr_numarray were already failing before this PR (measured, PASS=59 UNVER=27 FAIL=2 on --arms pr at e279b2d54). That PR reduces to one failing row rather than two, but one is still one, and #6981 has to close before promotion is possible.

Local verification summary

check	result
--arms all --pressure 8 (440 cells)	PASS=325 UNVER=100 XFAIL=1 FAIL=14, from 324/91/1/24
--arms pr --pressure 8	PASS=55 UNVER=30 FAIL=3, from 59/27/2; all three failures are one row
default arm liveness	copy-minor 0/22 → 12/22
gc-ratchet check --profile shared_ci (7 repeats)	exit 0, 89 rows ok, every gated retention and GC-accounting metric within band
cargo test -p perry-runtime --lib gc::	501 passed; the 3 failures are pre-existing (2 known macOS parallel-teardown flakes that pass serially, 1 = #7060, reproduced on pristine)
cargo test -p perry --test gc_copy_minor_under_heap_limit	ok
cargo fmt --all -- --check	clean
scripts/check_file_size.sh	no new offenders (gc/policy.rs is allowlisted)