Files
prometeu-runtime/docs/vm-arch/ARCHITECTURE.md
T
bquarkz a2275932a5
Intrepid/Prometeu/Runtime/pipeline/pr-master There was a failure building this commit
Keep PBX at v0 and simplify Jenkins quality gate
2026-10-14 14:35:44 +01:00

205 lines
13 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 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 <sysc_index>`. The loader resolves and patches them to numeric `SYSCALL <id>` 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.