Stack, Region, Arena, And Escape Promotion

Allocation promotion moves values away from the general heap only when the

compiler has a checked lifetime proof. The default is conservative: keep a

value on the heap unless escape, alias, ownership, closure, actor,

host-buffer, and FFI evidence proves a cheaper domain is safe.

Run:

make region-arena-promotion-check
make escape-analysis-check

make escape-analysis-check runs make region-arena-promotion-check before

the existing escape-analysis evidence. That keeps heap-elision decisions tied

to the same escape facts used by the optimizer.

Evidence Files

• allocation-promotion/escape-categories.tsv defines the escape categories

that can permit or block promotion.

• allocation-promotion/promotion-domains.tsv defines scalar, stack, region,

arena, heap, and dynamic-heapification domains.

• allocation-promotion/scalar-replacement.tsv records aggregate scalar

replacement decisions.

• allocation-promotion/stack-promotions.tsv records frame-local stack

promotion decisions.

• allocation-promotion/region-arena-scopes.tsv records bounded region and

arena lifetimes.

• allocation-promotion/heapification-policy.tsv records the narrow cases

where a promoted value may be dynamically heapified.

• allocation-promotion/diagnostics.tsv defines stable diagnostics.
• allocation-promotion/verification-cases.tsv records positive and negative

fixtures.

• release/allocation-promotion-decisions.tsv is the release decision ledger.
• release/allocation-promotion-lifetime-report.tsv records lifetime and

release-point checks.

• release/allocation-promotion-stress-report.tsv records behavior-preserving

stress coverage.

• release/allocation-promotion-diagnostics-report.tsv records rejected

promotion diagnostics.

• perf/allocation-promotion-benchmarks.tsv records allocator-traffic

reductions and analysis budgets.

• compat/allocation-promotion-contract.tsv records release ownership and

gate wiring.

• tools/allocation-promotion-check.py validates the evidence and fixtures.

Promotion Domains

The promotion domains are:

• scalar: the aggregate is split into fields and materialization is elided;
• stack: the value is frame-local and cannot survive the function return;
• region: the value lives inside a named bounded runtime scope;
• arena: the value lives inside a bulk-release arena such as compiler scratch

storage or request-local app runtime state;

• heap: the conservative fallback;
• dynamic-heapification: an explicit target-gated fallback for a value that

may start in a cheaper domain but must be heapified before a proven escape.

Dynamic heapification is not a general escape hatch. It is allowed only when a

target has explicit heapification proof and release evidence.

Escape Categories

Promotion is invalidated by:

• unknown or volatile aliasing;
• unknown, borrowed, or escaped ownership;
• escaping closures;
• actor-boundary crossing;
• host-retained buffers;
• unknown FFI behavior;
• process, host, or unknown lifetimes without a matching release point.

The gate fails closed when any of these categories contradicts the chosen

target domain.

Diagnostics

The promotion gate uses stable diagnostics:

ALLOCATION_PROMOTION_LIFETIME
ALLOCATION_PROMOTION_ALIAS
ALLOCATION_PROMOTION_OWNERSHIP
ALLOCATION_PROMOTION_CLOSURE
ALLOCATION_PROMOTION_ACTOR
ALLOCATION_PROMOTION_HOST_BUFFER
ALLOCATION_PROMOTION_FFI
ALLOCATION_PROMOTION_SCALAR
ALLOCATION_PROMOTION_STACK
ALLOCATION_PROMOTION_REGION
ALLOCATION_PROMOTION_HEAPIFY

ALLOCATION_PROMOTION_STACK means a stack-targeted value is not frame-local.

ALLOCATION_PROMOTION_HEAPIFY means the target lacks proof for dynamic

heapification or heap traffic regressed after promotion.

Documentation Impact

Allocation promotion, region lifetime, arena lifetime, scalar replacement,

dynamic heapification, or escape diagnostic changes must update this page, the

source-owned promotion evidence, release notes, and the public reference index

in the same change.