169 lines
3.4 KiB
Markdown
169 lines
3.4 KiB
Markdown
# 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.**
|