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:
@@ -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