# 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.**