prometeu-runtime/docs/runtime/specs/12-firmware-pos-and-prometeuhub.md

Firmware - POS and PrometeuHub

Domain: firmware and system orchestration Function: normative

This chapter defines the firmware layer of the PROMETEU machine.

It covers:

• machine authority above the VM;
• POS responsibilities;
• Hub responsibilities;
• firmware states and cartridge launch flow.

1 Firmware Scope

The PROMETEU firmware is composed of two cooperating layers:

• PrometeuOS (POS): the machine authority responsible for boot, VM/runtime orchestration, peripherals, crash handling, and system-level policy;
• PrometeuHub: the launcher/UI layer that runs over POS and uses the system window model.

The VM does not own the machine lifecycle. Firmware does.

2 Terms

• Host: the real platform that drives the core loop and presents output.
• POS: system firmware/core authority.
• PrometeuHub: launcher and system UI running over POS.
• PVM: the VM subsystem that executes cartridge bytecode.
• Cartridge: the executable package loaded by firmware.
• AppMode: cartridge mode, currently Game or System.
• Logical frame: execution unit completed when the app reaches FRAME_SYNC.
• Host tick: the host-driven outer update tick.

3 POS Responsibilities

POS is responsible for:

• deterministic reset into known machine state;
• VM initialization and teardown for cartridge execution;
• input latching and logical-frame budgeting;
• peripheral reset/orchestration;
• fault capture and crash-flow transition;
• return to Hub after app exit or crash.

At the VM boundary, POS must preserve:

• logical-frame semantics;
• FRAME_SYNC as the canonical frame boundary;
• deterministic transition from host tick to VM slice execution.

4 PrometeuHub Responsibilities

PrometeuHub is responsible for:

• presenting available apps;
• reading cartridge metadata needed for launch decisions;
• deciding launch behavior based on AppMode;
• managing the system window surface for system-mode apps.

The Hub does not execute bytecode directly. It always delegates execution setup to POS.

5 App Modes

Game

Game-mode cartridges:

• transition firmware into the game-running state;
• run as the active app flow;
• present through the main frame path.

System

System-mode cartridges:

• are initialized by POS;
• are integrated into the Hub/window environment;
• do not replace the firmware state with the game-running path.

6 Cartridge Load Flow

Current high-level flow:

1. POS receives a cartridge to load;
2. asset manager is initialized from the cartridge asset table, preload list, and packed asset bytes;
3. POS initializes the VM/runtime for the cartridge;
4. launch behavior branches by AppMode:
   • Game -> transition to the game-running firmware state;
   • System -> create/focus a Hub window and return to the Hub state.

If VM initialization fails, firmware transitions to the crash path.

7 Firmware States

The current firmware state model includes:

• Reset
• SplashScreen
• LaunchHub
• HubHome
• LoadCartridge
• GameRunning
• AppCrashes

These states express machine orchestration above the VM. They are not guest-visible bytecode states.

8 Execution Contract

For game-mode execution, firmware/runtime coordination preserves:

• input latched per logical frame;
• execution in host-driven slices until FRAME_SYNC;
• present only when a logical frame completes;
• no frame present when budget ends before FRAME_SYNC.

This keeps the machine model deterministic and observable.

9 Crash Handling

Firmware owns terminal fault presentation.

When a terminal app fault occurs:

• POS captures the crash report;
• firmware leaves normal app execution flow;
• the machine transitions to AppCrashes.

Crash handling is outside the guest VM execution model.

10 Relationship to Other Specs

• 02-vm-instruction-set.md defines the VM subsystem run by firmware.
• 09-events-and-concurrency.md defines the frame-boundary model used by firmware.
• 13-cartridge.md defines cartridge structure and metadata consumed by firmware.
• 14-boot-profiles.md defines startup target selection.