255 lines
5.6 KiB
Markdown
255 lines
5.6 KiB
Markdown
# PR-2.2 — Simplify VM Execution Loop (Pure Stack Machine)
|
||
|
||
### Briefing
|
||
|
||
The VM should operate as a simple stack-based interpreter with a clear fetch–decode–execute loop, without hidden side channels or legacy behaviors.
|
||
|
||
### Target
|
||
|
||
* Normalize the VM main loop to a clean stack-machine structure.
|
||
* Remove any legacy control paths tied to HIP/RC behavior.
|
||
|
||
### Work items
|
||
|
||
* Refactor the main interpreter loop to:
|
||
|
||
* Fetch instruction at PC.
|
||
* Decode opcode.
|
||
* Execute operation on stack/frames.
|
||
* Remove any conditional logic that depends on HIP/RC state.
|
||
* Ensure PC advancement is canonical and centralized.
|
||
|
||
### Acceptance checklist
|
||
|
||
* [ ] VM loop is structurally simple and readable.
|
||
* [ ] No HIP/RC conditionals remain.
|
||
* [ ] VM compiles and runs basic programs.
|
||
* [ ] `cargo test` passes.
|
||
|
||
### Tests
|
||
|
||
* Existing tests only.
|
||
|
||
### Junie instructions
|
||
|
||
**You MAY:**
|
||
|
||
* Refactor the interpreter loop for clarity.
|
||
* Remove legacy conditionals.
|
||
|
||
**You MUST NOT:**
|
||
|
||
* Change opcode semantics.
|
||
* Introduce GC, closures, or coroutines here.
|
||
* Redesign the instruction set.
|
||
|
||
**If unclear:**
|
||
|
||
* Ask before modifying control flow assumptions.
|
||
|
||
---
|
||
|
||
# PR-2.3 — Normalize Value Model (Stack vs Heap References)
|
||
|
||
### Briefing
|
||
|
||
The VM must use a clear value model: primitives and tuples on the stack, heap objects referenced through opaque handles. This PR prepares the VM for the GC-based heap.
|
||
|
||
### Target
|
||
|
||
* Define a single `Value` representation that distinguishes:
|
||
|
||
* Immediate primitives.
|
||
* Heap references (opaque handles).
|
||
* Remove any gate-based or borrow-based value types.
|
||
|
||
### Work items
|
||
|
||
* Review the `Value` or equivalent enum/struct.
|
||
* Remove variants related to gates, borrows, or HIP.
|
||
* Ensure only the following categories remain:
|
||
|
||
* Primitives (int, bool, etc.).
|
||
* Tuples or small aggregates.
|
||
* Heap reference handle (placeholder for future GC objects).
|
||
* Update stack operations accordingly.
|
||
|
||
### Acceptance checklist
|
||
|
||
* [ ] `Value` type has no HIP/gate-related variants.
|
||
* [ ] All stack operations compile with the new value model.
|
||
* [ ] No borrow/mutate semantics remain.
|
||
* [ ] `cargo test` passes.
|
||
|
||
### Tests
|
||
|
||
* Existing tests only.
|
||
|
||
### Junie instructions
|
||
|
||
**You MAY:**
|
||
|
||
* Simplify the `Value` enum/struct.
|
||
* Remove legacy variants and adjust matches.
|
||
|
||
**You MUST NOT:**
|
||
|
||
* Design the GC handle layout.
|
||
* Introduce new object systems.
|
||
* Change instruction semantics beyond type cleanup.
|
||
|
||
**If unclear:**
|
||
|
||
* Ask what the intended value shape should be.
|
||
|
||
---
|
||
|
||
# PR-2.4 — Consolidate Trap and Error Surface
|
||
|
||
### Briefing
|
||
|
||
With HIP removed, the runtime trap surface must be simplified and aligned with the new stack+heap model.
|
||
|
||
### Target
|
||
|
||
* Define a minimal, coherent set of runtime traps.
|
||
* Remove traps that only existed for HIP/RC semantics.
|
||
|
||
### Work items
|
||
|
||
* Audit the VM’s trap/error enums.
|
||
* Remove HIP/RC-related traps.
|
||
* Keep only traps that remain meaningful, such as:
|
||
|
||
* Illegal instruction.
|
||
* Stack underflow/overflow.
|
||
* Invalid jump target.
|
||
* Out-of-bounds memory access.
|
||
* Ensure trap handling paths are consistent and deterministic.
|
||
|
||
### Acceptance checklist
|
||
|
||
* [ ] Trap enum contains only relevant traps.
|
||
* [ ] No HIP/RC trap names remain.
|
||
* [ ] VM compiles and tests pass.
|
||
|
||
### Tests
|
||
|
||
* Adjust any tests expecting removed trap codes.
|
||
|
||
### Junie instructions
|
||
|
||
**You MAY:**
|
||
|
||
* Delete unused trap variants.
|
||
* Refactor match statements accordingly.
|
||
|
||
**You MUST NOT:**
|
||
|
||
* Add new trap categories without approval.
|
||
* Change the meaning of existing non-legacy traps.
|
||
|
||
**If unclear:**
|
||
|
||
* Ask before modifying trap semantics.
|
||
|
||
---
|
||
|
||
# PR-2.5 — Prepare Call Frame Structure for Closures and Coroutines
|
||
|
||
### Briefing
|
||
|
||
Before introducing closures and coroutines, the call frame structure must be neutral and future-proof, without HIP-specific fields.
|
||
|
||
### Target
|
||
|
||
* Simplify the call frame to a minimal, generic structure.
|
||
* Remove any HIP/borrow/gate-related fields.
|
||
|
||
### Work items
|
||
|
||
* Review the call frame struct.
|
||
* Remove fields tied to scope frames, borrow state, or gates.
|
||
* Ensure the frame contains only:
|
||
|
||
* Function identifier.
|
||
* Program counter.
|
||
* Base stack pointer.
|
||
* Locals or register area (if applicable).
|
||
* Keep the structure simple and extensible.
|
||
|
||
### Acceptance checklist
|
||
|
||
* [ ] Call frame struct has no HIP-related fields.
|
||
* [ ] VM call/return paths compile and work.
|
||
* [ ] `cargo test` passes.
|
||
|
||
### Tests
|
||
|
||
* Existing call-related tests must still pass.
|
||
|
||
### Junie instructions
|
||
|
||
**You MAY:**
|
||
|
||
* Remove unused fields from the frame.
|
||
* Refactor call/return code to match the new structure.
|
||
|
||
**You MUST NOT:**
|
||
|
||
* Introduce closure or coroutine logic yet.
|
||
* Redesign the call stack architecture.
|
||
|
||
**If unclear:**
|
||
|
||
* Ask before changing frame responsibilities.
|
||
|
||
---
|
||
|
||
# PR-2.6 — Remove Dead Runtime Modules and Symbols
|
||
|
||
### Briefing
|
||
|
||
After the VM reset, there will be leftover modules, helpers, or symbols that are no longer referenced. This PR performs a final cleanup pass.
|
||
|
||
### Target
|
||
|
||
* Remove dead or unreachable runtime code.
|
||
* Ensure the VM crate has a minimal, clean surface.
|
||
|
||
### Work items
|
||
|
||
* Use compiler warnings and search tools to find:
|
||
|
||
* Unused modules.
|
||
* Unused structs/enums/functions.
|
||
* Legacy HIP/RC terminology.
|
||
* Remove dead code.
|
||
* Update module trees and public exports.
|
||
|
||
### Acceptance checklist
|
||
|
||
* [ ] No dead modules remain.
|
||
* [ ] No HIP/RC terminology found in the VM crate.
|
||
* [ ] `cargo test` passes.
|
||
|
||
### Tests
|
||
|
||
* Existing tests only.
|
||
|
||
### Junie instructions
|
||
|
||
**You MAY:**
|
||
|
||
* Remove unused code and modules.
|
||
* Update `mod.rs` and exports.
|
||
|
||
**You MUST NOT:**
|
||
|
||
* Remove code that is still referenced.
|
||
* Replace deleted modules with new experimental ones.
|
||
|
||
**If unclear:**
|
||
|
||
* Ask before deleting anything that looks structurally important.
|