Intrepid/Prometeu/Runtime/pipeline/pr-master There was a failure building this commit
205 lines
13 KiB
Markdown
205 lines
13 KiB
Markdown
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.
|