Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
Remove INDEX_GUARD, ARRAY_CHECK_LENGTH, STORAGE_PUBLISH and FIELDS_PUBLISH from decoding, metadata, tooling, verification and execution. Keep ARRAY_LEN and overlap-safe ARRAY_COPY with complete-group ownership and early charging of calculable copy work, including refused attempts. Update specifications, producer handoff, qualification evidence and lessons. Share collection test support and remove redundant Copy clones for Clippy. Validation: make ci-domains passed with 1,095 workspace tests, five separately executed debugger socket tests and all 15 unchanged coverage domain gates. VM release, resource diagnostics and layer/quality suites also passed. BREAKING CHANGE: PBX using opcodes 0xA7, 0xA8, 0xAA or 0xAB is rejected, including unreachable instructions. Consumers must adapt their emission and collection algorithms or operational guarantees.
220 lines
14 KiB
Markdown
220 lines
14 KiB
Markdown
### Prometeu Bytecode — Core ISA
|
||
|
||
Status: bytecode-level normative
|
||
|
||
This document defines the stable Core ISA surface for the Prometeu Virtual Machine at the bytecode level. It specifies instruction encoding, the stack evaluation model, and the instruction set currently available in the canonical opcode surface used by encoder, decoder, disassembler, assembler, verifier, and VM execution.
|
||
|
||
Machine boundary:
|
||
|
||
- PROMETEU is not "just the VM". It is the broader fantasy console/handheld machine.
|
||
- This document covers only the bytecode ISA of the VM subsystem embedded in that machine.
|
||
|
||
Authority rule:
|
||
|
||
- This document is normative for bytecode-level encoding and opcode surface.
|
||
- 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
|
||
|
||
- Endianness: Little‑endian.
|
||
- Instruction layout: `[opcode: u16][immediate: spec.imm_bytes]`.
|
||
- Opcodes are defined in `prometeu_bytecode::isa::core::CoreOpCode`.
|
||
- Immediate sizes and stack effects are defined by `CoreOpCode::spec()` returning `CoreOpcodeSpec`.
|
||
- All jump immediates are absolute u32 byte offsets from the start of the current function.
|
||
|
||
#### Stack Machine Model
|
||
|
||
- The VM is stack‑based. Unless noted, operands are taken from the top of the operand stack and results are pushed back.
|
||
- Types at the bytecode level are represented by the `Value` enum; the VM may perform numeric promotion where appropriate (e.g., `Int32 + Float -> Float`).
|
||
- Stack underflow is a trap (TRAP_STACK_UNDERFLOW).
|
||
- Some operations may trap for other reasons (e.g., division by zero, invalid indices, type mismatches).
|
||
|
||
#### Instruction Set (Core)
|
||
|
||
- Execution control:
|
||
- `NOP` — no effect.
|
||
- `HALT` — terminates execution (block terminator).
|
||
- `JMP u32` — unconditional absolute jump (block terminator).
|
||
- `JMP_IF_FALSE u32` — pops `[bool]`, jumps if false.
|
||
- `JMP_IF_TRUE u32` — pops `[bool]`, jumps if true.
|
||
- `TRAP` — software trap/breakpoint (block terminator).
|
||
|
||
- Stack manipulation:
|
||
- `PUSH_CONST u32` — load constant by index → _pushes `[value]`.
|
||
- `PUSH_I64 i64`, `PUSH_F64 f64`, `PUSH_BOOL u8`, `PUSH_I32 i32` — push literals.
|
||
- `POP` — pops 1.
|
||
- `POP_N u32` — pops N.
|
||
- `DUP` — `[x] -> [x, x]`.
|
||
- `SWAP` — `[a, b] -> [b, a]`.
|
||
|
||
- 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]`.
|
||
- `AND`, `OR`, `NOT` — boolean logic.
|
||
- `BIT_AND`, `BIT_OR`, `BIT_XOR`, `SHL`, `SHR` — integer bit operations.
|
||
|
||
- Variables:
|
||
- `GET_GLOBAL u32`, `SET_GLOBAL u32` — access global slots.
|
||
- `GET_LOCAL u32`, `SET_LOCAL u32` — access local slots (current frame).
|
||
|
||
- 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 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.
|
||
|
||
- 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.
|
||
- `SYSCALL u32` — final numeric platform call in the executable image; raw `SYSCALL` in PBX pre-load artifacts is rejected by the loader.
|
||
- `INTRINSIC u32` — final numeric VM-owned intrinsic call.
|
||
- `FRAME_SYNC` — yield until the next frame boundary (e.g., vblank); explicit safepoint.
|
||
|
||
Host service arity is not encoded in the opcode itself. It is defined by resolved syscall metadata.
|
||
|
||
Example:
|
||
|
||
- `asset.load` currently resolves with `arg_slots = 2` and `ret_slots = 2`.
|
||
- The canonical stack contract is `asset_id, slot -> status, handle`.
|
||
- Callers do not provide an explicit asset kind; the runtime derives it from `asset_table`.
|
||
- `composer.bind_scene` resolves with `arg_slots = 1` and `ret_slots = 1`.
|
||
- The canonical stack contract is `bank_id -> status`.
|
||
- `composer.emit_sprite` resolves with `arg_slots = 9` and `ret_slots = 1`.
|
||
|
||
#### Canonical Intrinsic Registry Artifact
|
||
|
||
- Final intrinsic IDs and intrinsic stack metadata are published in [`INTRINSICS.csv`](INTRINSICS.csv).
|
||
- This CSV is the ISA-scoped artifact intended to be consumed by compiler/tooling consumers such as `../studio`.
|
||
- Each row defines one canonical intrinsic identity and its final numeric ID.
|
||
- `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:
|
||
- `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, random_rejection_v1, or argument_utf8_bytes_v1. cost_cycles is the full fixed
|
||
cost or the variable base. attempt_cost_cycles/max_attempts are zero for
|
||
fixed and String byte-cost entries; random.range publishes base 4, attempt 8, maximum 64.
|
||
hash.string publishes base 8, argument index 0 and one cycle per UTF-8 byte.
|
||
- 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.
|
||
|
||
#### Canonical Decoder Contract
|
||
|
||
- 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 opcodes produce deterministic UnknownOpcode errors; recognized retired opcodes produce structured load rejection before execution.
|
||
|
||
#### Module Boundary
|
||
|
||
- Core ISA lives under `prometeu_bytecode::isa::core` and re‑exports:
|
||
- `CoreOpCode` — the opcode enum of the core profile.
|
||
- `CoreOpcodeSpec` and `CoreOpCodeSpecExt` — spec with `imm_bytes`, stack effects, and flags.
|
||
- Consumers (encoder/decoder/disasm/verifier) should import from this module to avoid depending on internal layout.
|
||
|
||
#### Scope Notes
|
||
|
||
- "Core ISA" in the current repository means the canonical opcode surface implemented by the runtime today.
|
||
- 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 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/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` 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.
|
||
|
||
|
||
## Typed array range copy
|
||
|
||
ARRAY_COPY (0xA9, Array TypeId u32) consumes source, sourceStart, target,
|
||
targetStart, count without a result. Complete groups and owners survive overlap
|
||
and failed preparation. Charge 4+2*N*W before ordinary validation for available
|
||
Int64 count in 0..u32::MAX; other counts/underflow charge base 4. Checked cost
|
||
overflow charges base and traps SizeOverflow. The
|
||
[canonical contract](../specs/runtime/02-vm-instruction-set.md#typed-array-range-copy)
|
||
defines fault precedence, scratch and commit. ARRAY_LEN (0xA4) and physical array
|
||
checks remain. Encodings 0xA7/0xA8/0xAA/0xAB reject at load even in dead code;
|
||
no replacement publication/guard or transaction is provided.
|
||
|
||
## Identity/hash and catalog schema 2
|
||
|
||
The [identity/hash specification](../specs/runtime/02f-vm-identity-and-value-hashing.md)
|
||
defines opcodes 0x0097/0x0098, intrinsics 0x4100–0x4102, XXH64 hash-v1 and
|
||
borrowed_inline_v1. INTRINSICS.csv schema 2 retains its original eighteen columns
|
||
and appends schema_version, arg_nullable, invocation_model, scratch_model,
|
||
context_access, cost_arg_index and cost_per_byte. Descriptors remain authoritative;
|
||
unknown or inconsistent schemas/profiles/models must fail explicitly. Existing
|
||
canonical versions, signatures, effects and costs remain unchanged.
|
||
|
||
See the [identity/hash producer handoff](identity-hashing-producer-handoff.md) and
|
||
[qualification record](IDENTITY_HASHING_QUALIFICATION.md) for emitted PBX, catalog
|
||
provenance and consumer acceptance evidence.
|