Prometeu VM Runtime — Canonical Architecture Status: canonical This document is the authoritative architectural reference for the Prometeu VM runtime. It defines the invariants that govern architectural changes in the VM layer. Scope boundary: - PROMETEU itself is a fantasy handheld / fantasy console with a broader machine model, firmware model, cartridge model, and virtual hardware surface. - This document does not define the whole PROMETEU machine. - This document defines the VM/runtime subsystem that executes bytecode inside that machine. - For broader machine-level framing, see [`../specs/README.md`](../specs/runtime/README.md). Document roles: - This file is normative for VM/runtime architecture. - Detailed domain specifications may live under `docs/specs/runtime/`, but they must not contradict this document where VM/runtime invariants are concerned. - Future architectural changes become authoritative when this document is updated. - The machine-wide fantasy console framing lives in the runtime specs manual and related domain specs; those documents are complementary, not competing VM architecture sources. Maintenance rule: - Any PR that changes VM/runtime architectural invariants must update this document in the same change. 1. Overview ----------- - Stack‑based virtual machine - Operand stack + call frames; bytecode is fetched from a ROM/program image with a separate constant pool. - GC‑managed heap - Non‑compacting mark–sweep collector; stable object handles (`HeapRef`) while live. Sweep invalidates unreachable handles; objects are never moved. - Typed first-class Fn - Structural logical parameter/result signatures and heap Closure environments retained by CallFrames, without hidden arg0. - Single execution context - VM directly owns PC, stacks and globals; no heap Coroutine or guest scheduler. GC opportunities are FRAME_SYNC and successful last-root RET after result rooting. - Unified syscall ABI - PBX pre-load artifacts declare canonical host bindings in `SYSC` and encode call sites as `HOSTCALL `. The loader resolves and patches them to numeric `SYSCALL ` before verification/execution. Capability gating is enforced at load and checked again defensively at runtime. Syscalls are not first‑class values. 2. Memory Model ---------------- 2.1 Stack vs Heap - Stack - Each running context has an operand stack plus call frames (locals, return bookkeeping). Primitive values (integers, floats, booleans) reside on the stack. Heap objects are referenced by opaque `HeapRef` values on the stack. - The VM’s current operand stack and frames are GC roots. - Heap - The heap stores runtime objects that require identity and reachability tracking. Handles are `HeapRef { index: u32, generation: u32 }` values into an internal object store. Every access checks the live generation; reclaimed maximum-generation slots are retired permanently. - The collector is mark–sweep, non‑moving: it marks from roots, then reclaims unreachable objects without relocating survivors. Indices for live objects remain stable across collections. 2.2 Heap Object Kinds (as used today) - Typed arrays - Variable-length arrays use the Registry element layout and defaults. Primitive/builtin values are stored directly; Struct/Array elements contain generational references. Native String/Dynamic slots retain their ownership rules. Stack/local execution continues to use `Value`. - Closures - Carry a function identifier and a captured environment (a slice/vector of `Value`s stored with the closure). Captured `HeapRef`s are traversed by the GC. - Structs and Dynamic boxes - Typed payloads use resolved reference/ownership maps. Private Struct cells can share mutable captured bindings. Notes: - Literals like strings and numbers are sourced from the constant pool in the program image; heap allocation is only used for runtime objects (closures, arrays, Structs and Dynamic boxes). The constant pool never embeds raw `HeapRef`s. 2.3 GC Roots - Roots comprise globals, all live operand values, Closure owners in every active CallFrame and legally retained native/host roots. Inspection snapshots are not guest roots. Tracing visits complete typed fields, arrays, captures and cells. - Root results are transferred/rooted before the last frame is removed or GC runs, and remain owned until consumed/replaced/reset/unloaded. Unreachable cycles collect. 3. Execution Model ------------------- 3.1 Interpreter Loop - The VM runs a classic fetch–decode–execute loop over the ROM’s bytecode. The current program counter (PC), operand stack, and call frames define execution state. - Function calls establish new frames; returns restore the caller’s frame and adjust the operand stack to the callee’s declared return slot count (the verifier enforces this shape statically). - Errors - Traps (well‑defined fault conditions) surface as trap reasons; panics indicate internal consistency failures. The VM can report logical frame endings such as `FrameSync`, `BudgetExhausted`, `Halted`, end‑of‑ROM, `Breakpoint`, `Trap(code, …)`, and `Panic(msg)`. 3.2 Safepoints - Threshold GC opportunities are FRAME_SYNC and successful RET of the last root, after result rooting. Ordinary callee RET, entry preparation, syscalls and allocation/quota refusal do not collect. GC adds no guest callback, clock/frame advance, budget grant or partial sweep on scratch failure. 3.3 Single Context and Host Continuation - FRAME_SYNC may occur in any body, has no stack effect and resumes next PC with live frames/locals/environments. It closes the logical frame but does not restart entry. Budget exhaustion/breakpoints preserve the same open logical frame. - Last-root RET completes entry. Recurring host prepares FunctionId 0 next frame, preserving globals/init guard; preparation validates/reserves before replacing previous owners and allocates no Coroutine. HALT/trap/reset/unload retain their contracts. Render/asset workers remain independent of guest execution. - SPAWN/YIELD/SLEEP are retired: numbers 0x54–0x56 stay reserved and all uses reject at load, including unreachable code. No compatibility scheduler remains. 4. Verification Model ---------------------- 4.1 Verifier Responsibilities The verifier statically checks bytecode for structural safety and stack‑shape correctness. Representative checks include: - Instruction well‑formedness - Unknown opcode, truncated immediates/opcodes, malformed function boundaries, trailing bytes. - Control‑flow integrity - Jump targets within bounds and to instruction boundaries; functions must have proper terminators; path coverage ensures a valid exit. - Stack discipline - No underflow/overflow relative to declared max stack; consistent stack height at control‑flow joins; `RET` occurs at the expected height. - Call/return shape - Direct calls and returns must match the declared argument counts and return slot counts. Mismatches are rejected. - Syscalls - The verifier runs only on the patched executable image. `HOSTCALL` is invalid at verification time. Final `SYSCALL` IDs must exist per `SyscallMeta`, and arity/declared return slot counts must match metadata. - Closures - Expected FnTypeId determines complete parameter/result groups even when the concrete FunctionId is unknown. Known mismatch rejects; Unknown retains runtime checks. Capture indices and target metadata are checked, and direct entry into capturing bodies rejects. - Trait calls - Exact method signatures and complete views resolve through immutable tables; concrete receiver is the first callee parameter, with no capture environment. 4.2 Runtime vs Verifier Guarantees - The Registry verifier checks structure and stack shape and conservatively tracks known types through control flow. It rejects proved incompatibilities; Unknown values retain runtime checks at typed boundaries. Numeric domain checks, polymorphic comparisons and concrete syscall argument validation may still trap at runtime. - Capability gating for syscalls is enforced at load from cartridge capability flags and checked again at runtime by the VM/native interface. 5. Typed Fn and Environments ---------------------------- - Fn identity is ordered logical parameter/result TypeIds; names, target and captures are metadata. Pure Array/Fn structural cycles reject; nominal anchors stop expansion. - MAKE_CLOSURE takes FunctionId/FnTypeId, captures full declared groups and pushes a distinct one-slot instance. Immutable bindings copy values; mutable bindings can share private typed Struct cells. Metadata lives in required PBX section 8. - CALL_CLOSURE takes expected FnTypeId and retains the Closure in CallFrame, without public arg0. GET_CAPTURE takes an index and copies a complete group. Direct calls to capturing bodies reject; bound receivers use explicit adapter bodies. - Fn is valid in Struct/Array/Dynamic, defaults Null and compares instance identity. It gains no REF_* casts, Trait implementations, fault isolation or separate budget. - Validate/reserve before consume/publication; faults preserve input owners and expose no partial frame/object. Costs are 8+C / 6 / 2+W including traps, charged once. - CALL_TRAIT takes TraitTypeId/method index, consumes explicit args and a complete view, then passes concrete receiver first. Exact immutable-table dispatch costs 6. 6. Unified Syscall ABI ----------------------- - Identification - Host bindings are declared canonically as `(module, name, version)` in PBX `SYSC`, then executed as numeric IDs after loader patching. Syscalls are not first‑class values. - Metadata‑driven - `SyscallMeta` defines expected arity and return slot counts. The loader resolves `HOSTCALL` against this metadata and rejects raw `SYSCALL` in PBX pre-load artifacts; the verifier checks final IDs/arity/return‑slot counts against the same metadata. - Arguments and returns - Arguments are taken from the operand stack in the order defined by the ABI. Returns use multi‑slot results via a host‑side return buffer (`HostReturn`) which the VM copies back onto the stack, or zero slots for “void”. A mismatch in result counts is a fault/panic per current hardening logic. - Example: the canonical asset runtime load surface is `asset.load(asset_id, slot) -> (status, handle)`. The caller does not supply `asset_name` or `asset_type`; bank kind is derived from `asset_table` using `asset_id`. - Capabilities - Cartridge capability flags are applied before load-time host resolution. Missing required capability aborts load; invoking a syscall without the required capability also traps defensively at runtime. 7. Garbage Collection ---------------------- - Collector - Non‑moving mark–sweep. - Triggers - Threshold GC runs at FRAME_SYNC and successful last-root RET after result rooting. - Liveness - Globals, live operand values and active-frame Closures root complete typed object graphs, including cells and legally retained host/native owners. - Determinism - Opportunities depend on execution boundaries and thresholds, preserving deterministic guest execution with the same inputs. 8. Non‑Goals ------------- - No RC - No HIP - No preemption - No mailbox 9. Notes for Contributors -------------------------- - Keep the public surface minimal and metadata‑driven (e.g., syscalls via `SyscallMeta`). - Preserve explicit GC opportunities and root results before root-return collection. - When adding new opcodes or object kinds, extend the verifier and GC traversal accordingly (children enumeration, environment scanning, root sets). - Update this document alongside any architectural change that affects runtime invariants. ## Program Registry The [Program Registry contract](../specs/runtime/02c-program-registry-and-pbx-v0.md) defines immutable image-owned Type/Function metadata linked by dense IDs. Descriptors are native metadata outside guest GC; nominal identity does not depend on names. Stack/local execution retains Value, while typed storage uses resolved aligned layouts. PBX v0 is the sole target format; publication requires full bounded validation. Fn tag 4 and mandatory captures section 8 extend the Registry; no old-schema fallback is permitted. `ValidatedProgramImage::load` publishes a shared image only after bounded decoding, native binding and Registry verification; `VirtualMachine::from_image` creates sessions that consume its typed signatures, constants and conversion instructions. Production and internal generators must use this sole sealed-v1 path. Typed Fn integration and legacy removal are implemented together; publication alone is not proof that every consumer has migrated. [Registry Boundaries and Owned Values](../../discussion/lessons/DSC-0058-program-registry-type-and-function-metadata/LSN-0059-registry-boundaries-and-owned-values.md) explains the published mechanisms. The [producer handoff](registry-producer-handoff.md) documents schema, input IDs and named-argument order, while [layout evidence](registry-layout-evidence.md) records reproducible load/access/GC measurements and the current publication boundary. ## VM-owned random core See the [random contract](../specs/runtime/02e-vm-owned-random-core.md) for Random BuiltinId 0x0016, ObjectKind tag 9, intrinsics 0x4000–0x4003, atomic state mutation, bounded 4+8*N costs and rejection-limit trap 0x00000015. Random is managed by the VM heap and existing GC, without host entropy or PBX changes. ## Atomic publication of multiple Struct instances FIELDS_PUBLISH (0xAB) atomically publishes complete typed fields to multiple source-selected Struct destinations. Its schema is an ordinary Registry Struct; no new category, request object, syscall or safepoint is introduced. Exact nullable destination rules, stack effects, validation, costs and commit semantics are in the [canonical instruction contract](../specs/runtime/02-vm-instruction-set.md#atomic-publication-of-multiple-struct-instances).