# PR-3.1 — Introduce HeapRef Handle Type in Value Model ### Briefing 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 * Add a handle-based reference type for heap objects. * Integrate it into the `Value` representation. ### Work items * 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 * [ ] `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 * Existing tests only. ### Junie instructions **You MAY:** * Add a new handle type. * Extend the `Value` enum/struct. **You MUST NOT:** * Design or implement the GC algorithm here. * Introduce object allocation logic. * Add hidden ownership or lifetime systems. **If unclear:** * 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.