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.

The local Home games library is not a separate firmware boot target. It is host configuration consumed by the Hub profile after boot.

2 Boot Modes

Hub

When the boot target is Hub:

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

If the host also provides --games-root <dir>, the Hub may discover and render valid Game cartridges from that root. Selecting one is a system-owned Home action that requests cartridge loading after the Hub is already running.

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.
• games-root start -> enter Hub with a local Game library for Home.

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.

--run <cart> and --debug <cart> are direct cartridge boot profiles. They select one cartridge before normal Hub/Home interaction and remain independent from the local library.

--games-root <dir> is a Hub/Home library configuration. It does not auto-launch a cartridge and does not create a guest-visible launch API.

The v1 games root contract is:

• the root contains directory cartridges as immediate child directories;
• recursive discovery is not performed;
• only valid cartridges whose manifest declares app_mode: "Game" are listed;
• Shell/System apps, packaged .pmc cartridges, remote catalogs, marketplace metadata, search, icons, and rich presentation are outside this profile;
• invalid candidates are logged and omitted from the Home list;
• Home entries may display only title, app_id, and app_version;
• selecting a Home entry requests firmware/SystemOS loading for that cartridge and transitions through LoadCartridge;
• launch failure leaves or returns the machine to Home and records an error.

Game-to-game switching after a game is already active is not part of this boot profile. That orchestration belongs to the foreground/home and cartridge switch contracts.

The foreground/home contract defines Game -> Home/Shell -> same Game after a Game is already running. It does not change direct --run, debugger direct boot, or --games-root Home library startup semantics. Home/SystemOS requests are host/system controls, not guest cartridge boot APIs.

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 Smoke Validation

The local Home library path should be smoke tested in release mode for realistic interactive speed:

cargo run --release -p prometeu-host-desktop-winit -- --games-root test-cartridges

Direct single-cartridge boot remains a separate validation path:

cargo run --release -p prometeu-host-desktop-winit -- --run test-cartridges/stress-console

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