Implement GC-managed random generators, next/nextf intrinsics, bounded ranges and deterministic conformance coverage. Publish the runtime contract and producer guidance. Give coverage domains at least five percentage points of measured headroom while preserving sufficient floors. Record local qualification: make ci-domains passes with 939 tests and all domain gates green.
7.1 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:
- the caller prepares arguments;
CALLtransfers control;- the callee executes under its frame contract;
RETleaves 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
02-vm-instruction-set.mddefines the VM execution subsystem at a higher level.02b-vm-function-values-and-closures.mddefines first-class function values.03-memory-stack-heap-and-allocation.mddefines stack/heap and handle-backed objects.16-host-abi-and-syscalls.mdreuses the same slot-oriented argument/return philosophy for syscalls.
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.
Finite Float and explicit math conversions
Float is binary64 with the VM-owned software semantics in Gameplay Math and Numeric Semantics. NaN/infinity are rejected at image admission and native import, never stored as guest numeric defaults. Preserve signed-zero bits and subnormals; numeric equality treats both zeros equally. Numeric overflow faults by range. Exact Registry/intrinsic carriers prohibit implicit conversion; math/mathf supplies explicit conversions with truncation/range and ties-even rules. Existing arithmetic opcode promotions do not relax typed boundaries.
Random core integration
Random v1 is BuiltinId 0x0016: one nullable HeapRef slot, eight-byte reference storage aligned to eight with GuestReference ownership. Copies alias; only random.new constructs the object.