test(gc): the POINTER_FREE trace-skip hazard probe that faults (#7635)

[proggeramlug]

Fixes #7635 — the probe that faults, and the reason nobody could build one.

Root cause: the probes were vacuous, not the instruments

JSON.parse of a non-tiny blob is lazy by default (#7499's tape). Every probe in this investigation — the audit's two shapes and my reproduction — parsed, churned, and only then read the records back. The materialisation happens at read-back, after the collections ran: the cohort did not exist while the collectors were being tested, so no sabotage could strand it and no instrument could catch anything. The instruments were fine the entire time.

Demonstrated end-to-end on an instrumented build: the identical TS shape with one pre-churn touch loop (defeating the tape) faults immediately under the sabotage —

arm	result
sabotage, default cycles	SIGSEGV (rc=139)
sabotage + ZEAL=1 PROTECT_FROMSPACE=1	[gc-fromspace-protect] FAULT: signal 10 at 0x47ab075bbd0 — precise, named address
no sabotage (real code)	clean, and a trace-time audit confirms zero POINTER_FREE selections over pointer-bearing payloads

A supporting measurement that sealed it: under sabotage with the lazy probe, a trace-time counter saw only ~5 pointer-bearing PF selections across dozens of cycles × 4,000 records — the records simply weren't there.

The committed regression test

gc/tests/layout_pointer_free_hazard.rs, in the fromspace_protect planted-hazard convention, no env knobs:

• Red control — an object built through the materialiser's exact deferred-store path, whose only reference to a young string sits in a field slot, finalized with a lying saw_pointer=false. The copying minor moves the object, honors the state, skips the payload — asserted on both halves of the strand: the slot bits survive unrewritten (the skip was live), and the child sits in poisoned from-space (QUARANTINE_POISON_WORD).
• Green twin — truthful finalize: the child is evacuated and the slot rewritten.
• Subject-liveness asserted in both arms (the object must have MOVED), so neither can pass vacuously.

Consequences for the record

• The POINTER_FREE trace-skip is real, observable, and load-bearing — outcome (3) of the issue's trichotomy, with the missing shape identified.
• perf(gc): defer the JSON materialiser's per-slot layout notes to one finalize (#7630) #7633's "zeal arm: output identical" line was indeed non-discriminating for parse-only shapes, exactly as the audit said. The discriminating form now lives in CI.
• Standing rule for this family: any parse-cohort GC probe must defeat the lazy tape (touch the cohort before the collections) or state explicitly that it exercised the lazy path.

perry-runtime suite: 1,904 passed / 0 failed (both new tests green). cargo fmt --check and check_file_size.sh clean. No production code changed — this PR is the test alone.

Summary by CodeRabbit

• Bug Fixes

  • Added regression coverage for garbage collection of pointer-free layouts.
  • Verified that referenced objects are correctly evacuated and rewritten during collection, preventing stranded or invalid references.

• Documentation

  • Documented the pointer-free tracing hazard and guidance for ensuring garbage-collection probes exercise the intended behavior.

[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: 2a6b5edd-b683-4f17-8ade-256083cca713

📥 Commits

Reviewing files that changed from the base of the PR and between 4fb66a8 and e268592.

⛔ Files ignored due to path filters (1)

• Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing (2)

• CLAUDE.md
• Cargo.toml

---

📝 Walkthrough

Walkthrough

The change adds GC regression tests for the POINTER_FREE layout hazard. It compares false and truthful pointer metadata during minor collection, documents lazy-materialization probe requirements, and increments the package version.

Changes

POINTER_FREE hazard regression coverage

Layer / File(s)	Summary
Hazard fixture and test wiring crates/perry-runtime/src/gc/tests/layout_pointer_free_hazard.rs, crates/perry-runtime/src/gc/tests/mod.rs, changelog.d/7644-pointer-free-hazard-probe.md, Cargo.toml, CLAUDE.md	The fixture creates deferred objects with young string children and applies false or truthful pointer metadata. The test module is registered. The changelog documents the lazy-materialization behavior. The package version is updated to 0.5.1366.
Layout hazard regression tests crates/perry-runtime/src/gc/tests/layout_pointer_free_hazard.rs	The tests verify that false metadata leaves a child pointing to poisoned from-space, while truthful metadata rewrites the child to an evacuated string. Both tests verify that the containing object moves.

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

Possibly related issues

• Promote the tape=0 + from-space-scan parse-then-churn check to a CI gate for the layout-state family #7647 — Both issues address GC layout-state hazards in parse and churn probes and add coverage for stranded or poisoned child references.

Possibly related PRs

• PerryTS/perry#7643 — Adds related POINTER_FREE GC hazard tests for deferred finalization and lazy JSON parsing.
• PerryTS/perry#7633 — Introduces the deferred JSON layout and finalization behavior covered by this regression test.
• PerryTS/perry#7553 — Implements related pointer-free JSON tape and LazyArrayHeader GC behavior.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the GC regression test and the POINTER_FREE trace-skip hazard addressed by the changes.
Description check	✅ Passed	The description explains the root cause, test design, linked issue, and verification results, although it does not reproduce every template heading.
Linked Issues check	✅ Passed	The test satisfies #7635 by exercising a movable child reachable only through the object slot and detecting stranded state versus truthful evacuation.
Out of Scope Changes check	✅ Passed	The changes are limited to the requested GC regression test, its module registration, and related changelog documentation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch gc/7635-pointer-free-discriminator

---

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]

Audit — merged as v0.5.1366

Two agents worked #7635 independently and landed on the same root cause without contact: the probes were vacuous because JSON.parse is lazy for non-tiny blobs, so the record cohort was materialised after the last collection. That convergence is worth more than either report alone — it was the one conclusion I most doubted, since it means my own #7635 filing was wrong.

Kept alongside #7643 rather than closed as a duplicate, because the two observe different layers:

	#7643	#7644 (this)
observes	the enumerator — gc_child_slots reports zero payload slots	the memory — the stranded child sits in QUARANTINE_POISON_WORD from-space
catches	a misdeclared object being skipped	the same, plus a case where the enumerator reports correctly but the rewrite pass drops the slot anyway

#7643 asks the collector what it intends to visit; this asks what actually happened after it ran. The second is the one that would survive a refactor that fixed the enumeration and broke the rewrite.

Sabotage-verified two-sided, which the red-control design earns: inverting the plant's finalize_truthfully reddens both arms — the lying arm fails "must not have been rewritten", the truthful arm fails "must have been rewritten to the evacuated copy" — with 0 compile errors, so both are load-bearing on the actual layout state rather than on the construction. A one-sided check (neutering the finalize) would have left the red control green and proved only half of it.

Two design details I checked specifically:

• The red control leaves a deliberately stranded child, which in most tests would be a landmine for the next collection on that thread. It is safe here by construction — the object stays POINTER_FREE, so no collector will ever follow that slot — and CopyingNurseryTestGuard::drop calls reset_shadow_stack() regardless. Notably the opposite of test(gc): make the POINTER_FREE misdeclaration hazard detectable (#7635) #7643's cleanup, which restores layout_mark_unknown; doing that here would arm the landmine rather than defuse it. Both are right for their own shape.
• Subject-liveness asserted in both arms (assert_ne!(moved_obj, obj)). Without it a cycle that moved nothing would pass the "slot unchanged" assertion trivially — the 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 failure mode exactly.

Gates: 20/20 from the lint job enumerated out of test.yml, cargo fmt --all --check clean, cargo test -p perry-runtime --lib --no-fail-fast 1908 passed / 0 failed (1906 + these 2). No production code changed.

The standing rule in your writeup is the durable part and I've taken it into CLAUDE.md's orbit: any parse-cohort GC probe must defeat the lazy tape by touching the cohort before the collections, or state explicitly that it is exercising the lazy path. #7647 tracks the end-to-end CI gate — still open and still wanted, since both merged tests are unit-level and neither would catch a new materialiser path that forgets to finalize at all.