docs(gc): state the static checker's scope and its three blind spots

[proggeramlug]

Addresses the Major review comment on #7281, which I merged past.

docs/src/internals/gc-rooting-invariant.md said:

scripts/gc_root_dominance_check.py is structurally blind to this class

and, eight lines later:

It is the only instrument that sees this class before it crashes.

Both sentences were true of different classes, but read sequentially they contradict, and the second is the one someone acts on. That is how a clean checker report becomes evidence of safety.

This states the scope explicitly — emitted-LLVM rooting hazards — and names the three blind spots, each attributed to the incident that found it:

• Runtime tables / interning caches (GC: enumerate the unrooted runtime-side caches — the population no static checker can see #7231). Tell: fails 10/10, not intermittently.
• Unrooted locals in runtime Rust (fix(gc): run the globalThis bootstrap in a no-move window (#7217) #7249). It read 0 violations on both sides of a real bug whose fix was a one-line GcSuppressScope.
• Anything its symbol sets fail to name (fix(gc): classify the emitted property-GET dispatch as poll-capable (#7154) #7284). POLL_CAPABLE_RUNTIME carried js_object_get_field_by_name — which codegen never emits — beside js_object_set_field_by_name, which it emits verbatim. Sets classified MOVING: YES, gets MOVING: no, and 31 stale uses were dropped by --moving-only.

Also points at the coverage gap #7280 records: 25 curated corpus files pass while 20 lines of stock zod fail, so a dependency-scale workload belongs in the checklist next to the zeal arms.

Docs only.

Summary by CodeRabbit

• Documentation
  • Clarified the static checker’s scope and limitations when identifying emitted-code garbage-collection rooting hazards.
  • Documented known blind spots, including runtime caches, unrooted runtime locals, and symbols missing from analyzed symbol sets.
  • Added guidance on symbol matching, potential false classifications, and complementary runtime validation techniques.
  • Added a changelog entry summarizing these limitations.

[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: 466c16b1-3303-492e-8262-65e110e27356

📥 Commits

Reviewing files that changed from the base of the PR and between 16da69f and 1e82573.

📒 Files selected for processing (2)

• changelog.d/7289-clarify-static-checker-scope.md
• docs/src/internals/gc-rooting-invariant.md

---

📝 Walkthrough

Walkthrough

The PR documents the static checker’s emitted-LLVM scope, three known blind spots, symbol-set classification issues, and validation methods. It adds matching changelog text.

Changes

Static checker scope documentation

Layer / File(s)	Summary
Scope and limitation documentation docs/src/internals/gc-rooting-invariant.md, changelog.d/7289-clarify-static-checker-scope.md	The documentation limits checker coverage to emitted-LLVM rooting hazards, lists runtime caches, unrooted runtime locals, and omitted symbols as blind spots, and describes validation with zeal/quarantine instrumentation and broad workloads.

Estimated code review effort: 1 (Trivial) | ~3 minutes

Possibly related issues

• GC: enumerate the unrooted runtime-side caches — the population no static checker can see #7231 — Documents the runtime-side unrooted caches identified as a static checker blind spot.

Possibly related PRs

• PerryTS/perry#7192 — Introduces and uses the static GC-rooting checker whose scope this PR documents.
• PerryTS/perry#7212 — Updates the same GC-rooting invariant documentation.
• PerryTS/perry#7284 — Modifies the checker’s POLL_CAPABLE_RUNTIME symbol matching documented here.

Suggested reviewers: jdalton

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/7289-checker-scope

---

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