feat(vm)!: implement typed callables and single-context execution
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
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.
This commit is contained in:
@@ -3,68 +3,98 @@
|
||||
Domain: VM closures and function values
|
||||
Function: normative
|
||||
|
||||
This chapter defines how the PVM models first-class function values.
|
||||
Didactic companion: [Typed Callables and Frame-Owned Continuations](../../../discussion/lessons/DSC-0052-vm-closures-captures-and-dynamic-calls/LSN-0061-typed-callables-and-frame-owned-continuations.md).
|
||||
|
||||
## 1 First-Class Function Model
|
||||
## 1 Typed First-Class Functions
|
||||
|
||||
The PVM treats user function values as closures.
|
||||
Registry Fn (tag 4) contains Signature: ordered logical parameter/result TypeIds.
|
||||
Optional names are metadata. Identity is exactly these lists, excluding FunctionId,
|
||||
captures and physical widths. Duplicate Fn keys reject without ID remapping or
|
||||
variance. One Vec2 result and two Float results differ despite equal slot counts.
|
||||
Structural expansion through Array elements and Fn parameters/results MUST be
|
||||
finite; nominal Struct/Trait stop expansion. Forward references, recursive calls,
|
||||
captured Fn values and runtime object cycles remain legal.
|
||||
|
||||
This means:
|
||||
Fn occupies one Value slot, an 8-byte/8-aligned guest HeapRef in typed storage, and
|
||||
defaults to Null. Invoking absence traps. Fn is allowed in parameters/results,
|
||||
Struct/Array/Dynamic; REF_* retain their category rules and Fn does not implement
|
||||
Trait implicitly. Syscalls are not first-class values.
|
||||
|
||||
- functions can be stored in variables;
|
||||
- functions can be passed as arguments;
|
||||
- functions can be returned from other functions;
|
||||
- function values carry explicit runtime representation.
|
||||
## 2 Instances and Captures
|
||||
|
||||
Even functions without captures may be represented as closures with an empty capture set.
|
||||
Every value uses a heap Closure, including empty captures:
|
||||
`Closure { fn_type_id, function_id, typed_capture_components[] }`.
|
||||
Distinct creation has distinct identity; copying a reference preserves identity.
|
||||
Equality compares handles, never code/environment. Target and capture bindings
|
||||
are immutable; objects referenced by them may remain mutable.
|
||||
|
||||
## 2 Closure Layout
|
||||
Immutable bindings are captured by value. Shared mutable lexical bindings use
|
||||
private typed Struct cells with ordinary field operations, common to creator and
|
||||
closures. Another factory can allocate another cell. No Cell category or
|
||||
SET_CAPTURE is introduced; language lowering belongs to each frontend.
|
||||
|
||||
Closures are heap objects.
|
||||
PBX v1 MUST include exactly one captures section, kind 8: little-endian
|
||||
`function_count:u32`, then per FunctionId `capture_count:u32` and ordered capture
|
||||
TypeIds:u32. Outer count equals the function table; empty lists are explicit.
|
||||
Offsets/widths/maps derive at load. Records, capacities and graph work use existing
|
||||
budgets. Images lacking this section or using old closure encodings reject.
|
||||
|
||||
Conceptual layout:
|
||||
## 3 Calls and Environments
|
||||
|
||||
```
|
||||
Closure {
|
||||
func_id
|
||||
captures[]
|
||||
}
|
||||
```
|
||||
Opcodes are u16, immediates u32, all little-endian:
|
||||
|
||||
Captures may be:
|
||||
| Instruction | Immediates | Stack / attempted cost |
|
||||
| --- | --- | --- |
|
||||
| MAKE_CLOSURE 0x52 | FunctionId, FnTypeId | capture groups -> Fn; 8+C |
|
||||
| CALL_CLOSURE 0x53 | expected FnTypeId | args..., Fn -> results... after RET; 6 |
|
||||
| GET_CAPTURE 0x57 | capture index | append complete capture group; 2+W |
|
||||
| CALL_TRAIT 0x58 | TraitTypeId, method index | args..., receiver, ImplementationId -> results...; 6 |
|
||||
|
||||
- copied values;
|
||||
- handles to heap objects.
|
||||
C is declared capture-slot sum; W is indexed capture width. Charge once per
|
||||
attempt including traps. CALL/RET retain 5/4; zero budget executes nothing and
|
||||
positive budget admits a whole instruction, which may overshoot.
|
||||
|
||||
Closure environments are part of the GC root graph as long as the closure remains reachable.
|
||||
CALL_CLOSURE validates expected Fn type and target signature. CallFrame retains
|
||||
the Closure as environment root, without hidden arg0 in public parameters.
|
||||
GET_LOCAL addresses public parameters/locals; GET_CAPTURE reads that frame's
|
||||
indexed environment. Nested calls own separate environments. Nonempty-capture
|
||||
bodies cannot be entered by direct CALL or host preparation without environment.
|
||||
A bound-method Fn can use an explicit adapter capturing its receiver.
|
||||
|
||||
## 3 Direct and Indirect Calls
|
||||
CALL_TRAIT validates the complete view and resolves FunctionId through the
|
||||
immutable implementation table. Callee gets concrete receiver first, then explicit
|
||||
method arguments; ImplementationId is not a parameter. Exact method signatures
|
||||
and empty target captures are required. Absent/malformed/stale/incompatible views
|
||||
fault. No lookup by name, implicit wrappers, variance or adaptations are added.
|
||||
|
||||
The PVM supports two forms of invocation:
|
||||
## 4 Verification, Faults and Resources
|
||||
|
||||
| Opcode | Description |
|
||||
| -------------- | -------------------------------------- |
|
||||
| `CALL` | Direct call by function id |
|
||||
| `CALL_CLOSURE` | Indirect call through a closure handle |
|
||||
Expected FnTypeId supplies parameter/result groups even for unknown concrete
|
||||
targets. Known mismatch rejects loading; Unknown retains full runtime checks.
|
||||
Validate every instruction and metadata before image publication. Creation,
|
||||
call and capture access validate whole groups and reserve capacity before consume
|
||||
or publication. Refusal preserves operands/owners and publishes no partial object
|
||||
or frame; provisional reservations refund and attempted cycles remain. No quota
|
||||
rescue GC. Use existing distinct NullReference/InvalidHandle/Type/Resource traps.
|
||||
Fn can invoke syscalls, mutate and fault: no purity flag, fault isolation, separate
|
||||
budget, guest unwind or rollback of earlier body effects.
|
||||
|
||||
For `CALL_CLOSURE`:
|
||||
## 5 Context, GC and Host
|
||||
|
||||
1. the closure handle is read from the stack;
|
||||
2. the VM resolves the target function;
|
||||
3. captured environment state becomes available to the callee according to the closure calling convention.
|
||||
VM owns one PC, operand/call stacks and globals directly. FRAME_SYNC retains
|
||||
frames/locals/environments and resumes next PC in any body. Budget exhaustion
|
||||
retains the same logical frame. Last-root RET completes entry, rooting results
|
||||
before threshold GC. Recurring host entry remains FunctionId 0 with init once.
|
||||
|
||||
## 4 Verification and Safety
|
||||
Threshold GC opportunities are FRAME_SYNC and successful last-root RET. Roots
|
||||
include globals, live stack values, Closures retained by every active CallFrame
|
||||
and legally retained native/host roots. Trace whole capture groups and shared
|
||||
cells; unreachable cycles collect. Results remain roots until consumed/replaced,
|
||||
reset/unload. No GC at ordinary callee RET or allocation/quota rescue.
|
||||
HeapRef copies/inspection snapshots establish no guest roots or cross-session
|
||||
imports. No native registration/delivery/reentry API is created here. Guest
|
||||
callbacks are ordinary Fn calls in the main execution context.
|
||||
|
||||
The verifier ensures, at minimum:
|
||||
|
||||
- closure call sites have coherent arity;
|
||||
- invalid closure call shapes are rejected or trapped according to the verifier/runtime boundary;
|
||||
- return-slot contracts remain valid.
|
||||
|
||||
Handle validity, heap reachability, and dynamic misuse remain subject to runtime checks where static proof is not possible.
|
||||
|
||||
## 5 Relationship to Memory and GC
|
||||
|
||||
- Closure objects live in heap memory, so their object model is constrained by [`03-memory-stack-heap-and-allocation.md`](03-memory-stack-heap-and-allocation.md).
|
||||
- Captured heap references participate in the GC root graph.
|
||||
- Closures are function values, not syscalls; syscall calls remain a separate non-first-class boundary defined in [`16-host-abi-and-syscalls.md`](16-host-abi-and-syscalls.md).
|
||||
See [memory](03-memory-stack-heap-and-allocation.md),
|
||||
[Registry/PBX](02c-program-registry-and-pbx-v1.md) and
|
||||
[host ABI](16-host-abi-and-syscalls.md).
|
||||
|
||||
Reference in New Issue
Block a user