Files
prometeu-runtime/docs/specs/runtime/02a-vm-values-and-calling-convention.md
T
bquarkz ec84a6bba5
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
feat(vm)!: implement typed callables and single-context execution
Add structural Fn signatures, typed capture environments, indirect calls and Trait dispatch while preserving logical parameter and result groups, ownership and budgets.

Remove guest coroutine execution and legacy loading. Activate bounded sealed PBX v1 with mandatory capture metadata, preserve frame continuations and root return results, and migrate producers and shipped cartridges.

Publish coordinated specs, handoffs and the completed runtime lesson. Validation: 880 workspace tests passed, 9 existing tests ignored; both cartridges completed six production-host frames.
2026-10-09 05:47:24 +01:00

6.3 KiB

VM Values and Calling Convention

Domain: VM values and calling convention Function: normative

This chapter isolates the slot/value model and the rules for calls, returns, tuples, and frames.

1 Value Types

All runtime values are stored in VM slots as Value.

Primitive value types

Type Description
Int32 32-bit signed integer
Int64 64-bit signed integer
bool Boolean value
float 64-bit floating point

String values

PROMETEU supports string values in the VM language surface.

String rules:

  • hardcoded strings may be materialized once during build/load through constant-pool-backed storage;
  • runtime-created strings may materialize at the point where a new string value is semantically created;
  • the public value model does not require repeated payload copies after first materialization;
  • reducing repeated string copy pressure is an internal runtime concern and MUST NOT be interpreted as a guest-visible ABI distinction.

Built-in vector and graphics types

These are treated as VM values with stable layout semantics.

Type Description
vec2 2D vector (x, y)
color Packed RGBA8888 color value
pixel Combination of position and color

These values:

  • live on the stack;
  • are copied by value;
  • do not require heap allocation by themselves.

The canonical color raw channel order is RGBA. RGB565 is not a public VM color contract.

Heap values

Heap-resident entities are referenced indirectly through handles.

Type Description
handle Reference to a heap object
null Null handle

Handle semantics are defined in 03-memory-stack-heap-and-allocation.md.

2 Tuples and Multi-Return ABI

The PVM supports multi-value returns.

Tuple rules:

  • tuples are stack-only;
  • tuples are not heap objects by default;
  • tuple persistence requires explicit boxing into a heap representation when such a representation exists in the language/toolchain;
  • return shape is part of the function contract.

3 Call Convention

Each function declares a fixed return-slot shape.

At call time:

  1. the caller prepares arguments;
  2. CALL transfers control;
  3. the callee executes under its frame contract;
  4. RET leaves exactly the declared return-slot shape on the stack.

The verifier ensures:

  • all reachable return paths agree on return-slot count;
  • stack depth remains coherent across the function body.

4 Call Stack and Frames

The VM uses a call stack.

Conceptual frame shape:

Frame {
    return_pc
    base_pointer
    ret_slots
}

Execution uses the public call instructions:

Opcode Description
CALL Calls a function by id
RET Returns from function

There is no separate public ISA for manual frame stack manipulation.

5 Relationship to Other Specs

Typed signatures and frames

Derive P=sum(parameter widths), L=local_slots and R=sum(result widths). A frame contains parameters, L extra locals then temporaries. GET/SET_LOCAL address only P+L; operand operations cannot consume below the temporary base. CALL consumes P caller temporaries in signature/component order and validates complete groups before publishing the frame. Concrete method receiver is the first declared parameter. No hidden closure receiver is invented by this rule.

RET requires exactly R temporaries, validates ordered types, releases frame owners and returns R slots. Wrong height uses TRAP_BAD_RET_SLOTS; unproved runtime type mismatch uses TRAP_TYPE. Locals begin as Value::Null, not numeric defaults or Uninitialized. Parameter/local slots can be reused after entry; SET_LOCAL updates abstract knowledge. Definite assignment/source variable types remain frontend concerns. Do not introduce silent Int32/Int64, concrete/trait or concrete/Dynamic conversions at boundaries.

Verifier decodes every function range, validates instruction boundaries/IDs/jump destinations, and analyzes structurally reachable control flow. Track temporary height and local/temporary facts in a finite domain: Unknown, known null, carrier facts and proven semantic/multi-slot groups. Initial parameters follow signatures; other locals start null. GET copies facts; SET replaces. Equal facts survive joins; conflicting facts become Unknown, while unequal heights are rejected. Do not require one permanent local type or infer unbounded unions/branch conditions.

Use a bounded worklist to fixed point, reprocessing widened states; decide state-dependent type errors after convergence so visitation order cannot cause rejection. Signature contracts suffice for calls; no interprocedural body inference is required. Partial group mutation invalidates relational facts. Unknown is not proof of compatibility and does not alone reject code: retain complete runtime checks. Type knowledge alone does not eliminate null/generation/bounds checks. CALL_CLOSURE uses expected FnTypeId to establish parameter/result groups even for unknown concrete targets. GET_CAPTURE accesses typed metadata of the enclosing function; environment is retained by CallFrame without hidden arg0. Known mismatch rejects, Unknown retains runtime checks. Exceeding memory/work budget rejects loading, never skips verification.

Builtin IDs, exact slot carriers, nullable defaults and stored layouts are defined in Program Registry and PBX v1. A fixed list of results does not imply a tuple object or boxing. Parameter names are optional signature metadata; frontend argument reordering must preserve source evaluation order.