prometeu-runtime/files/TODOs.md

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.