Files
prometeu-runtime/docs/specs/runtime/03-memory-stack-heap-and-allocation.md
T
bquarkz dcf6561ea7
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
refactor(vm)!: remove publication and logical guard opcodes
Remove INDEX_GUARD, ARRAY_CHECK_LENGTH, STORAGE_PUBLISH and FIELDS_PUBLISH
from decoding, metadata, tooling, verification and execution. Keep ARRAY_LEN
and overlap-safe ARRAY_COPY with complete-group ownership and early charging
of calculable copy work, including refused attempts.

Update specifications, producer handoff, qualification evidence and lessons.
Share collection test support and remove redundant Copy clones for Clippy.

Validation: make ci-domains passed with 1,095 workspace tests, five separately
executed debugger socket tests and all 15 unchanged coverage domain gates.
VM release, resource diagnostics and layer/quality suites also passed.

BREAKING CHANGE: PBX using opcodes 0xA7, 0xA8, 0xAA or 0xAB is rejected,
including unreachable instructions. Consumers must adapt their emission and
collection algorithms or operational guarantees.
2026-10-23 23:37:56 +01:00

10 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:

  • alive becomes false;
  • generation is 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_SYNC and successful last-root RET, 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:

  1. reserve object storage;
  2. create or reuse gate entry;
  3. 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:

  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

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.

Prepared array range copy

ARRAY_COPY reserves all copy scratch against TemporaryBytes and captures complete source groups before changing any destination. Preserve Dynamic tags, immutable boxes, native String owners, HeapRefs and trait groups without boxing or new guest objects/request tokens. Operands remain roots; commit has no allocation, fallible validation, callback, GC or scheduler boundary. No rescue GC is performed. Failure preserves destinations and operands and releases provisional scratch; success also releases scratch, then consumes the five operands. Charged cycles are never refunded. Overlap reads the pre-attempt source sequence, without an identity discount. Earlier instructions retain their effects; multiple ordinary stores do not form a transaction. See the instruction contract.

Borrowed intrinsic invocation

The bounded intrinsic profile keeps original arguments/owners rooted until result validation and stack commit. Hash intrinsics use no guest allocation, dynamic scratch or stack growth; native output storage is bounded by the declared result layout. They do not collect, reenter or call guest code. Hash values create no roots. Legacy intrinsic resource/effect contracts remain explicit and do not inherit these guarantees.