Intrepid/prometeu-runtime
Intrepid/prometeu-runtime
4
0
Fork 0
Code Pull Requests Activity
prometeu-runtime/discussion/workflow/plans/PLN-0145-centralize-resident-game-resume-transition.md
bQUARKz 0ecab2910b
implements PLN-0145
2026-07-04 18:52:04 +01:00

6.3 KiB
Raw Blame History

id ticket title status created ref_decisions tags
PLN-0145 foreground-stack-game-pause-shell-vm-backed Centralize Resident Game Resume Transition done 2026-07-04
DEC-0037
runtime
os
lifecycle
shell
game
vm
foreground
architecture

Briefing

DEC-0037 requires returning to the same resident Game to reactivate the Game VM, restore render ownership, send a resume/foreground lifecycle notification, and clear or barrier pending Game input. That transition currently exists in more than one firmware path: Firmware::resume_resident_game_from_home and the Hub library click path that resumes the selected resident Game by app_id.

The behavior is correct, but the duplication is fragile. Any future change to resume ordering, input barriers, render ownership, or lifecycle event delivery could fix one path while leaving the other path stale.

Objective

Create one firmware-owned resident Game resume helper and route every Home/Hub-to-Game resume path through it.

Dependencies

  • Source decision: DEC-0037.
  • Depends on the accepted v1 identity rule that app_id is unique for all games and may be used to decide whether a Hub game selection refers to the current resident Game.
  • Should preserve the behavior introduced by PLN-0142, PLN-0143, and PLN-0144.

Scope

Included:

  • Centralize resident Game resume orchestration in Firmware.
  • Preserve resume lifecycle event queuing through LifecycleFacade::resume_task.
  • Preserve render ownership transition back to AppMode::Game.
  • Preserve input barrier behavior across all Home/Hub-to-Game resume paths.
  • Preserve the Hub rule that selecting the same resident Game resumes it, while selecting a different Game remains blocked by v1 scope.
  • Keep tests proving same-task resume, lifecycle event delivery, and input barriering.

Excluded:

  • No Game-to-Game switching.
  • No multiple resident Games.
  • No change to app_id uniqueness policy.
  • No direct Shell-to-Game close behavior.

Non-Goals

  • Do not move foreground authority from SystemOS into firmware.
  • Do not change pause budget or suspend behavior.
  • Do not add UI affordances beyond the existing Hub game row selection.

Execution Method

  1. Introduce a single resident Game resume helper.

    • What changes: create a private firmware method that performs the complete resident Game resume operation and returns the target TaskId or a typed failure.
    • How it changes: move the shared sequence currently duplicated across resume_resident_game_from_home and HubHomeStep: read resident task, call LifecycleFacade::resume_task, transition VM render ownership to AppMode::Game, install GameRunningStep, clear state initialization, and arm the input barrier.
    • File(s): crates/console/prometeu-firmware/src/firmware/firmware.rs.

  2. Route explicit resume through the helper.

    • What changes: Firmware::resume_resident_game_from_home becomes a thin wrapper around the centralized helper.
    • How it changes: preserve its public bool return contract for existing tests and call sites.
    • File(s): crates/console/prometeu-firmware/src/firmware/firmware.rs.

  3. Route Hub same-game selection through the helper.

    • What changes: HubHomeStep must no longer hand-roll resume task, render ownership, and input clearing.
    • How it changes: expose a state transition request that lets the firmware perform the centralized helper, or restructure the Hub action handling so the parent Firmware owns this transition. Keep HubHomeStep responsible only for recognizing that the selected cartridge matches the resident app_id.
    • File(s): crates/console/prometeu-firmware/src/firmware/firmware.rs, crates/console/prometeu-firmware/src/firmware/firmware_step_hub_home.rs, crates/console/prometeu-firmware/src/firmware/firmware_state.rs if a new transition variant is needed.

  4. Keep different-game launch blocked under v1.

    • What changes: selecting a different app_id while a resident Game exists continues to log and remain in Hub.
    • How it changes: keep the existing warning behavior, but ensure it does not duplicate resume side effects.
    • File(s): crates/console/prometeu-firmware/src/firmware/firmware_step_hub_home.rs.

  5. Update regression tests.

    • What changes: tests should prove both explicit resume and Hub same-game selection use the same observable transition.
    • How it changes: assert same TaskId, foreground owner restored to Game, pending resume lifecycle event exists before the next Game tick, delivered resume event after the Game tick, and input barrier suppresses held input.
    • File(s): crates/console/prometeu-firmware/src/firmware/firmware.rs.

Acceptance Criteria

  • There is exactly one implementation of the resident Game resume sequence.
  • Firmware::resume_resident_game_from_home preserves its external behavior.
  • Hub selection of the same resident Game resumes the existing TaskId without creating or loading a new Game task.
  • The resume path always queues and delivers the Game lifecycle ResumeForeground event.
  • The resume path always barriers held Game input.
  • Selecting a different Game while one Game is resident remains blocked in v1.

Tests

  • Unit/integration tests in prometeu-firmware for explicit resume from Home.
  • Unit/integration tests in prometeu-firmware for Hub same-game selection after Home suspension.
  • Regression assertion that held input does not leak into the Game immediately after resume.
  • Run cargo test -p prometeu-firmware resident_game_resume.
  • Run cargo test -p prometeu-firmware hub_home_clicking_resident_game.
  • Run cargo test -p prometeu-system.
  • Run discussion validate.

Affected Artifacts

  • crates/console/prometeu-firmware/src/firmware/firmware.rs
  • crates/console/prometeu-firmware/src/firmware/firmware_step_hub_home.rs
  • crates/console/prometeu-firmware/src/firmware/firmware_state.rs

Risks

  • The current step/state architecture gives HubHomeStep a PrometeuContext but not direct access to private Firmware fields. If a new transition variant is introduced, it must stay narrow and must not turn state steps into owners of lifecycle authority.
  • Duplicating less logic must not accidentally weaken the input barrier that was added for Hub-to-Game transitions.