perf(gc): memoize typed layouts by ShapeId

[proggeramlug]

Summary

• memoize typed object layouts by immutable runtime ShapeId
• bypass repeated authoritative shape-descriptor lookups after the slot-count proof is cached
• preserve per-instance field validation, ambiguity poisoning, moving-GC behavior, and keyless-object fallback
• add the cycles.ts issue reproducer, direct fast-path regression coverage, and the reviewed shape-census reduction

Performance

For benchmarks/issue-8289/cycles.ts, the median of five local runs dropped from 2.177B to 1.804B retired instructions (-17.1%) while preserving output (3999998000000).

Testing

• cargo test -p perry-runtime (2,572 passed, 4 ignored; doc tests: 7 ignored)
• focused shape-install memo tests after the final rebase (5 passed)
• RUSTFLAGS="-D warnings" cargo check -p perry-runtime --all-targets
• cargo fmt --all -- --check
• python3 scripts/shape_descriptor_census.py
• python3 scripts/raw_handle_debt.py
• git diff --check
• prior CI run: all six gap-suite shards and GC stress passed

No version or manifest files changed.

Refs #8289

Summary by CodeRabbit

• Performance

  • Improved allocation performance for classes containing pointer fields.
  • Reduced repeated validation and metadata processing when creating similar objects.
  • Benchmark results show approximately 17% fewer retired instructions in the targeted workload.

• Reliability

  • Preserved per-instance validation, fallback behavior for ambiguous layouts, and garbage-collection tracing.

• Testing

  • Expanded regression coverage for layout reuse, invalidation, pointer-mask handling, and unsupported layouts.

[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: 5fce0569-4155-4d67-88da-b99f6d5e2e37

📥 Commits

Reviewing files that changed from the base of the PR and between 95917cc and ce84122.

📒 Files selected for processing (1)

• changelog.d/8301-shape-id-typed-layouts.md

Included review availability: Your plan includes up to 8 reviews per rolling hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The runtime replaces keys_array pointer keys with immutable ShapeId keys for typed-layout descriptors and shape-install memoization. It adds probe-count validation, updates related tests and census data, and adds a cyclic allocation benchmark and changelog entry.

Changes

ShapeId typed-layout integration

Layer / File(s)	Summary
ShapeId descriptor lookup and installation crates/perry-runtime/src/gc/hot_tls.rs, crates/perry-runtime/src/gc/layout.rs, crates/perry-runtime/src/gc/layout/typed_shape.rs	Typed-layout maps and shared descriptor operations now use ShapeId values instead of keys_array pointers.
Shape-install memo identity crates/perry-runtime/src/gc/shape_install.rs	Memo entries, hashing, lookup, recording, counters, and tests now use ShapeId and preserve mask, dimension, invalidation, and pointer-mask behavior.
Regression validation and reported benchmark crates/perry-runtime/src/gc/tests/layout_trace/*, benchmarks/issue-8289/cycles.ts, scripts/shape_descriptor_census_baseline.json, changelog.d/8301-shape-id-typed-layouts.md	Tests verify descriptor-probe reuse and relocation behavior. The benchmark, census, and changelog record the updated implementation.

Estimated code review effort: 4 (Complex) | ~45 minutes

Merge Risk: ⚪ Minimal · up to ce841

This change memoizes typed layouts by immutable ShapeId while retaining the documented validation and GC behavior; no actionable merge-blocking risk remains after normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant TypedShapeInstaller
  participant ShapeInstallMemo
  participant SHAPE_LAYOUTS
  TypedShapeInstaller->>ShapeInstallMemo: Look up ShapeId and mask tuple
  ShapeInstallMemo-->>TypedShapeInstaller: Return cached state or miss
  TypedShapeInstaller->>SHAPE_LAYOUTS: Probe descriptor on miss
  SHAPE_LAYOUTS-->>TypedShapeInstaller: Return typed-layout descriptor
  TypedShapeInstaller->>ShapeInstallMemo: Record validated entry

Loading

Possibly related issues

• PerryTS/perry issue 8047: Replaces pointer-based typed-layout and shape-install memoization keys with immutable ShapeId values.

Possibly related PRs

• PerryTS/perry#6801: Provides stable ShapeId infrastructure used by this change.
• PerryTS/perry#6939: Directly relates to replacing keys_array pointer keys in typed-layout handling.
• PerryTS/perry#7535: Introduces the shape-install memo paths refined here.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the primary change: memoizing typed layouts by immutable ShapeId.
Description check	✅ Passed	The description explains the change, performance impact, related issue, testing, and restricted-file status, with sufficient detail despite omitting template headings and checklist items.
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

---

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

[proggeramlug]

Merging. Responsive to #8289, which named cycles as one of the four remaining Perry-vs-Node gaps with the largest instruction ratio (3.19× Node for 1.41× wall) — so it was the row I flagged as most likely tractable, and −17.1% instructions is a good bite out of it.

The invariants I wanted are all covered and passing, which matters because a layout memo keyed by an identifier is only sound if the identifier is stable and the memo yields to validation:

• ambiguity_poison_invalidates_the_memo — the invalidation path
• a_contradicting_field_is_refused_even_with_the_memo_warm — the memo does not override per-instance validation
• a_memo_hit_produces_the_same_header_state_as_the_install — hit and miss agree
• memo_installed_objects_survive_a_copying_minor_with_their_children
• test_shape_keyed_typed_layout_survives_copying_minor and ..._survives_layout_transfer — new, and these are the two that pin the ShapeId keying specifically across a move

Verified: perry-runtime --lib 2572/0/4, perry-codegen --no-fail-fast 28 suites, 1535 passed, 9 failed — all baseline, and all 47 lint gates via the new scripts/run_lint_gates.sh.

Two notes:

A flake, not a regression. One full-suite run showed r#box::release_tests::the_intrusive_free_list_round_trips_a_whole_cohort failing. It passes in isolation and on a re-run of the full suite, and passes on main. That test is from #8208's intrusive free list and looks order-dependent under parallel execution — worth a --test-threads=1 guard or explicit state reset before it bites someone as a phantom regression.

Census baseline: your later commit already refreshed it. For the record the delta is strictly removals — two raw keys_array reads gone, 184 → 182 sites — which is the memo doing its job.

One fix pushed: the changelog fragment was named 8289-… after the issue rather than the PR; renamed to 8301-.