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:
2026-10-23 00:46:39 +01:00
parent 76a8b074e8
commit c410e35001
46 changed files with 2683 additions and 165 deletions
@@ -1,7 +1,7 @@
# Typed common Registry and PBX v0
Status: normative. Owner: `compiler/general`. Runtime contract reference:
`runtime` revision `f7d7c167531bb662a1af9d73fc326bb476bf8aa7`,
`runtime` revision `d9b9eeb171d2861ec660d4cf5703b0795eac49a9`,
`docs/specs/runtime/02c-program-registry-and-pbx-v0.md` and
`docs/vm-arch/ISA_CORE.md` in that repository.
@@ -186,3 +186,61 @@ Synthetic common IR additionally exercises linking, lowering, optimization and
emission without PBS. Frontend migration and integrated release readiness are
tracked separately in AGD75; passing common conformance does not claim complete
PBS lowering or complete Studio/runtime integration.
## Generic logical guards and atomic storage publication
The core includes the following generic operations, with u16 opcodes and
little-endian u32 immediates. They introduce no new Registry category, syscall,
source-language collection or ambient transaction. Operand order below is bottom
to top; all integer operands are Int64.
| Opcode | Immediate | Stack operands consumed |
| --- | --- | --- |
| INDEX_GUARD `0xA7` | none | index, exclusive limit |
| ARRAY_CHECK_LENGTH `0xA8` | Array TypeId | length |
| ARRAY_COPY `0xA9` | Array TypeId | source, sourceStart, target, targetStart, count |
| STORAGE_PUBLISH `0xAA` | Array TypeId, Struct TypeId, first field, second field | source, sourceStart, target, targetStart, count, fillStart, fillCount, element group, owner, first field group, second field group |
All operations return no values. INDEX_GUARD accepts exactly
`0 <= index < limit`, otherwise TRAP_OOB. It does not use physical storage length.
ARRAY_CHECK_LENGTH accepts zero through u32::MAX without allocating. Negative
lengths produce TRAP_OOB; values above u32::MAX produce the same resource
SizeOverflow failure as ARRAY_NEW. This check does not reserve future allocation.
ARRAY_COPY and STORAGE_PUBLISH require exact Array receiver identities and complete
stored groups. Every range must have nonnegative start/count and fit its physical
array; an empty range may start at length. Invalid ranges produce TRAP_OOB, never
clamping or truncation. Copy reads the pre-attempt source sequence, including for
overlapping source/target ranges. Presence tags, immutable boxes, native owners and
object identities are preserved without payload unpacking or repacking.
STORAGE_PUBLISH first copies the selected source range, then fills the selected
target range with the supplied element group, then writes the two selected fields
on the supplied Struct owner. Fields must be distinct valid indices on that Struct;
their types and widths come from the immutable Registry. Source code/producer owns
selection of every range, value, owner and field. The VM implements these generic
ordered effects and does not select collection algorithms.
Loading validates all immediate identities/categories/fields even in unreachable
code. Verification requires complete typed operands. ARRAY_COPY consumes five
slots; STORAGE_PUBLISH consumes `8 + elementWidth + firstWidth + secondWidth`.
INDEX_GUARD consumes two slots and ARRAY_CHECK_LENGTH consumes one.
Execution validates all receivers, lengths/ranges, supplied groups and source
groups, and reserves the complete charged copy scratch before writing. Validation,
quota or host allocation refusal leaves all input operands and destinations
unchanged, including both fields and native owners. Scratch uses TemporaryBytes,
is refunded on success/refusal and does not relax any resource ceiling. Existing
operands remain roots during preparation. There is no GC, callback, scheduler or
other interleaving inside this single instruction. Commit uses already validated
complete groups, performs no fallible allocation and consumes operands only after
all selected effects have been published. No prepared token escapes the attempt.
Base cycle costs are 2 for either guard, 4 for ARRAY_COPY and 6 for STORAGE_PUBLISH.
Copy adds `2 * count * elementWidth`; publication additionally adds
`fillCount * elementWidth + firstWidth + secondWidth`. Work arithmetic is checked
before mutation. A refused preparation still charges the attempted work. Neither
operation is a safepoint. Consumers must prepare any potentially failing return
carrier and all call operands before publication; a series of ordinary stores is
not a substitute for whole-operation safety.
@@ -0,0 +1,175 @@
# SDK List and snapshot Cursor
Owner: `compiler/pbs`. List and Cursor algorithms belong to the executable PBS
SDK. Logical guards, complete stored-group transfers and atomic publication are
language-neutral compiler/runtime mechanisms. This contract builds on
[arrays and optional](typed-arrays-and-optional-execution.md),
[generic structs](generic-structs-and-free-functions.md) and
[generic contracts](generic-contracts.md).
## Type, identity and construction
The SDK exports the ordinary generic struct `list<T>` and contract `Cursor<T>`
from its collections module. Applications are invariant. A directly optional
element, including through grouping, is invalid; `optional (list<T>)` is valid.
Nested valid arrays, structs, contracts, functions and value groups keep their
normal types and identities. An unrelated user declaration named list does not
acquire SDK behavior.
`new list<T>()` creates size zero and capacity 16. `new list<T>(capacity)` creates
size zero with exactly that capacity, including zero. Contextual `new list()`
and `new list(capacity)` require an expected concrete List type. Constructor
values do not infer T. Only the backing array is allocated; elements are absent.
List has stable reference identity. Assignment and parameter passing share that
identity; aliases observe mutations even when growth replaces its private backing
array. Storage, internal nodes and private compiler bindings are inaccessible to
clients. No public Dynamic or universal element type is introduced.
## Logical positions and operations
Every observable List satisfies `0 <= size <= capacity`. Size includes holes.
Capacity is physical storage and never makes additional indices accessible.
Zero and false are present values, distinct from holes.
| Operation | Result | Behavior |
| --- | --- | --- |
| `size()` | long | Logical positions, including holes |
| `capacity()` | long | Physical backing length |
| `xs[i]` | optional T | Present value or hole at `0 <= i < size` |
| `xs[i] = value` | unit | Replace one valid position without extending size |
| `add(value)` | unit | Append at size; do not fill earlier holes |
| `insert(i, value)` | unit | Insert at `0 <= i <= size`; shift slots and holes right |
| `clearAt(i)` | unit | Clear a valid position without shifting or changing size |
| `removeAt(i)` | optional T | Return old content, shift left, clear old tail, decrement size |
| `clear()` | unit | Clear all contents and size, preserve capacity |
| `resize(n)` | unit | Grow with holes or clear discarded suffix; set logical size |
| `reserve(n)` | unit | Grow exactly to n only when n exceeds capacity |
| `trim()` | unit | Set capacity exactly to size, including zero |
| `cursor()` | Cursor<T> | Complete immediate snapshot of present occurrences |
Removing a hole still removes its position and decrements size. Shrink, removal
and clear discard all hidden suffix references: regrowing must not resurrect old
values. Physical shrinking occurs only through trim. `resize(0)` preserves capacity.
Receiver and arguments are evaluated once in source order. Indices, lengths and
capacities accept int and long with localized lossless promotion; this does not
add general numeric conversion. No long value may be truncated.
Invalid logical indices raise TRAP_OOB, including indices inside physical capacity.
Negative lengths, structural overflow and quota refusals preserve the applicable
Array/provider fault classification. Failures are never translated into none.
## Capacity policy
When required size r exceeds capacity c, automatic growth is:
```text
candidate = max(r, c + max(1, ceil(c / 2)))
new capacity = min(Array structural maximum, candidate)
```
Calculate without overflow. Clamp only if r itself fits the structural maximum;
otherwise raise the applicable provider failure. Explicit reserve uses exactly n,
never shrinks and preserves size. Trim uses exactly size. Old and candidate arrays
may coexist; neither discarded references nor replaced storage promise immediate
GC or immediate quota recovery.
## Complete mutation attempts
Private storage transfer preserves whole existing groups, presence tags and
reference identities. Shifting must not unpack each public Array optional and
repack/rebox every payload. Prepare potentially failing validation, packing,
allocations, return carriers, scratch and publication operands before modifying
observable storage. Then publish the complete selected slot/range and field
changes without a fallible allocation, callback, scheduler or GC boundary.
Any refused attempt leaves size, backing reference, capacity, slots and roots
unchanged. This includes insert/remove without growth and preparation of
removeAt's optional result. Individually atomic Array instructions do not by
themselves establish this guarantee. Previously evaluated argument effects are
not rolled back. Unpublished candidates obey normal ownership and budgets.
## Cursor protocol
```pbs
declare contract Cursor<T> {
fn hasNext() -> bool;
fn next();
fn current() -> optional T;
}
```
The shared SDK implementation captures one private immutable singly linked,
non-circular node per present occurrence. It uses no snapshot array and retains
no source-slot or editable source-node association. List capture scans logical
positions and preserves increasing index order, duplicates and complete values.
Capture finishes before returning; failure exposes no partial Cursor.
A nonempty Cursor starts on its first node. `hasNext()` tests for a successor.
`next()` advances only when a successor exists; otherwise it does nothing.
`current()` reports the current node without advancing. Only a snapshot born
empty reports none. Repeated calls never advance beyond the last node.
| Snapshot and position | hasNext() | current() |
| --- | --- | --- |
| Empty, initially or after any next | false | none |
| [A], initially or after any next | false | some(A) |
| [A, B], initially | true | some(A) |
| [A, B], after one or any further next | false | some(B) |
Consume the current value before deciding whether to advance:
```pbs
while true {
if let value = cursor.current() {
// Consume value.
} else {
break;
}
if cursor.hasNext() {
cursor.next();
} else {
break;
}
}
```
A hasNext-only loop skips the last element. Waiting for current to become none
does not terminate a nonempty snapshot. There is no index, reset, removal, clone
or new for-in protocol. Another complete traversal creates another snapshot.
Captured object references preserve identity and observe subsequent field mutation.
Later List insertions, replacements, removals, clear, resize and backing changes
do not alter the captured sequence. Snapshot links and captured values are not
rewritten. The Cursor retains only its current node and suffix, allowing consumed
prefixes to become unreachable. It keeps the final node/value while reachable.
Other owners remain independent; reclamation happens through normal GC.
The outer optional describes node existence. A future producer with optional T
must distinguish `some(none)` from an empty Cursor. Type/resource faults remain
faults. List itself rejects directly optional elements.
## Reuse, costs and conformance
The shared implementation is independent of List representation. Future Linked<T>
and Set<T> producers use Cursor<T>; Map<K,V> uses Cursor<keyval<K,V>>. Set/Map gain
no ordering guarantee between captures. A captured keyval association is read-only
and does not follow later association replacement; referenced objects stay shared.
Those collections and keyval are separate deliveries.
For n logical List positions and k present occurrences, capture takes O(n) work
and O(k) additional nodes; next follows one link in O(1). Each node costs allocation,
ownership and eventual GC work. Do not promise lower memory than arrays, zero
allocation or allocation-free optional results. All complete groups remain rooted
through allocations and calls; provider quotas remain unchanged.
Conformance must execute real PBS through common IR and PBX in the production VM.
It covers every operation, constructor/type rule, logical bounds, exact growth,
holes and full groups, aliases, the entire Cursor table, snapshot independence,
shared object mutation, non-List producers, full-operation refusals with and without
growth, prefix reclamation, last-node retention, editor projections and installed
SDK/spec/example distribution. Generic publication also requires non-PBS tests.
Value search/removal, sorting, bulk APIs, new equality, public nodes, deep freezing,
general effect/transaction syntax and Linked/Set/Map implementations are out of scope.
@@ -81,7 +81,10 @@ Conformance must compile real PBS through typed IR and production PBX into the p
- [Dynamic semantics](../../../specs/compiler-languages/pbs/9.%20Dynamic%20Semantics%20Specification.md)
- [Existing type runtime alignment](input-and-existing-type-runtime-alignment.md)
List/Set/Map, growth, iteration, equality and hashing policies belong to the separate SDK collections discussion. A future list capacity does not create logical elements; fixed array length does.
[SDK List and Cursor](sdk-list-and-cursor.md) define logical size, growth and
snapshot traversal above private fixed-length arrays. List capacity does not
create logical elements; fixed array length does. Set/Map, equality and hashing
policies remain separate concerns.
See [Runtime Random integration](runtime-random-integration.md) for opaque generator aliases in typed storage and captures.
+66 -47
View File
@@ -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
View File
@@ -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 -1
View File
@@ -1,3 +1,3 @@
runtime.revision=f7d7c167531bb662a1af9d73fc326bb476bf8aa7
runtime.revision=d9b9eeb171d2861ec660d4cf5703b0795eac49a9
INTRINSICS.csv.sha256=0c1bb78a9b81d1e3480ef5713f3d70f0b06772a7dfab2fd00c1f0a6364f98daa
BUILTIN_CONSTANTS.csv.sha256=e407e4718127aa7ef7b1097b5b4b67d86dd979235e73a551a7c36b628cddc039