Files
prometeu-studio/docs/vm-arch/ARCHITECTURE.md
T
bquarkz 632ba6d0d6
Test / Tests and coverage
Intrepid/Prometeu/Studio/pipeline/pr-master This commit looks good
refactor(compiler)!: migrate SDK to minimal storage ISA
Replace retired guards and publication opcodes with SDK checks, neutral TRAP and sequential List/Linked mutations with explicit failure phases. Preserve snapshot cursors and import schema 2 metadata with the delivered provider pin.

Include common/source/installed conformance, debug and release evidence, synchronized specs and the consolidated lesson. Runtime checkout remains unchanged.
2026-10-24 01:35:42 +01:00

14 KiB
Raw Blame History

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.

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.
  1. 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 Values stored with the closure). Captured HeapRefs 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 HeapRefs.

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.
  1. 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.
  1. 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.
  1. 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.
  1. 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.
  1. 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.
  1. Non‑Goals

  • No RC
  • No HIP
  • No preemption
  • No mailbox
  1. 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 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 explains the published mechanisms. The producer handoff documents schema, input IDs and named-argument order, while layout evidence records reproducible load/access/GC measurements and the current publication boundary.

VM-owned random core

See the random contract 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.

Typed array range copy

ARRAY_COPY (0xA9) copies complete groups between exact typed arrays with strict physical ranges and pre-attempt overlap semantics. Preparation reserves scratch before infallible commit; failures preserve operands/destinations and retain charged work. No callbacks, GC or scheduling occur inside the instruction. The instruction contract defines encoding, fault order and early cost selection. ARRAY_LEN remains the physical query; producer algorithms own logical limits and multi-owner invariants. There is no transactional sequence of stores. Encodings 0xA7/0xA8/0xAA/0xAB are unsupported, including in dead code.