From dc7da102c831db476bd22e5ee9a9b4f50b6bfaad Mon Sep 17 00:00:00 2001
From: bQUARKz <bquarkz@gmail.com>
Date: Wed, 18 Feb 2026 16:09:18 +0000
Subject: [PATCH] pr2.6

---
 .../prometeu-vm/src/virtual_machine.rs        |  23 --
 files/TODOs.md                                | 382 +++++++++++++++++-
 2 files changed, 364 insertions(+), 41 deletions(-)

diff --git a/crates/console/prometeu-vm/src/virtual_machine.rs b/crates/console/prometeu-vm/src/virtual_machine.rs
index f36e2c01..4dcb6706 100644
--- a/crates/console/prometeu-vm/src/virtual_machine.rs
+++ b/crates/console/prometeu-vm/src/virtual_machine.rs
@@ -92,7 +92,6 @@ pub struct VirtualMachine {
     pub breakpoints: std::collections::HashSet<usize>,
 }
 
-// HIP/Handle runtime structures removed per PR-2.1
 
 impl Default for VirtualMachine {
     fn default() -> Self {
@@ -305,14 +304,6 @@ impl VirtualMachine {
         })
     }
 
-    /// Peeks at the next 16-bit value in the ROM without advancing the PC.
-    fn peek_u16(&self) -> Result<u16, String> {
-        if self.pc + 2 > self.program.rom.len() {
-            return Err("Unexpected end of ROM".into());
-        }
-        let bytes = [self.program.rom[self.pc], self.program.rom[self.pc + 1]];
-        Ok(u16::from_le_bytes(bytes))
-    }
 
     /// Executes a single instruction at the current Program Counter (PC).
     ///
@@ -1605,20 +1596,6 @@ mod tests {
         assert!(vm.pop().is_err()); // Stack should be empty
     }
 
