94 lines
4.1 KiB
Markdown
94 lines
4.1 KiB
Markdown
---
|
|
id: PLN-0164
|
|
ticket: hub-suspended-game-kill-affordance
|
|
title: Expose Resident Game Termination Contract
|
|
status: done
|
|
created: 2026-07-05
|
|
ref_decisions: [DEC-0040]
|
|
tags: [hub, lifecycle, game, ui]
|
|
---
|
|
|
|
## Briefing
|
|
|
|
DEC-0040 requires the Hub kill affordance to reuse the same resident-game termination path used by cartridge switching. This plan creates the lifecycle/runtime contract that the Hub UI can call without duplicating cleanup logic.
|
|
|
|
## Objective
|
|
|
|
Expose a single SystemOS/Firmware operation that terminates the current resident `Game` cartridge from Hub context and performs the complete cleanup required by DEC-0040.
|
|
|
|
## Dependencies
|
|
|
|
- Source decision: DEC-0040.
|
|
- Related lifecycle behavior: DSC-0043 / DEC-0039 cartridge switch orchestrator.
|
|
- Must be completed before PLN-0163 can wire the Hub UI click.
|
|
|
|
## Scope
|
|
|
|
- Add or reuse a resident-game termination operation in SystemOS lifecycle/facade code.
|
|
- Ensure the operation closes task/process lifecycle state.
|
|
- Ensure the operation removes the VM session and resident game state.
|
|
- Ensure render ownership returns to Shell/Hub.
|
|
- Ensure game audio pause/lifecycle state is cleared.
|
|
- Ensure Game2D composer scene binding/cache state is cleared.
|
|
- Ensure cartridge asset manager state and physical memory banks are cleared.
|
|
- Emit an explicit `INFO` log for manual Hub kill.
|
|
|
|
## Non-Goals
|
|
|
|
- Do not change cartridge switching semantics except to reuse the same termination path.
|
|
- Do not add Hub UI rendering or hit testing; that belongs to PLN-0163.
|
|
- Do not add confirmation semantics; DEC-0040 explicitly rejects confirmation for this version.
|
|
- Do not support shell/system app killing through this affordance.
|
|
|
|
## Execution Method
|
|
|
|
1. Locate the current game switch termination path in firmware/SystemOS lifecycle code.
|
|
- Files: `crates/console/prometeu-firmware/src/firmware/`, `crates/console/prometeu-system/src/`.
|
|
- Confirm which function currently closes the resident game before switching cartridges.
|
|
|
|
2. Extract or expose a named resident-game termination operation.
|
|
- The operation must be callable from Hub context without a target cartridge.
|
|
- It must return an explicit status: no resident game, terminated game, or failure if the lifecycle cannot close cleanly.
|
|
- It must preserve existing switch behavior by making switch call the same operation or a shared internal helper.
|
|
|
|
3. Wire complete cleanup into that operation.
|
|
- Close task/process lifecycle state.
|
|
- Remove the VM session and resident game state.
|
|
- Transition render ownership to Shell/Hub.
|
|
- Clear game lifecycle audio pause state.
|
|
- Unbind `Game2D` scene/composer state.
|
|
- Shutdown cartridge assets and clear physical memory banks.
|
|
|
|
4. Emit the manual kill log.
|
|
- Source must be `HUB` or `POS`.
|
|
- Level must be `INFO`.
|
|
- Message must include the killed title, equivalent to `Resident game killed from Hub: <title>`.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] There is one canonical resident-game termination path used by both cartridge switching and Hub manual kill.
|
|
- [ ] Calling the operation with no resident game is harmless and does not mutate unrelated Hub state.
|
|
- [ ] Calling the operation with a suspended `Game` closes the task/process and removes the VM session.
|
|
- [ ] The runtime cannot resume the killed game after the operation.
|
|
- [ ] Render ownership is Shell/Hub after the operation.
|
|
- [ ] Game audio pause/lifecycle state is not left active after the operation.
|
|
- [ ] Composer and cartridge asset/bank state are cleared.
|
|
- [ ] An explicit INFO log is emitted for Hub manual kill.
|
|
|
|
## Tests
|
|
|
|
- Unit or integration test around the lifecycle operation:
|
|
- no resident game is a no-op;
|
|
- resident game is terminated;
|
|
- VM session lookup returns none after kill;
|
|
- resident game state returns none after kill;
|
|
- render owner is Shell/Hub after kill.
|
|
- Regression test proving cartridge switch still terminates through the same cleanup behavior.
|
|
- Asset/composer cleanup assertions should mirror the recent Stress/Dummy switch tests where applicable.
|
|
|
|
## Affected Artifacts
|
|
|
|
- `crates/console/prometeu-system/src/`
|
|
- `crates/console/prometeu-firmware/src/`
|
|
- Existing switch tests under firmware/SystemOS test modules
|