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.
• VM-backed cartridges are initialized in a POS-owned VM session associated with the created task/process.

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 a boot profile. That orchestration belongs to the foreground/home and cartridge switch contracts. In that path, SystemOS owns the switch policy: selecting the same resident Game resumes it, while selecting a different Game performs destructive replacement and creates a fresh VM session for the new Game.

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.

Direct boot creates the initial VM session for the selected cartridge. It does not create a reusable global VM shared by later Game or Shell cartridges. Direct boot and debug boot MUST NOT be treated as failed-switch recovery paths: load or initialization failures for direct boot may transition to the crash flow, while Home-driven switch failures return to Home and do not restore the previous Game.

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

Game switch validation should cover the Home-driven two-cartridge path, for example Stress Console -> Home -> Dummy Boy, and assert that the first Game is not resumable after replacement.

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.