# 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.

---

# PR-8 — Tooling & Test Harness (JVM-Grade Discipline)

This phase establishes tooling and test discipline required to keep the Prometeu VM at JVM-grade quality.

Goals:

* Deterministic execution
* Reproducible tests
* Strong disassembler guarantees
* Layered test coverage
* Zero legacy artifacts enforcement

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

---

# PR-8.1 — Disassembler (Roundtrip + Snapshot Reliability)

## Briefing

The disassembler must be:

* Deterministic
* Complete
* Roundtrip-safe (encode → decode → encode)
* Snapshot-friendly

It must fully support:

* New opcodes (MAKE_CLOSURE, CALL_CLOSURE, SPAWN, YIELD, SLEEP)
* Updated syscall representation
* Closure and coroutine instructions

## Target

1. Update disassembler to support all new opcodes.
2. Guarantee stable formatting.
3. Add roundtrip validation tests.

Formatting rules:

* No unstable ordering.
* No implicit formatting differences across platforms.
* Explicit numeric representation where required.

## Acceptance Checklist

* [ ] All opcodes supported.
* [ ] Deterministic formatting.
* [ ] Roundtrip encode/decode test passes.
* [ ] Snapshot tests stable.

## Tests

1. Encode → disasm → reassemble → byte-equal check.
2. Snapshot test for representative programs.
3. Closure/coroutine disasm coverage.

## Junie Instructions

You MAY:

* Modify disassembler module.
* Add snapshot tests.

You MUST NOT:

* Change bytecode encoding format.
* Introduce formatting randomness.

If any opcode semantics unclear, STOP and ask.

---

# PR-8.2 — Deterministic Execution Harness

## Briefing

The VM must be testable deterministically.

Requirements:

* No wall-clock time.
* Controlled tick progression.
* Fixed seed where randomness exists (if any).

## Target

Introduce a test harness wrapper:

* Controlled `tick` counter.
* Deterministic scheduler stepping.
* Explicit run_budget boundaries.

Provide utilities:

* `run_until_halt()`
* `run_ticks(n)`
* `run_frames(n)`

No external timing.

## Acceptance Checklist

* [ ] No real-time dependencies.
* [ ] Deterministic coroutine wake order.
* [ ] Repeatable runs produce identical traces.

## Tests

1. Same program run twice produces identical state traces.
2. Sleep/wake ordering stable.

## Junie Instructions

You MAY:

* Extend test harness.
* Add deterministic trace utilities.

You MUST NOT:

* Introduce randomness.
* Use system time.

If current VM depends on real time, STOP and refactor before proceeding.

---

# PR-8.3 — Layered Test Suite Architecture

## Briefing

Tests must be structured by layer to isolate failures.

Layers:

1. Bytecode encode/decode
2. Verifier
3. VM execution
4. GC behavior
5. Scheduler behavior

## Target

Organize tests into modules per layer.

Enforce:

* No cross-layer assumptions.
* Verifier tests do not execute VM.
* VM tests assume verified input.

Add minimal coverage per layer.

## Acceptance Checklist

* [ ] Tests grouped logically.
* [ ] No duplicated logic.
* [ ] Clear separation of concerns.

## Tests

Add representative tests per layer:

* Encode/decode edge cases.
* Verifier rejects invalid closures.
* VM executes valid programs.
* GC collects unreachable closures.
* Scheduler deterministic ordering.

## Junie Instructions

You MAY:

* Refactor test layout.
* Add missing coverage.

You MUST NOT:

* Merge unrelated layers.
* Hide verifier failures inside runtime traps.

If a test spans layers, STOP and split appropriately.

---

# PR-8.4 — No Legacy Artifacts Enforcement

## Briefing

The codebase must not contain legacy RC/HIP artifacts.

Forbidden patterns:

* retain
* release
* hip
* gate
* borrow
* scope (legacy usage context)
* RC-related modules

## Target

Implement automated check:

* Script or test that scans source tree for forbidden symbols.
* Fails CI if found.

Also:

* Remove dead modules/files.
* Remove unused features.

## Acceptance Checklist

* [ ] Automated legacy scan exists.
* [ ] No legacy symbols present.
* [ ] Dead modules removed.

## Tests

1. Intentionally insert forbidden symbol in test branch → test fails.
2. Scan passes on clean tree.

## Junie Instructions

You MAY:

* Add static scan test.
* Remove dead code.

You MUST NOT:

* Suppress warnings instead of fixing code.
* Leave deprecated modules commented out.

If unsure whether a symbol is legacy or valid, STOP and ask.

---

## Final Definition of Done

* Disassembler roundtrip-safe.
* Deterministic harness in place.
* Layered test suite established.
* No legacy artifacts remain.
* All tests reproducible and stable.

---

# PR-9 — Final Hardening & Baseline Documentation

