batch: land #8838, #8839, #8843, #8845

[proggeramlug]

Batch landing of four reviewed PRs, validated once as a single merged tree (rebased onto b83a903e3 and re-validated after main moved mid-run).

PR
#8838	docs: design Node-API host
#8839	perf: reuse guarded ECS entity indices
#8843	fix(runtime): reject oversized generic Array slice results
#8845	perf: specialize guarded ECS typed columns

Audit notes

#8839 is in the same family as #8833, whose submitted form carried a real soundness bug, so it got the same scrutiny — and its design avoids that trap. Invalidation is driven by a runtime flag (store i1 1, ptr %proof_dirty) emitted at the call-emission choke point, so it is genuinely path-sensitive at execution rather than a flow-insensitive compile-time map keyed by local id. It also fails closed: dirty_stable_packed_revalidations_before_call skips dirtying only for the narrow allowlist llvm.* / js_shadow_* / js_write_barrier* (all record-only, none can collect), and because the guard is direct_callee.is_some_and(…), an indirect call passes None, does not match, and dirties. active_stable_packed_proofs_are_dirtied_only_by_executed_non_intrinsic_calls covers exactly those cases including call_indirect, and asserts ordering (fabs before the dirty store).

Fixes applied while landing (both #8845's)

• gc_store_site_inventory flagged four raw stores in expr/proven_view_access.rs. The classification the author intended is correct — these are typed-array backing-store writes (I16/I32/F32/DOUBLE into an element pointer, no GC pointer involved) — and a GC_STORE_AUDIT(POINTER_FREE) marker was already present above the match, but the scanner's proximity window only reaches the first arm. Added per-arm markers rather than adding an allowlist entry.
• check_file_size: expr/index_set.rs reached 2003 lines. Extracted the 398-line packed-loop store lowering block (lower_packed_f64_loop_store_value, lower_packed_numeric_loop_store_value, lower_packed_f64_range_loop_index_set, lower_packed_numeric_loop_index_set) into expr/index_set_packed_loop.rs, following the existing flat index_set_* sibling convention. Now 1605.

Validation (merged tree)

• all 30 lint-job gates pass
• perry-codegen 1266, perry-runtime 2698, perry-stdlib 120, perry-hir 337 — all 0 failed
• moving-GC arm (PERRY_GC_FORCE_EVACUATE=1 PERRY_GC_VERIFY_EVACUATION=1): 16 failed on the batch and 16 on clean main — same-commit A/B, so none is introduced here; those 16 are tests that assert non-evacuating behaviour and fail under those knobs by design
• df checked before and after every run; no result produced under ENOSPC

Summary by CodeRabbit

• New Features

  • Improved performance for eligible numeric and ECS-style loops through optimized typed-array access.
  • Added safer handling for packed numeric data and out-of-bounds indexing.

• Bug Fixes

  • Fixed Array.prototype.slice behavior for array-like objects with invalid or extremely large lengths.
  • Preserved sparse entries and improved safety during slicing.

• Documentation

  • Added comprehensive Node-API host design documentation.
  • Linked the new documentation in the internals guide.

[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: 7edcbeb3-2f39-4f84-9eb0-df0fcd851b4c

📥 Commits

Reviewing files that changed from the base of the PR and between b83a903 and ee01796.

📒 Files selected for processing (25)

• changelog.d/8839-guarded-ecs-entity-index-cache.md
• crates/perry-codegen/src/block.rs
• crates/perry-codegen/src/expr/i32_fast_path.rs
• crates/perry-codegen/src/expr/index_get.rs
• crates/perry-codegen/src/expr/index_set.rs
• crates/perry-codegen/src/expr/index_set_packed_loop.rs
• crates/perry-codegen/src/expr/mod.rs
• crates/perry-codegen/src/expr/proven_view_access.rs
• crates/perry-codegen/src/expr/shadow_slot.rs
• crates/perry-codegen/src/runtime_decls/objects.rs
• crates/perry-codegen/src/stmt/let_stmt.rs
• crates/perry-codegen/src/stmt/loops.rs
• crates/perry-codegen/src/stmt/mod.rs
• crates/perry-codegen/src/stmt/stable_packed_loop.rs
• crates/perry-codegen/src/stmt/stable_packed_typed_array.rs
• crates/perry-runtime/src/array/generic.rs
• crates/perry-runtime/src/array/subclass.rs
• crates/perry-runtime/src/array/subclass_tests.rs
• crates/perry-runtime/src/object/global_this/array_error.rs
• crates/perry-runtime/src/object/mod.rs
• crates/perry-runtime/src/typedarray/mod.rs
• crates/perry/tests/issue_5898_array_slice_invalid_length.rs
• crates/perry/tests/issue_8773_closure_capture_packed_loops.rs
• docs/src/SUMMARY.md
• docs/src/internals/node-api-host.md

---

📝 Walkthrough

Walkthrough

The change adds guarded ECS packed-loop lowering with exact Uint32Array validation, proof invalidation, repeated-read caching, and numeric fast stores. It also changes array-like slice validation and adds a Node-API host design document.

Changes

Guarded ECS packed-loop fast path

Layer / File(s)	Summary
Proof invalidation and repeated-read caching crates/perry-codegen/src/block.rs, crates/perry-codegen/src/expr/mod.rs, crates/perry-codegen/src/stmt/stable_packed_loop.rs, crates/perry/tests/issue_8773_closure_capture_packed_loops.rs	Stable packed loops track revalidation slots and repeated-read caches. Executed calls dirty active proofs. Clean reads use cached values; dirty reads revalidate or use generic fallback.
Uint32 admission and view installation crates/perry-codegen/src/stmt/stable_packed_typed_array.rs, crates/perry-runtime/src/array/subclass.rs, crates/perry-runtime/src/typedarray/mod.rs, crates/perry-codegen/src/runtime_decls/objects.rs, crates/perry-runtime/src/array/subclass_tests.rs	Eligible loops admit two to four distinct inline Uint32Array columns. The runtime guard validates exact entity indices and equal column lengths. Code generation installs and restores stable views.
Uint32 reads and packed numeric stores crates/perry-codegen/src/expr/proven_view_access.rs, crates/perry-codegen/src/expr/index_set_packed_loop.rs, crates/perry-codegen/src/expr/i32_fast_path.rs, crates/perry-codegen/src/stmt/let_stmt.rs	Proven views support checked and common-bound u32 loads and stores. Packed F64, I32, and U32 loop stores use guarded raw writes and side exits. Derived locals retain native u32 values.

Array slice behavior

Layer / File(s)	Summary
Array-like slice execution and regression coverage crates/perry-runtime/src/array/generic.rs, crates/perry-runtime/src/object/global_this/array_error.rs, crates/perry/tests/issue_5898_array_slice_invalid_length.rs	Plain array-like receivers use the generic slice path. Result length is validated before allocation or indexed reads. Selected elements are copied directly while preserving holes.

Node-API host design

Layer / File(s)	Summary
Node-API host contract docs/src/internals/node-api-host.md, docs/src/SUMMARY.md	The documentation defines ABI support, handles, GC roots, exceptions, native classes, buffers, async work, threading, addon loading, distribution, caching, API coverage, and acceptance gates.

Estimated code review effort: 5 (Critical) | ~120 minutes

Sequence Diagram(s)

sequenceDiagram
  participant LoopLowerer
  participant ECSGuard
  participant Uint32Columns
  participant ProvenViewAccess
  LoopLowerer->>ECSGuard: request guarded column admission
  ECSGuard->>Uint32Columns: validate owners, kinds, lengths, and entity prefix
  Uint32Columns-->>ECSGuard: return column addresses or generic-path result
  ECSGuard-->>LoopLowerer: return guard descriptor
  LoopLowerer->>ProvenViewAccess: lower checked Uint32 reads and stores

Loading

Suggested reviewers: thehypnoo

✨ 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 merge/batch-8838-8845

---

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