---
id: PLN-0047
ticket: runtime-mode-separation-game-system
title: Firmware Runtime Profile Dispatch
status: done
created: 2026-05-14
completed:
ref_decisions: [DEC-0023]
tags: [runtime, firmware, hub, system-apps, game-mode, scheduler]
---

## Briefing

This plan implements the first routing split required by `DEC-0023`: focused `System` cartridges must not enter `GameRunningStep` or the game frame pipeline. The existing game path must remain behaviorally unchanged.

## Decisions de Origem

- `DEC-0023` - System Pipeline Separation.

## Alvo

Make firmware dispatch choose an explicit runtime profile path after cartridge load: `Game` routes to `GameRunningStep`, while `System` routes to a Runtime/Hub-owned system step.

## Escopo

- Introduce explicit profile dispatch around cartridge load and firmware state transitions.
- Add a dedicated system-running firmware step or equivalent dispatch branch.
- Keep `GameRunningStep` semantics unchanged for `AppMode::Game`.
- Preserve current minimal WindowManager window creation/focus behavior for `AppMode::System`.

## Fora de Escopo

- No redesign of `GameRunningStep`, `FrameComposer`, canonical game composition, game input, banks, sprites, or memory-card semantics.
- No complete WindowManager or public PBS `System` ABI.
- No multitasking/scheduler contract beyond one focused system app path.

## Plano de Execucao

### Step 1 - Add a profile-named system firmware step

**What:** Create a dedicated step for focused `System` cartridge execution.
**How:** Add a `SystemRunningStep` or similarly explicit type under the firmware module and register it in `firmware_state`.
**File(s):** `crates/console/prometeu-firmware/src/firmware/firmware_step_system_running.rs`, `crates/console/prometeu-firmware/src/firmware/mod.rs`, `crates/console/prometeu-firmware/src/firmware/firmware_state.rs`.

### Step 2 - Route cartridge load by `AppMode`

**What:** Replace implicit HubHome fallback with explicit profile dispatch.
**How:** In `LoadCartridgeStep::on_update`, route `AppMode::Game` to `FirmwareState::GameRunning(GameRunningStep)` and `AppMode::System` to the new system-running state after creating/focusing the hub window.
**File(s):** `crates/console/prometeu-firmware/src/firmware/firmware_step_load_cartridge.rs`.

### Step 3 - Preserve game behavior

**What:** Ensure the game path still calls `ctx.os.tick(ctx.vm, ctx.signals, ctx.hw)` and presents exactly as before.
**How:** Do not change `GameRunningStep` except for imports required by compile fallout.
**File(s):** `crates/console/prometeu-firmware/src/firmware/firmware_step_game_running.rs`.

### Step 4 - Add route tests

**What:** Prove `System` does not transition to `GameRunning`.
**How:** Add or update firmware tests that load a `System` cartridge and assert the resulting firmware state is the dedicated system state, while a `Game` cartridge still reaches `GameRunning`.
**File(s):** `crates/console/prometeu-firmware/src/firmware/firmware.rs` or nearby firmware tests.

## Criterios de Aceite

- [ ] Loading an `AppMode::Game` cartridge transitions to `GameRunning`.
- [ ] Loading an `AppMode::System` cartridge transitions to a dedicated system profile state.
- [ ] No `AppMode::System` path enters `GameRunningStep`.
- [ ] Existing game-running behavior remains unchanged except for profile guards.

## Tests / Validacao

- `cargo test -p prometeu-firmware`
- `cargo test -p prometeu-system`
- Add assertions that the system route creates/focuses a hub window without selecting `GameRunning`.

## Riscos

- Existing `HubHomeStep` currently mixes hub GUI work and focused system VM ticking; splitting state names may reveal hidden assumptions in host/debugger state reporting.
- The implementation must not use this step to redesign game presentation or hub UI.