test(gc): collect at stack depth, and gate walker liveness on every arm

[proggeramlug]

The problem

The native-root stack walker had no probe that made it work.

Every probe in benchmarks/gc_ratchet/probes/ calls gc() at the end, from a shallow stack. Measured on 04_dead_after_deep_stack — the probe whose name promises a deep stack — macOS and Linux report:

"native_stack_maps":{"frames_visited":7,"records_matched":2,"locations_visited":0}

Zero root locations. Both arms would have passed the entire suite unchanged with a walker that visited nothing at all, because other root sources cover those probes. The suite was green and proved nothing about the walker.

Windows is the only arm that walks a deep stack (5,626 frames / 5,449 records), and it does so by accident of heap sizing — its GC happens to trigger mid-recursion rather than at exit. That accident is why the --require-locations liveness gate from #7354 could be applied to Windows and nowhere else.

This is CLAUDE.md's fourth failure mode almost exactly: "the gate runs but its subject never did."

The probe

11_collect_at_depth makes deep-stack coverage deliberate and portable instead of incidental:

function descend(depth: number): number {
  const mine = new Payload(depth);          // live ACROSS the call below
  if (depth === 0) { escape = mine; gc(); escape = null; return mine.value(); }
  const deeper = descend(depth - 1);
  return (mine.value() + deeper) | 0;       // reads `mine` AFTER the collection
}

Three properties make it a real test rather than a slower one:

• One live root per frame, all mid-frame. mine is live across the recursive call, so at collection time there are ~220 roots resident, none of them in the leaf frame. A walker that stops after a few frames loses them.
• Every slot is read afterwards. mine.value() runs after gc() returns, so a missed or mis-based root is a wrong checksum, not an invisible near-miss.
• PERRY_GC_FORCE_EVACUATE=1 moves every survivor, so a stale pointer cannot be accidentally right.

Measured

Byte-matching node --expose-gc --experimental-strip-types at the pinned version:

arm	frames	records	locations	was
macOS aarch64	228	222	221	7 / 0
x86-64 Linux	231	—	221	7 / 0

221 locations on both, from three separate deep cycles, then a final shallow gc() that correctly reports 7 frames / 0 locations. The two arms agree on the root count while disagreeing on frame count by 3 — different prologue shapes above main, which is what you'd expect.

Full ratchet suite: 11/11 byte-identical to the oracle under PERRY_RS4GC=1 PERRY_GC_FORCE_EVACUATE=1 PERRY_GC_VERIFY_EVACUATION=1.

The gate widening

With both Unix arms now walking a real stack, gc_walker_trace_assert.py --require-locations moves out of its if [ "$RUNNER_OS" = "Windows" ] branch onto the shared path, pointed at 11_collect_at_depth. All three arms now have to prove the walker ran.

I want to be explicit that the Windows-only scoping was not an oversight to be fixed by deleting the condition — it was correct at the time, because macOS and Linux could not have passed it. The probe is what makes the widening honest; without it, this PR would just be turning a gate red.

Risk

Test-only. No compiler or runtime code changes — the diff is one new probe and a moved if.

The one way this bites: if the walker regresses on a platform, the gate now fails there instead of passing silently. That is the intent.

Summary by CodeRabbit

• Tests
  • Expanded native garbage collection walker verification from Windows-only to all platforms (macOS, Linux, Windows)
  • Added new probe to validate garbage collection behavior under deep call stack conditions

[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: 790f3a67-ca9f-4fe7-a3d2-ee30e59168ce

📥 Commits

Reviewing files that changed from the base of the PR and between 7428437 and 9a4196c.

📒 Files selected for processing (3)

• .github/workflows/gc-native-roots.yml
• benchmarks/gc_ratchet/probes/11_collect_at_depth.ts
• changelog.d/7359-deep-stack-collect-probe.md

---

📝 Walkthrough

Walkthrough

The PR adds a deep-recursion GC probe with live roots in each stack frame. The workflow runs the probe with tracing and forced evacuation on macOS, Linux, and Windows, and requires walker telemetry on every platform.

Changes

GC root validation

Layer / File(s)	Summary
Deep-stack collection probe benchmarks/gc_ratchet/probes/11_collect_at_depth.ts, changelog.d/7359-deep-stack-collect-probe.md	The probe creates live Payload objects across 220 recursive frames, collects at maximum depth, validates the checksum, and reports memory metrics. The changelog documents the probe and its cross-platform validation.
Cross-platform workflow validation .github/workflows/gc-native-roots.yml	The workflow replaces the Windows-only assertion with a walker-liveness check for 11_collect_at_depth on every platform arm. It requires nonzero frame, record, and location telemetry.

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

Sequence Diagram(s)

sequenceDiagram
  participant Workflow
  participant Probe
  participant GC
  Workflow->>Probe: run 11_collect_at_depth with tracing
  Probe->>Probe: recurse with one live Payload per frame
  Probe->>GC: collect at maximum depth
  GC-->>Probe: relocate live roots
  Probe-->>Workflow: emit checksum and memory metrics
  Workflow->>Workflow: require nonzero walker telemetry

Loading

Possibly related issues

• Windows: native-root stack walker so PERRY_RS4GC=1 works there (#7173) #7354 — Adds the deep-stack probe and CI gate for the native-root stack walker implemented by the issue.

Possibly related PRs

• PerryTS/perry#7355 — Directly relates to extending GC walker telemetry and all-platform workflow validation.
• PerryTS/perry#7338 — Establishes evacuation configuration and assertions used by the deep-recursion probe.
• PerryTS/perry#7349 — Establishes the multi-platform workflow matrix used by this validation.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the new deep-stack GC probe and the walker liveness gate applied across platforms.
Description check	✅ Passed	The description clearly explains the problem, implementation, measurements, gate change, testing, and risk, but it does not use the repository template headings.
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 docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/deep-stack-collect-probe

---

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