8.7 KiB
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;
- string 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:
alivebecomes false;generationis incremented, or the slot is permanently retired after its maximum-generation incarnation; generation must never wrap.
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 use declared-order typed offsets with alignment and padding; stack Value slots are not the heap layout;
- there is no raw pointer arithmetic in the VM model;
- layout rules are explicit and verifier/runtime-friendly.
Closures and frame-owned environments use this memory model; their behavioral rules are documented separately:
6 Garbage Collection
The PVM uses a mark-sweep collector.
GC properties
- non-moving in the baseline model;
- runs only at safepoints;
- threshold opportunities:
FRAME_SYNCand successful last-rootRET, after rooting results.
GC triggers
GC may run when:
- the configured allocation threshold is reached at an established safepoint.
Root set
The collector marks from:
- operand stack;
- call stack frames;
- global variables;
- closure environments;
- host-held roots where the host legally retains VM heap references.
7 Allocation and Deallocation
Allocation
Heap allocation conceptually performs:
- reserve object storage;
- create or reuse gate entry;
- return validated handle.
First materialization cost is distinct from repeated hot-path copy pressure.
Implications:
- constant-pool-backed values may pay materialization cost before execution begins;
- runtime-created values may pay materialization cost when a new value is semantically produced;
- the runtime SHOULD minimize repeated implicit copying on hot paths after that first materialization;
- zero-allocation happy-path work is an engineering optimization target, not a published compatibility guarantee by itself.
If allocation fails:
- the attempt refuses with the applicable structured resource fault;
- it does not trigger reentrant GC or scheduling to satisfy its quota.
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:
- all heap access goes through handles;
- generation checks validate handle freshness;
- object and field access is bounds-checked;
- there is no guest-visible raw pointer arithmetic;
- 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.mddefines stack values and tuple/call-slot semantics.02b-vm-function-values-and-closures.mddefines closure function values.09a-coroutines-and-cooperative-scheduling.mddefines direct execution ownership and frame continuation.15-asset-management.mddefines asset-bank surfaces outside VM heap ownership.08-save-memory-and-memcard.mddefines save storage outside VM heap ownership.16a-syscall-policies.mddefines host-root rules and host/heap interaction policy.
Program Registry integration
Program Registry and PBX v0 specifies compact typed layouts, defaults, native String/Dynamic ownership and generational handles. Its memory quotas apply jointly before allocation. Registry metadata is immutable image-owned native memory, outside guest GC. Stack/local execution retains Value.
Typed Array and Struct Storage
Registry-backed Arrays have fixed u32 lengths; Structs have mutable declared fields. Instances use resolved aligned offsets/strides and ownership maps. Builtins remain inline; Struct/Array fields and elements hold references. Copies preserve identity and aliasing, including nested arrays. List, Set and Map policies and implementations belong to each language SDK, composed from runtime Array capabilities.
NEW fully initializes all storage before publishing a handle: primitive/builtin canonical zeros, null String and concrete references, absent Trait [Null, Null], and untyped-null Dynamic [Null, Null]. Empty instances remain valid identities. No source constructor, callback or referenced instance/subarray is invoked or allocated implicitly. A frontend may root a default instance, store fields and call its own constructor.
GET copies a complete group and native owners without implicit boxing; SET validates the entire group before replacing it. String copies retain Arc ownership/provenance/accounting; null and empty String differ. Trait stores receiver and ImplementationId together (zero is a valid implementation); Dynamic preserves its complete pair and shares existing immutable boxes.
After validation, an attempt provisionally reserves net stack growth and construction resources, keeping source operands/roots alive. It prepares complete defaults/results before publication. Commit replaces the whole stored group or publishes the complete result, then consumes operands. No fallible reservation/allocation follows publication. Refusal preserves operands and prior storage/owners, publishes no partial handle, and releases provisional reservations/owners. Attempted work/cycles are retained; preexisting auxiliary capacities follow their existing growth contract. NEW never invokes reentrant GC or scheduling to satisfy quota. GC remains confined to established safepoints; live transitively rooted graphs and native owners survive them, while unrooted cycles become reclaimable.
Typed Fn and Root-Return Collection
Threshold GC opportunities are FRAME_SYNC and successful RET of the last root, after results are transferred and rooted. No automatic GC at ordinary callee RET, entry preparation or allocation/quota refusal. VM owns its single execution context directly. Roots include globals, all live operand values, Closures retained by every active CallFrame and legally retained native/host roots. Trace complete typed capture/cell graphs; unreachable cycles collect. Inspection snapshots and raw handle copies create no guest root or session import. Results remain roots until consumed/replaced/reset/unload. Scratch refusal preserves owners and prohibits partial sweep.
Random core integration
Random objects use ObjectKind tag 9 (tag 6 remains reserved), 32 logical payload bytes and quota-accounted headers/handles/auxiliary storage. They are opaque GC leaves; Dynamic holds their direct reference and exact TypeId.