# 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: ```rust 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 `, 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 ` and `--debug ` are direct cartridge boot profiles. They select one cartridge before normal Hub/Home interaction and remain independent from the local library. `--games-root ` 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: ```sh cargo run --release -p prometeu-host-desktop-winit -- --games-root test-cartridges ``` Direct single-cartridge boot remains a separate validation path: ```sh 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`](12-firmware-pos-and-prometeuhub.md) defines the firmware state machine that consumes boot targets. - [`13-cartridge.md`](13-cartridge.md) defines cartridge structure. - [`10-debug-inspection-and-profiling.md`](10-debug-inspection-and-profiling.md) defines the observability/debugging layer.