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
+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.