80 lines
3.7 KiB
Markdown
80 lines
3.7 KiB
Markdown
---
|
|
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.
|