feat(vm)!: implement typed callables and single-context execution
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:
2026-10-09 05:47:24 +01:00
parent 86bade3e1f
commit ec84a6bba5
96 changed files with 3656 additions and 6075 deletions
@@ -3,7 +3,7 @@
Domain: VM program metadata, binary format, typed storage and resource boundaries
Function: normative
This chapter defines the required v1 contract; implementation is being migrated and this publication is not a claim that all execution paths already satisfy it. The callable/closure/coroutine type boundary remains separately specified: no provisional untyped reference type is authorized. Existing closure/coroutine behavior must be preserved until its approved replacement can be integrated.
The production loader, internal producers and runtime examples use this sealed v1 contract. Typed Fn and frame environments follow [the function-value contract](02b-vm-function-values-and-closures.md); retired coroutine instructions reject at load. No provisional untyped reference is authorized.
Didactic companion: [Registry Boundaries and Owned Values](../../../discussion/lessons/DSC-0058-program-registry-type-and-function-metadata/LSN-0059-registry-boundaries-and-owned-values.md).
@@ -15,11 +15,11 @@ The requirements below use MUST/MUST NOT semantics. The Registry owns type/funct
- Registry logically joins Type Registry and Function Registry. It belongs to ProgramImage, is immutable after successful resolution, and is shared across sessions. Metadata is native, outside the guest GC heap; it has no HeapRef and remains alive while any image consumer needs it. Code, constants, exports and debug are separate responsibilities.
- TypeId, FunctionId and ImplementationId are distinct u32 newtypes, dense zero-based table indices local to the image. TraitId is a TypeId checked as Trait, not a separate namespace. Field and method indices are owner-local. BuiltinId, IntrinsicId and constant-pool tags are separate domains. Names never establish identity.
- Struct/Trait are nominal; identical names/layouts do not merge them. Producers link references and deduplicate the same declaration across modules. Array identity is structural by element TypeId, invariant and mutable, with length on instances; nested arrays store array references.
- One descriptor per imported BuiltinId and per Array element TypeId; duplicate records are rejected without loader remapping. Forward references and nominal reference recursion are legal. Array-only cycles and infinite inline layouts, overflow and wrong-category references are rejected with bounded graph processing. Runtime object cycles remain legal.
- Four descriptor categories: Builtin, Struct, Array, Trait. No Service or input endpoint category. Services lower to a nominal Struct and one rooted global instance per session; singleton language rules stay in the frontend. Builtin-value trait adapters are explicit Struct allocations with separate nominal identity.
- One descriptor per imported BuiltinId and per Array element TypeId; duplicate records are rejected without loader remapping. Forward references and nominal reference recursion are legal. Cycles exclusively through Array/Fn structural edges and infinite inline layouts, overflow and wrong-category references are rejected with bounded graph processing. Runtime object cycles remain legal.
- Five descriptor categories: Builtin, Struct, Array, Trait, Fn. Fn identity is its ordered parameter/result TypeIds, ignoring names; duplicate Fn keys reject. Nominal Struct/Trait stop structural expansion. No Service or input endpoint category. Services lower to a nominal Struct and one rooted global instance per session; singleton language rules stay in the frontend. Builtin-value trait adapters are explicit Struct allocations with separate nominal identity.
- Function signatures contain ordered typed parameters/results. Results have fixed semantic arity; zero results means zero slots, not null, and multiple results do not require tuple objects. A vec2 is one semantic result occupying two slots. Widths are derived, not duplicated in PBX.
- Parameter names are optional signature metadata independent of debug. Frontends reorder named arguments to signature order while preserving source evaluation order, using temporaries. Mixing/default-argument syntax and diagnostics stay with frontends; optional/default parameters are not implicitly introduced.
- Trait implementations are unique per (Struct, Trait), complete, immutable and ordered by method index. Explicit parameter/result TypeIds, order and arity match exactly; the implementation function has its concrete receiver as first parameter. No variance or implicit adaptation: frontend adapter functions may satisfy the exact signature. Actual trait dispatch belongs to the separate callable/closure/coroutine contract.
- Trait implementations are unique per (Struct, Trait), complete, immutable and ordered by method index. Explicit parameter/result TypeIds, order and arity match exactly; the implementation function has its concrete receiver as first parameter. No variance or implicit adaptation: frontend adapter functions may satisfy the exact signature. CALL_TRAIT resolves TraitTypeId/method index through this immutable table; targets have empty captures and receive concrete receiver first, never ImplementationId as an argument.
## PBX v1 encoding
@@ -35,6 +35,7 @@ PBX v1 only: magic `PBX\0`, little-endian, 32-byte header, zero reserved bytes a
| 5 | syscalls | exactly once |
| 6 | types | exactly once |
| 7 | implementations | exactly once |
| 8 | captures | exactly once |
The fixed header is:
@@ -73,11 +74,13 @@ Encoding primitives: list=`count:u32` followed by records; optional name=`presen
| Record | Exact field order |
| --- | --- |
| Type | kind:u8, optional name, category payload; tags 0 Builtin / 1 Struct / 2 Array / 3 Trait |
| Type | kind:u8, optional name, category payload; tags 0 Builtin / 1 Struct / 2 Array / 3 Trait / 4 Fn |
| Builtin payload | builtin_id:u32 |
| Struct payload | ordered field list |
| Array payload | element_type_id:u32 |
| Trait payload | ordered method list; each method has optional name, explicit-parameter list, result list; concrete receiver is not repeated here |
| Fn payload | ordered parameter list, result list; names do not define identity |
| Captures section | function_count:u32, then each FunctionId in order: capture_count:u32 and TypeIds:u32; counts match functions, empty lists explicit |
| Function | optional name, parameter list, result list, code_offset:u32, code_len:u32, local_slots:u32, max_stack_slots:u32 |
| Implementation | owner_type_id:u32, trait_type_id:u32, method_count:u32, FunctionIds:u32 in trait-method order; count must match |
@@ -103,7 +106,7 @@ Unlisted BuiltinIds, including zero and removed input IDs 0x0100–0x0102, canno
Preserve declared field order; round each offset to field alignment and final payload size to maximum alignment. Empty Struct has payload zero, alignment one, but retains object identity/header. Array stride is aligned stored-element size; Array<Struct> stores references, not Struct payloads. Checked arithmetic precedes allocation. Padding is not data or a GC reference. Allocate truly aligned storage or use appropriate accesses; Vec<u8> does not justify unsafe casts. Native Arc/Value layouts are target-dependent and never a portable PBX ABI.
Defaults apply before publication/GC, including reused storage: Int32/Int64 zero, Float +0.0, Bool false, Struct/Array/String references null, vec2 (+0,+0), color transparent raw zero, pixel (0,0,transparent), trait absent, Dynamic untyped null. Do not instantiate referenced objects/subarrays or invoke source constructors. Empty arrays require no element values. Catalog defaults are resolved without arbitrary per-element callbacks. Native values must be constructed correctly rather than assumed valid after memset.
Defaults apply before publication/GC, including reused storage: Int32/Int64 zero, Float +0.0, Bool false, Struct/Array/Fn/String references null, vec2 (+0,+0), color transparent raw zero, pixel (0,0,transparent), trait absent, Dynamic untyped null. Do not instantiate referenced objects/subarrays or invoke source constructors. Empty arrays require no element values. Catalog defaults are resolved without arbitrary per-element callbacks. Native values must be constructed correctly rather than assumed valid after memset.
Heap references: index:u32 + generation:u32, stored size/alignment 8, still one Value::HeapRef slot. Generation starts at one; zero is reserved. Compact null=(0,0), while index zero remains valid with a live generation. Other generation-zero pairs are invalid. Validate index/liveness/generation/type before dereference. Increment generation on reclamation; retire the slot after its maximum-generation incarnation rather than wrap. Handles belong to their heap/session; native boundaries preserve provenance without introducing a heap ID into this encoding.
@@ -143,7 +146,7 @@ RET requires exactly R temporaries, validates ordered types, releases frame owne
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.
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 derives ordered parameter/result groups from its expected FnTypeId, including unknown concrete targets; known mismatches reject, unknown values retain runtime checks. Exceeding memory/work budget rejects loading, never skips verification.
## Input
@@ -232,5 +235,5 @@ Nested records count fields, methods, parameters/results and implementation Func
| Runtime operation temporary buffers | 64 MiB per session |
| Call depth including entry frame | 1,024 frames per execution flow |
Auxiliary state includes capacities of active/suspended Value stacks, frames, globals, handles/free lists, scheduler queues, string ledgers and persistent GC structures. Moving stacks between VM and coroutine transfers charges; never bill the same stack in both auxiliary and heap domains. Coroutine header/own payload remains heap-owned. Per-flow depth and per-frame cap coexist with aggregate session auxiliary cap. No separate task quota/lifecycle design is added here. Constants are checked at load; runtime excess traps. Growth must not geometrically reserve beyond available quota. Cycle/frame budgets remain separate. Asset and host admission limits are outside these totals.
Auxiliary state includes capacities of the VM operand stack, CallFrames, globals, handles/free lists, string ledgers and persistent GC structures. The VM owns one context directly; entry preparation allocates no heap execution object. Closure headers and capture payloads remain heap-owned. Call depth and per-frame cap coexist with aggregate session auxiliary cap. Constants are checked at load; runtime excess traps. Growth must not geometrically reserve beyond available quota. Cycle/frame budgets remain separate. Asset and host admission limits are outside these totals.