prometeu-runtime/docs/specs/runtime/02a-vm-values-and-calling-convention.md

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
int	64-bit signed integer
bool	Boolean value
float	64-bit floating point

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 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.

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

• 02-vm-instruction-set.md defines the VM execution subsystem at a higher level.
• 02b-vm-function-values-and-closures.md defines first-class function values.
• 03-memory-stack-heap-and-allocation.md defines stack/heap and handle-backed objects.
• 16-host-abi-and-syscalls.md reuses the same slot-oriented argument/return philosophy for syscalls.