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

PR-02 — Define ir_vm ISA v0 (Memory & Gates Only)

Goal

Define a minimal, PBS-compatible but PBS-agnostic VM instruction set.

Required Instructions

Constant Pool

• PushConst(ConstId)

HIP Allocation (Deterministic)

• Alloc { type_id: TypeId, slots: u32 }

Gate-Based Heap Access

• GateLoad { offset: u32 }
• GateStore { offset: u32 }

All heap access must follow: gate validation → base+slots resolution → bounds check → read/write.

Scope Markers (Semantic Preservation)

• GateBeginPeek / GateEndPeek
• GateBeginBorrow / GateEndBorrow
• GateBeginMutate / GateEndMutate

These may be runtime no-ops in v0 but must exist to preserve semantics and debug invariants.

Safe Point Hook

• FrameSync (optional but recommended)

Non-goals

• No RC implementation
• No VM execution logic

Tests

• Unit tests ensuring the instruction enum is stable and cloneable
• Snapshot or debug-format test to lock the ISA surface

---

PR-03 — Remove “Ref” Leakage from ir_vm

Goal

Eliminate pointer-based mental models from the VM IR.

Required Changes

• Rename any existing LoadRef / StoreRef to:

  • LocalLoad { slot: u32 }
  • LocalStore { slot: u32 }

• Remove or rename any type named Ref that refers to HIP

Hard rule: the word Ref must never refer to HIP memory in ir_vm.

Tests

• Grep-style or unit test ensuring no Ref-named HIP ops exist in ir_vm

---

PR-04 — Update core_to_vm Lowering (Kill Placeholders)

Goal

Make lowering the only integration point between Core IR and VM IR.

Required Mapping

• ir_core::Alloc { ty, slots } → ir_vm::Alloc { type_id, slots }

• BeginPeek / Borrow / Mutate → GateBegin*

• EndPeek / Borrow / Mutate → GateEnd*

Forbidden:

• LoadRef(0)
• Nop as semantic replacement

Tests

• Given a Core IR program with alloc + begin/end, VM IR must contain:

  • shape-explicit Alloc
  • correctly paired gate begin/end
  • zero placeholders

---

PR-05 — Gate-Aware Access Path (Choose One, Explicitly)

Goal

Close the loop between Core IR access semantics and VM IR access execution.

Choose One Approach (Explicit in PR Description)

Approach A (Preferred)

• Core IR expresses semantic access:

  • CoreGateLoadField(field_id)
  • CoreGateStoreField(field_id)

• Lowering resolves field_id → offset

• VM IR emits GateLoad/GateStore

Approach B (Minimal)

• Core IR already carries offset
• Lowering maps directly to GateLoad/GateStore

Hard rule: no direct heap access, no fake offsets.

Tests

• Lowering emits correct offsets
• Offset is visible in VM IR (not implicit)

---

PR-06 — RC Hooks Documentation (No RC Yet)

Goal

Prepare the VM for RC without implementing it yet.

Required Changes

• Document which VM instructions are RC-sensitive:

  • LocalStore
  • GateStore
  • stack pop / drop (if present)
  • frame end / FrameSync as safe points

• Document RC rules:

  • retain on handle copy
  • release on overwrite/drop

Tests

• Documentation test or unit assertion that the RC-sensitive list exists

---

STOP POINT

After PR-06:

• ir_core and ir_vm are fully decoupled
• Lowering is deterministic and placeholder-free
• VM ISA v0 is defined and stable
• VM runtime work may begin safely

Any VM changes before this point must be rejected.