prometeu-runtime/docs/specs/03-memory-stack-heap-and-allocation.md

Memory Model

Domain: VM memory model Function: normative

This chapter defines the VM memory architecture: stack, heap, handles, object layout, allocation, and garbage collection.

It intentionally focuses on VM-managed memory.

Host-owned memory surfaces such as asset banks and persistent save storage are covered by their own domain specs and by the host ABI docs.

1 Overview

The PVM memory model is based on:

• stack-resident execution values;
• heap-resident objects;
• validated handles for indirect heap access;
• GC-managed object lifetime.

2 Stack Memory

The stack stores transient execution values and frame-scoped data.

Stack value types

The stack may contain:

• primitive values;
• built-in fixed-layout values;
• heap handles;
• tuple-shaped multi-return values.

See 02a-vm-values-and-calling-convention.md for the slot/value model.

Stack properties

• stack values are local to execution state;
• stack discipline is verifier-sensitive;
• stack underflow and invalid access are traps.

3 Heap Memory

The heap stores runtime objects that require identity and reachability tracking.

Heap characteristics

• user objects live in the heap;
• arrays and closures live in the heap;
• heap access is indirect through handles;
• the collector is non-moving in the baseline model.

4 Handles and Gate Table

All heap objects are accessed via handles.

A conceptual handle:

handle = { index, generation }

Conceptual gate entry:

GateEntry {
    alive: bool
    generation: u32
    base: usize
    slots: u32
    type_id: u32
}

Handle safety

When an object is freed:

• alive becomes false;
• generation is incremented.

When a handle is used:

• the index must exist;
• the generation must match;
• invalid or stale handles trap.

This prevents:

• use-after-free;
• stale references;
• hidden raw memory access.

5 Object Layout

Heap objects use explicit, implementation-visible layout rules.

Conceptual form:

Object {
    type_id
    field_0
    field_1
    ...
}

Properties:

• fields are stored in slot order;
• there is no raw pointer arithmetic in the VM model;
• layout rules are explicit and verifier/runtime-friendly.

Closures and coroutine-owned state may build on top of this memory model, but their behavioral rules are documented separately:

• 02b-vm-function-values-and-closures.md
• 09a-coroutines-and-cooperative-scheduling.md

6 Garbage Collection

The PVM uses a mark-sweep collector.

GC properties

• non-moving in the baseline model;
• runs only at safepoints;
• primary safepoint: FRAME_SYNC.

GC triggers

GC may run when:

• heap usage exceeds threshold;
• allocation pressure is high.

Root set

The collector marks from:

• operand stack;
• call stack frames;
• global variables;
• coroutine-owned execution state;
• closure environments;
• host-held roots where the host legally retains VM heap references.

7 Allocation and Deallocation

Allocation

Heap allocation conceptually performs:

1. reserve object storage;
2. create or reuse gate entry;
3. return validated handle.

If allocation fails:

• the VM may trigger GC;
• if pressure remains unresolved, allocation may trap or fail according to the runtime contract.

Deallocation

Objects are reclaimed by GC.

When reclaimed:

• the gate is marked dead;
• the generation is incremented;
• storage becomes reusable.

8 Memory Safety Rules

The VM enforces:

1. all heap access goes through handles;
2. generation checks validate handle freshness;
3. object and field access is bounds-checked;
4. there is no guest-visible raw pointer arithmetic;
5. stack discipline remains verifier-constrained.

Any violation results in a trap or rejected program image.

9 Relationship to Other Specs

• 02a-vm-values-and-calling-convention.md defines stack values and tuple/call-slot semantics.
• 02b-vm-function-values-and-closures.md defines closure function values.
• 09a-coroutines-and-cooperative-scheduling.md defines coroutine state and scheduling behavior.
• 15-asset-management.md defines asset-bank surfaces outside VM heap ownership.
• 08-save-memory-and-memcard.md defines save storage outside VM heap ownership.
• 16a-syscall-policies.md defines host-root rules and host/heap interaction policy.