Intrepid/prometeu-runtime
Intrepid/prometeu-runtime
4
0
Fork 0
Code Pull Requests Activity
prometeu-runtime/discussion/workflow/plans/PLN-0047-firmware-runtime-profile-dispatch.md

3.7 KiB
Raw Blame History

id ticket title status created completed ref_decisions tags
PLN-0047 runtime-mode-separation-game-system Firmware Runtime Profile Dispatch done 2026-05-14
DEC-0023
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.