# Coroutines and Cooperative Scheduling

Domain: VM coroutine model
Function: normative

This chapter isolates PROMETEU coroutine semantics from the broader event/frame model.

## 1 Coroutine Model

PROMETEU provides coroutines as the only guest-visible concurrency model.

Coroutines are:

- cooperative;
- deterministic;
- scheduled only at safepoints;
- never preemptive.

There is:

- no parallel execution;
- no hidden threads;
- no scheduler behavior outside explicit machine rules.

## 2 Coroutine Lifecycle

Each coroutine can be in one of the following states:

- `Ready`
- `Running`
- `Sleeping`
- `Finished`

Coroutine-local execution state includes, conceptually:

```
Coroutine {
    call_stack
    operand_stack
    state
}
```

## 3 Scheduling

At each eligible scheduling boundary:

1. the scheduler selects the next coroutine;
2. ordering remains deterministic;
3. execution continues within the frame-budget model.

Baseline policy:

- round-robin or equivalent deterministic ordering;
- no surprise priority inversion hidden from the model;
- no preemption between safepoints.

## 4 Coroutine Operations

Typical operations:

| Operation | Description                   |
| --------- | ----------------------------- |
| `spawn`   | Create a coroutine            |
| `yield`   | Voluntarily suspend execution |
| `sleep`   | Suspend for N frames          |

`yield` and `sleep` only take effect at safepoints.

## 5 Interaction with the Frame Loop

Coroutine scheduling happens inside the frame model, not beside it.

Conceptually:

```
FRAME N
------------------------
Sample Input
Deliver Events
Schedule Coroutine
Run VM
FRAME_SYNC
------------------------
```

This preserves:

- deterministic replay;
- explicit cost accounting;
- consistent host/runtime handoff.

## 6 Costs and Determinism

Coroutine management:

- consumes cycles;
- contributes to certification/cost reporting;
- remains part of the deterministic execution trace.

Nothing about scheduling is "free" or hidden.

## 7 Relationship to Other Specs

- [`09-events-and-concurrency.md`](09-events-and-concurrency.md) defines the broader frame/event model.
- [`02-vm-instruction-set.md`](02-vm-instruction-set.md) defines coroutine-related instruction families.
- [`03-memory-stack-heap-and-allocation.md`](03-memory-stack-heap-and-allocation.md) defines coroutine-owned execution state in the memory model.