Files
prometeu-runtime/docs/specs/runtime/02-vm-instruction-set.md
T
Nilton Constantino 57992cf214 feat(vm): publish typed fields across multiple structs atomically
Add schema-driven FIELDS_PUBLISH without collection-specific runtime behavior. Validate every nullable destination and complete field group before allocation-free publication, with neutral ownership, malformed-input and quota coverage.
2026-10-23 09:53:40 +01:00

256 lines
15 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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;
- single-context continuation 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 threshold GC and host handoff;
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;
- 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](../../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`, `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:
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 single-context continuation and entry completion.
- [`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;
- 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](02c-program-registry-and-pbx-v0.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<T> | 8 + sum(w(fields)) |
| STRUCT_GET type=T, field=f | 0x00A1 | T, f | 10 | ref<T> → slots(F) | 3 + w(F) |
| STRUCT_SET type=T, field=f | 0x00A2 | T, f | 10 | ref<T>, slots(F) → [] | 4 + w(F) |
| ARRAY_NEW T | 0x00A3 | T | 6 | length:Int64 → ref<T> | 8 + N*w(E), valid N; otherwise 8 |
| ARRAY_LEN T | 0x00A4 | T | 6 | ref<T> → length:Int64 | 3 |
| ARRAY_GET T | 0x00A5 | T | 6 | ref<T>, index:Int64 → slots(E) | 3 + w(E) |
| ARRAY_SET T | 0x00A6 | T | 6 | ref<T>, 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 v0 image boundary described in [Program Registry](02c-program-registry-and-pbx-v0.md).
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](02b-vm-function-values-and-closures.md). Numbers 0x54–0x56 stay reserved and reject anywhere at load.
## Random core integration
INTRINSIC also dispatches the [VM-owned random operations](02e-vm-owned-random-core.md), IDs 0x4000–0x4003. NEW cannot construct Random. TRAP_RANDOM_REJECTION_LIMIT is 0x00000015.
## Logical guards and atomic storage publication
The core includes the following generic operations, with u16 opcodes and
little-endian u32 immediates. They introduce no new Registry category, syscall,
source-language collection or ambient transaction. Operand order below is bottom
to top; all integer operands are Int64.
| Opcode | Immediate | Stack operands consumed |
| --- | --- | --- |
| INDEX_GUARD `0xA7` | none | index, exclusive limit |
| ARRAY_CHECK_LENGTH `0xA8` | Array TypeId | length |
| ARRAY_COPY `0xA9` | Array TypeId | source, sourceStart, target, targetStart, count |
| STORAGE_PUBLISH `0xAA` | Array TypeId, Struct TypeId, first field, second field | source, sourceStart, target, targetStart, count, fillStart, fillCount, element group, owner, first field group, second field group |
All operations return no values. INDEX_GUARD accepts exactly
`0 <= index < limit`, otherwise TRAP_OOB. It does not use physical storage length.
ARRAY_CHECK_LENGTH accepts zero through u32::MAX without allocating. Negative
lengths produce TRAP_OOB; values above u32::MAX produce the same resource
SizeOverflow failure as ARRAY_NEW. This check does not reserve future allocation.
ARRAY_COPY and STORAGE_PUBLISH require exact Array receiver identities and complete
stored groups. Every range must have nonnegative start/count and fit its physical
array; an empty range may start at length. Invalid ranges produce TRAP_OOB, never
clamping or truncation. Copy reads the pre-attempt source sequence, including for
overlapping source/target ranges. Presence tags, immutable boxes, native owners and
object identities are preserved without payload unpacking or repacking.
STORAGE_PUBLISH first copies the selected source range, then fills the selected
target range with the supplied element group, then writes the two selected fields
on the supplied Struct owner. Fields must be distinct valid indices on that Struct;
their types and widths come from the immutable Registry. Source code/producer owns
selection of every range, value, owner and field. The VM implements these generic
ordered effects and does not select collection algorithms.
Loading validates all immediate identities/categories/fields even in unreachable
code. Verification requires complete typed operands. ARRAY_COPY consumes five
slots; STORAGE_PUBLISH consumes `8 + elementWidth + firstWidth + secondWidth`.
INDEX_GUARD consumes two slots and ARRAY_CHECK_LENGTH consumes one.
Execution validates all receivers, lengths/ranges, supplied groups and source
groups, and reserves the complete charged copy scratch before writing. Validation,
quota or host allocation refusal leaves all input operands and destinations
unchanged, including both fields and native owners. Scratch uses TemporaryBytes,
is refunded on success/refusal and does not relax any resource ceiling. Existing
operands remain roots during preparation. There is no GC, callback, scheduler or
other interleaving inside this single instruction. Commit uses already validated
complete groups, performs no fallible allocation and consumes operands only after
all selected effects have been published. No prepared token escapes the attempt.
Base cycle costs are 2 for either guard, 4 for ARRAY_COPY and 6 for STORAGE_PUBLISH.
Copy adds `2 * count * elementWidth`; publication additionally adds
`fillCount * elementWidth + firstWidth + secondWidth`. Work arithmetic is checked
before mutation. A refused preparation still charges the attempted work. Neither
operation is a safepoint. Consumers must prepare any potentially failing return
carrier and all call operands before publication; a series of ordinary stores is
not a substitute for whole-operation safety.
## Atomic publication of multiple Struct instances
FIELDS_PUBLISH (`0xAB`) has one little-endian u32 schema TypeId immediate. The
schema MUST be a Registry Struct whose ordered field types are all Struct types.
Names are descriptive only. The schema is declarative metadata; no request object,
new Registry category or preparation token is allocated or exposed.
For each schema entry, the operand stack supplies one nullable destination
reference followed by every destination field's complete typed value group, in
field declaration order. The stack effect is the sum, over entries, of one plus
the destination instance's initialization-slot count; no results are produced.
Null skips that destination, but every supplied field group is still validated.
Non-null destinations require exact concrete Struct identity and a live reference
of the current session/generation. Array, Trait, Fn and builtin schema entries are
invalid, including in unreachable instructions. The full schema and exact stack
height/groups are checked under normal Registry admission/work limits.
Validate all destinations and value groups before any shared write or operand
consumption. The original operands remain roots throughout preparation. Then write
all fields in schema order, without allocation, fallible validation, callbacks,
GC or scheduler interleaving, and consume the entire input. Input values are
captured before publication; repeated destinations use ordered last-write
semantics. Complete multi-slot/native/reference groups retain identity and normal
ownership. A failed attempt preserves every destination and the operand stack.
The operation allocates no publication scratch or guest object. Operand/frame and
source value preparation remain normally charged and may fail before publication.
Base cost is 6 cycles. After the stack-height check, precharge one cycle per schema
entry and one per destination field execution slot for the complete declared
attempt, including skipped destinations. Quotas are unchanged.
This is a generic typed storage mechanism; collection algorithms and node topology
remain source-owned, with no collection-specific VM instruction or syscall.