150 lines
6.3 KiB
Markdown
150 lines
6.3 KiB
Markdown
---
|
|
id: PLN-0145
|
|
ticket: foreground-stack-game-pause-shell-vm-backed
|
|
title: Centralize Resident Game Resume Transition
|
|
status: done
|
|
created: 2026-07-04
|
|
ref_decisions: [DEC-0037]
|
|
tags: [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.
|