87 lines
3.1 KiB
Markdown
87 lines
3.1 KiB
Markdown
---
|
|
id: PLN-0159
|
|
ticket: system-os-cartridge-switch-orchestrator
|
|
title: Recover Failed Game Switches Back To Home
|
|
status: done
|
|
created: 2026-07-05
|
|
ref_decisions: [DEC-0039]
|
|
tags: [runtime, os, lifecycle, game, cartridge, architecture]
|
|
---
|
|
|
|
## Briefing
|
|
|
|
DEC-0039 rejects preserving Game A after a switch begins. If Game B fails to
|
|
load, the system must discard partial Game B state and return to Home/Hub with a
|
|
diagnostic, not attempt rollback to Game A.
|
|
|
|
## Objective
|
|
|
|
Implement controlled failed-switch recovery to Home/Hub after destructive Game
|
|
replacement begins.
|
|
|
|
## Dependencies
|
|
|
|
- Source decision: DEC-0039.
|
|
- Requires PLN-0157 target contract.
|
|
- Requires PLN-0158 resident Game termination/session removal.
|
|
|
|
## Scope
|
|
|
|
- Detect load/init failure while switching to a different Game.
|
|
- Discard any partial new Game task/session/window/render/input/audio state.
|
|
- Return firmware/SystemOS to Home/Hub.
|
|
- Log or expose a diagnostic that Home can surface or tests can assert.
|
|
- Ensure previous Game is not restored after switch failure.
|
|
|
|
## Non-Goals
|
|
|
|
- Do not implement transactional rollback.
|
|
- Do not preserve the previous Game after switch begins.
|
|
- Do not design final user-facing error UI.
|
|
- Do not change direct boot failure behavior unless needed to keep paths
|
|
separate.
|
|
|
|
## Execution Method
|
|
|
|
1. Inspect existing load failure flow in
|
|
`crates/console/prometeu-firmware/src/firmware/firmware_step_load_cartridge.rs`.
|
|
2. Add a switch-specific failure outcome or context flag that distinguishes
|
|
SystemOS Game switching from direct boot load.
|
|
3. On switch load failure:
|
|
- remove partial new VM session/task/process if created;
|
|
- clear partial cartridge-scoped state;
|
|
- transition to `HubHome` instead of app crash when appropriate for switch
|
|
recovery;
|
|
- log a diagnostic containing target identity/path and failure summary.
|
|
4. Preserve existing direct boot and explicit load failure tests unless a direct
|
|
boot path intentionally still goes to crash.
|
|
5. Add tests for bad Game B after Game A was already terminated.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- Failed `Game A -> Home -> Broken Game B` returns to Home/Hub.
|
|
- Previous Game A is not resident, resumable, or restored.
|
|
- Partial Game B VM session/task/process state is removed or closed.
|
|
- A diagnostic is logged or otherwise observable.
|
|
- Existing direct boot/debug boot failure semantics remain separate.
|
|
|
|
## Tests
|
|
|
|
- `cargo test -p prometeu-firmware`
|
|
- `cargo test -p prometeu-system`
|
|
- `cargo test -p prometeu-host-desktop-winit`
|
|
- `cargo clippy -p prometeu-system -p prometeu-firmware -p prometeu-host-desktop-winit --all-targets -- -D warnings`
|
|
- Add tests for:
|
|
- switch failure returns Home;
|
|
- old Game not restored;
|
|
- partial new session cleanup;
|
|
- direct boot failure path remains unchanged.
|
|
|
|
## Affected Artifacts
|
|
|
|
- `crates/console/prometeu-firmware/src/firmware/firmware_step_load_cartridge.rs`
|
|
- `crates/console/prometeu-firmware/src/firmware/firmware_step_hub_home.rs`
|
|
- `crates/console/prometeu-firmware/src/firmware/firmware.rs`
|
|
- `crates/console/prometeu-system/src/os/facades/sessions.rs`
|
|
- `crates/console/prometeu-system/src/os/lifecycle.rs`
|