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.
13 KiB
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.
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;
- single-context continuation internals;
- host ABI policy.
Those now live in focused companion specs:
02a-vm-values-and-calling-convention.md02b-vm-function-values-and-closures.md03-memory-stack-heap-and-allocation.md09a-coroutines-and-cooperative-scheduling.md16-host-abi-and-syscalls.md16a-syscall-policies.md
2 Core Design Principles
The PVM is designed around the following constraints:
- Deterministic execution: no hidden threads or asynchronous callbacks.
- Frame-based timing: execution is bounded by frame time and explicit safepoints.
- Safe memory model: heap access is mediated by validated handles.
- Simple compilation target: stack-based bytecode with verified control flow.
- Stable ABI: calls and syscalls follow fixed slot-based contracts.
- First-class functions: user function values are represented through closures.
3 Execution Model
The PVM executes bytecode inside the PROMETEU frame loop.
Each frame:
- firmware enters the VM;
- the VM runs until:
- the frame budget is consumed; or
- a
FRAME_SYNCinstruction is reached;
- at
FRAME_SYNC, the VM reaches the primary safepoint for threshold GC and host handoff; - 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;
- logical frame handoff;
- frame-completion semantics;
- deterministic return to firmware.
4 Instruction Families
The public VM instruction surface is documented at the bytecode level in Core ISA. 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,CALL_TRAIT
- function values:
MAKE_CLOSURE,CALL_CLOSURE,GET_CAPTURE
- VM/host boundary:
HOSTCALL,SYSCALL,INTRINSIC
Former coroutine numbers 0x54–0x56 are reserved. SPAWN, YIELD and SLEEP
reject during loading, including unreachable code, and cannot be emitted by the assembler.
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:
- valid instruction decoding;
- valid jump targets;
- consistent stack depth across control-flow joins;
- valid call/return shape;
- closure call safety rules;
- 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.mddefines slot values, tuples, frames, and return-slot semantics.02b-vm-function-values-and-closures.mddefines closure representation and function-value behavior.03-memory-stack-heap-and-allocation.mddefines stack/heap, handles, object layout, and GC.09-events-and-concurrency.mddefines events, timers, and the frame boundary model.09a-coroutines-and-cooperative-scheduling.mddefines single-context continuation and entry completion.16-host-abi-and-syscalls.mddefines the syscall ABI boundary.
7 Summary
The PVM is:
- stack-based;
- deterministic;
- frame-synchronized;
- verifier-gated;
- closure-capable;
- single execution context; retired SPAWN/YIELD/SLEEP are rejected;
- embedded inside the larger PROMETEU console model, not equal to it.
Program Registry integration
Program Registry and PBX v0 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; charging follows time and cycles. See the producer handoff for independent byte oracles and construction examples. Production consumers must enter through the validated PBX v0 image boundary described in Program Registry.
Typed callable instructions are MAKE_CLOSURE (FunctionId,FnTypeId), CALL_CLOSURE (FnTypeId), GET_CAPTURE (index) and CALL_TRAIT (TraitTypeId,method_index). Their groups, encodings and attempted costs are defined in the Fn contract. Numbers 0x54–0x56 stay reserved and reject anywhere at load.
Random core integration
INTRINSIC also dispatches the VM-owned random operations, IDs 0x4000–0x4003. NEW cannot construct Random. TRAP_RANDOM_REJECTION_LIMIT is 0x00000015.
Typed array range copy
ARRAY_COPY uses little-endian u16 opcode 0xA9 followed by one little-endian u32 Array TypeId. It consumes five operands, bottom to top: source, sourceStart, target, targetStart, count, and produces no result. Receivers require the exact Array type; sourceStart, targetStart and count require exact Int64 carriers. Ranges must be nonnegative and fit each physical array, without clamping, truncation or coercion. An empty range may start at the physical length.
Loading validates Array identity/category even in unreachable code. Registry verification requires five complete operands. The instruction may trap, but is neither a branch, terminator nor safepoint. ARRAY_LEN (0xA4) remains the physical length query. Logical collection limits and error paths belong to producers. The encodings 0xA7, 0xA8, 0xAA and 0xAB are unsupported and reject at admission, including in unreachable code. Bytes inside immediates or data are not opcodes. There is no multi-owner publication, generic batch or atomic-region replacement.
Copy preserves complete stored groups, including presence tags, immutable boxes, native String owners, HeapRefs, traits and identities without boxing or payload repacking. All source groups are captured before the first destination write, so overlap observes the pre-attempt source sequence. All copy scratch is reserved under TemporaryBytes before writing and released on success or failure. Original operands remain roots throughout preparation. No guest object or request token is allocated. Quota refusal does not trigger rescue GC.
Validation, quota or recoverable allocation failure preserves operands and all destinations/owners. Commit uses prevalidated infallible writes; no callback, allocation, GC or scheduler boundary occurs inside the instruction. Consume the five operands only after commit. Cycles and diagnostics retain the attempt. This guarantee begins with prepared operands; it does not undo earlier source calculations, allocations or callbacks, or make a sequence of stores transactional.
Let N=count and W=element storage slots from the immutable validated Registry. The planned cost is C=4+2NW. Charge base 4 for every admitted attempt. Only inspect count for cost selection when all five operands are available in the temporary stack region; frame locals are not operands. If N is exact Int64 in 0..u32::MAX, charge representable C before validating receivers, offsets, ranges, source groups or reserving scratch. Retain C on any later refusal. Otherwise retain base 4 and follow ordinary validation; count is neither converted nor accepted. Checked overflow of C retains only base 4 and produces structured RESOURCE_LIMIT with SizeOverflow before ordinary validation, without wrapping or saturation.
Early count inspection selects cost only. Apart from cost overflow, fault order is temporary height, source receiver, target receiver, carriers of sourceStart, targetStart and count, source range, target range, scratch reservation, then source group reads/validation in order. Thus above-u32 count with otherwise valid inputs fails physical bounds, not an allocation-size check. N=0 still validates receivers and ranges and costs 4. Identity and overlap grant no discount. N=10/W=1 costs 24 on success, invalid receiver/range or scratch refusal. Zero budget executes no attempt; a positive budget admits the whole instruction with overshoot. Trap prevails over BudgetExhausted on failure, with no successful target step. Rejected images execute no guest instruction and charge zero guest cycles.
Identity and value hashing
Identity and value hashing defines REF_IDENTITY_HASH 0x0097 and REF_IDENTITY_EQ 0x0098, complete typed source groups, one/two TypeId immediates, exact attempted costs and operand-preserving faults. It also defines intrinsics 0x4100–0x4102 and their shared bounded invocation profile. Old EQ and REF_* categories retain their contracts.