prometeu-runtime/discussion/workflow/plans/PLN-0164-expose-resident-game-termination-contract.md

id	ticket	title	status	created	ref_decisions	tags
PLN-0164	hub-suspended-game-kill-affordance	Expose Resident Game Termination Contract	done	2026-07-05	DEC-0040	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