Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
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.
132 lines
6.3 KiB
Markdown
132 lines
6.3 KiB
Markdown
# 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. 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](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.
|