prometeu-runtime/files/TODOs.md

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.