# 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 Foreground Lifecycle Events

Foreground lifecycle events are system events with bounded delivery points.
They do not execute arbitrary guest callbacks at arrival time.

The Game pause path is:

```text
Home/SystemOS request
    -> pause event becomes visible to the Game
    -> bounded pause reaction budget
    -> SystemOS suspension, even if the Game did not cooperate
```

The Game resume path is:

```text
SystemOS resume request
    -> VM reactivation
    -> resume or foreground-restore event becomes visible to the Game
    -> Game may synchronize while still internally paused
    -> visual foreground returns after a valid current-epoch render submission
```

`Paused` is the Game-visible event/state. `Suspended` is the OS-owned
scheduler/runtime state. A Game may observe pause/resume, but it must not
control whether SystemOS suspends or resumes the VM.

When SystemOS replaces one Game with another from Home, the old Game MAY receive
a cooperative terminate/save lifecycle event if the runtime supports such an
event. That event is non-blocking in v1. SystemOS remains authoritative and may
close the old Game task/session without guest acknowledgement.

Pause budgets are measured in deterministic machine units, not host wall-clock
time. A suspended Game receives no normal gameplay ticks, no normal Game input,
and no frame pacing. Real background execution is outside the v1 foreground
contract.

## 8 VM Sessions and Execution Eligibility

Every VM-backed process MUST own a distinct VM session. A VM session owns the
mutable execution context for that process, including the VM instance,
per-session runtime counters, lifecycle delivery bookkeeping, debug/pause state,
and transient handles opened through VM-facing services.

Foreground ownership and execution eligibility are related but separate
concepts:

- foreground ownership selects the visual/navigation owner;
- execution eligibility selects which sessions may receive VM ticks;
- v1 grants normal VM execution only to the foreground VM-backed task, plus the
  bounded Game pause handoff tick defined above;
- a suspended resident Game preserves its VM session but MUST NOT receive
  normal gameplay ticks, normal Game input, or frame pacing;
- a VM-backed Shell owns its own VM session and MUST NOT overwrite or advance
  the resident Game session while the Shell is foreground;
- a native Shell does not own a VM session.

The model is intentionally compatible with future background execution. Future
service or media processes may become execution-eligible without changing the
rule that mutable VM context belongs to the owning session. This chapter does
not grant any v1 background progress guarantee.

Durable app data remains keyed by `app_id` where the relevant storage contract
requires it. Transient VM handles, open files, lifecycle delivery queues, and
staging state are session-scoped unless another spec explicitly makes them
durable app data.

During destructive Game replacement, the old Game VM session MUST be removed
from execution eligibility and resumable state before the new Game becomes the
foreground Game. The new Game MUST receive a fresh VM session. Failure while
loading or initializing the replacement Game MUST return the machine to
Hub/Home and MUST NOT restore the previous Game in v1.

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

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

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

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