fix(codegen): lower precise roots in native LLVM construction

[proggeramlug]

Summary

• apply Perry's finalized precise-root lowering before direct C-API construction feeds mapped functions to RS4GC
• preserve the same lowering in the distinct split-unit freeze/worker path
• keep the existing exact emitted-object differential oracle unchanged

Cause

LlFunction::to_ir() is where js_shadow_slot_bind calls become ptr addrspace(1) root slots. The direct native backend streamed FinalItems before that whole-function pass, while still copying gc "statepoint-example" onto the function. LLVM therefore verified and optimized a native arm with no RS4GC-visible roots. The existing byte comparison correctly reported a semantic mismatch; this is not object metadata and nothing is normalized away.

LlModule::skeleton_ir() also now mirrors the statepoint declarations and Apple stack-map retention directive used by the text module.

Verification

• exact single-unit text/native emitted objects are byte-identical after both arms run RS4GC
• exact two-unit text/native emitted + partial-linked objects are byte-identical
• both controls assert the trusted text arm demonstrably contains addrspace(1) roots and no shadow-slot bind call
• cargo fmt --all -- --check
• git diff --check

Closes #8052.
Refs #7971, #7966.

No version bump.

Summary by CodeRabbit

• Bug Fixes
  • Improved native code generation for precise garbage-collection roots.
  • Fixed stack-map and root-lowering behavior across both direct and split builds.
  • Ensured consistent generated output between native construction modes.
  • Improved compatibility with Apple platforms by preserving required LLVM stack-map data.
• Tests
  • Added coverage verifying precise-root lowering and identical output across supported build paths.
• Documentation
  • Added a changelog entry describing the root-lowering fix.

[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: d85fad04-53a9-4f26-8dad-403ff40cdd0b

📥 Commits

Reviewing files that changed from the base of the PR and between bd9580e and b7876c0.

📒 Files selected for processing (4)

• changelog.d/8062-native-rs4gc-root-lowering.md
• crates/perry-codegen/src/function.rs
• crates/perry-codegen/src/module.rs
• crates/perry-codegen/src/native_emit.rs

---

📝 Walkthrough

Walkthrough

Native LLVM construction now applies precise-root lowering before RS4GC for direct and split codegen units. Stack-map declarations and accessors support this path, while tests compare lowered output and native objects byte-for-byte.

Changes

Native RS4GC lowering

Layer / File(s)	Summary
Stack-map contracts and LLVM declarations crates/perry-codegen/src/function.rs, crates/perry-codegen/src/module.rs	LlFunction exposes whether stack maps are requested. skeleton_ir emits Apple stack-map retention assembly and LLVM statepoint declarations when native stack roots are enabled.
Direct and split native emission crates/perry-codegen/src/native_emit.rs	Native construction and split-unit freezing use finalized function text for functions that require personality handling or stack maps. Other functions retain typed streaming.
Precise-root validation and changelog crates/perry-codegen/src/native_emit.rs, changelog.d/8062-native-rs4gc-root-lowering.md	Tests verify shadow-stack root lowering, removal of the original bind call, and byte-identical direct and split native objects. The changelog records the fix.

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

Mergeability Score: ⚪ Minimal · up to b7876

The change aligns native LLVM construction with precise-root lowering and preserves the split-unit path, with exact emitted-object checks confirming matching behavior; no actionable merge-blocking risk remains beyond normal checks and review.

Possibly related PRs

• PerryTS/perry#7314: Related native stack-root and RS4GC lowering implementation.
• PerryTS/perry#7339: Related in-process RS4GC pipeline changes.
• PerryTS/perry#7301: Earlier in-process LLVM native construction extended by these changes.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the primary native LLVM precise-root lowering fix.
Description check	✅ Passed	The description explains the cause, changes, linked issues, verification, and version policy, but uses alternate headings and omits the checklist.
Linked Issues check	✅ Passed	The changes address issue #8052 by fixing native precise-root lowering, preserving exact object comparison, and validating single- and split-unit equivalence.
Out of Scope Changes check	✅ Passed	All code, tests, module declarations, and changelog documentation directly support the native precise-root lowering and object-equivalence objectives.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ 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 fix/8052-native-root-diff

---

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