From 33f70d1c6e62fb045a1eb76c508a1d3a86bbcb87 Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Sat, 4 Jul 2026 13:10:55 +0100 Subject: [PATCH] implements PLN-0139 --- .../src/firmware/firmware.rs | 57 +++++++++++++++++++ discussion/index.ndjson | 2 +- ...alidate-game-home-shell-game-end-to-end.md | 2 +- .../12-firmware-pos-and-prometeuhub.md | 25 +++++++- 4 files changed, 83 insertions(+), 3 deletions(-) diff --git a/crates/console/prometeu-firmware/src/firmware/firmware.rs b/crates/console/prometeu-firmware/src/firmware/firmware.rs index d9e1669a..fe083683 100644 --- a/crates/console/prometeu-firmware/src/firmware/firmware.rs +++ b/crates/console/prometeu-firmware/src/firmware/firmware.rs @@ -876,6 +876,63 @@ mod tests { assert!(!platform.input().touch().f().down); } + #[test] + fn game_home_shell_hub_same_game_flow_is_end_to_end_deterministic() { + let mut firmware = Firmware::new(None); + let mut platform = TestPlatform::new(); + let signals = InputSignals::default(); + + firmware.load_cartridge(valid_cartridge(AppMode::Game)); + firmware.tick(&signals, &mut platform); + + let game_task = match &firmware.state { + FirmwareState::GameRunning(step) => step.task_id, + other => panic!("expected GameRunning state, got {:?}", other), + }; + + firmware.request_home_from_host(); + firmware.tick(&signals, &mut platform); + + assert!(matches!(firmware.state, FirmwareState::HubHome(_))); + assert_eq!(firmware.os.lifecycle().foreground_owner(), ForegroundOwner::Hub); + assert_eq!(firmware.os.lifecycle().resident_game_task(), Some(game_task)); + assert_eq!(firmware.os.lifecycle().task_state(game_task), Some(TaskState::Suspended)); + + firmware.tick(&signals, &mut platform); + let shell_a_click = + InputSignals { f_signal: true, x_pos: 112, y_pos: 172, ..Default::default() }; + firmware.tick(&shell_a_click, &mut platform); + + let shell_task = match &firmware.state { + FirmwareState::ShellRunning(step) => step.task_id, + other => panic!("expected ShellRunning state, got {:?}", other), + }; + assert_eq!(firmware.os.lifecycle().foreground_owner(), ForegroundOwner::Shell(shell_task)); + assert_eq!(firmware.os.lifecycle().resident_game_task(), Some(game_task)); + assert_eq!(firmware.os.lifecycle().task_state(game_task), Some(TaskState::Suspended)); + + let close_shell = InputSignals { start_signal: true, ..Default::default() }; + firmware.tick(&close_shell, &mut platform); + + assert!(matches!(firmware.state, FirmwareState::HubHome(_))); + assert_eq!(firmware.os.lifecycle().foreground_owner(), ForegroundOwner::Hub); + assert_eq!(firmware.os.lifecycle().task_state(shell_task), Some(TaskState::Closed)); + assert_eq!(firmware.os.lifecycle().resident_game_task(), Some(game_task)); + + assert!(firmware.resume_resident_game_from_home()); + + match &firmware.state { + FirmwareState::GameRunning(step) => assert_eq!(step.task_id, game_task), + other => panic!("expected GameRunning state, got {:?}", other), + } + assert_eq!(firmware.os.lifecycle().foreground_owner(), ForegroundOwner::Game(game_task)); + assert_eq!(firmware.os.lifecycle().task_state(game_task), Some(TaskState::Foreground)); + assert_eq!( + firmware.os.lifecycle().pending_game_lifecycle_events().last().map(|event| event.kind), + Some(GameLifecycleEventKind::ResumeForeground) + ); + } + #[test] fn direct_game_boot_does_not_depend_on_userland_run_cart_syscall() { assert!(Syscall::from_u32(0x0002).is_none()); diff --git a/discussion/index.ndjson b/discussion/index.ndjson index a0aa7b43..143d6d40 100644 --- a/discussion/index.ndjson +++ b/discussion/index.ndjson @@ -2,7 +2,7 @@ {"type":"discussion","id":"DSC-0043","status":"open","ticket":"system-os-cartridge-switch-orchestrator","title":"SystemOS Cartridge Switch Orchestrator","created_at":"2026-07-03","updated_at":"2026-07-03","tags":["runtime","os","lifecycle","game","cartridge","architecture"],"agendas":[{"id":"AGD-0044","file":"AGD-0044-systemos-cartridge-switch-orchestrator.md","status":"open","created_at":"2026-07-03","updated_at":"2026-07-03"}],"decisions":[],"plans":[],"lessons":[]} {"type":"discussion","id":"DSC-0039","status":"abandoned","ticket":"render-pipeline-family-and-future-3d","title":"Render Pipeline Family and Future 3D","created_at":"2026-06-04","updated_at":"2026-06-04","tags":["gfx","renderer","runtime","architecture","pipeline"],"agendas":[{"id":"AGD-0039","file":"AGD-0039-render-pipeline-family-and-future-3d.md","status":"abandoned","created_at":"2026-06-04","updated_at":"2026-06-04","_override_reason":"User explicitly chose to close this agenda without a new decision because DSC-0038 already established enough architecture for future extension, and 3D is intentionally deferred."}],"decisions":[],"plans":[],"lessons":[],"_override_reason":"User explicitly chose to close this agenda without a new decision because DSC-0038 already established enough architecture for future extension, and 3D is intentionally deferred."} {"type":"discussion","id":"DSC-0040","status":"done","ticket":"vm-render-parallel-execution-boundary","title":"VM and Render Parallel Execution Boundary","created_at":"2026-06-04","updated_at":"2026-06-06","tags":["runtime","renderer","vm","concurrency","architecture","perf"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0048","file":"discussion/lessons/DSC-0040-vm-render-parallel-execution-boundary/LSN-0048-render-workers-need-a-closed-packet-contract.md","status":"done","created_at":"2026-06-06","updated_at":"2026-06-06"}]} -{"type":"discussion","id":"DSC-0041","status":"in_progress","ticket":"foreground-stack-game-pause-shell-vm-backed","title":"Foreground Stack, Game Pause, and VM-Backed Shell Coexistence","created_at":"2026-06-05","updated_at":"2026-07-03","tags":["runtime","os","lifecycle","shell","game","vm","foreground","architecture"],"agendas":[{"id":"AGD-0041","file":"AGD-0041-foreground-stack-game-pause-shell-vm-backed.md","status":"accepted","created_at":"2026-06-05","updated_at":"2026-07-03"}],"decisions":[{"id":"DEC-0037","file":"DEC-0037-foreground-stack-and-game-pause-contract.md","status":"accepted","created_at":"2026-07-03","updated_at":"2026-07-03","ref_agenda":"AGD-0041"}],"plans":[{"id":"PLN-0136","file":"PLN-0136-route-desktop-home-key-outside-guest-input.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]},{"id":"PLN-0137","file":"PLN-0137-implement-systemos-foreground-stack-state.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]},{"id":"PLN-0138","file":"PLN-0138-specify-foreground-pause-and-home-contract.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]},{"id":"PLN-0139","file":"PLN-0139-validate-game-home-shell-game-end-to-end.md","status":"open","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]},{"id":"PLN-0140","file":"PLN-0140-deliver-game-pause-resume-and-suspension.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]},{"id":"PLN-0141","file":"PLN-0141-integrate-render-audio-and-input-pause-boundaries.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]}],"lessons":[]} +{"type":"discussion","id":"DSC-0041","status":"in_progress","ticket":"foreground-stack-game-pause-shell-vm-backed","title":"Foreground Stack, Game Pause, and VM-Backed Shell Coexistence","created_at":"2026-06-05","updated_at":"2026-07-03","tags":["runtime","os","lifecycle","shell","game","vm","foreground","architecture"],"agendas":[{"id":"AGD-0041","file":"AGD-0041-foreground-stack-game-pause-shell-vm-backed.md","status":"accepted","created_at":"2026-06-05","updated_at":"2026-07-03"}],"decisions":[{"id":"DEC-0037","file":"DEC-0037-foreground-stack-and-game-pause-contract.md","status":"accepted","created_at":"2026-07-03","updated_at":"2026-07-03","ref_agenda":"AGD-0041"}],"plans":[{"id":"PLN-0136","file":"PLN-0136-route-desktop-home-key-outside-guest-input.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]},{"id":"PLN-0137","file":"PLN-0137-implement-systemos-foreground-stack-state.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]},{"id":"PLN-0138","file":"PLN-0138-specify-foreground-pause-and-home-contract.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]},{"id":"PLN-0139","file":"PLN-0139-validate-game-home-shell-game-end-to-end.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]},{"id":"PLN-0140","file":"PLN-0140-deliver-game-pause-resume-and-suspension.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]},{"id":"PLN-0141","file":"PLN-0141-integrate-render-audio-and-input-pause-boundaries.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]}],"lessons":[]} {"type":"discussion","id":"DSC-0042","status":"done","ticket":"real-render-worker-establishment","title":"Real Render Worker Establishment","created_at":"2026-06-06","updated_at":"2026-06-20","tags":["runtime","renderer","worker","concurrency","host","hal","architecture"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0049","file":"discussion/lessons/DSC-0042-real-render-worker-establishment/LSN-0049-render-worker-publication-boundary.md","status":"done","created_at":"2026-06-20","updated_at":"2026-06-20"}]} {"type":"discussion","id":"DSC-0038","status":"done","ticket":"render-frame-packet-boundary","title":"Logical Render Pipelines and Command Packets","created_at":"2026-05-25","updated_at":"2026-06-04","tags":["gfx","renderer","runtime","frame-composer","architecture","ui","pipeline"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0047","file":"discussion/lessons/DSC-0038-render-frame-packet-boundary/LSN-0047-typed-render-submissions-preserve-domain-boundaries.md","status":"done","created_at":"2026-06-04","updated_at":"2026-06-04"}]} {"type":"discussion","id":"DSC-0035","status":"done","ticket":"task-owned-shell-windows","title":"Agenda - Task-Owned Shell Windows","created_at":"2026-05-15","updated_at":"2026-05-15","tags":["runtime","os","task","window-manager","shell","lifecycle"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0044","file":"discussion/lessons/DSC-0035-task-owned-shell-windows/LSN-0044-task-window-liveness-belongs-to-the-task.md","status":"done","created_at":"2026-05-15","updated_at":"2026-05-15"}]} diff --git a/discussion/workflow/plans/PLN-0139-validate-game-home-shell-game-end-to-end.md b/discussion/workflow/plans/PLN-0139-validate-game-home-shell-game-end-to-end.md index b8f7086e..9df5d7fb 100644 --- a/discussion/workflow/plans/PLN-0139-validate-game-home-shell-game-end-to-end.md +++ b/discussion/workflow/plans/PLN-0139-validate-game-home-shell-game-end-to-end.md @@ -2,7 +2,7 @@ id: PLN-0139 ticket: foreground-stack-game-pause-shell-vm-backed title: Validate Game Home Shell Game End To End -status: open +status: done created: 2026-07-03 ref_decisions: [DEC-0037] tags: [runtime, validation, firmware, host, lifecycle] diff --git a/docs/specs/runtime/12-firmware-pos-and-prometeuhub.md b/docs/specs/runtime/12-firmware-pos-and-prometeuhub.md index 3958b3b5..d4c5782a 100644 --- a/docs/specs/runtime/12-firmware-pos-and-prometeuhub.md +++ b/docs/specs/runtime/12-firmware-pos-and-prometeuhub.md @@ -266,7 +266,30 @@ When a terminal app fault occurs: Crash handling is outside the guest VM execution model. -## 12 Relationship to Other Specs +## 12 Desktop Smoke Validation + +The foreground contract can be smoke-tested on the desktop host with: + +```text +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 +``` + +Expected behavior: + +- direct `--run` still boots the selected Game without using a guest cartridge + switching API; +- `--games-root` starts in Home and launches Games through the Home library; +- while a Game is running, `Esc` opens Home/SystemOS without entering the guest + pad input surface; +- the Game is paused, then suspended after the bounded SystemOS budget; +- Home remains foreground while the Game is resident; +- launching and closing a Shell app returns to Home without losing the resident + Game; +- returning to the same Game resumes it through the foreground lifecycle and + waits for current-epoch Game rendering before visual Game presentation. + +## 13 Relationship to Other Specs - [`02-vm-instruction-set.md`](02-vm-instruction-set.md) defines the VM subsystem run by firmware. - [`09-events-and-concurrency.md`](09-events-and-concurrency.md) defines the frame-boundary model used by firmware.