This phase finalizes the new Prometeu VM baseline after the architectural reset (GC, closures, coroutines, unified syscall ABI, deterministic scheduler).

Goals:

* Consolidated architecture documentation (short, precise, authoritative)
* Minimal and controlled public surface area
* Removal of temporary feature flags
* Final cleanup: dead code, warnings, outdated docs/examples

All PRs below are self-contained and must compile independently.

---

# PR-9.1 — Consolidated Architecture Documentation

## Briefing

The project must include a short, authoritative architecture document in English describing the new baseline.

It must reflect the current state only (no legacy, no transitional wording).

This document becomes the canonical reference for contributors.

## Target

Create `ARCHITECTURE.md` at repository root with sections:

1. Overview

    * Stack-based VM
    * GC-managed heap (mark-sweep, non-compacting)
    * Closures (Model B, hidden arg0)
    * Cooperative coroutines (FRAME_SYNC safepoints)
    * Unified syscall ABI

2. Memory Model

    * Stack vs heap
    * Heap object kinds
    * GC roots (VM + suspended coroutines)

3. Execution Model

    * Interpreter loop
    * Safepoints
    * Scheduler behavior

4. Verification Model

    * Verifier responsibilities
    * Runtime vs verifier guarantees

5. Non-Goals

    * No RC
    * No HIP
    * No preemption
    * No mailbox

The document must be concise (no more than ~4–6 pages equivalent).

## Acceptance Checklist

* [ ] ARCHITECTURE.md exists.
* [ ] No mention of RC/HIP.
* [ ] Reflects actual implementation.
* [ ] Reviewed for consistency with code.

## Tests

Manual review required.

## Junie Instructions

You MAY:

* Create new documentation files.

You MUST NOT:

* Invent features not implemented.
* Reference legacy behavior.

If architecture details are unclear, STOP and request clarification.

---

# PR-9.2 — Public Surface Area Minimization

## Briefing

The public API must be minimal and intentional.

Internal modules must not leak implementation details.

## Target

1. Audit all `pub` items.
2. Reduce visibility to `pub(crate)` where possible.
3. Hide internal modules behind private boundaries.
4. Ensure only intended API is exported.

Focus areas:

* VM core
* Heap internals
* Scheduler internals
* GC internals

## Acceptance Checklist

* [ ] No unnecessary `pub` items.
* [ ] Public API documented.
* [ ] Internal types hidden.
* [ ] `cargo doc` shows clean public surface.

## Tests

* Build documentation.
* Ensure no accidental public modules remain.

## Junie Instructions

You MAY:

* Restrict visibility.
* Refactor module structure.

You MUST NOT:

* Break existing internal usage.
* Expose new APIs casually.

If removing `pub` causes architectural issue, STOP and escalate.

---

# PR-9.3 — Remove Temporary Feature Flags

## Briefing

During refactor phases, temporary feature flags or conditional compilation may have been introduced.

These must not remain in the final baseline.

## Target

1. Identify all feature flags related to transitional behavior.
2. Remove obsolete `cfg` gates.
3. Remove commented legacy branches.
4. Ensure single authoritative execution path.

## Acceptance Checklist

* [ ] No transitional feature flags remain.
* [ ] No commented-out legacy logic.
* [ ] Single execution model.
* [ ] All tests pass.

## Tests

* Full test suite passes without feature toggles.

## Junie Instructions

You MAY:

* Remove obsolete flags.
* Simplify code paths.

You MUST NOT:

* Remove legitimate platform flags.
* Leave partial dead branches.

If unsure whether a flag is temporary or architectural, STOP and ask.

---

# PR-9.4 — Final Cleanup & Quality Sweep

## Briefing

This PR performs the final cleanup pass.

Goal: Zero warnings. No dead code. No outdated examples.

## Target

1. Remove dead modules/files.
2. Remove unused imports and code.
3. Eliminate compiler warnings.
4. Update outdated examples.
5. Remove stale TODOs referencing removed architecture.

Optional (if present):

* Enforce `cargo clippy` clean baseline.
* Ensure `rustfmt` compliance.

## Acceptance Checklist

* [ ] No dead code.
* [ ] Zero compiler warnings.
* [ ] Clippy clean (if configured).
* [ ] Examples reflect new baseline.
* [ ] No TODO referencing RC/HIP.

## Tests

* Full test suite passes.
* Clean build with warnings denied (if configured).

## Junie Instructions

You MAY:

* Remove unused code.
* Refactor minor clarity issues.

You MUST NOT:

* Introduce new features.
* Change runtime semantics.

If cleanup requires semantic change, STOP and split into new PR.

---

## Final Definition of Done

* Architecture documented clearly.
* Public API minimal and controlled.
* No temporary flags remain.
* Codebase clean, warning-free, and aligned with the new VM baseline.