This commit is contained in:
Nilton Constantino
2026-01-30 15:15:38 +00:00
parent 25482e865f
commit a534b226fb
9 changed files with 392 additions and 93 deletions
+6 -27
View File
@@ -1,27 +1,6 @@
## Global Rules (Binding)
1. **No semantic leakage**
* `ir_vm` must not encode PBS semantics (no `when`, `optional`, `result`, etc.).
* `ir_core` must not encode VM execution details (no stack slots, no offsets-as-pointers).
2. **Feature freeze discipline**
* `ir_vm` is treated as a *stable ISA*.
* Any change to `ir_vm` requires an explicit PR and review.
3. **No placeholders**
* No `LoadRef(0)`, no `Nop` as semantic stand-ins.
* If something cannot be represented, the PR must stop and report it.
4. **No creativity**
* Implement exactly what is specified.
* Do not add sugar, shortcuts, or inferred behavior.
5. **Tests are mandatory**
* Every PR must include tests validating the new surface.
---
> **Hard constraints:**
>
> * `ir_core` and `ir_vm` remain **fully decoupled**.
> * The only contact point is lowering (`core_to_vm`).
> * **No placeholders**, no guessed offsets, no runtime inference of language semantics.
> * Every PR must include tests.
+130
View File
@@ -0,0 +1,130 @@
## 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