# 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`](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.