# Events and Scheduling

Domain: machine events and frame scheduling
Function: normative

This chapter defines events, timers, faults, and the frame-boundary model of the PROMETEU machine.

Coroutine lifecycle and cooperative scheduling details now live in a dedicated companion chapter.

## 1 Core Philosophy

PROMETEU does not model hidden asynchronous execution.

Machine-visible event behavior is based on:

- explicit frame steps;
- deterministic delivery points;
- observable costs;
- no surprise callbacks.

## 2 Events

### 2.1 Definition

Events are machine-level facts made visible to the system in controlled phases.

Examples include:

- input state changes;
- timer expiry;
- host-signaled machine events;
- fault publication at the machine boundary.

### 2.2 Event Queue

Events are conceptually queued and processed at known synchronization points.

The machine model forbids arbitrary guest code execution at event arrival time.

## 3 Frame Boundary (Sync Phase)

The frame boundary is the primary global synchronization point of the machine.

At this phase, the system may:

- sample input;
- deliver pending events;
- account for frame-level work;
- coordinate VM/runtime/firmware transitions around `FRAME_SYNC`.

This preserves determinism and keeps machine behavior legible.

## 4 System Events vs System Faults

### 4.1 Normal events

Normal events report machine state changes without implying system failure.

### 4.2 System faults

System faults are not ordinary events.

When a terminal fault occurs:

- execution stops or transitions to fault-handling flow;
- diagnostics are produced;
- the fault is not treated like a recoverable guest event queue item.

## 5 Timers

Timers are modeled as frame-based counters.

Properties:

- measured in frames, not wall-clock time;
- deterministic across runs;
- integrated with the frame model rather than hidden interrupts.

Timers do not execute code by themselves; they make state or events available to be observed at deterministic boundaries.

## 6 Relationship Between Events and the Frame Loop

High-level structure:

```
FRAME N
------------------------
Sample Input
Deliver Events
Run VM until:
  - budget exhausted, or
  - FRAME_SYNC reached
Sync Phase
------------------------
```

Important properties:

- events are processed at known points;
- no execution occurs outside the frame loop;
- frame structure remains observable for tooling and certification.

## 7 Determinism and Best Practices

PROMETEU encourages:

- treating events as data;
- querying state explicitly;
- structuring logic around frame boundaries;
- avoiding implicit control flow hidden behind event delivery.

PROMETEU discourages:

- asynchronous callback simulation;
- hidden timing channels;
- ambiguous out-of-band execution.

## 8 Relationship to Other Specs

- [`09a-coroutines-and-cooperative-scheduling.md`](09a-coroutines-and-cooperative-scheduling.md) defines coroutine lifecycle and scheduling behavior.
- [`10-debug-inspection-and-profiling.md`](10-debug-inspection-and-profiling.md) defines observability and diagnostics surfaces.
- [`12-firmware-pos-and-prometeuhub.md`](12-firmware-pos-and-prometeuhub.md) defines firmware orchestration at machine level.
- [`02-vm-instruction-set.md`](02-vm-instruction-set.md) defines VM execution inside this frame model.