feat(pbs): add mutable lists and stable snapshot cursors
Implement SDK list<T> and Cursor<T> with trusted compiler bindings and generic storage publication across IR and PBX. Pin the runtime provider and include specs, conformance coverage, installed examples, and DSC-0090 lessons.
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,8 +14,8 @@ 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.
|
||||
- Roadmaps, agendas, and PR proposals may discuss future changes, but they are not authoritative until this document is updated.
|
||||
- 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.
|
||||
|
||||
Maintenance rule:
|
||||
@@ -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.
|
||||
|
||||
@@ -48,29 +48,28 @@ Maintenance rule:
|
||||
- The VM’s current operand stack and frames are GC roots.
|
||||
|
||||
- Heap
|
||||
- The heap stores runtime objects that require identity and reachability tracking. Handles are `HeapRef` indices into an internal object store.
|
||||
- The heap stores runtime objects that require identity and reachability tracking. Handles are `HeapRef { index: u32, generation: u32 }` values into an internal object store. Every access checks the live generation; reclaimed maximum-generation slots are retired permanently.
|
||||
- The collector is mark–sweep, non‑moving: it marks from roots, then reclaims unreachable objects without relocating survivors. Indices for live objects remain stable across collections.
|
||||
|
||||
2.2 Heap Object Kinds (as used today)
|
||||
|
||||
- Arrays of `Value`
|
||||
- Variable‑length arrays whose elements may contain further `HeapRef`s.
|
||||
- Typed arrays
|
||||
- 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 verifier guarantees structural correctness and stack‑shape invariants. It does not perform full type checking of value contents; dynamic checks (e.g., numeric domain checks, polymorphic comparisons, concrete syscall argument validation) occur at runtime and may trap.
|
||||
- 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,6 +189,16 @@ 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
|
||||
|
||||
The [Program Registry contract](../specs/runtime/02c-program-registry-and-pbx-v0.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 v0 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 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.
|
||||
|
||||
## VM-owned random core
|
||||
|
||||
See the [random contract](../specs/runtime/02e-vm-owned-random-core.md) for Random BuiltinId 0x0016, ObjectKind tag 9, intrinsics 0x4000–0x4003, atomic state mutation, bounded 4+8*N costs and rejection-limit trap 0x00000015. Random is managed by the VM heap and existing GC, without host entropy or PBX changes.
|
||||
|
||||
+71
-16
@@ -12,7 +12,7 @@ Machine boundary:
|
||||
Authority rule:
|
||||
|
||||
- This document is normative for bytecode-level encoding and opcode surface.
|
||||
- Runtime-wide invariants still live in [`../../ARCHITECTURE.md`](../../ARCHITECTURE.md).
|
||||
- Runtime-wide invariants still live in [`ARCHITECTURE.md`](ARCHITECTURE.md).
|
||||
- If a bytecode-level rule here conflicts with runtime architecture, the conflict must be resolved explicitly in both documents; neither should drift silently.
|
||||
|
||||
#### Encoding Rules
|
||||
@@ -51,6 +51,7 @@ Authority rule:
|
||||
- Arithmetic:
|
||||
- `ADD`, `SUB`, `MUL`, `DIV`, `MOD` — binary numeric ops.
|
||||
- `NEG` — unary numeric negation.
|
||||
- Integer arithmetic wraps at the resulting carrier width. For `DIV`, the signed minimum divided by `-1` returns that minimum; for `MOD`, the same operands return zero. Division or modulo by zero still traps. Mixed Int32/Int64 division promotes to Int64 before the operation.
|
||||
|
||||
- Comparison and logic:
|
||||
- `EQ`, `NEQ`, `LT`, `LTE`, `GT`, `GTE` — comparisons → `[bool]`.
|
||||
@@ -64,13 +65,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.
|
||||
@@ -97,12 +98,28 @@ Example:
|
||||
- `canonical_name` is the fully qualified intrinsic identity seen by compiler-side intrinsic pools.
|
||||
- `arg_slots` and `ret_slots` are the real stack effect contract for verifier/lowering consumers.
|
||||
- `arg_layout` and `ret_layout` use `|`-separated ABI atoms:
|
||||
- `int`
|
||||
- `float`
|
||||
- `bool`
|
||||
- `Int32`
|
||||
- `Int64`
|
||||
- `Float`
|
||||
- `Bool`
|
||||
- `String`
|
||||
- `builtin:<builtin_name>`
|
||||
- Rows must remain unique by both `(canonical_name, canonical_version)` and `final_id_hex` / `final_id_dec`.
|
||||
- Rows must remain deterministically ordered by final ID.
|
||||
- parameter_names uses ordered | separated names for flattened argument slots.
|
||||
- cost_model is fixed or random_rejection_v1. cost_cycles is the full fixed
|
||||
cost or the variable base. attempt_cost_cycles/max_attempts are zero for
|
||||
fixed entries; random.range publishes base 4, attempt 8, maximum 64.
|
||||
- Mathematical and random attempts charge upfront, including failure, without
|
||||
an additional generic INTRINSIC cycle. Random draws retain attempt costs.
|
||||
- mutates_guest_state distinguishes reproducible stateful calls from pure
|
||||
computation. It is true for all random entries; may_allocate is true only
|
||||
for random.new. Consumers must preserve stateful calls and source order.
|
||||
- Both [INTRINSICS.csv](INTRINSICS.csv) and
|
||||
[BUILTIN_CONSTANTS.csv](BUILTIN_CONSTANTS.csv) are generated from runtime
|
||||
descriptors. Float constants publish bits rather than decimal approximations.
|
||||
- See [numeric semantics and consumer examples](../specs/runtime/02d-gameplay-math-and-numeric-semantics.md)
|
||||
for math/mathf, scalar IDs 0x3000–0x3019, numeric traps and the revised vec2 v1 contract.
|
||||
|
||||
For exact immediates and stack effects, see `CoreOpCode::spec()` which is the single source of truth used by the decoder, disassembler, and verifier.
|
||||
|
||||
@@ -110,7 +127,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,24 +139,62 @@ 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.
|
||||
- Tools MAY optionally annotate it as a safepoint in comments, e.g., `FRAME_SYNC ; safepoint`.
|
||||
|
||||
- Verification notes:
|
||||
- The bytecode verifier treats `FRAME_SYNC` as a normal instruction with no stack effect and no control-flow targets. It is permitted before `RET`, between basic blocks, and as the last instruction of a function. Jumps targeting the function end (`pc == end`) remain valid under the end-exclusive rule.
|
||||
- The bytecode verifier treats `FRAME_SYNC` as a normal instruction with no stack effect and no control-flow targets. It is permitted before `RET` and between basic blocks; a reachable path must still terminate explicitly rather than fall through the function range. Jumps targeting the function end (`pc == end`) remain valid under the end-exclusive rule. A taken end branch completes the current call with the same result-height/type checks, frame release and root-return safepoint as `RET`. It consumes only the decoded branch's cycles, without an additional implicit `RET` charge, and never executes the neighboring function or range gap.
|
||||
|
||||
## Registry instruction encodings
|
||||
|
||||
The [Registry contract](../specs/runtime/02c-program-registry-and-pbx-v0.md#dynamic-and-reference-instructions)
|
||||
defines opcodes 0x0090–0x0096. Tooling recognizes their u32 TypeId immediates:
|
||||
|
||||
```text
|
||||
DYN_PACK 0
|
||||
DYN_UNPACK 0
|
||||
DYN_CAN_UNPACK 0
|
||||
REF_IS_EXACT source=4, target=5
|
||||
REF_IMPLEMENTS source=4, target=6
|
||||
REF_TO_TRAIT source=4, target=6
|
||||
REF_CAST source=6, target=4
|
||||
```
|
||||
|
||||
Dynamic instructions occupy six bytes; reference instructions occupy ten bytes.
|
||||
Static opcode metadata must represent Registry-dependent slot effects as unresolved,
|
||||
never as zero. Resolve the semantic widths and immediate categories from the validated
|
||||
Registry. Encoding/decoding support alone does not authorize execution: a slot-only
|
||||
image/verifier must reject these instructions until typed-image integration is present.
|
||||
|
||||
#### Registry-backed collections
|
||||
|
||||
STRUCT_NEW (0x00A0), STRUCT_GET (0x00A1), STRUCT_SET (0x00A2), ARRAY_NEW (0x00A3), ARRAY_LEN (0x00A4), ARRAY_GET (0x00A5) and ARRAY_SET (0x00A6) require a validated Registry. Their exact immediates, full group effects, attempt costs and failure ordering are normative in the [typed collection instruction table](../specs/runtime/02-vm-instruction-set.md#typed-collection-instructions). These operations have no implicit conversion or safepoint. See the [producer handoff](collection-producer-handoff.md) for emission oracles.
|
||||
|
||||
## VM-owned random core
|
||||
|
||||
See the [random contract](../specs/runtime/02e-vm-owned-random-core.md) for Random BuiltinId 0x0016, ObjectKind tag 9, intrinsics 0x4000–0x4003, atomic state mutation, bounded 4+8*N costs and rejection-limit trap 0x00000015. Random is managed by the VM heap and existing GC, without host entropy or PBX changes.
|
||||
|
||||
|
||||
## Logical guards and atomic storage publication
|
||||
|
||||
INDEX_GUARD (0xA7), ARRAY_CHECK_LENGTH (0xA8), ARRAY_COPY (0xA9) and
|
||||
STORAGE_PUBLISH (0xAA) provide generic logical validation, complete stored-group
|
||||
transfer and prepared atomic publication. Their encoding, typed operands, exact
|
||||
faults, overlap semantics, costs and preflight/commit guarantees are defined by
|
||||
the [canonical instruction contract](../specs/runtime/02-vm-instruction-set.md#logical-guards-and-atomic-storage-publication). No new Registry category, syscall, collection algorithm or safepoint is introduced.
|
||||
|
||||
@@ -1,3 +1,3 @@
|
||||
runtime.revision=f7d7c167531bb662a1af9d73fc326bb476bf8aa7
|
||||
runtime.revision=d9b9eeb171d2861ec660d4cf5703b0795eac49a9
|
||||
INTRINSICS.csv.sha256=0c1bb78a9b81d1e3480ef5713f3d70f0b06772a7dfab2fd00c1f0a6364f98daa
|
||||
BUILTIN_CONSTANTS.csv.sha256=e407e4718127aa7ef7b1097b5b4b67d86dd979235e73a551a7c36b628cddc039
|
||||
|
||||
Reference in New Issue
Block a user