prometeu-runtime/files/TODOs.md

PR-6.5 — Verifier Support for Closures (Model B)

Briefing

The verifier must understand closure values and enforce safe invocation rules.

Under Model B:

• CALL_CLOSURE injects hidden arg0.
• User-visible arg_count excludes hidden arg.
• Captures are accessed via explicit instructions (future PR).

---

Target

Extend verifier to:

1. Introduce stack type: ClosureValue.
2. Validate MAKE_CLOSURE effects.
3. Validate CALL_CLOSURE semantics:

• Ensure top of stack is ClosureValue.
• Ensure sufficient args present.
• Validate arg_count matches function signature expectations.
• Account for hidden arg0 when checking callee arg arity.

4. Validate ret_slots against function metadata.

---

Work Items

1. Extend type lattice with ClosureValue.
2. Define stack transitions for MAKE_CLOSURE.
3. Define stack transitions for CALL_CLOSURE.
4. Enforce strict failure on mismatch.

---

Acceptance Checklist

• ClosureValue type exists.
• Invalid CALL_CLOSURE rejected.
• Hidden arg0 accounted for.
• ret_slots validated.
• All verifier tests pass.

---

Tests

1. Valid closure call passes verification.
2. CALL_CLOSURE with wrong arg_count fails.
3. CALL_CLOSURE on non-closure fails verification.
4. Nested closure calls verify correctly.

---

Junie Instructions

You MAY:

• Extend verifier model.
• Add tests.

You MUST NOT:

• Weaken verification rules.
• Replace verifier checks with runtime-only traps.

If function metadata (arg_slots/ret_slots) is insufficient, STOP and request clarification.

---

Definition of Done

Verifier fully supports closure creation and invocation under Model B semantics.

---

PR-7 — Coroutines (Cooperative, Deterministic, No Mailbox)

Coroutines are the only concurrency model in the Prometeu VM.

This phase introduces:

• Cooperative scheduling
• Deterministic execution order
• SPAWN / YIELD / SLEEP
• Switching only at safepoints (FRAME_SYNC)
• Full GC integration

No mailbox. No message passing. No preemption.

Each PR below is self-contained and must compile independently.

---

PR-7.1 — Coroutine Heap Object

Briefing

A coroutine is a suspended execution context with its own stack and call frames.

No mailbox is implemented in this phase.

Target

Define ObjectKind::Coroutine with:

• state: enum { Ready, Running, Sleeping, Finished, Faulted }
• wake_tick: u64
• stack: Vec<Value>
• frames: Vec<CallFrame>

Rules:

• Allocated in GC heap.
• Addressed via HeapRef.
• Stack and frames stored inside the coroutine object.

Checklist

• Coroutine heap object defined.
• Stack/frames encapsulated.
• No RC/HIP remnants.
• Compiles and tests pass.

Tests

• Allocate coroutine object.
• Validate state transitions manually.

Junie Rules

You MAY extend heap object kinds. You MUST NOT implement scheduling yet. If stack representation is unclear, STOP and ask.

---

PR-7.2 — Deterministic Scheduler Core

Briefing

Implement a cooperative deterministic scheduler.

Target

Scheduler structure inside VM:

• ready_queue: VecDeque<HeapRef>
• sleeping: Vec<HeapRef> (sorted or scanned by wake_tick)
• current: Option<HeapRef>

Policy:

• FIFO for ready coroutines.
• Sleeping coroutines move to ready when wake_tick <= current_tick.

No execution switching yet.

Checklist

• Scheduler struct exists.
• Deterministic FIFO behavior.
• No randomness.

Tests

• Enqueue 3 coroutines and ensure dequeue order stable.

Junie Rules

You MAY add scheduler struct. You MUST NOT implement SPAWN/YIELD/SLEEP yet.

---

PR-7.3 — SPAWN Instruction

Briefing

SPAWN creates a new coroutine and schedules it.

Target

Introduce opcode:

SPAWN fn_id, arg_count

Semantics:

• Pop arg_count args.
• Create new coroutine object.
• Initialize its stack/frame with entry fn.
• Push coroutine handle onto ready queue.

Current coroutine continues execution.

Checklist

• SPAWN opcode exists.
• Coroutine created.
• Scheduled in ready queue.
• No immediate context switch.

Tests

• Spawn coroutine and verify it appears in ready queue.

Junie Rules

You MAY modify interpreter dispatch. You MUST NOT switch execution immediately. If entry frame layout unclear, STOP and ask.

---

PR-7.4 — YIELD Instruction

Briefing

YIELD voluntarily gives up execution.

Target

Opcode:

YIELD

Semantics:

• Current coroutine moves to end of ready queue.
• Scheduler selects next coroutine at safepoint.

Switching must occur only at FRAME_SYNC.

Checklist

• YIELD opcode implemented.
• Current coroutine enqueued.
• No mid-instruction switching.

Tests

• Two coroutines yielding alternate deterministically.

Junie Rules

You MAY modify VM execution loop. You MUST NOT allow switching outside safepoints.

---

PR-7.5 — SLEEP Instruction

Briefing

SLEEP suspends coroutine until a future tick.

Target

Opcode:

SLEEP duration_ticks

Semantics:

• Remove coroutine from ready queue.
• Set wake_tick.
• Add to sleeping list.

At each FRAME_SYNC:

• Check sleeping coroutines.
• Move ready ones to ready_queue.

Checklist

• SLEEP implemented.
• wake_tick respected.
• Deterministic wake behavior.

Tests

• Sleep and verify delayed execution.

Junie Rules

You MAY add tick tracking. You MUST NOT rely on real wall clock time.

---

PR-7.6 — Safepoint Integration

Briefing

Execution switching must occur only at safepoints.

Target

Switch coroutine only:

• After FRAME_SYNC
• After instruction completes

Never mid-instruction.

Checklist

• Switch only at safepoints.
• No reentrancy.

Tests

• Stress test switching under heavy loops.

Junie Rules

You MUST enforce deterministic switching.

---

PR-7.7 — GC Integration

Briefing

Suspended coroutines must be GC roots.

Target

GC mark phase must traverse:

• All coroutine stacks
• All coroutine frames

Checklist

• GC visits all suspended coroutines.
• No leaked references.

Tests

• Coroutine capturing heap object remains alive.
• Finished coroutine collected.

Junie Rules

You MUST NOT change sweep policy.

---

PR-7.8 — Verifier Rules

Briefing

Verifier must enforce coroutine safety.

Target

Rules:

• YIELD forbidden inside invalid contexts (define minimal safe rule).
• SPAWN argument validation.
• SLEEP argument type validation.

Checklist

• Invalid YIELD rejected.
• SPAWN arg mismatch rejected.

Tests

• Invalid bytecode rejected.

Junie Rules

You MUST NOT weaken verifier.

---

PR-7.9 — Determinism & Stress Tests

Briefing

Validate deterministic behavior.

Target

Tests must confirm:

• Same order across runs.
• Sleep/wake order stable.
• GC works with many coroutines.

Checklist

• Deterministic order tests.
• Stress test 100+ coroutines.

Junie Rules

Tests must not depend on wall clock or randomness.

---

Final Definition of Done

• Cooperative coroutines implemented.
• Deterministic scheduling.
• No mailbox.
• GC and verifier fully integrated.
• All tests pass.