# 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`](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 - [`02-vm-instruction-set.md`](02-vm-instruction-set.md) defines the VM execution subsystem at a higher level. - [`02b-vm-function-values-and-closures.md`](02b-vm-function-values-and-closures.md) defines first-class function values. - [`03-memory-stack-heap-and-allocation.md`](03-memory-stack-heap-and-allocation.md) defines stack/heap and handle-backed objects. - [`16-host-abi-and-syscalls.md`](16-host-abi-and-syscalls.md) reuses 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. Retain current UnknownClosureCallee protection until the separate callable/closure/coroutine contract provides a replacement contract. 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](02c-program-registry-and-pbx-v1.md#values-storage-and-initialization). 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.