docs(gc): write down why the this-patch closure roots need no explicit release

[proggeramlug]

Comment only — no codegen change.

CodeRabbit's review of #6975 raised one more finding after that PR merged:

Release this-closure temp roots before the final rooted handle release.
rooted_handle_release(ctx, rooted) only truncates the root pushed by rooted_handle_begin, so temp_root_push_double entries added for captures_this: true closures in this_patches remain on the temp-root stack.

That one is a false positive, but only because of a semantic that was never written down at the site: js_gc_temp_root_truncate is a stack cut, not a pop. It truncates the vector to base, dropping base and everything pushed above it. In lower_object_literal:

1. rooted_handle_begin pushes the object handle (index N),
2. the property loop pushes each captures_this closure value (N+1, N+2, …),
3. rooted_handle_release(ctx, rooted) at the end truncates to N,

so the single release does drop every closure root. gc::tests::temp_roots::truncate_drops_every_slot_above_the_base pins the cut semantics.

It does depend on the push order, though, and nothing said so — a refactor that hoisted the closure pushes above rooted_handle_begin, or moved the release before the patch loop, would silently leak (or under-root). This adds eight lines of comment stating the invariant, naming the two constraints it rests on, and pointing at the test.

Verified: cargo check -p perry-codegen and cargo fmt --all -- --check clean; no emitted IR changes (comment only).

Summary by CodeRabbit

• Documentation
  • Clarified the lifetime and release semantics for temporary this-related closure roots during object-literal lowering.
  • Explained how temp_root truncation works as a stack cut and how a later single release covers roots created afterward, removing ambiguity around expected cleanup behavior.

[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: f9616d36-6188-42c1-a0ed-ed2fdae129f9

📥 Commits

Reviewing files that changed from the base of the PR and between 4d627f9 and 92f1e85.

📒 Files selected for processing (1)

• changelog.d/6979-temp-root-cut-invariant.md

---

📝 Walkthrough

Walkthrough

The object literal lowering code and changelog document temporary-root lifetime handling in the captures_this closure path, including deferred release ordering and truncation behavior.

Changes

Object literal rooting

Layer / File(s)	Summary
Document deferred root release crates/perry-codegen/src/expr/object_literal.rs, changelog.d/6979-temp-root-cut-invariant.md	The closure patching path and changelog explain that post-phase temp_root truncation releases roots pushed during patching, avoiding per-root releases.

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

Possibly related PRs

• PerryTS/perry#6972: Addresses related precise temporary-root handling in object literal lowering.
• PerryTS/perry#6975: Modifies related deferred closure patching and temporary-root logic.
• PerryTS/perry#6983: Uses the same temporary-root truncation and release invariant.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly states the main change: documenting why the this-patch closure roots do not need explicit release.
Description check	✅ Passed	The description explains the change, rationale, related finding, and verification steps, though it doesn't follow the template headings exactly.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% 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
• Commit unit tests in branch docs/6975-temp-root-cut-invariant

---

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