Stack promotion: short-lived objects on the stack under every memory model

[ASDAlexander77]

Summary

An allocation whose object provably never outlives its function now goes in the function's stack frame instead of on the heap, under every memory model (gc, rc, own, none). It is automatic and silent: a site the analysis cannot prove safe stays on the heap exactly as before.

• What is promoted: class instances (new C(), and C(), which now means exactly the same), object literals with methods, array literals that never change length, and closure capture boxes (gc/none).
• How: a new StackPromotionPass runs at the affine level after own's inference. StackEscapeFacts computes, for every function in the module, whether each parameter may escape (to a fixpoint, with virtual calls resolved through the module's vtables). A promoted object is an entry-block block laid out like a heap block with an immortal header, so every retain, release and destroy leaves it alone. Under rc and own, the new ts.ReleaseContents op gives back what its fields own: at the allocation site with reset (for loop reuse) and before every return.
• Stays on the heap: returned, thrown, stored or converted objects; calls into other modules; functions with try, async, generators and recursion (including recursion through function values); loop-carried objects; objects over 256 bytes or past a 4096-byte frame budget; under rc/own, objects owning memory in a module that uses Shared (because Shared.count would see the later release).
• Flags: --no-stack-promotion, --stack-promotion-max-object=, --stack-promotion-max-frame=, --stack-promotion-report (per-site remark: stack, or heap: <reason>).

Design: tslang/docs/superpowers/specs/2026-10-18-stack-promotion-design.md. Plan, with the deviations listed: tslang/docs/superpowers/plans/2026-10-18-stack-promotion.md. User docs: docs/memory-models.md.

Measured

Milliseconds, best of three, --opt --opt_level=3, --no-stack-promotion → default:

program	gc	rc	own	none
vector temporaries (5M iterations)	18 → 20	296 → 16	287 → 27	27 → 20
ray tracer	342 → 341	153 → 170	—	182 → 157

The ray tracer under rc is about 8% slower and this is not understood. Only two one-time setup objects are promoted, the hot functions' IR is identical, and a build that runs the analysis but promotes nothing matches --no-stack-promotion.

Tests

• tslang/test/tester/stack-promotion/: a run test per program under all four models, plus a decision test per escape rule asserting the remark.
• Full ctest suite: 4599/4599 with promotion on, and 4599/4599 with the new TSLANG_TEST_NO_STACK_PROMOTION=ON option (every runner test built with --no-stack-promotion).
• Teeth: with the argument rule disabled, pass_to_keeper and ctor_keeps_this read dangling stack memory and fail under every model.

Follow-ups (not in this PR)

• Early-return and break uses inside a loop count as loop-carried.
• A directly called local closure keeps its heap box.
• The try-region exclusion is unnecessary under gc/none.
• Recursion detection should be one call-graph pass.
• Unrelated bug found while testing: truthiness of an any holding a class instance throws "uncaught exception".

🤖 Generated with Claude Code