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:
+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.
|
||||
|
||||
Reference in New Issue
Block a user