99 lines
3.9 KiB
Markdown
99 lines
3.9 KiB
Markdown
---
|
|
id: PLN-0158
|
|
ticket: system-os-cartridge-switch-orchestrator
|
|
title: Terminate Resident Game Before Switching Cartridges
|
|
status: done
|
|
created: 2026-07-05
|
|
ref_decisions: [DEC-0039]
|
|
tags: [runtime, os, lifecycle, game, cartridge, architecture]
|
|
---
|
|
|
|
## Briefing
|
|
|
|
DEC-0039 defines `Game A -> Home -> Game B` as destructive replacement. The
|
|
current same-Game resume flow keeps the resident Game session alive; switching
|
|
to a different Game must instead close/remove that resident session and create a
|
|
fresh session for the new Game.
|
|
|
|
## Objective
|
|
|
|
Implement the SystemOS lifecycle/session operation that terminates the current
|
|
resident Game before loading a different Game cartridge.
|
|
|
|
## Dependencies
|
|
|
|
- Source decision: DEC-0039.
|
|
- Requires PLN-0157 target contract.
|
|
- Should be implemented before PLN-0159 and PLN-0161.
|
|
|
|
## Scope
|
|
|
|
- Add a controlled resident Game termination/replacement operation to SystemOS
|
|
lifecycle/session services.
|
|
- Optionally emit a cooperative terminate/close/save lifecycle event when the
|
|
current event model can carry it, but do not block replacement on it.
|
|
- Remove the previous Game from resident/resumable state.
|
|
- Remove the previous Game VM session before activating the new Game.
|
|
- Clear or reassign app-scoped state that cannot leak into the new Game:
|
|
session VM, open handles, pending lifecycle state, input barrier/pending
|
|
input, audio active app state, render ownership, telemetry/debug/crash state.
|
|
|
|
## Non-Goals
|
|
|
|
- Do not preserve Game A for rollback.
|
|
- Do not implement failed-load recovery beyond surfacing errors; that is
|
|
PLN-0159.
|
|
- Do not add background execution or multiple resident Games.
|
|
- Do not build final launcher UX.
|
|
|
|
## Execution Method
|
|
|
|
1. Inspect lifecycle/session state in:
|
|
- `crates/console/prometeu-system/src/os/lifecycle.rs`;
|
|
- `crates/console/prometeu-system/src/os/facades/sessions.rs`;
|
|
- `crates/console/prometeu-system/src/services/foreground`;
|
|
- `crates/console/prometeu-firmware/src/firmware/firmware_step_hub_home.rs`;
|
|
- `crates/console/prometeu-firmware/src/firmware/firmware_step_load_cartridge.rs`.
|
|
2. Add a `replace_resident_game` or equivalent operation that:
|
|
- finds the current resident Game;
|
|
- marks its task/process closed or stopped according to existing lifecycle
|
|
semantics;
|
|
- removes the resident Game entry from foreground stack/lifecycle state;
|
|
- removes its VM session.
|
|
3. Ensure same-Game resume still bypasses replacement and remains governed by
|
|
DEC-0037.
|
|
4. Update game launch from Home so launching a different app_id triggers
|
|
replacement before load.
|
|
5. Ensure render ownership transitions away from the old Game before the new
|
|
Game becomes foreground.
|
|
6. Add focused tests for resident Game termination and session removal.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- Launching a different Game from Home closes/removes the resident Game rather
|
|
than resuming it.
|
|
- The previous Game VM session is absent before the new Game is made active.
|
|
- Same-Game selection still resumes the existing resident Game.
|
|
- A cooperative close/terminate event, if added, is non-blocking.
|
|
- No previous Game VM, handle, lifecycle, render, or debug state is reused by
|
|
the new Game.
|
|
|
|
## Tests
|
|
|
|
- `cargo test -p prometeu-system`
|
|
- `cargo test -p prometeu-firmware`
|
|
- `cargo clippy -p prometeu-system -p prometeu-firmware --all-targets -- -D warnings`
|
|
- Add tests for:
|
|
- different Game launch removes previous resident session;
|
|
- same Game launch resumes existing resident session;
|
|
- old Game task/process state is closed/stopped;
|
|
- old Game session cannot be resolved after replacement starts.
|
|
|
|
## Affected Artifacts
|
|
|
|
- `crates/console/prometeu-system/src/os/lifecycle.rs`
|
|
- `crates/console/prometeu-system/src/os/facades/sessions.rs`
|
|
- `crates/console/prometeu-system/src/services/foreground`
|
|
- `crates/console/prometeu-firmware/src/firmware/firmware_step_hub_home.rs`
|
|
- `crates/console/prometeu-firmware/src/firmware/firmware_step_load_cartridge.rs`
|