fix(gc): classify the emitted property-GET dispatch as poll-capable (#7154)

[jdalton]

The adjudication

Two of the effort's GC instruments disagreed at zod's clone.
PERRY_GC_PROTECT_FROMSPACE=1 PERRY_GC_PROTECT_FROMSPACE_DEPTH=800 faulted
deterministically; scripts/gc_root_dominance_check.py --stale-registers
classified the same window MOVING: no, so the --moving-only arm
gc-root-dominance.yml gates on could not see it.

The checker was wrong. POLL_CAPABLE_RUNTIME is an exact-emitted-symbol
set, and it carried js_object_get_field_by_name next to
js_object_set_field_by_name — which reads as symmetric coverage of property
access and is not. Codegen emits the SET verbatim (27 sites in perry-codegen,
205 in the gate corpus) and never emits the GET at all: every property read
lowers to js_object_get_field_by_name_f64, js_object_get_field_ic_miss or
js_typed_feedback_object_get_field_by_name_f64 — 1324 / 532 / 556 calls in the
same corpus — and not one was in the set. Property sets classified
MOVING: YES, property gets classified MOVING: no. That asymmetry is what put
"all five violations the gate reports are MOVING: YES via js_object_set_field_by_name" in the rooting-invariant doc and left the whole
GET side unread. 55 stale uses on the gate corpus have an emitted GET helper
in their window; 31 of them were dropped by --moving-only.

Auditing the set the way #7227 audits ALLOC_RE then found a second, larger
hole: ten of twenty-eight entries named symbols that do not exist
(js_apply_function, js_array_for_each, js_array_sort, js_call_closure,
js_call_value, js_function_call, js_invoke_closure,
js_object_get_property, js_object_set_property, js_string_replace). Four
of the ten were four different spellings of "call a JS closure" — the most
obviously poll-capable operation in the language, covered zero times — while
RECEIVER_SINKS three hundred lines away in the same file already spelled it
closure_call\w*. Each phantom is replaced by the emitted symbol carrying
its premise, never merely deleted; deleting turns the audit green and leaves the
hole.

Full reach proofs, per symbol, are in the block comment on
POLL_CAPABLE_RUNTIME and in changelog.d/7284-….

The two hypotheses that were not the answer

• Attribution mismatch (stale parameter arriving as an argument).
  heap_source_kind genuinely has no incoming-parameter source kind, and that
  is a real gap — but not this one. Perry spills and binds parameters, so the
  re-read is a slotload the checker already models. Measured: 1708 params
  spilled, 256 not; of the 256, exactly 4 are used below a collecting call and
  all 4 are double/i64 arithmetic in typed-f64 specialisations, none a
  pointer. Needs its own change with its own hit count. The new fixture passes
  its receiver and key as bare parameters so the shape is on the record.
• Protector overreach at DEPTH=800. Structurally impossible. A page-set
  enters the quarantine only because an evacuating minor retired it as
  from-space (arena/quarantine.rs; the knob gates
  copying_reset_from_spaces_and_flip and nothing else), so a fault on a
  quarantined address is a genuine stale read at any depth. Eviction hands
  blocks back to Eden, where the same read silently succeeds — depth removes
  false negatives and cannot manufacture a false positive. The doc now says so.

Verification

No Rust changed, so cargo test is untouched by construction. Corpus: 141
.ll, 2321 functions, 3068 root stores, built from this worktree at
97c69211d.

over the gate corpus	parent 97c69211d	this PR
compiled functions in poll_reaching	473	671
--stale-registers, raw	4860	4860
--stale-registers --moving-only	65	115
--stale-registers --fatal-sinks	1055	1055
--stale-registers --moving-only --fatal-sinks	1	13
bind-anchored --moving-only (the gate)	0	0, allowlist still empty
--unrooted-allocas --moving-only (the gate)	0	0

Raw counts do not move: this reclassifies windows, it does not widen what counts
as a heap-value source.

The gate can now fail on the shape

New --self-test arm, red against the parent's set and green against this one:

self-test FAIL: the generic property-GET dispatch resolves a user getter
(object/field_get_set/get_field_by_name.rs:1064) and routes a Proxy to
js_proxy_get (:84), so a register held across it MUST classify MOVING and
survive --moving-only. Got {} ...
exit 1

And the gate's own command over a corpus mutant that splices exactly one
js_object_get_field_ic_miss into one real allocation-to-root-store gap:

--moving-only --allowlist … --seeded-violations 40 over the mutant corpus	parent	this PR
violations	0	1
exit status	0 (green — blind)	1 (red)

test_gap_array_iterator_next…::perry_closure_…__1
  alloc  : %r15 = call i64 @js_closure_alloc_singleton(...)
  between: js_object_get_field_ic_miss
  MOVING : YES via js_object_get_field_ic_miss

Complementary direction on the unmutated corpus: reseeding
--seeded-violations' spliced call with js_object_get_field_ic_miss instead
of js_call_function gives 40 planted, 0 caught, 40 MISSED on the parent and
40 planted, 40 caught here.

All six of the workflow's checker invocations exit 0 on this branch:
--self-test, --audit-alloc-re, --audit-poll-capable,
--audit-immovable-sources, and both --moving-only corpus arms.

Follow-up needed (not in this PR)

--audit-poll-capable ships as a mode but is not yet wired into
.github/workflows/gc-root-dominance.yml — pushing a workflow change needs an
OAuth workflow scope this session did not have. The step is a two-line
addition next to the --audit-alloc-re step and should land before this is
relied on as a gate; until then the mode is a command, not a check.

Summary by CodeRabbit

• Documentation

  • Expanded guidance on garbage-collection rooting, runtime symbol matching, stale-read troubleshooting, and verification procedures.
  • Added changelog details covering poll-capable property access checks, audit metrics, and CI gate behavior.

• Bug Fixes

  • Improved detection of poll-capable runtime operations, including property access, closure calls, sorting, iteration, and string replacement.
  • Added checks to identify invalid runtime symbol classifications and stale-register scenarios.

• Tests

  • Added self-test fixtures and verification coverage for moving classifications, reload controls, and property-access behavior.
  • Added automated validation to ensure all audited runtime symbols are available.

[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: 1493e9ab-571f-4c9e-810f-b7774b4193a2

📥 Commits

Reviewing files that changed from the base of the PR and between 3bd1342 and 235c66d.

📒 Files selected for processing (4)

• .github/workflows/gc-root-dominance.yml
• changelog.d/7284-poll-capable-property-get-and-audit.md
• docs/src/internals/gc-rooting-invariant.md
• scripts/gc_root_dominance_check.py

---

📝 Walkthrough

Walkthrough

The GC-root dominance checker now audits POLL_CAPABLE_RUNTIME against exported symbols and classifies emitted property-GET, closure-call, sorting, iteration, and string-replacement symbols. Fixtures, self-tests, CI wiring, documentation, and changelog records cover the changes.

Changes

Poll-capable runtime audit

Layer / File(s)	Summary
Runtime symbol classification and auditing scripts/gc_root_dominance_check.py	POLL_CAPABLE_RUNTIME now uses emitted runtime symbols. audit_poll_capable validates entries against exported symbols and rejects phantom entries.
Property-GET detection and command dispatch scripts/gc_root_dominance_check.py, .github/workflows/gc-root-dominance.yml	Fixtures and self-tests cover stale registers across property-GET dispatch, reload controls, audit validation, and the --audit-poll-capable option. CI runs the audit before the build.
Verification records and rooting documentation docs/src/internals/gc-rooting-invariant.md, changelog.d/7284-poll-capable-property-get-and-audit.md	Documentation records symbol matching, audit commands, CI checks, detection-window behavior, verification metrics, and validation results.

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

Sequence Diagram(s)

sequenceDiagram
  participant CI
  participant gc_root_dominance_check
  participant POLL_CAPABLE_RUNTIME
  participant ExportedRuntimeSymbols
  CI->>gc_root_dominance_check: invoke --audit-poll-capable
  gc_root_dominance_check->>POLL_CAPABLE_RUNTIME: read runtime entries
  gc_root_dominance_check->>ExportedRuntimeSymbols: validate emitted symbols
  ExportedRuntimeSymbols-->>gc_root_dominance_check: return matches
  gc_root_dominance_check-->>CI: report audit result

Loading

Possibly related PRs

• PerryTS/perry#7192: Extends the same analyzer with poll-capable runtime auditing and classification.
• PerryTS/perry#7212: Updates the same checker and GC-rooting documentation.
• PerryTS/perry#7240: Modifies the same POLL_CAPABLE_RUNTIME classification.

Suggested reviewers: proggeramlug

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description is technically detailed but omits the required template sections, including Summary, Changes, Related issue, checklist, and standard test-plan checkboxes.	Restructure the description using the repository template and include the required sections, issue reference, test-plan checklist, and contributor checklist.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the primary change: classifying emitted property-GET dispatches as poll-capable.
Docstring Coverage	✅ Passed	Docstring coverage is 83.33% which is sufficient. The required threshold is 80.00%.
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 unit tests (beta)

• Create PR with unit tests

---

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

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/src/internals/gc-rooting-invariant.md`:
- Around line 304-310: Update docs/src/internals/gc-rooting-invariant.md at
lines 304-310 and 171-221 to state that --audit-poll-capable CI wiring is
pending a follow-up rather than already running before the build; update
changelog.d/7284-poll-capable-property-get-and-audit.md at lines 65-76 likewise
so it does not claim a shipped gc-root-dominance.yml step. Preserve the claims
about --audit-alloc-re and the audit behavior itself.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 85f78f3b-9185-4843-8910-c23e2e6e6d76

📥 Commits

Reviewing files that changed from the base of the PR and between 97c6921 and 3bd1342.

📒 Files selected for processing (3)

• changelog.d/7284-poll-capable-property-get-and-audit.md
• docs/src/internals/gc-rooting-invariant.md
• scripts/gc_root_dominance_check.py