107 lines
4.0 KiB
Markdown
107 lines
4.0 KiB
Markdown
---
|
|
id: PLN-0139
|
|
ticket: foreground-stack-game-pause-shell-vm-backed
|
|
title: Validate Game Home Shell Game End To End
|
|
status: done
|
|
created: 2026-07-03
|
|
ref_decisions: [DEC-0037]
|
|
tags: [runtime, validation, firmware, host, lifecycle]
|
|
---
|
|
|
|
## Briefing
|
|
|
|
`DEC-0037` is not complete until the product flow is proven end to end:
|
|
a Game runs, the user requests Home, the Game is paused/suspended, Hub or a
|
|
VM-backed Shell takes foreground, closing Shell returns to Hub, and the same
|
|
Game can resume only after a valid current-epoch frame exists.
|
|
|
|
This plan adds final validation after the spec, SystemOS, VM, host input, and
|
|
render/audio/input boundary plans are implemented.
|
|
|
|
## Decisions of Origin
|
|
|
|
- `DEC-0037` - Foreground Stack and Game Pause Contract.
|
|
|
|
## Target
|
|
|
|
Prove the complete `Game -> Home/Shell -> same Game` lifecycle and prevent
|
|
regressions around guest input, foreground authority, and stale rendering.
|
|
|
|
## Scope
|
|
|
|
- Add integration-style tests for:
|
|
- Game running to Home request;
|
|
- pause notification and forced suspension;
|
|
- Hub foreground while Game is resident;
|
|
- VM-backed Shell foreground while Game is suspended;
|
|
- Shell close returning to Hub;
|
|
- resume request returning to same Game;
|
|
- first-valid-frame visual restore;
|
|
- host `Esc`/`Home` not entering guest input.
|
|
- Add manual smoke instructions for desktop host.
|
|
- Confirm direct `--run` and games-root Home launch remain separate.
|
|
|
|
## Out of Scope
|
|
|
|
- No new implementation beyond tests and developer-facing validation notes.
|
|
- No Game A -> Home -> Game B switching.
|
|
- No performance tuning.
|
|
- No polished UI.
|
|
|
|
## Execution Plan
|
|
|
|
1. Add firmware/SystemOS integration tests.
|
|
Use the most stable existing seams in `crates/console/prometeu-firmware/src/firmware/firmware.rs`
|
|
and `crates/console/prometeu-system` tests to drive Game foreground, Home
|
|
request, Shell foreground, Shell close, and Game resume.
|
|
|
|
2. Add host input integration tests.
|
|
Ensure `Esc` and physical `Home` create a host Home event and do not mutate
|
|
guest `InputSignals`.
|
|
|
|
3. Add render publication validation.
|
|
Assert stale submissions from the pre-pause Game epoch are rejected after
|
|
Home takes foreground and that the Game is not visually restored until a new
|
|
current-epoch submission exists.
|
|
|
|
4. Add audio/input boundary validation.
|
|
Assert Game input is cleared or barriered across pause/resume. Assert Game
|
|
audio pause follows Game suspension.
|
|
|
|
5. Add direct boot and games-root regression checks.
|
|
Ensure direct `--run <cart>` remains independent from Home request handling
|
|
and that games-root Home launch still enters the Game path.
|
|
|
|
6. Document manual smoke commands.
|
|
Add or update developer-facing spec text with release-mode commands:
|
|
- `cargo run --release -p prometeu-host-desktop-winit -- --run test-cartridges/stress-console`
|
|
- `cargo run --release -p prometeu-host-desktop-winit -- --games-root test-cartridges`
|
|
Include the expected `Esc -> Home -> Shell -> Hub -> resume Game` behavior
|
|
once implemented.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- Automated tests cover `Game -> Home -> same Game`.
|
|
- Automated tests cover `Game -> Home -> Shell -> Hub -> same Game`.
|
|
- Tests prove Home request is host/SystemOS control, not guest pad input.
|
|
- Tests prove suspended Game does not tick.
|
|
- Tests prove stale render submissions are not presented.
|
|
- Tests prove visual return waits for a current-epoch Game frame.
|
|
- Direct `--run` and games-root Home launch regressions pass.
|
|
|
|
## Tests / Validation
|
|
|
|
- Run `cargo test -p prometeu-system`.
|
|
- Run `cargo test -p prometeu-firmware`.
|
|
- Run `cargo test -p prometeu-host-desktop-winit`.
|
|
- Run any targeted render worker tests affected by ownership epoch changes.
|
|
- Run `discussion validate`.
|
|
|
|
## Risks
|
|
|
|
- The current test seams may not expose enough host-driven lifecycle behavior.
|
|
If needed, add narrow test-only helpers rather than testing through sleeps or
|
|
real-time window loops.
|
|
- End-to-end validation can become flaky if it depends on wall-clock timing.
|
|
Use deterministic ticks and explicit state transitions.
|