# Prometeu Virtual Machine (PVM) Domain: VM subsystem overview Function: normative This chapter defines the VM as an execution subsystem inside the PROMETEU machine. It is intentionally narrower than the broader machine specs: - execution model; - opcode families; - verifier boundary; - relationship between the VM and adjacent specs. For the bytecode-level instruction contract, see [`../virtual-machine/ISA_CORE.md`](../../vm-arch/ISA_CORE.md). ## 1 Scope The PVM is a **deterministic, stack-based VM** designed for a fantasy console environment with fixed frame timing and explicit hardware-facing services. This chapter does not fully restate: - detailed value and calling semantics; - heap/gate/GC internals; - coroutine scheduling internals; - host ABI policy. Those now live in focused companion specs: - [`02a-vm-values-and-calling-convention.md`](02a-vm-values-and-calling-convention.md) - [`02b-vm-function-values-and-closures.md`](02b-vm-function-values-and-closures.md) - [`03-memory-stack-heap-and-allocation.md`](03-memory-stack-heap-and-allocation.md) - [`09a-coroutines-and-cooperative-scheduling.md`](09a-coroutines-and-cooperative-scheduling.md) - [`16-host-abi-and-syscalls.md`](16-host-abi-and-syscalls.md) - [`16a-syscall-policies.md`](16a-syscall-policies.md) ## 2 Core Design Principles The PVM is designed around the following constraints: 1. **Deterministic execution**: no hidden threads or asynchronous callbacks. 2. **Frame-based timing**: execution is bounded by frame time and explicit safepoints. 3. **Safe memory model**: heap access is mediated by validated handles. 4. **Simple compilation target**: stack-based bytecode with verified control flow. 5. **Stable ABI**: calls and syscalls follow fixed slot-based contracts. 6. **First-class functions**: user function values are represented through closures. ## 3 Execution Model The PVM executes bytecode inside the PROMETEU frame loop. Each frame: 1. firmware enters the VM; 2. the VM runs until: - the frame budget is consumed; or - a `FRAME_SYNC` instruction is reached; 3. at `FRAME_SYNC`, the VM reaches the primary safepoint for GC and cooperative scheduling; 4. control returns to firmware/runtime orchestration. `FRAME_SYNC` is the primary VM synchronization point. It is the boundary where the machine can safely account for: - GC opportunity; - coroutine handoff; - frame-completion semantics; - deterministic return to firmware. ## 4 Instruction Families The public VM instruction surface is documented at the bytecode level in [`../virtual-machine/ISA_CORE.md`](../../vm-arch/ISA_CORE.md). At the machine/spec level, the instruction families are: - execution control: - `NOP`, `HALT`, `JMP`, `JMP_IF_FALSE`, `JMP_IF_TRUE`, `TRAP`, `FRAME_SYNC` - stack manipulation: - `PUSH_CONST`, literal pushes, `POP`, `POP_N`, `DUP`, `SWAP` - arithmetic and logic: - numeric, comparison, boolean, and bitwise operations - variable access: - globals and locals - function calls: - `CALL`, `RET` - function values: - `MAKE_CLOSURE`, `CALL_CLOSURE` - cooperative concurrency: - `SPAWN`, `YIELD`, `SLEEP` - VM/host boundary: - `HOSTCALL`, `SYSCALL`, `INTRINSIC` The machine-level rule is simple: - opcodes define explicit behavior; - there are no hidden execution paths; - timing-sensitive behavior is exposed through frame and safepoint semantics. ## 5 Verifier Boundary Before execution, bytecode must pass the verifier. The verifier ensures, at minimum: 1. valid instruction decoding; 2. valid jump targets; 3. consistent stack depth across control-flow joins; 4. valid call/return shape; 5. closure call safety rules; 6. patched syscall and intrinsic validity. The verifier is structural. It does not replace runtime validation of dynamic values. ## 6 Relationship to Adjacent Specs - [`02a-vm-values-and-calling-convention.md`](02a-vm-values-and-calling-convention.md) defines slot values, tuples, frames, and return-slot semantics. - [`02b-vm-function-values-and-closures.md`](02b-vm-function-values-and-closures.md) defines closure representation and function-value behavior. - [`03-memory-stack-heap-and-allocation.md`](03-memory-stack-heap-and-allocation.md) defines stack/heap, handles, object layout, and GC. - [`09-events-and-concurrency.md`](09-events-and-concurrency.md) defines events, timers, and the frame boundary model. - [`09a-coroutines-and-cooperative-scheduling.md`](09a-coroutines-and-cooperative-scheduling.md) defines coroutine lifecycle and scheduling. - [`16-host-abi-and-syscalls.md`](16-host-abi-and-syscalls.md) defines the syscall ABI boundary. ## 7 Summary The PVM is: - stack-based; - deterministic; - frame-synchronized; - verifier-gated; - closure-capable; - coroutine-capable; - embedded inside the larger PROMETEU console model, not equal to it. ## Program Registry v1 integration [Program Registry and PBX v1](02c-program-registry-and-pbx-v1.md) defines typed immediate domains, opcodes 0x0090–0x0096, complete multi-slot groups and conservative type-flow verification. Unknown facts require runtime validation and do not alone reject an otherwise valid join. Opcode bytes remain u16; TypeId immediates are u32 little-endian. ## Typed Collection Instructions These instructions require a validated Program Registry. Opcodes are u16 little-endian; TypeId and field immediates are u32 little-endian. T is the receiver descriptor, F its declared field type, E its Array element type. Stack order below is bottom to top; groups retain Registry component order. | Instruction | Code | Immediate | Bytes | Stack effect | Full attempt cycles | | --- | --- | --- | ---: | --- | --- | | STRUCT_NEW T | 0x00A0 | T | 6 | [] → ref | 8 + sum(w(fields)) | | STRUCT_GET type=T, field=f | 0x00A1 | T, f | 10 | ref → slots(F) | 3 + w(F) | | STRUCT_SET type=T, field=f | 0x00A2 | T, f | 10 | ref, slots(F) → [] | 4 + w(F) | | ARRAY_NEW T | 0x00A3 | T | 6 | length:Int64 → ref | 8 + N*w(E), valid N; otherwise 8 | | ARRAY_LEN T | 0x00A4 | T | 6 | ref → length:Int64 | 3 | | ARRAY_GET T | 0x00A5 | T | 6 | ref, index:Int64 → slots(E) | 3 + w(E) | | ARRAY_SET T | 0x00A6 | T | 6 | ref, index:Int64, slots(E) → [] | 4 + w(E) | w is the resolved execution-slot width: scalar, String, color and concrete references use one; vec2, Trait and Dynamic use two; pixel uses three. Reference width never traverses referenced instances. The Struct construction sum is cached during bounded Registry resolution, with no PBX schema change. `OpCode::cycles()` supplies only the base component for these instructions. STRUCT operations require a Struct descriptor; ARRAY operations require an Array descriptor, never its element TypeId or BuiltinId. Fields are immediate owner-local indices in declaration order. Every operation may trap; none branches, terminates or constitutes a safepoint. All instructions, including unreachable ones, undergo bounded structural verification and exact Registry height analysis. Finite type/group facts converge before proven conflicts are rejected. Unknown facts retain runtime checking; locals have no permanent type. After charging the attempt, incomplete temporary operands trap with STACK_UNDERFLOW. Instance operations check receiver carrier, absence, liveness/generation, category, Registry and exact TypeId first; array access then checks exact Int64 index and bounds; SET checks the complete value group last. There is no numeric, Trait or Dynamic coercion. Negative lengths or indices and indices at/above length trap with OOB (0x03); wrong carriers/types/groups trap with TYPE (0x04); absent receivers with NULL_REFERENCE (0x0E); invalid/dead/stale handles with INVALID_HANDLE (0x0F). Positive lengths above u32, checked size/cost overflow, resource quotas and recoverable allocation failures trap with RESOURCE_LIMIT (0x10), preserving resource reason/requested/limit. Static invalid TypeIds/categories/fields produce LOAD_INVALID_REFERENCE; proven stack/type conflicts produce LOAD_INVALID_CODE. Runtime TrapInfo preserves the attempted PC, opcode and available source span. Publication and ownership follow [typed collection memory](03-memory-stack-heap-and-allocation.md); charging follows [time and cycles](01-time-model-and-cycles.md). See the [producer handoff](../../vm-arch/collection-producer-handoff.md) for independent byte oracles and construction examples. Production consumers must enter through the validated PBX v1 image boundary described in [Program Registry](02c-program-registry-and-pbx-v1.md).