prometeu-runtime/docs/specs/runtime/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 host tooling and host-owned certification.

7 Render Worker Concurrency

The render worker is not a machine-visible event source and does not introduce guest callbacks. It is an implementation-side consumer of closed render submissions.

The render worker handoff uses single-slot latest-wins semantics:

• a producer publishes at most one pending owned RenderSubmission;
• a newer submission replaces an older unconsumed pending submission;
• replacement is counted as telemetry;
• the producer does not wait for worker rasterization or host present;
• the worker takes ownership of the submission it consumes.

The worker publishes OwnedRgba8888Frame values. Each published frame owns its RGBA8888 pixel vector and carries frame and ownership metadata. Repeating a frame reuses the latest published owned frame and does not execute guest code or recompose the frame.

Render resources reachable from a submission are resolved through read-only ID-based access. The worker MUST NOT hold mutable VM state, mutable Hardware, mutable Gfx, or a live mutable FrameComposer as its cross-thread contract.

Shutdown is explicit and bounded. A shutdown request wakes a waiting worker, causes pending work that will not be consumed to be discarded, and reports a typed failure if the worker cannot join within the configured timeout.

8 Async Asset and IO Work Lane

The asset/IO async work lane is not a machine-visible event source and does not introduce guest callbacks. It is an implementation-side lane for asset IO/decode/materialization and compatible persistence IO work.

The lane is serial:

• it has at most one active job;
• it keeps an ordered backlog;
• it is separate from the render worker;
• it must not create one OS thread per guest-visible asset request.

Asset jobs are keyed by target bank_type/slot. A newer request for the same target supersedes the older request. Superseding is an operational status and does not execute guest code.

Asset install/commit into resident banks happens on the main runtime lane at predictable ownership points. The async lane prepares materialized results; it does not publish resident graphics/audio/scene state directly.

FS and game persistence services may consume this lane for IO-style work, but public FS API shape is defined by the FS/app-home contract, not by this chapter.

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

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