prometeu-runtime/docs/runtime/specs/09-events-and-concurrency.md

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 defines coroutine lifecycle and scheduling behavior.
• 10-debug-inspection-and-profiling.md defines observability and diagnostics surfaces.
• 12-firmware-pos-and-prometeuhub.md defines firmware orchestration at machine level.
• 02-vm-instruction-set.md defines VM execution inside this frame model.