-    #[test]
-    fn test_hip_traps_oob_removed_legacy() {
-        // Legacy HIP opcodes removed; test deleted.
-        assert!(true);
-    }
-
-    #[test]
-    fn test_hip_traps_type_removed_legacy() { assert!(true); }
-
-    #[test]
-    fn test_gate_ids_distinct_and_round_trip_removed_legacy() { assert!(true); }
-
-    #[test]
-    fn test_invalid_gate_traps_removed_legacy() { assert!(true); }
 
     #[test]
     fn test_entry_point_ret_with_prepare_call() {
diff --git a/files/TODOs.md b/files/TODOs.md
index 3ba101cf..8abe8d15 100644
--- a/files/TODOs.md
+++ b/files/TODOs.md
@@ -1,28 +1,26 @@
-# PR-2.6 — Remove Dead Runtime Modules and Symbols
+# PR-3.1 — Introduce HeapRef Handle Type in Value Model
 
 ### 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.
+The VM must reference heap objects through opaque handles. This PR introduces a `HeapRef` (or equivalent) type and integrates it into the VM value model without implementing the GC yet.
 
 ### Target
 
-* Remove dead or unreachable runtime code.
-* Ensure the VM crate has a minimal, clean surface.
+* Add a handle-based reference type for heap objects.
+* Integrate it into the `Value` representation.
 
 ### 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.
+* Define a `HeapRef` struct or newtype (e.g., index-based handle).
+* Add a `Value::HeapRef` (or equivalent) variant.
+* Ensure stack operations can carry this value type.
+* Do not allocate real objects yet; this is only the type integration.
 
 ### Acceptance checklist
 
-* [ ] No dead modules remain.
-* [ ] No HIP/RC terminology found in the VM crate.
+* [ ] `HeapRef` type exists and is used in `Value`.
+* [ ] VM compiles with the new value variant.
+* [ ] No GC or allocator logic is introduced yet.
 * [ ] `cargo test` passes.
 
 ### Tests
@@ -33,14 +31,362 @@ After the VM reset, there will be leftover modules, helpers, or symbols that are
 
 **You MAY:**
 
-* Remove unused code and modules.
-* Update `mod.rs` and exports.
+* Add a new handle type.
+* Extend the `Value` enum/struct.
 
 **You MUST NOT:**
 
-* Remove code that is still referenced.
-* Replace deleted modules with new experimental ones.
+* Design or implement the GC algorithm here.
+* Introduce object allocation logic.
+* Add hidden ownership or lifetime systems.
 
 **If unclear:**
 
-* Ask before deleting anything that looks structurally important.
+* Ask what fields the handle should contain.
+
+---
+
+# PR-3.2 — Define Heap Object Header and Object Kind Tags
+
+### Briefing
+
+All heap objects must share a common header so the GC can traverse them. This PR introduces the canonical object header and object kind tagging.
+
+### Target
+
+* Define a unified object header.
+* Introduce object kind tags for future types (array, string, closure, etc.).
+
+### Work items
+
+* Define `ObjectHeader` containing:
+
+  * Mark bit or flag.
+  * Object kind/tag.
+  * Size or length field if required.
+* Define an `ObjectKind` enum.
+* Ensure header layout is clearly documented in comments.
+* Do not implement traversal or GC logic yet.
+
+### Acceptance checklist
+
+* [ ] `ObjectHeader` and `ObjectKind` are defined.
+* [ ] Code compiles without GC logic.
+* [ ] Comments explain header semantics in English.
+* [ ] `cargo test` passes.
+
+### Tests
+
+* None required.
+
+### Junie instructions
+
+**You MAY:**
+
+* Introduce header structs and enums.
+* Add comments explaining layout.
+
+**You MUST NOT:**
+
+* Implement object traversal logic.
+* Add allocation strategies or pools.
+
+**If unclear:**
+
+* Ask before choosing header fields.
+
+---
+
+# PR-3.3 — Implement Basic Heap Allocator (No GC Yet)
+
+### Briefing
+
+We need a simple heap allocator that can store objects and return handles. This PR introduces a minimal allocator without garbage collection.
+
+### Target
+
+* Create a heap structure that stores objects.
+* Return `HeapRef` handles for allocated objects.
+
+### Work items
+
+* Implement a `Heap` struct.
+* Store objects in a vector or arena-like container.
+* Provide methods such as:
+
+  * `allocate_object(kind, payload)`.
+  * Return a `HeapRef` handle.
+* Integrate heap into VM state.
+
+### Acceptance checklist
+
+* [ ] Heap exists and can allocate objects.
+* [ ] VM can hold a heap instance.
+* [ ] Allocation returns valid `HeapRef`.
+* [ ] `cargo test` passes.
+
+### Tests
+
+* Add a unit test allocating a few objects and verifying handles are valid.
+
+### Junie instructions
+
+**You MAY:**
+
+* Use a simple vector-backed heap.
+* Implement minimal allocation logic.
+
+**You MUST NOT:**
+
+* Implement garbage collection here.
+* Add compaction or generational strategies.
+
+**If unclear:**
+
+* Ask before choosing allocation layout.
+
+---
+
+# PR-3.4 — Define GC Root Set (Stack, Frames, Globals)
+
+### Briefing
+
+The GC must know where roots are located. This PR defines the root set abstraction without running a full GC yet.
+
+### Target
+
+* Identify and enumerate all GC roots.
+* Provide a mechanism to iterate them.
+
+### Work items
+
+* Define a root traversal interface or helper.
+* Enumerate roots from:
+
+  * Value stack.
+  * Call frames.
+  * Globals or constant pools if applicable.
+* Provide a function like `visit_roots(visitor)`.
+
+### Acceptance checklist
+
+* [ ] Root set traversal exists.
+* [ ] Stack and frames are included as roots.
+* [ ] Code compiles.
+* [ ] `cargo test` passes.
+
+### Tests
+
+* Add a test that inserts a `HeapRef` in the stack and confirms it is visited by root traversal.
+
+### Junie instructions
+
+**You MAY:**
+
+* Add root iteration helpers.
+* Traverse stack and frames.
+
+**You MUST NOT:**
+
+* Implement marking logic yet.
+* Change frame or stack architecture.
+
+**If unclear:**
+
+* Ask which structures must be roots.
+
+---
+
+# PR-3.5 — Implement Mark Phase (Reachability Traversal)
+
+### Briefing
+
+This PR introduces the mark phase of a simple mark-sweep collector. It must traverse from roots and mark reachable objects.
+
+### Target
+
+* Implement reachability marking from root set.
+* Set mark bits on visited objects.
+
+### Work items
+
+* Implement a `mark()` function in the heap.
+* Traverse roots using the root iterator.
+* For each `HeapRef`, mark the object.
+* Recursively traverse references inside objects.
+* Ensure no infinite loops on cycles.
+
+### Acceptance checklist
+
+* [ ] Mark phase visits all reachable objects.
+* [ ] Cycles are handled safely.
+* [ ] Unreachable objects remain unmarked.
+* [ ] `cargo test` passes.
+
+### Tests
+
+* Add tests:
+
+  * Reachable object stays marked.
+  * Unreachable object remains unmarked.
+  * Cyclic references do not crash.
+
+### Junie instructions
+
+**You MAY:**
+
+* Implement a simple DFS or stack-based marking.
+
+**You MUST NOT:**
+
+* Add generational, incremental, or parallel GC.
+* Change object layout.
+
+**If unclear:**
+
+* Ask before deciding traversal structure.
+
+---
+
+# PR-3.6 — Implement Sweep Phase (Reclaim Unmarked Objects)
+
+### Briefing
+
+After marking, the GC must reclaim unreachable objects. This PR implements the sweep phase.
+
+### Target
+
+* Remove or reclaim unmarked objects.
+* Reset mark bits for the next cycle.
+
+### Work items
+
+* Iterate over heap storage.
+* For each object:
+
+  * If unmarked, reclaim it.
+  * If marked, clear the mark bit.
+* Ensure handles to reclaimed objects become invalid or reused safely.
+
+### Acceptance checklist
+
+* [ ] Unreachable objects are reclaimed.
+* [ ] Reachable objects remain intact.
+* [ ] Mark bits are cleared after sweep.
+* [ ] `cargo test` passes.
+
+### Tests
+
+* Add tests:
+
+  * Allocate objects, drop references, run sweep, confirm removal.
+  * Confirm live objects survive.
+
+### Junie instructions
+
+**You MAY:**
+
+* Implement a simple sweep over the heap vector.
+
+**You MUST NOT:**
+
+* Implement compaction or handle relocation.
+* Introduce advanced memory strategies.
+
+**If unclear:**
+
+* Ask before choosing handle invalidation strategy.
+
+---
+
+# PR-3.7 — Integrate GC Cycle at Safepoint (`FRAME_SYNC`)
+
+### Briefing
+
+The GC must only run at safepoints. This PR connects the mark-sweep collector to the VM’s safepoint logic, primarily at `FRAME_SYNC`.
+
+### Target
+
+* Trigger GC cycles only at safepoints.
+* Keep execution deterministic.
+
+### Work items
+
+* Identify safepoint handling code in the VM.
+* Add logic:
+
+  * If allocation threshold exceeded, run GC at `FRAME_SYNC`.
+* Ensure GC does not run in arbitrary instruction contexts.
+
+### Acceptance checklist
+
+* [ ] GC runs only at safepoints.
+* [ ] No GC during arbitrary instruction execution.
+* [ ] VM remains deterministic.
+* [ ] `cargo test` passes.
+
+### Tests
+
+* Add a test where allocations trigger GC only at `FRAME_SYNC`.
+
+### Junie instructions
+
+**You MAY:**
+
+* Hook GC invocation into safepoint handling.
+
+**You MUST NOT:**
+
+* Trigger GC at random points.
+* Add background or concurrent GC.
+
+**If unclear:**
+
+* Ask before modifying safepoint semantics.
+
+---
+
+# PR-3.8 — GC Smoke and Stress Tests
+
+### Briefing
+
+We need confidence that the GC behaves correctly under simple and stressed conditions.
+
+### Target
+
+* Add deterministic smoke and stress tests for the GC.
+
+### Work items
+
+* Add tests:
+
+  * Simple allocation and collection cycle.
+  * Many short-lived objects.
+  * Cyclic references.
+* Ensure tests are deterministic.
+
+### Acceptance checklist
+
+* [ ] Smoke tests pass.
+* [ ] Stress tests pass.
+* [ ] No nondeterministic failures.
+* [ ] `cargo test` passes.
+
+### Tests
+
+* New GC-specific tests.
+
+### Junie instructions
+
+**You MAY:**
+
+* Add deterministic tests.
+
+**You MUST NOT:**
+
+* Introduce random or timing-dependent tests.
+* Modify GC semantics to satisfy tests.
+
+**If unclear:**
+
+* Ask before changing test scenarios.