prometeu-runtime/discussion/workflow/plans/PLN-0139-validate-game-home-shell-game-end-to-end.md

id	ticket	title	status	created	ref_decisions	tags
PLN-0139	foreground-stack-game-pause-shell-vm-backed	Validate Game Home Shell Game End To End	done	2026-07-03	DEC-0037	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.