prometeu-runtime/docs/specs/runtime/14-boot-profiles.md

Boot Profiles

Domain: firmware boot flow Function: normative

This chapter defines how PROMETEU chooses what to execute at startup.

1 Boot Target

The current firmware-side boot target concept is:

enum BootTarget {
  Hub,
  Cartridge { path: String, debug: bool, debug_port: u16 },
}

This is a firmware/host orchestration contract, not a guest-visible ABI.

2 Boot Modes

Hub

When the boot target is Hub:

• firmware boots into the Hub flow;
• no cartridge is auto-launched.

Cartridge

When the boot target is Cartridge:

1. firmware loads the requested cartridge;
2. cartridge metadata is read;
3. launch behavior follows cartridge app_mode;
4. bytecode execution starts through the cartridge boot protocol defined by the cartridge contract, not by textual entry metadata.

3 Launch Resolution by App Mode

For a cartridge boot target:

• Game cartridges transition into the game-running pipeline;
• System cartridges transition into a Runtime/Hub pipeline dedicated to system UI and app hosting.

This preserves the distinction between machine firmware state and app execution mode.

The System route must not be treated as the game pipeline running inside a window. It is a separate runtime profile path oriented around Hub ownership and WindowManager integration. The initial implementation may be minimal, but the routing boundary is normative: System does not enter GameRunning as its profile pipeline.

4 Host CLI Relationship

Typical host-facing boot intents are:

• default start -> enter Hub;
• run cartridge -> boot with cartridge target;
• debug cartridge -> boot with cartridge target plus debug mode parameters.

The CLI is an entry surface for boot target selection; the firmware contract remains the same underneath.

Host CLI, debugger, and equivalent single-game launch flows are the supported direct cartridge boot surfaces. Direct boot is not requested by guest bytecode through a system.run_cart syscall or any other app-callable cartridge boot ABI.

5 Firmware State Relationship

Boot target selection feeds into firmware states such as:

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

Additional firmware states may represent dedicated System profile execution. Such states are part of the Runtime/Hub route and do not change the Game pipeline contract.

Boot target is not itself a firmware state. It is an input to the firmware state machine.

6 Debug Boot

When booting a cartridge in debug mode:

• firmware/runtime uses the cartridge target path;
• debugger-related startup behavior is enabled;
• execution still follows the same cartridge/app-mode resolution path.

Debug mode changes orchestration, not the cartridge contract.

7 Relationship to Other Specs

• 12-firmware-pos-and-prometeuhub.md defines the firmware state machine that consumes boot targets.
• 13-cartridge.md defines cartridge structure.
• 10-debug-inspection-and-profiling.md defines the observability/debugging layer.