perf(repsel): admit logical return-shape producers (#7170 R2)

[proggeramlug]

Summary

Admit short-circuiting && / || expressions as Ptr<Shape> return producers when every value that can escape the complete expression is a fresh allocation of one admissible class. This is the logical-expression producer increment identified by #7170's post-R1 measurement.

Changes

• Model fresh, non-fresh truthy, and non-fresh falsy outcomes through nested conditional and logical return expressions.
• Admit deterministic and fallback forms such as true && new C() and (flag && new C()) || new C().
• Fail closed when a primitive or unknown operand can escape, when reachable allocation classes disagree, and for ?? pending a nullish-specific outcome partition.
• Keep optimization-report accounting aligned with the producer proof, marking only allocations that can actually become the logical result as served.
• Add positive, nested, primitive-escape, consumed-operand, nullish, caller-seeding, and report-classification coverage.

The proof continues to use the existing class-admission, containment, module-barrier, caller-slot, and rooting machinery. It introduces no new pointer position or ABI change.

Related issue

Refs #7170 (R2 logical producer increment; the broader issue remains open for cross-module and method-call consumers).

Test plan

• cargo check --profile perry-dev -p perry-codegen
• cargo test --profile perry-dev -p perry-codegen --lib ptr_shape_returns --no-fail-fast (35 passed)
• cargo test --profile perry-dev -p perry-codegen --lib 'ptr_shape::opt_report_tests' --no-fail-fast (22 passed)
• ./scripts/test_affected_crates.sh --base origin/main (perry: 959 passed; perry-codegen: 950 passed)
• cargo fmt --all --check
• git diff --check
• ./scripts/pre-tag-check.sh --quick has one pre-existing failure on unchanged crates/perry-codegen/src/expr/property_set.rs:1457 in the GC store-site inventory; every other quick check passed
• Added or updated #[test] coverage in the affected crate
• Docs update not required: no CLI, stdlib, runtime API, or user-facing syntax changed
• Platform UI build not applicable

Checklist

• I have NOT bumped the workspace version or edited CLAUDE.md / CHANGELOG.md
• My commits follow the repository's commit-prefix convention
• I've read CONTRIBUTING.md and agree to the Code of Conduct

Summary by CodeRabbit

• New Features

  • Improved optimization analysis for functions returning freshly allocated objects through && and || expressions.
  • Supports nested logical fallbacks when all possible returned objects share the same compatible shape.
  • Optimization reports now identify only allocations that can become the logical result.

• Bug Fixes

  • Prevents consumed, primitive, unknown, mismatched, and nullish-coalescing values from being incorrectly treated as returned objects.

• Tests

  • Added coverage for deterministic, nested, incomplete, and short-circuited logical-expression scenarios.

[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: a270dd68-e103-4bb6-8e79-239d3a4c5499

📥 Commits

Reviewing files that changed from the base of the PR and between 2d6633f and b9c8e8f.

📒 Files selected for processing (5)

• changelog.d/8015-logical-return-shapes.md
• crates/perry-codegen/src/collectors/ptr_shape_opt_report_tests.rs
• crates/perry-codegen/src/collectors/ptr_shape_report.rs
• crates/perry-codegen/src/collectors/ptr_shape_returns.rs
• crates/perry-codegen/src/collectors/ptr_shape_returns_tests.rs

---

📝 Walkthrough

Walkthrough

The change adds Ptr<Shape> return-shape inference for fresh allocations in && and || expressions. It tracks truthy and falsy outcomes, rejects unsupported paths, and updates optimization reporting to mark only result-producing allocations.

Changes

Return-shape analysis and reporting

Layer / File(s)	Summary
Fresh outcome analysis crates/perry-codegen/src/collectors/ptr_shape_returns.rs	The collector models truthy and falsy logical paths, identifies fresh return sources, preserves class agreement checks, and keeps ?? and unsupported expressions fail-closed.
Returned allocation reporting crates/perry-codegen/src/collectors/ptr_shape_report.rs	Return scanning uses possible_return_shape_new_sources and traverses conditional and logical result operands while excluding conditions and consumed short-circuit operands.
Logical return-shape tests and documentation crates/perry-codegen/src/collectors/ptr_shape_returns_tests.rs, crates/perry-codegen/src/collectors/ptr_shape_opt_report_tests.rs, changelog.d/8015-logical-return-shapes.md	Tests cover nested fallbacks, consumed allocations, incomplete paths, nullish coalescing, caller seeding, and optimization-report output. The changelog documents the behavior.

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

Mergeability Score: ⚪ Minimal · up to b9c8e

This change is merge-ready after normal checks and review; no actionable merge-blocking risk remains.

Sequence Diagram(s)

sequenceDiagram
  participant ReturnExpression
  participant ptr_shape_returns
  participant ptr_shape_report
  participant OptReport
  ReturnExpression->>ptr_shape_returns: analyze && or || return outcomes
  ptr_shape_returns-->>ptr_shape_report: provide fresh result allocations
  ptr_shape_report->>OptReport: mark result-producing allocations

Loading

Possibly related PRs

• PerryTS/perry#7037: Introduced the --opt-report functionality extended by this change.
• PerryTS/perry#7107: Added the related Ptr<Shape> return-shape analysis that this change expands.
• PerryTS/perry#8007: Added conditional-expression support in the same return-shape analysis and reporting paths.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the main change: admitting logical return-shape producers for performance-related representation selection.
Description check	✅ Passed	The description covers the required summary, changes, related issue, test plan, and checklist, including the documented pre-existing test failure.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch perf/7170-logical-return-shapes

---

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]

Review complete: no blocking correctness finding. The truthy/falsy outcome partition matches JavaScript operand-value semantics for &&/||, fresh allocations are correctly treated as truthy, unsupported and nullish cases remain fail-closed, and opt-report source selection stays aligned with the producer proof. Local focused validation passed: 35 return-shape tests and 22 opt-report tests. The gc-ptr-shape-off-witness CI failure still had byte-exact Node parity in 23/23 cells; its failure was the independent liveness requirement (zero moving cells), not a behavioral mismatch from this diff.