prometeu-runtime/docs/runtime/specs/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 game-running flow;
• System cartridges are initialized and integrated into the Hub/window path.

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

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.

5 Firmware State Relationship

Boot target selection feeds into firmware states such as:

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

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.