Hub Suspended Game Kill Affordance
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good

This commit is contained in:
2026-07-05 16:27:05 +01:00
parent 49cb16b6cb
commit de53eb5ad7
17 changed files with 142 additions and 1413 deletions
@@ -0,0 +1,67 @@
---
id: LSN-0053
ticket: system-os-cartridge-switch-orchestrator
title: Game Switching Is Lifecycle Replacement, Not Loader Work
created: 2026-07-05
tags: [runtime, os, lifecycle, game, cartridge]
---
## Context
PROMETEU supports two superficially similar flows:
- `Game -> Home -> same Game`, which is pause/suspend/resume.
- `Game A -> Home -> Game B`, which is destructive replacement.
The second flow is not a loader feature. It is a SystemOS lifecycle operation
that happens to use the cartridge loader after the old resident Game has been
removed from resumable state.
## Key Decisions
### SystemOS Game Cartridge Switch Orchestrator
**What:** A different-Game launch from Home terminates the previous resident
Game before loading the new cartridge. The new Game receives a fresh VM session.
**Why:** Reusing or preserving the old Game while the new Game loads creates a
rollback problem across VM state, handles, assets, input, audio, render
ownership, debug state, and lifecycle delivery. V1 does not need that
transactional model.
**Trade-offs:** Failed replacement returns to Home and does not restore the old
Game. This is intentionally simpler than snapshot/rollback and makes state
ownership visible in tests.
## Patterns and Algorithms
Use a resolved SystemOS switch target, not a guest syscall, for Home launches.
The target carries cartridge path and identity, while SystemOS owns the policy:
1. detect whether the selected Game matches the resident `app_id`;
2. resume if it is the same Game;
3. terminate the old resident Game if it is different;
4. load the new cartridge through the normal loader;
5. create and initialize a fresh VM session;
6. return to Home on replacement failure without restoring the previous Game.
The loader stays a materializer. It does not close tasks, remove sessions,
repair foreground state, or own failure recovery.
## Pitfalls
- Treating a different Game as a resume path leaks VM execution state.
- Letting the loader own lifecycle cleanup hides policy in the wrong layer.
- Keeping the old Game as rollback state requires correctness across assets,
render ownership, input barriers, audio, open handles, and debugger state.
- A switch test with only one cartridge cannot prove identity replacement.
## Takeaways
- Same-Game Home selection is resume; different-Game Home selection is
destructive replacement.
- SystemOS owns cartridge switching policy; the cartridge loader only loads.
- Replacement failure should be a clean Home state, not a rollback to the old
Game.
- End-to-end switch tests need visually distinct cartridges to catch stale
session or stale frame reuse.
@@ -0,0 +1,72 @@
---
id: LSN-0054
ticket: hub-suspended-game-kill-affordance
title: Manual Hub Kill Must Share Game Termination Cleanup
created: 2026-07-05
tags: [hub, lifecycle, game, ui, assets]
---
## Context
After a Game returns to Home, the Game can remain resident and suspended so it
can be resumed later. That state needs a visible, direct way to terminate the
resident Game without launching another cartridge just to force replacement.
The Hub kill affordance solved the UX gap, but the durable engineering lesson is
the cleanup boundary: manual kill must not become a second, partial termination
path.
## Key Decisions
### Hub Suspended Game Kill Affordance
**What:** Hub renders a red bottom-right control when a Game is resident and
suspended. The control shows only the Game title. Clicking it immediately
terminates the resident Game and keeps the user in Hub.
**Why:** The user can distinguish "resume this Game" from "discard this resident
Game" without starting a different cartridge. Reusing the canonical termination
path prevents a repeat of stale scene/glyph/asset state bugs.
**Trade-offs:** V1 has no confirmation step. The destructive nature is carried
by placement, color, and the fact that the target Game is already out of
foreground.
## Patterns and Algorithms
Manual Hub kill and destructive Game replacement should call the same resident
Game termination helper. That helper is responsible for the whole runtime
surface:
- close the Game task;
- stop the process;
- remove the VM session;
- clear resident Game state and task-scoped lifecycle delivery;
- restore Shell/Hub render ownership;
- clear lifecycle audio pause state;
- unbind the Game2D composer scene;
- shut down cartridge-scoped asset manager state and physical banks;
- emit explicit Hub/POS observability for manual kill.
The Hub itself should emit a high-level action such as `KillResidentGame`; it
should not know how to clean runtime subsystems.
## Pitfalls
- A UI-only kill that removes a task but leaves assets or composer binding alive
can still fail later when another Game renders.
- A cleanup-only helper without an end-to-end Hub click test can miss the
interaction between hitbox, foreground ownership, render owner, and no-resume.
- Hard-coded click coordinates in tests make the UI contract harder to maintain;
expose the layout hitbox when tests need to exercise it.
## Takeaways
- Visible system controls should produce system actions, not direct subsystem
mutation from UI code.
- Manual kill and Game replacement are variants of the same resident Game
termination contract.
- Cleanup tests should prove both logical state removal and visible-frame
behavior: the control appears before kill and disappears after kill.
- "No resume after kill" is as important as "task closed" because resumability
is the user-facing state.