131 lines
2.9 KiB
Markdown
131 lines
2.9 KiB
Markdown
## PR-09 — HIP ISA Freeze v0: Opcode Table + Encoding Contract (Bytecode)
|
|
|
|
### Goal
|
|
|
|
Freeze the HIP-related opcode set and encoding so bytecode becomes stable.
|
|
|
|
### Required Changes
|
|
|
|
1. Update `prometeu-bytecode`:
|
|
|
|
* Define the canonical HIP opcode subset:
|
|
|
|
* `PUSH_CONST`
|
|
* `ALLOC(type_id, slots)`
|
|
* `GATE_BEGIN_PEEK`, `GATE_END_PEEK`
|
|
* `GATE_BEGIN_BORROW`, `GATE_END_BORROW`
|
|
* `GATE_BEGIN_MUTATE`, `GATE_END_MUTATE`
|
|
* `GATE_LOAD(offset)`
|
|
* `GATE_STORE(offset)`
|
|
* `GATE_RETAIN`, `GATE_RELEASE`
|
|
* `FRAME_SYNC` (if included)
|
|
|
|
2. Define canonical encodings (normative in comments/doc):
|
|
|
|
* `GateId` encoding: `u32` little-endian
|
|
* `TypeId` encoding: `u32` little-endian
|
|
* `ConstId` encoding: `u32` little-endian
|
|
* `slots`: `u32` little-endian
|
|
* `offset`: `u32` little-endian
|
|
|
|
3. Update bytecode emitter so it emits these exact opcodes with these exact payloads.
|
|
|
|
### Non-goals
|
|
|
|
* No runtime execution changes
|
|
|
|
### Tests (Mandatory)
|
|
|
|
1. **Golden bytecode tests**:
|
|
|
|
* Given a minimal VM IR program using each HIP opcode, assert the exact emitted bytes.
|
|
|
|
2. **Opcode stability test**:
|
|
|
|
* Snapshot test of the opcode enum ordering and numeric values.
|
|
|
|
> If opcode numeric values already exist, DO NOT renumber. If new opcodes are added, append them.
|
|
|
|
---
|
|
|
|
## PR-10 — HIP ABI Freeze v0: Trap Conditions + Debug Surface
|
|
|
|
### Goal
|
|
|
|
Freeze the runtime-visible ABI behavior for HIP operations.
|
|
|
|
### Required Content (Normative)
|
|
|
|
Add a document (or module-level docs) defining traps:
|
|
|
|
* Invalid `GateId` → trap `TRAP_INVALID_GATE`
|
|
* Dead gate access → trap `TRAP_DEAD_GATE`
|
|
* Out-of-bounds offset (`offset >= slots`) → trap `TRAP_OOB`
|
|
* Type mismatch (if enforced) → trap `TRAP_TYPE`
|
|
|
|
Define what a trap includes:
|
|
|
|
* opcode
|
|
* message
|
|
* optional span (if debug info is present)
|
|
|
|
### Required Changes
|
|
|
|
* Add trap codes/constants in bytecode/VM interface.
|
|
* Ensure bytecode format reserves space / structure for propagating trap info.
|
|
|
|
### Tests (Mandatory)
|
|
|
|
* Unit tests verifying trap codes are stable (numeric values frozen).
|
|
* Doc tests or snapshot for ABI text.
|
|
|
|
---
|
|
|
|
## PR-11 — Cross-Layer Conformance Tests: Core→VM→Bytecode (HIP)
|
|
|
|
### Goal
|
|
|
|
Prove end-to-end determinism and stability.
|
|
|
|
### Required Tests
|
|
|
|
1. PBS snippet (or Core IR fixture) that:
|
|
|
|
* allocates a storage struct
|
|
* mutates a field
|
|
* peeks value
|
|
|
|
Assert:
|
|
|
|
* VM IR contains:
|
|
|
|
* `Alloc(type_id, slots)`
|
|
* `GateBeginMutate/EndMutate`
|
|
* `GateStore(offset)`
|
|
* `GateBeginPeek/EndPeek`
|
|
* `GateLoad(offset)`
|
|
* RC ops (retain/release)
|
|
|
|
2. Bytecode golden output for the same program:
|
|
|
|
* assert the exact bytes match the frozen ISA/ABI.
|
|
|
|
### Non-goals
|
|
|
|
* No runtime execution
|
|
|
|
---
|
|
|
|
## STOP POINT (Hard Gate)
|
|
|
|
* HIP access is fully deterministic
|
|
* RC events are explicit and testable
|
|
* HIP ISA/ABI v0 is frozen with golden bytecode tests
|
|
|
|
Only after this point may we implement/tune:
|
|
|
|
* Gate Pool
|
|
* Heap allocation
|
|
* RC counters + safe point reclaim
|
|
* Traps at runtime
|