prometeu-runtime/docs/specs/pbs/files/PRs para Junie.md

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