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:
@@ -167,3 +167,7 @@ The [collection ISA table](02-vm-instruction-set.md#typed-collection-instruction
|
||||
Examples: empty Struct/Array costs eight; a Struct containing Int32, vec2 and Trait costs thirteen; ten vec2 elements cost twenty-eight even on quota refusal; pixel GET costs six including bounds failure; pixel SET costs seven including group rejection; LEN costs three including receiver failure. Charged cycles are never refunded by rollback.
|
||||
|
||||
Budget admission remains between instructions. Zero executes nothing. A positive remaining budget admits the entire next instruction, which may overshoot; continuation then returns BudgetExhausted before the following instruction. Thus ARRAY_NEW of ten vec2 under run_budget(1) consumes twenty-eight cycles. Trap takes priority on refusal, with the same cycle delta and no successful target step. steps_executed counts only successful steps; cycles_used includes failed attempts. Collection operations add no implicit frame sync, tick, GC or coroutine switch, no extra length cap and no cycle pre-admission rule.
|
||||
|
||||
## Typed Callable Costs
|
||||
|
||||
Charge each admitted attempt once, including trap: MAKE_CLOSURE 8+C (declared capture-slot sum), CALL_CLOSURE 6, GET_CAPTURE 2+W (selected complete-group width), CALL_TRAIT 6. Direct CALL/RET retain 5/4. No extra callback budget, partial-instruction pause or GC-cycle redesign. Zero budget executes nothing; positive budget may admit an instruction that overshoots. Root-return GC does not grant cycles, advance frames or invoke guest cleanup.
|
||||
|
||||
@@ -22,7 +22,7 @@ This chapter does not fully restate:
|
||||
|
||||
- detailed value and calling semantics;
|
||||
- heap/gate/GC internals;
|
||||
- coroutine scheduling internals;
|
||||
- single-context continuation internals;
|
||||
- host ABI policy.
|
||||
|
||||
Those now live in focused companion specs:
|
||||
@@ -55,19 +55,19 @@ Each frame:
|
||||
2. the VM runs until:
|
||||
- the frame budget is consumed; or
|
||||
- a `FRAME_SYNC` instruction is reached;
|
||||
3. at `FRAME_SYNC`, the VM reaches the primary safepoint for GC and cooperative scheduling;
|
||||
3. at `FRAME_SYNC`, the VM reaches the primary safepoint for threshold GC and host handoff;
|
||||
4. control returns to firmware/runtime orchestration.
|
||||
|
||||
`FRAME_SYNC` is the primary VM synchronization point. It is the boundary where the machine can safely account for:
|
||||
|
||||
- GC opportunity;
|
||||
- coroutine handoff;
|
||||
- logical frame handoff;
|
||||
- frame-completion semantics;
|
||||
- deterministic return to firmware.
|
||||
|
||||
## 4 Instruction Families
|
||||
|
||||
The public VM instruction surface is documented at the bytecode level in [`../virtual-machine/ISA_CORE.md`](../../vm-arch/ISA_CORE.md). At the machine/spec level, the instruction families are:
|
||||
The public VM instruction surface is documented at the bytecode level in [Core ISA](../../vm-arch/ISA_CORE.md). At the machine/spec level, the instruction families are:
|
||||
|
||||
- execution control:
|
||||
- `NOP`, `HALT`, `JMP`, `JMP_IF_FALSE`, `JMP_IF_TRUE`, `TRAP`, `FRAME_SYNC`
|
||||
@@ -78,14 +78,15 @@ The public VM instruction surface is documented at the bytecode level in [`../vi
|
||||
- variable access:
|
||||
- globals and locals
|
||||
- function calls:
|
||||
- `CALL`, `RET`
|
||||
- `CALL`, `RET`, `CALL_TRAIT`
|
||||
- function values:
|
||||
- `MAKE_CLOSURE`, `CALL_CLOSURE`
|
||||
- cooperative concurrency:
|
||||
- `SPAWN`, `YIELD`, `SLEEP`
|
||||
- `MAKE_CLOSURE`, `CALL_CLOSURE`, `GET_CAPTURE`
|
||||
- VM/host boundary:
|
||||
- `HOSTCALL`, `SYSCALL`, `INTRINSIC`
|
||||
|
||||
Former coroutine numbers 0x54–0x56 are reserved. `SPAWN`, `YIELD` and `SLEEP`
|
||||
reject during loading, including unreachable code, and cannot be emitted by the assembler.
|
||||
|
||||
The machine-level rule is simple:
|
||||
|
||||
- opcodes define explicit behavior;
|
||||
@@ -113,7 +114,7 @@ The verifier is structural. It does not replace runtime validation of dynamic va
|
||||
- [`02b-vm-function-values-and-closures.md`](02b-vm-function-values-and-closures.md) defines closure representation and function-value behavior.
|
||||
- [`03-memory-stack-heap-and-allocation.md`](03-memory-stack-heap-and-allocation.md) defines stack/heap, handles, object layout, and GC.
|
||||
- [`09-events-and-concurrency.md`](09-events-and-concurrency.md) defines events, timers, and the frame boundary model.
|
||||
- [`09a-coroutines-and-cooperative-scheduling.md`](09a-coroutines-and-cooperative-scheduling.md) defines coroutine lifecycle and scheduling.
|
||||
- [`09a-coroutines-and-cooperative-scheduling.md`](09a-coroutines-and-cooperative-scheduling.md) defines single-context continuation and entry completion.
|
||||
- [`16-host-abi-and-syscalls.md`](16-host-abi-and-syscalls.md) defines the syscall ABI boundary.
|
||||
|
||||
## 7 Summary
|
||||
@@ -125,7 +126,7 @@ The PVM is:
|
||||
- frame-synchronized;
|
||||
- verifier-gated;
|
||||
- closure-capable;
|
||||
- coroutine-capable;
|
||||
- single execution context; retired SPAWN/YIELD/SLEEP are rejected;
|
||||
- embedded inside the larger PROMETEU console model, not equal to it.
|
||||
|
||||
## Program Registry v1 integration
|
||||
@@ -154,3 +155,5 @@ STRUCT operations require a Struct descriptor; ARRAY operations require an Array
|
||||
After charging the attempt, incomplete temporary operands trap with STACK_UNDERFLOW. Instance operations check receiver carrier, absence, liveness/generation, category, Registry and exact TypeId first; array access then checks exact Int64 index and bounds; SET checks the complete value group last. There is no numeric, Trait or Dynamic coercion. Negative lengths or indices and indices at/above length trap with OOB (0x03); wrong carriers/types/groups trap with TYPE (0x04); absent receivers with NULL_REFERENCE (0x0E); invalid/dead/stale handles with INVALID_HANDLE (0x0F). Positive lengths above u32, checked size/cost overflow, resource quotas and recoverable allocation failures trap with RESOURCE_LIMIT (0x10), preserving resource reason/requested/limit. Static invalid TypeIds/categories/fields produce LOAD_INVALID_REFERENCE; proven stack/type conflicts produce LOAD_INVALID_CODE. Runtime TrapInfo preserves the attempted PC, opcode and available source span.
|
||||
|
||||
Publication and ownership follow [typed collection memory](03-memory-stack-heap-and-allocation.md); charging follows [time and cycles](01-time-model-and-cycles.md). See the [producer handoff](../../vm-arch/collection-producer-handoff.md) for independent byte oracles and construction examples. Production consumers must enter through the validated PBX v1 image boundary described in [Program Registry](02c-program-registry-and-pbx-v1.md).
|
||||
|
||||
Typed callable instructions are MAKE_CLOSURE `(FunctionId,FnTypeId)`, CALL_CLOSURE `(FnTypeId)`, GET_CAPTURE `(index)` and CALL_TRAIT `(TraitTypeId,method_index)`. Their groups, encodings and attempted costs are defined in the [Fn contract](02b-vm-function-values-and-closures.md). Numbers 0x54–0x56 stay reserved and reject anywhere at load.
|
||||
|
||||
@@ -125,7 +125,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 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.
|
||||
|
||||
@@ -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).
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -113,7 +113,7 @@ Properties:
|
||||
- there is no raw pointer arithmetic in the VM model;
|
||||
- layout rules are explicit and verifier/runtime-friendly.
|
||||
|
||||
Closures and coroutine-owned state may build on top of this memory model, but their behavioral rules are documented separately:
|
||||
Closures and frame-owned environments use this memory model; their behavioral rules are documented separately:
|
||||
|
||||
- [`02b-vm-function-values-and-closures.md`](02b-vm-function-values-and-closures.md)
|
||||
- [`09a-coroutines-and-cooperative-scheduling.md`](09a-coroutines-and-cooperative-scheduling.md)
|
||||
@@ -126,7 +126,7 @@ The PVM uses a **mark-sweep collector**.
|
||||
|
||||
- non-moving in the baseline model;
|
||||
- runs only at safepoints;
|
||||
- primary safepoint: `FRAME_SYNC`.
|
||||
- threshold opportunities: `FRAME_SYNC` and successful last-root `RET`, after rooting results.
|
||||
|
||||
### GC triggers
|
||||
|
||||
@@ -141,7 +141,6 @@ The collector marks from:
|
||||
- operand stack;
|
||||
- call stack frames;
|
||||
- global variables;
|
||||
- coroutine-owned execution state;
|
||||
- closure environments;
|
||||
- host-held roots where the host legally retains VM heap references.
|
||||
|
||||
@@ -195,7 +194,7 @@ Any violation results in a trap or rejected program image.
|
||||
|
||||
- [`02a-vm-values-and-calling-convention.md`](02a-vm-values-and-calling-convention.md) defines stack values and tuple/call-slot semantics.
|
||||
- [`02b-vm-function-values-and-closures.md`](02b-vm-function-values-and-closures.md) defines closure function values.
|
||||
- [`09a-coroutines-and-cooperative-scheduling.md`](09a-coroutines-and-cooperative-scheduling.md) defines coroutine state and scheduling behavior.
|
||||
- [`09a-coroutines-and-cooperative-scheduling.md`](09a-coroutines-and-cooperative-scheduling.md) defines direct execution ownership and frame continuation.
|
||||
- [`15-asset-management.md`](15-asset-management.md) defines asset-bank surfaces outside VM heap ownership.
|
||||
- [`08-save-memory-and-memcard.md`](08-save-memory-and-memcard.md) defines save storage outside VM heap ownership.
|
||||
- [`16a-syscall-policies.md`](16a-syscall-policies.md) defines host-root rules and host/heap interaction policy.
|
||||
@@ -214,3 +213,7 @@ NEW fully initializes all storage before publishing a handle: primitive/builtin
|
||||
GET copies a complete group and native owners without implicit boxing; SET validates the entire group before replacing it. String copies retain Arc ownership/provenance/accounting; null and empty String differ. Trait stores receiver and ImplementationId together (zero is a valid implementation); Dynamic preserves its complete pair and shares existing immutable boxes.
|
||||
|
||||
After validation, an attempt provisionally reserves net stack growth and construction resources, keeping source operands/roots alive. It prepares complete defaults/results before publication. Commit replaces the whole stored group or publishes the complete result, then consumes operands. No fallible reservation/allocation follows publication. Refusal preserves operands and prior storage/owners, publishes no partial handle, and releases provisional reservations/owners. Attempted work/cycles are retained; preexisting auxiliary capacities follow their existing growth contract. NEW never invokes reentrant GC or scheduling to satisfy quota. GC remains confined to established safepoints; live transitively rooted graphs and native owners survive them, while unrooted cycles become reclaimable.
|
||||
|
||||
## Typed Fn and Root-Return Collection
|
||||
|
||||
Threshold GC opportunities are FRAME_SYNC and successful RET of the last root, after results are transferred and rooted. No automatic GC at ordinary callee RET, entry preparation or allocation/quota refusal. VM owns its single execution context directly. Roots include globals, all live operand values, Closures retained by every active CallFrame and legally retained native/host roots. Trace complete typed capture/cell graphs; unreachable cycles collect. Inspection snapshots and raw handle copies create no guest root or session import. Results remain roots until consumed/replaced/reset/unload. Scratch refusal preserves owners and prohibits partial sweep.
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
Domain: virtual hardware: graphics
|
||||
Function: normative
|
||||
|
||||
Didactic companion: [`../learn/mental-model-gfx.md`](../runtime/learn/mental-model-gfx.md)
|
||||
Didactic companion: [GFX Mental Model](../../../discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0011-mental-model-gfx.md)
|
||||
|
||||
## 1. Overview
|
||||
|
||||
|
||||
@@ -5,7 +5,7 @@ Function: normative
|
||||
|
||||
This chapter defines events, timers, faults, and the frame-boundary model of the PROMETEU machine.
|
||||
|
||||
Coroutine lifecycle and cooperative scheduling details now live in a dedicated companion chapter.
|
||||
Single-context continuation and retired coroutine operations are defined in the companion lifecycle chapter.
|
||||
|
||||
## 1 Core Philosophy
|
||||
|
||||
@@ -250,7 +250,9 @@ PROMETEU discourages:
|
||||
|
||||
## 12 Relationship to Other Specs
|
||||
|
||||
- [`09a-coroutines-and-cooperative-scheduling.md`](09a-coroutines-and-cooperative-scheduling.md) defines coroutine lifecycle and scheduling behavior.
|
||||
- [`09a-coroutines-and-cooperative-scheduling.md`](09a-coroutines-and-cooperative-scheduling.md) defines single-context continuation, root completion and retired coroutine operations.
|
||||
- [`10-debug-inspection-and-profiling.md`](10-debug-inspection-and-profiling.md) defines observability and diagnostics surfaces.
|
||||
- [`12-firmware-pos-and-prometeuhub.md`](12-firmware-pos-and-prometeuhub.md) defines firmware orchestration at machine level.
|
||||
- [`02-vm-instruction-set.md`](02-vm-instruction-set.md) defines VM execution inside this frame model.
|
||||
|
||||
Logical frames also complete on successful RET of the last root. FRAME_SYNC instead preserves context and resumes next PC; budget exhaustion preserves the same open frame. Neither preparation nor callback calls create a coroutine scheduling phase.
|
||||
|
||||
@@ -1,107 +1,36 @@
|
||||
# Coroutines and Cooperative Scheduling
|
||||
# Single Execution Context and Frame Continuation
|
||||
|
||||
Domain: VM coroutine model
|
||||
Domain: VM execution lifecycle
|
||||
Function: normative
|
||||
|
||||
This chapter isolates PROMETEU coroutine semantics from the broader event/frame model.
|
||||
VM directly owns one PC, operand stack, call stack and globals. Entry preparation
|
||||
does not allocate a heap execution object. There are no guest coroutine instances,
|
||||
ready/sleeping queues, sleeper clock or coroutine scheduling phase.
|
||||
|
||||
## 1 Coroutine Model
|
||||
SPAWN/YIELD/SLEEP are retired; 0x54–0x56 remain reserved. Loading MUST reject them
|
||||
before execution, including unreachable code. Assembler rejects their mnemonics;
|
||||
diagnostic decoding can identify retired numbers. No compatibility mode exists.
|
||||
Other instruction numbers are unchanged.
|
||||
|
||||
PROMETEU provides coroutines as the only guest-visible concurrency model.
|
||||
FRAME_SYNC closes a logical frame and preserves context. It has zero stack effect,
|
||||
is not a terminator, can occur in any body and resumes next PC. Host MUST NOT
|
||||
prepare fresh entry solely because sync occurred. Budget exhaustion/breakpoints
|
||||
preserve the same open frame without draw publication or extra callback budget.
|
||||
|
||||
Coroutines are:
|
||||
Successful RET of the last root completes entry and leaves rooted results on VM
|
||||
stack. Recurring host may prepare FunctionId 0 next logical frame, preserving
|
||||
globals/init guard. Callee RET does not close a frame. Replacement preparation
|
||||
validates/reserves before releasing owners. HALT/trap/reset/unload retain their
|
||||
contracts.
|
||||
|
||||
- cooperative;
|
||||
- deterministic;
|
||||
- scheduled only at safepoints;
|
||||
- never preemptive.
|
||||
Threshold GC opportunities are sync and successful root RET after result rooting.
|
||||
Preparation, ordinary callee RET and allocation failure add no opportunity. GC
|
||||
advances no clock/frame, grants no budget and invokes no guest cleanup/callback.
|
||||
Asset/render workers retain their independent protocols and run no guest code;
|
||||
no physical-core affinity is implied.
|
||||
|
||||
There is:
|
||||
|
||||
- no parallel execution;
|
||||
- no hidden threads;
|
||||
- no scheduler behavior outside explicit machine rules.
|
||||
|
||||
## 2 Coroutine Lifecycle
|
||||
|
||||
Each coroutine can be in one of the following states:
|
||||
|
||||
- `Ready`
|
||||
- `Running`
|
||||
- `Sleeping`
|
||||
- `Finished`
|
||||
|
||||
Coroutine-local execution state includes, conceptually:
|
||||
|
||||
```
|
||||
Coroutine {
|
||||
call_stack
|
||||
operand_stack
|
||||
state
|
||||
}
|
||||
```
|
||||
|
||||
## 3 Scheduling
|
||||
|
||||
At each eligible scheduling boundary:
|
||||
|
||||
1. the scheduler selects the next coroutine;
|
||||
2. ordering remains deterministic;
|
||||
3. execution continues within the frame-budget model.
|
||||
|
||||
Baseline policy:
|
||||
|
||||
- round-robin or equivalent deterministic ordering;
|
||||
- no surprise priority inversion hidden from the model;
|
||||
- no preemption between safepoints.
|
||||
|
||||
## 4 Coroutine Operations
|
||||
|
||||
Typical operations:
|
||||
|
||||
| Operation | Description |
|
||||
| --------- | ----------------------------- |
|
||||
| `spawn` | Create a coroutine |
|
||||
| `yield` | Voluntarily suspend execution |
|
||||
| `sleep` | Suspend for N frames |
|
||||
|
||||
`yield` and `sleep` only take effect at safepoints.
|
||||
|
||||
## 5 Interaction with the Frame Loop
|
||||
|
||||
Coroutine scheduling happens inside the frame model, not beside it.
|
||||
|
||||
Conceptually:
|
||||
|
||||
```
|
||||
FRAME N
|
||||
------------------------
|
||||
Sample Input
|
||||
Deliver Events
|
||||
Schedule Coroutine
|
||||
Run VM
|
||||
FRAME_SYNC
|
||||
------------------------
|
||||
```
|
||||
|
||||
This preserves:
|
||||
|
||||
- deterministic replay;
|
||||
- explicit cost accounting;
|
||||
- consistent host/runtime handoff.
|
||||
|
||||
## 6 Costs and Determinism
|
||||
|
||||
Coroutine management:
|
||||
|
||||
- consumes cycles;
|
||||
- contributes to certification/cost reporting;
|
||||
- remains part of the deterministic execution trace.
|
||||
|
||||
Nothing about scheduling is "free" or hidden.
|
||||
|
||||
## 7 Relationship to Other Specs
|
||||
|
||||
- [`09-events-and-concurrency.md`](09-events-and-concurrency.md) defines the broader frame/event model.
|
||||
- [`02-vm-instruction-set.md`](02-vm-instruction-set.md) defines coroutine-related instruction families.
|
||||
- [`03-memory-stack-heap-and-allocation.md`](03-memory-stack-heap-and-allocation.md) defines coroutine-owned execution state in the memory model.
|
||||
Persistent operations can advance through short steps in normal frame execution
|
||||
and invoke typed Fn callbacks. UI/SDK APIs and future coroutine protocols require
|
||||
separate contracts. See [Fn](02b-vm-function-values-and-closures.md),
|
||||
[events](09-events-and-concurrency.md) and
|
||||
[memory](03-memory-stack-heap-and-allocation.md).
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
Domain: machine diagnostics
|
||||
Function: normative
|
||||
|
||||
Didactic companion: [`../learn/mental-model-observability-and-debugging.md`](../runtime/learn/mental-model-observability-and-debugging.md)
|
||||
Didactic companion: [Observability and Debugging Mental Model](../../../discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0013-mental-model-observability-and-debugging.md)
|
||||
|
||||
## 1 Scope
|
||||
|
||||
|
||||
@@ -29,7 +29,7 @@ The VM does not own the machine lifecycle. Firmware does.
|
||||
- **PVM**: the VM subsystem that executes cartridge bytecode.
|
||||
- **Cartridge**: the executable package loaded by firmware.
|
||||
- **AppMode**: cartridge mode, currently `Game` or `System`.
|
||||
- **Logical frame**: execution unit completed when the app reaches `FRAME_SYNC`.
|
||||
- **Logical frame**: execution unit completed when the app reaches FRAME_SYNC or successfully returns from its last root. Sync preserves next-PC continuation; root return completes entry.
|
||||
- **Host tick**: the host-driven outer update tick.
|
||||
- **Process**: technical execution owned by POS lifecycle.
|
||||
- **Task**: navigable presence associated with an app flow.
|
||||
@@ -73,7 +73,7 @@ POS is responsible for:
|
||||
At the VM boundary, POS must preserve:
|
||||
|
||||
- logical-frame semantics;
|
||||
- `FRAME_SYNC` as the canonical frame boundary;
|
||||
- `FRAME_SYNC` and successful last-root `RET` as logical frame boundaries;
|
||||
- deterministic transition from host tick to VM slice execution.
|
||||
|
||||
Firmware must not treat a single global VM object as the canonical execution
|
||||
@@ -336,9 +336,9 @@ These states express machine orchestration above the VM. They are not guest-visi
|
||||
For game-mode execution, firmware/runtime coordination preserves:
|
||||
|
||||
- input latched per logical frame;
|
||||
- execution in host-driven slices until `FRAME_SYNC`;
|
||||
- execution in host-driven slices until `FRAME_SYNC` or successful last-root `RET`;
|
||||
- present only when a logical frame completes;
|
||||
- no frame present when budget ends before `FRAME_SYNC`.
|
||||
- no frame present when budget ends before a logical frame boundary.
|
||||
|
||||
This keeps the machine model deterministic and observable.
|
||||
|
||||
|
||||
@@ -221,3 +221,7 @@ The cartridge spec therefore distinguishes:
|
||||
## Program Registry v1 integration
|
||||
|
||||
Program payloads MUST use the PBX v1 envelope and mandatory sections defined in [Program Registry and PBX v1](02c-program-registry-and-pbx-v1.md#pbx-v1-encoding). The file limit is 64 MiB and Code is limited to 32 MiB. Unsupported versions are rejected; runtime examples are regenerated rather than converted by a compatibility loader. The existing func_id = 0 boot authority is unchanged.
|
||||
|
||||
## Fn Execution Boundary
|
||||
|
||||
Typed Fn callbacks execute as ordinary guest calls on the single VM context. Boot remains physical FunctionId 0; preparation requires an empty capture environment and existing argument checks. FRAME_SYNC preserves context for next-PC resumption; successful last-root RET completes entry and leaves rooted results before threshold GC. No native callback registration, retention or reentry API is introduced; raw HeapRef/ValueSnapshot copies do not establish guest roots or authorize cross-session imports. Syscalls remain non-first-class.
|
||||
|
||||
@@ -387,3 +387,7 @@ Only user-defined functions and closures are first-class.
|
||||
## Program Registry v1 integration
|
||||
|
||||
Native boundaries MUST respect the [Registry typed-value and ownership contract](02c-program-registry-and-pbx-v1.md): exact carriers and complete groups, generational reference validation, string provenance and preallocation quotas. Existing SYSC binding errors remain structured and separate from Registry errors. Input consists of 54 VM-owned fixed queries, never endpoint objects or host syscalls.
|
||||
|
||||
## Fn Execution Boundary
|
||||
|
||||
Typed Fn callbacks execute as ordinary guest calls on the single VM context. Boot remains physical FunctionId 0; preparation requires an empty capture environment and existing argument checks. FRAME_SYNC preserves context for next-PC resumption; successful last-root RET completes entry and leaves rooted results before threshold GC. No native callback registration, retention or reentry API is introduced; raw HeapRef/ValueSnapshot copies do not establish guest roots or authorize cross-session imports. Syscalls remain non-first-class.
|
||||
|
||||
@@ -179,3 +179,7 @@ This keeps the host ABI compatible with a deterministic frame machine.
|
||||
- [`03-memory-stack-heap-and-allocation.md`](03-memory-stack-heap-and-allocation.md) defines VM heap ownership and handles.
|
||||
- [`10-debug-inspection-and-profiling.md`](10-debug-inspection-and-profiling.md) defines visibility of cost and diagnostics.
|
||||
- domain chapters (e.g. `04`, `05`, `15`) define per-operation status tables.
|
||||
|
||||
## Fn Execution Boundary
|
||||
|
||||
Typed Fn callbacks execute as ordinary guest calls on the single VM context. Boot remains physical FunctionId 0; preparation requires an empty capture environment and existing argument checks. FRAME_SYNC preserves context for next-PC resumption; successful last-root RET completes entry and leaves rooted results before threshold GC. No native callback registration, retention or reentry API is introduced; raw HeapRef/ValueSnapshot copies do not establish guest roots or authorize cross-session imports. Syscalls remain non-first-class.
|
||||
|
||||
@@ -23,7 +23,6 @@ Does not belong in `docs/specs/runtime/` as the primary canonical source:
|
||||
- bytecode-level ISA:
|
||||
[`../virtual-machine/ISA_CORE.md`](../../vm-arch/ISA_CORE.md);
|
||||
- pedagogical guides and learning material:
|
||||
[`../learn/README.md`](../runtime/learn/README.md) and
|
||||
[published lessons](../../../discussion/lessons/).
|
||||
|
||||
## Organization Rules
|
||||
@@ -87,7 +86,7 @@ In the current state, no chapter under the active `docs/specs/runtime/` root is
|
||||
| [`07-touch-peripheral.md`](07-touch-peripheral.md) | virtual hardware: touch | normative |
|
||||
| [`08-save-memory-and-memcard.md`](08-save-memory-and-memcard.md) | virtual hardware: save memory | normative |
|
||||
| [`09-events-and-concurrency.md`](09-events-and-concurrency.md) | machine events and frame scheduling | normative |
|
||||
| [`09a-coroutines-and-cooperative-scheduling.md`](09a-coroutines-and-cooperative-scheduling.md) | VM coroutine model | normative |
|
||||
| [`09a-coroutines-and-cooperative-scheduling.md`](09a-coroutines-and-cooperative-scheduling.md) | Single execution context and frame continuation | normative |
|
||||
| [`10-debug-inspection-and-profiling.md`](10-debug-inspection-and-profiling.md) | machine diagnostics | normative |
|
||||
| [`11-portability-and-cross-platform-execution.md`](11-portability-and-cross-platform-execution.md) | portability contract | normative |
|
||||
| [`11a-headless-automation-protocol.md`](11a-headless-automation-protocol.md) | external headless host automation | normative |
|
||||
|
||||
@@ -2,7 +2,7 @@ Prometeu VM Runtime — Canonical Architecture
|
||||
|
||||
Status: canonical
|
||||
|
||||
This document is the authoritative architectural reference for the Prometeu VM runtime. It reflects the implementation as it exists today and defines the invariants that govern architectural changes in the VM layer.
|
||||
This document is the authoritative architectural reference for the Prometeu VM runtime. It defines the invariants that govern architectural changes in the VM layer.
|
||||
|
||||
Scope boundary:
|
||||
|
||||
@@ -14,7 +14,7 @@ Scope boundary:
|
||||
Document roles:
|
||||
|
||||
- This file is normative for VM/runtime architecture.
|
||||
- Detailed domain specifications may live under `docs/runtime/specs/`, but they must not contradict this document where VM/runtime invariants are concerned.
|
||||
- Detailed domain specifications may live under `docs/specs/runtime/`, but they must not contradict this document where VM/runtime invariants are concerned.
|
||||
- Future architectural changes become authoritative when this document is updated.
|
||||
- The machine-wide fantasy console framing lives in the runtime specs manual and related domain specs; those documents are complementary, not competing VM architecture sources.
|
||||
|
||||
@@ -30,10 +30,10 @@ Maintenance rule:
|
||||
- Operand stack + call frames; bytecode is fetched from a ROM/program image with a separate constant pool.
|
||||
- GC‑managed heap
|
||||
- Non‑compacting mark–sweep collector; stable object handles (`HeapRef`) while live. Sweep invalidates unreachable handles; objects are never moved.
|
||||
- Closures (Model B)
|
||||
- First‑class closures with a heap‑allocated environment. The closure object is passed to the callee as a hidden `arg0` when invoking a closure.
|
||||
- Cooperative coroutines
|
||||
- Deterministic, cooperative scheduling. Switching and GC occur only at explicit safepoints (`FRAME_SYNC`).
|
||||
- Typed first-class Fn
|
||||
- Structural logical parameter/result signatures and heap Closure environments retained by CallFrames, without hidden arg0.
|
||||
- Single execution context
|
||||
- VM directly owns PC, stacks and globals; no heap Coroutine or guest scheduler. GC opportunities are FRAME_SYNC and successful last-root RET after result rooting.
|
||||
- Unified syscall ABI
|
||||
- PBX pre-load artifacts declare canonical host bindings in `SYSC` and encode call sites as `HOSTCALL <sysc_index>`. The loader resolves and patches them to numeric `SYSCALL <id>` before verification/execution. Capability gating is enforced at load and checked again defensively at runtime. Syscalls are not first‑class values.
|
||||
|
||||
@@ -57,20 +57,19 @@ Maintenance rule:
|
||||
- Variable-length arrays use the Registry element layout and defaults. Primitive/builtin values are stored directly; Struct/Array elements contain generational references. Native String/Dynamic slots retain their ownership rules. Stack/local execution continues to use `Value`.
|
||||
- Closures
|
||||
- Carry a function identifier and a captured environment (a slice/vector of `Value`s stored with the closure). Captured `HeapRef`s are traversed by the GC.
|
||||
- Coroutines
|
||||
- Heap‑resident coroutine records (state + wake time + suspended operand stack and call frames). These act as GC roots when suspended.
|
||||
- Structs and Dynamic boxes
|
||||
- Typed payloads use resolved reference/ownership maps. Private Struct cells can share mutable captured bindings.
|
||||
|
||||
Notes:
|
||||
- Literals like strings and numbers are sourced from the constant pool in the program image; heap allocation is only used for runtime objects (closures, arrays, coroutine records, and any future heap kinds). The constant pool never embeds raw `HeapRef`s.
|
||||
- Literals like strings and numbers are sourced from the constant pool in the program image; heap allocation is only used for runtime objects (closures, arrays, Structs and Dynamic boxes). The constant pool never embeds raw `HeapRef`s.
|
||||
|
||||
2.3 GC Roots
|
||||
|
||||
- VM roots
|
||||
- Current operand stack and call frames of the running coroutine (or main context).
|
||||
- Suspended coroutines
|
||||
- All heap‑resident, suspended coroutine objects are treated as roots. Their saved stacks/frames are scanned during marking.
|
||||
- Root traversal
|
||||
- The VM exposes a root‑visitor that walks the operand stack, frames, and coroutine records to feed the collector. The collector then follows children from each object kind (e.g., array elements, closure environments, coroutine stacks).
|
||||
- Roots comprise globals, all live operand values, Closure owners in every active
|
||||
CallFrame and legally retained native/host roots. Inspection snapshots are not
|
||||
guest roots. Tracing visits complete typed fields, arrays, captures and cells.
|
||||
- Root results are transferred/rooted before the last frame is removed or GC runs,
|
||||
and remain owned until consumed/replaced/reset/unloaded. Unreachable cycles collect.
|
||||
|
||||
|
||||
3. Execution Model
|
||||
@@ -85,20 +84,22 @@ Notes:
|
||||
|
||||
3.2 Safepoints
|
||||
|
||||
- `FRAME_SYNC` is the only safepoint.
|
||||
- At `FRAME_SYNC`, the VM performs two actions in a well‑defined order:
|
||||
1) Garbage‑collection opportunity: root enumeration + mark–sweep.
|
||||
2) Scheduler handoff: the currently running coroutine may yield/sleep, and a next ready coroutine is selected deterministically.
|
||||
- No other opcode constitutes a GC or scheduling safepoint. Syscalls do not implicitly trigger GC or rescheduling.
|
||||
- Threshold GC opportunities are FRAME_SYNC and successful RET of the last root,
|
||||
after result rooting. Ordinary callee RET, entry preparation, syscalls and
|
||||
allocation/quota refusal do not collect. GC adds no guest callback, clock/frame
|
||||
advance, budget grant or partial sweep on scratch failure.
|
||||
|
||||
3.3 Scheduler Behavior (Cooperative Coroutines)
|
||||
3.3 Single Context and Host Continuation
|
||||
|
||||
- Coroutines are cooperative and scheduled deterministically (FIFO among ready coroutines).
|
||||
- `YIELD` and `SLEEP` take effect at `FRAME_SYNC`:
|
||||
- `YIELD` places the current coroutine at the end of the ready queue.
|
||||
- `SLEEP` parks the current coroutine until its exact `wake_tick`, after which it re‑enters the ready queue at the correct point.
|
||||
- `SPAWN` creates a new coroutine with its own stack/frames recorded in the heap and enqueues it deterministically.
|
||||
- No preemption: the VM never interrupts a coroutine between safepoints.
|
||||
- FRAME_SYNC may occur in any body, has no stack effect and resumes next PC with
|
||||
live frames/locals/environments. It closes the logical frame but does not restart
|
||||
entry. Budget exhaustion/breakpoints preserve the same open logical frame.
|
||||
- Last-root RET completes entry. Recurring host prepares FunctionId 0 next frame,
|
||||
preserving globals/init guard; preparation validates/reserves before replacing
|
||||
previous owners and allocates no Coroutine. HALT/trap/reset/unload retain their
|
||||
contracts. Render/asset workers remain independent of guest execution.
|
||||
- SPAWN/YIELD/SLEEP are retired: numbers 0x54–0x56 stay reserved and all uses reject
|
||||
at load, including unreachable code. No compatibility scheduler remains.
|
||||
|
||||
|
||||
4. Verification Model
|
||||
@@ -119,25 +120,33 @@ The verifier statically checks bytecode for structural safety and stack‑shape
|
||||
- Syscalls
|
||||
- The verifier runs only on the patched executable image. `HOSTCALL` is invalid at verification time. Final `SYSCALL` IDs must exist per `SyscallMeta`, and arity/declared return slot counts must match metadata.
|
||||
- Closures
|
||||
- `CALL_CLOSURE` is only allowed on closure values; the callee function must be known; argument counts for closure calls must match.
|
||||
- Coroutines
|
||||
- `YIELD` context must be valid; `SPAWN` argument counts are validated.
|
||||
- Expected FnTypeId determines complete parameter/result groups even when the concrete FunctionId is unknown. Known mismatch rejects; Unknown retains runtime checks. Capture indices and target metadata are checked, and direct entry into capturing bodies rejects.
|
||||
- Trait calls
|
||||
- Exact method signatures and complete views resolve through immutable tables; concrete receiver is the first callee parameter, with no capture environment.
|
||||
|
||||
4.2 Runtime vs Verifier Guarantees
|
||||
|
||||
- The Registry verifier checks structure and stack shape and conservatively tracks known types through control flow. It rejects proved incompatibilities; Unknown values retain runtime checks at typed boundaries. Numeric domain checks, polymorphic comparisons and concrete syscall argument validation may still trap at runtime. The legacy production loader remains pending the callable migration described below.
|
||||
- The Registry verifier checks structure and stack shape and conservatively tracks known types through control flow. It rejects proved incompatibilities; Unknown values retain runtime checks at typed boundaries. Numeric domain checks, polymorphic comparisons and concrete syscall argument validation may still trap at runtime.
|
||||
- Capability gating for syscalls is enforced at load from cartridge capability flags and checked again at runtime by the VM/native interface.
|
||||
|
||||
|
||||
5. Closures (Model B) — Calling Convention
|
||||
-------------------------------------------
|
||||
5. Typed Fn and Environments
|
||||
----------------------------
|
||||
|
||||
- Creation
|
||||
- `MAKE_CLOSURE` captures N values from the operand stack into a heap‑allocated environment alongside a function identifier. The opcode _pushes a `HeapRef` to the new closure.
|
||||
- Call
|
||||
- `CALL_CLOSURE` invokes a closure. The closure object itself is supplied to the callee as a hidden `arg0`. User‑visible arguments follow the function’s declared arity.
|
||||
- Access to captures
|
||||
- The callee can access captured values via the closure’s environment. Captured `HeapRef`s are traced by the GC.
|
||||
- Fn identity is ordered logical parameter/result TypeIds; names, target and captures
|
||||
are metadata. Pure Array/Fn structural cycles reject; nominal anchors stop expansion.
|
||||
- MAKE_CLOSURE takes FunctionId/FnTypeId, captures full declared groups and pushes a
|
||||
distinct one-slot instance. Immutable bindings copy values; mutable bindings can
|
||||
share private typed Struct cells. Metadata lives in required PBX section 8.
|
||||
- CALL_CLOSURE takes expected FnTypeId and retains the Closure in CallFrame, without
|
||||
public arg0. GET_CAPTURE takes an index and copies a complete group. Direct calls
|
||||
to capturing bodies reject; bound receivers use explicit adapter bodies.
|
||||
- Fn is valid in Struct/Array/Dynamic, defaults Null and compares instance identity.
|
||||
It gains no REF_* casts, Trait implementations, fault isolation or separate budget.
|
||||
- Validate/reserve before consume/publication; faults preserve input owners and expose
|
||||
no partial frame/object. Costs are 8+C / 6 / 2+W including traps, charged once.
|
||||
- CALL_TRAIT takes TraitTypeId/method index, consumes explicit args and a complete
|
||||
view, then passes concrete receiver first. Exact immutable-table dispatch costs 6.
|
||||
|
||||
|
||||
6. Unified Syscall ABI
|
||||
@@ -160,11 +169,11 @@ The verifier statically checks bytecode for structural safety and stack‑shape
|
||||
- Collector
|
||||
- Non‑moving mark–sweep.
|
||||
- Triggers
|
||||
- GC runs only at `FRAME_SYNC` safepoints.
|
||||
- Threshold GC runs at FRAME_SYNC and successful last-root RET after result rooting.
|
||||
- Liveness
|
||||
- Roots comprise: the live VM stack/frames and all suspended coroutines. The collector traverses object‑specific children (array elements, closure environments, coroutine stacks).
|
||||
- Globals, live operand values and active-frame Closures root complete typed object graphs, including cells and legally retained host/native owners.
|
||||
- Determinism
|
||||
- GC opportunities and scheduling order are tied to `FRAME_SYNC`, ensuring repeatable execution traces across runs with the same inputs.
|
||||
- Opportunities depend on execution boundaries and thresholds, preserving deterministic guest execution with the same inputs.
|
||||
|
||||
|
||||
8. Non‑Goals
|
||||
@@ -180,12 +189,12 @@ The verifier statically checks bytecode for structural safety and stack‑shape
|
||||
--------------------------
|
||||
|
||||
- Keep the public surface minimal and metadata‑driven (e.g., syscalls via `SyscallMeta`).
|
||||
- Do not assume implicit safepoints; schedule and GC only at `FRAME_SYNC`.
|
||||
- Preserve explicit GC opportunities and root results before root-return collection.
|
||||
- When adding new opcodes or object kinds, extend the verifier and GC traversal accordingly (children enumeration, environment scanning, root sets).
|
||||
- Update this document alongside any architectural change that affects runtime invariants.
|
||||
|
||||
## Program Registry v1
|
||||
|
||||
The [Program Registry contract](../specs/runtime/02c-program-registry-and-pbx-v1.md) defines immutable image-owned Type/Function metadata linked by dense IDs. Descriptors are native metadata outside guest GC; nominal identity does not depend on names. Stack/local execution retains Value, while typed storage uses resolved aligned layouts. PBX v1 is the sole target format; publication requires full bounded validation. Callable/closure/coroutine typed integration awaits its separate contract and must preserve existing behavior until then.
|
||||
The [Program Registry contract](../specs/runtime/02c-program-registry-and-pbx-v1.md) defines immutable image-owned Type/Function metadata linked by dense IDs. Descriptors are native metadata outside guest GC; nominal identity does not depend on names. Stack/local execution retains Value, while typed storage uses resolved aligned layouts. PBX v1 is the sole target format; publication requires full bounded validation. Fn tag 4 and mandatory captures section 8 extend the Registry; no old-schema fallback is permitted.
|
||||
|
||||
`ValidatedProgramImage::load` publishes a shared image only after bounded decoding, native binding and Registry verification; `VirtualMachine::from_image` creates sessions that consume its typed signatures, constants and conversion instructions. Production `initialize` and the existing example generators remain pending coordinated migration that preserves typed callable behavior. [Registry Boundaries and Owned Values](../../discussion/lessons/DSC-0058-program-registry-type-and-function-metadata/LSN-0059-registry-boundaries-and-owned-values.md) explains the published mechanisms. The [producer handoff](registry-producer-handoff.md) documents schema, input IDs and named-argument order, while [layout evidence](registry-layout-evidence.md) records reproducible load/access/GC measurements and the current publication boundary.
|
||||
`ValidatedProgramImage::load` publishes a shared image only after bounded decoding, native binding and Registry verification; `VirtualMachine::from_image` creates sessions that consume its typed signatures, constants and conversion instructions. Production and internal generators must use this sole sealed-v1 path. Typed Fn integration and legacy removal are implemented together; publication alone is not proof that every consumer has migrated. [Registry Boundaries and Owned Values](../../discussion/lessons/DSC-0058-program-registry-type-and-function-metadata/LSN-0059-registry-boundaries-and-owned-values.md) explains the published mechanisms. The [producer handoff](registry-producer-handoff.md) documents schema, input IDs and named-argument order, while [layout evidence](registry-layout-evidence.md) records reproducible load/access/GC measurements and the current publication boundary.
|
||||
|
||||
+11
-11
@@ -64,13 +64,13 @@ Authority rule:
|
||||
- Functions and scopes:
|
||||
- `CALL u32` — call by function index; argument/result arity per function metadata.
|
||||
- `RET` — return from current function (block terminator).
|
||||
- `MAKE_CLOSURE u32,u32` — create closure from `(fn_id, capture_count)`.
|
||||
- `CALL_CLOSURE u32` — invoke closure with `arg_count` user arguments.
|
||||
- `MAKE_CLOSURE u32,u32` — create typed closure from `(FunctionId, FnTypeId)`; cost 8+C.
|
||||
- `CALL_CLOSURE u32` — invoke against expected FnTypeId; cost 6.
|
||||
- `GET_CAPTURE u32` (0x57) — copy indexed complete capture group from current frame; cost 2+W.
|
||||
- `CALL_TRAIT u32,u32` (0x58) — invoke TraitTypeId/method index through complete view; cost 6.
|
||||
|
||||
- Concurrency:
|
||||
- `SPAWN u32,u32` — create coroutine for `(fn_id, arg_count)`.
|
||||
- `YIELD` — request cooperative yield at the next safepoint.
|
||||
- `SLEEP u32` — request suspension for a logical tick duration.
|
||||
- Retired execution operations:
|
||||
- 0x54–0x56 (SPAWN/YIELD/SLEEP) remain reserved and reject at load, including unreachable code. Diagnostic decoding may identify them; no execution or assembler emission is permitted.
|
||||
|
||||
- System/Timing:
|
||||
- `HOSTCALL u32` — PBX pre-load host binding call by `SYSC` table index; the loader must resolve and rewrite it before verification or execution.
|
||||
@@ -110,7 +110,7 @@ For exact immediates and stack effects, see `CoreOpCode::spec()` which is the si
|
||||
|
||||
- The canonical decoder is `prometeu_bytecode::decode_next(pc, bytes)`.
|
||||
- It uses the Core ISA spec to determine immediate size and the canonical `next_pc`.
|
||||
- Unknown or legacy opcodes must produce a deterministic `UnknownOpcode` error.
|
||||
- Unknown opcodes produce deterministic UnknownOpcode errors; recognized retired opcodes produce structured load rejection before execution.
|
||||
|
||||
#### Module Boundary
|
||||
|
||||
@@ -122,20 +122,20 @@ For exact immediates and stack effects, see `CoreOpCode::spec()` which is the si
|
||||
#### Scope Notes
|
||||
|
||||
- "Core ISA" in the current repository means the canonical opcode surface implemented by the runtime today.
|
||||
- It includes closures, coroutines, `HOSTCALL` patching semantics, `INTRINSIC`, and `FRAME_SYNC`.
|
||||
- It includes typed closures, trait calls, `HOSTCALL` patching semantics, `INTRINSIC`, and `FRAME_SYNC`.
|
||||
- It does not, by itself, define higher-level runtime policy such as crash taxonomy, firmware behavior, cartridge lifecycle, or host service organization. Those belong to the canonical runtime architecture and related specs.
|
||||
|
||||
#### FRAME_SYNC — Semantics and Placement (Bytecode Level)
|
||||
|
||||
- Semantics:
|
||||
- `FRAME_SYNC` is a zero-operand instruction and does not modify the operand stack.
|
||||
- It marks a VM safepoint for GC and the cooperative scheduler. In `CoreOpcodeSpec` this is exposed as `spec.is_safepoint == true`.
|
||||
- On execution, the VM may suspend the current coroutine until the next frame boundary and/or perform GC. After resuming, execution continues at the next instruction.
|
||||
- It marks a VM safepoint for threshold GC. In `CoreOpcodeSpec` this is exposed as `spec.is_safepoint == true`.
|
||||
- Execution returns to the host at the logical frame boundary, preserving the single context. Resumption continues at the next instruction with live frames/locals/environments. Successful last-root RET is a separate GC opportunity after result rooting and completes that entry.
|
||||
|
||||
- Placement rules (representable and checkable):
|
||||
- `FRAME_SYNC` may appear anywhere inside a function body where normal instructions can appear. It is NOT a block terminator (`spec.is_terminator == false`).
|
||||
- Instruction boundaries are canonical: encoders/emitters must only place `FRAME_SYNC` at valid instruction PCs. The verifier already enforces “jump-to-boundary” and end-exclusive `[start, end)` function ranges using the canonical layout routine.
|
||||
- Entrypoints that represent a render/update loop SHOULD ensure at least one reachable `FRAME_SYNC` along every long-running path to provide deterministic safepoints for GC/scheduling. This policy is semantic and may be enforced by higher-level tooling; at the bytecode level it is representable via `spec.is_safepoint` and can be counted by static analyzers.
|
||||
- Entrypoints that represent a render/update loop SHOULD ensure at least one reachable `FRAME_SYNC` along every long-running path to provide deterministic safepoints for GC/frame handoff. This policy is semantic and may be enforced by higher-level tooling; at the bytecode level it is representable via `spec.is_safepoint` and can be counted by static analyzers.
|
||||
|
||||
- Disassembly:
|
||||
- Disassemblers must print the mnemonic `FRAME_SYNC` verbatim for this opcode.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Typed collection producer and consumer handoff
|
||||
|
||||
The [collection ISA](../specs/runtime/02-vm-instruction-set.md#typed-collection-instructions), [memory contract](../specs/runtime/03-memory-stack-heap-and-allocation.md#typed-array-and-struct-storage) and [attempt charging](../specs/runtime/01-time-model-and-cycles.md#collection-attempt-charging) are normative. This interface has executable evidence through locally serialized PBX v1, `ValidatedProgramImage::load` and `VirtualMachine::from_image`. Production initialize and example generators still require coordinated v1 migration; no external SDK or frontend activation is implied.
|
||||
The [collection ISA](../specs/runtime/02-vm-instruction-set.md#typed-collection-instructions), [memory contract](../specs/runtime/03-memory-stack-heap-and-allocation.md#typed-array-and-struct-storage) and [attempt charging](../specs/runtime/01-time-model-and-cycles.md#collection-attempt-charging) are normative. This interface has executable evidence through locally serialized PBX v1, `ValidatedProgramImage::load` and `VirtualMachine::from_image`. Production initialize, internal test producers and both example generators use the same sealed v1 path. External SDK/frontend adaptation remains a separate consumer obligation.
|
||||
|
||||
## Encoding and complete groups
|
||||
|
||||
@@ -58,10 +58,15 @@ Static bad IDs/categories/fields reject load with typed LOAD_INVALID_REFERENCE c
|
||||
|
||||
## Consumer integration and evidence
|
||||
|
||||
Consumers must recognize all seven encodings, invoke Registry-derived effects in bounded structural/height/type verification and use validated-image execution. Metadata-free/legacy verification rejects these instructions with RegistryRequired. Reuse compact typed storage, default initialization, native ownership maps and generational handles; do not replace them with raw Value arrays or SDK container implementations.
|
||||
Consumers must recognize all seven encodings, invoke Registry-derived effects in bounded structural/height/type verification and use validated-image execution. The metadata-free verifier and legacy decoder have been removed. Reuse compact typed storage, default initialization, native ownership maps and generational handles; do not replace them with raw Value arrays or SDK container implementations.
|
||||
|
||||
Executable oracles live in bytecode `tests/registry_isa.rs`, VM `tests/collection_conformance.rs`, VM `virtual_machine/collections_tests.rs` and layer `tests/typed_collections.rs`. They cover independent bytes, default/alias/group operations, attempt costs and refusals, malformed/proven types, ownership and actual FRAME_SYNC graph reclamation. VM unit tests inject otherwise unreachable invalid state only inside tests. Optimized ownership/conformance runs complement debug evidence.
|
||||
|
||||
Dummy Boy and Stress currently emit PBX version 0. The optional Dummy Boy palette migration therefore belongs with production v1 integration: initialize one global-rooted Array<color> containing red/green/blue, mirror its frame counter in exact Int64 at the same initialization/increment points, select mirror modulo ARRAY_LEN using ARRAY_GET, and compare six logical frames. Preserve phase/drawing and verify one array allocation plus safepoint retention. This independent collection delivery does not migrate those producers or claim that smoke has run.
|
||||
Dummy Boy and Stress emit sealed PBX v1, including empty captures sections, and
|
||||
run through the production host. Fn is a one-slot nullable HeapRef value in fields
|
||||
and arrays; Dynamic can carry it with its exact Fn TypeId. Closure environments and
|
||||
shared private cells participate in existing reference maps. Default construction
|
||||
never invokes callbacks. Threshold GC runs at FRAME_SYNC and successful last-root
|
||||
RET after rooting results. Quota refusal cannot invoke rescue GC.
|
||||
|
||||
The published patterns and validation limits are explained in [Collection Attempts Preserve Groups and Charge Work Before Publication](../../discussion/lessons/DSC-0051-game-state-collections-and-objects/LSN-0060-collection-attempts-preserve-groups-and-charge-work-before-publication.md).
|
||||
|
||||
@@ -3,30 +3,22 @@
|
||||
This document describes the Registry v1 producer and consumer interfaces. The normative contract
|
||||
is [Program Registry and PBX v1](../specs/runtime/02c-program-registry-and-pbx-v1.md).
|
||||
The rationale and published mechanisms are explained in [Registry Boundaries and Owned Values](../../discussion/lessons/DSC-0058-program-registry-type-and-function-metadata/LSN-0059-registry-boundaries-and-owned-values.md).
|
||||
The completed callable and production integration is explained in [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).
|
||||
|
||||
## Publication state
|
||||
|
||||
The bounded writer/owned decoder, sealed `ValidatedProgramImage::load`, shared
|
||||
session factory, typed direct-call/return boundaries, Dynamic/reference execution,
|
||||
fixed input catalogue, typed collection operations and string accounting have executable tests. The production
|
||||
`initialize` transition, removal of old unchecked entry points, all producer
|
||||
migration and both regenerated runtime examples remain pending. Existing closure
|
||||
receivers need a typed callable contract; none of the four accepted Registry
|
||||
categories may be used as a provisional closure type.
|
||||
The production `initialize` path uses bounded `ValidatedProgramImage::load` and
|
||||
`VirtualMachine::from_image`. The v0 decoder, slot-only verifier, scheduler and
|
||||
unchecked executable constructors have been removed. Internal test producers,
|
||||
Dummy Boy and Stress emit sealed v1 with typed Fn metadata and mandatory captures.
|
||||
The runtime retains existing constant/string ownership, collections, Dynamic and
|
||||
reference boundaries. The separate render frame scheduler remains active.
|
||||
|
||||
### Pending production integration
|
||||
|
||||
| Component | Pending implementation and validation |
|
||||
| --- | --- |
|
||||
| Loader and image | Switch production initialize to the sealed strict v1 factory; retire old decoder and unchecked entry points while preserving typed callable behavior. |
|
||||
| Constant ownership | Complete image/constant provenance on migrated production entry points using the delivered ledgers and native retention domains. |
|
||||
| Verification | Route production loads through bounded Registry verification; remove the old verifier while adding typed callable checks. |
|
||||
| Diagnostics | Audit structured load/runtime/native diagnostics through the final active loader and hosts. |
|
||||
| Producers and examples | Migrate producers/fixtures, regenerate dummy-boy and stress-console PBX files, and execute both through the active runtime. These generators are ordinary programs sharing the production consumer being migrated. |
|
||||
| Conformance | Add migrated producer/example/callable evidence to this handoff and the existing conformance matrix. |
|
||||
| Publication | Audit final coordinated publication, legacy removal, traceability and migrated workspace/examples. |
|
||||
|
||||
This integration reuses the delivered Registry foundation and [typed collection producer interface](collection-producer-handoff.md). New strings/bytes/save APIs, coordinated stress and representative-game headroom each require their own technical contract or validation workload.
|
||||
Fn values, frame-owned capture environments, typed indirect calls and receiver-first
|
||||
trait dispatch use [the function-value contract](../specs/runtime/02b-vm-function-values-and-closures.md).
|
||||
FRAME_SYNC resumes next PC; successful root RET permits recurring entry preparation.
|
||||
New strings/bytes/save APIs, long-run stress and representative-game headroom require
|
||||
separate technical contracts and workloads.
|
||||
|
||||
The external Studio handoff targets are the build-pipeline
|
||||
`backend/bytecode/BytecodeModule.java` and `backend/irvm/IRVMIntrinsicRegistry.java`,
|
||||
@@ -40,7 +32,7 @@ repository publishes requirements and oracles; those modules have not been edite
|
||||
Emit PBX version 1 only. The header is 32 bytes: magic at 0, u16 version at 4,
|
||||
little-endian flag 0 at 6, reserved zero at 7, section count at 8 and twenty zero
|
||||
bytes at 12. Directory entries are file-relative u32 kind/offset/length triples.
|
||||
Mandatory kinds are 0, 1, 2, 4, 5, 6 and 7; debug kind 3 is optional. Keep empty
|
||||
Mandatory kinds are 0, 1, 2, 4, 5, 6, 7 and 8; debug kind 3 is optional. Keep empty
|
||||
mandatory tables with count zero. Never skip unknown sections or retain a legacy
|
||||
fallback. Use the canonical chapter's field order and UTF-8 rules, not Rust layouts.
|
||||
|
||||
@@ -66,18 +58,19 @@ unknown declarations, invalid indices and unused declarations are rejected.
|
||||
## Independent binary oracles
|
||||
|
||||
The manually specified minimal executable in
|
||||
`crates/console/prometeu-bytecode/tests/registry_v1.rs::minimal_bytes` is 173 bytes.
|
||||
Its directory begins at 32; seven entries end at 116:
|
||||
`crates/console/prometeu-bytecode/tests/registry_v1.rs::minimal_bytes` is 193 bytes.
|
||||
Its directory begins at 32; eight entries end at 128:
|
||||
|
||||
| Kind | Offset | Length | Payload |
|
||||
| --- | ---: | ---: | --- |
|
||||
| constants | 116 | 4 | count 0 |
|
||||
| functions | 120 | 29 | one unnamed zero-parameter/result function, offset 0, length 2, locals/max 0 |
|
||||
| code | 149 | 2 | `01 00` (HALT) |
|
||||
| exports | 151 | 4 | count 0 |
|
||||
| syscalls | 155 | 4 | count 0 |
|
||||
| types | 159 | 10 | one unnamed Bool import, BuiltinId `0x0013` |
|
||||
| implementations | 169 | 4 | count 0 |
|
||||
| constants | 128 | 4 | count 0 |
|
||||
| functions | 132 | 29 | one unnamed zero-parameter/result function, offset 0, length 2, locals/max 0 |
|
||||
| code | 161 | 2 | `01 00` (HALT) |
|
||||
| exports | 163 | 4 | count 0 |
|
||||
| syscalls | 167 | 4 | count 0 |
|
||||
| types | 171 | 10 | one unnamed Bool import, BuiltinId `0x0013` |
|
||||
| implementations | 181 | 4 | count 0 |
|
||||
| captures | 185 | 8 | function count 1; empty environment |
|
||||
|
||||
The independent multi-slot fixture in the same suite declares `fn(vec2)->vec2`
|
||||
with TypeId 0, no serialized widths, no extra locals and max 2. Its fourteen code
|
||||
@@ -128,11 +121,11 @@ human wording or manufacture runtime PCs for rejected loads.
|
||||
| Consumer | Accepted handoff | Status / remaining ownership |
|
||||
| --- | --- | --- |
|
||||
| Studio/PBS | PBX schema, signatures/names, effect-order and binary oracles, nine imports, all input IDs and diagnostics | External implementation and source-language tests pending; no external edits claimed |
|
||||
| Collections | Typed aligned layouts/defaults, exact storage groups, reference/native maps and checked adapters | Internal containers are tested; guest collection operations/costs/GC integration require a complete operation contract |
|
||||
| Callables | Function/implementation tables and direct-call contracts; exact trait views | Callable/capture/dispatch/coroutine semantics and coordinated producer migration remain pending |
|
||||
| Collections | Typed aligned layouts/defaults, exact storage groups, reference/native maps and checked adapters | Typed collection operations, costs, complete-group storage and GC execute through the active sealed loader |
|
||||
| Callables | Function/implementation tables and direct-call contracts; exact trait views | Fn, typed captures, CALL_CLOSURE/GET_CAPTURE/CALL_TRAIT and single-context production migration are implemented |
|
||||
| Strings/bytes/save | Arc strings, image/session Weak ledgers, bounded native writers and explicit import/export provenance | Existing string paths are integrated; new operations and their operation-specific evidence remain pending |
|
||||
| Resource stability | Product ceilings, generational handles, fallible capacity reservations and structured faults | Focused ownership/quota rollback is core evidence; coordinated long-run/cross-host stress requires separate workloads |
|
||||
| Reference game | Runtime contract, example migration requirement and technical measurements | Game workload/headroom/readiness requires representative-game evidence, not unit test counts |
|
||||
| Reference game | Runtime contract, migrated example images and focused technical measurements | Game workload/headroom/readiness requires representative-game evidence, not unit test counts |
|
||||
|
||||
Image constant allocations are shared between sessions without a session-content
|
||||
charge. New/imported runtime allocations belong to their session; equal text does
|
||||
@@ -141,3 +134,26 @@ Arc. `ValueSnapshot` keeps domain owners alive while tooling retains values and
|
||||
serializes only the ordinary value list. Cross-session import copies external
|
||||
content into the destination domain. Stored String slots remain `Option<Arc<str>>`;
|
||||
native ownership is not a guest GC reference or an input hardware carrier.
|
||||
|
||||
## Callable producer obligations
|
||||
|
||||
Emit Fn tag 4 with ordered logical parameter AND result TypeIds; parameter names do
|
||||
not change identity. Emit one descriptor per signature. Array/Fn structural cycles
|
||||
must terminate at nominal Struct/Trait anchors. Function bodies carry no hidden arg0.
|
||||
Captures section 8 contains a u32 function count and, for every FunctionId in order,
|
||||
a u32 capture count followed by ordered TypeIds; emit explicit empty lists too.
|
||||
Mutable bindings lower to shared private typed Struct cells; immutable captures
|
||||
copy their complete values. CALL/host preparation cannot enter capturing bodies.
|
||||
|
||||
MAKE_CLOSURE 0x52 carries FunctionId/FnTypeId (10 bytes), CALL_CLOSURE 0x53 carries
|
||||
expected FnTypeId (6), GET_CAPTURE 0x57 carries environment-group index (6), and
|
||||
CALL_TRAIT 0x58 carries TraitTypeId/method index (10). Costs are 8+C, 6, 2+W and 6.
|
||||
Trait views follow explicit arguments; the target receives its concrete receiver
|
||||
first. Typed Fn can be stored in Struct/Array/Dynamic but cannot implement Trait.
|
||||
SPAWN/YIELD/SLEEP 0x54–0x56 reject anywhere in code. Old captures=/argc= assembler
|
||||
forms reject. Neither callbacks nor captures introduce a scheduling phase.
|
||||
|
||||
External compiler acceptance requires these exact bytes and signatures, Fn
|
||||
pass/return/storage, shared cells, named-argument evaluation order, nested sync
|
||||
continuation and structured failure tests. The runtime's binary/behavioral oracles
|
||||
are available; no external implementation is claimed.
|
||||
|
||||
Reference in New Issue
Block a user