prometeu-runtime/discussion/lessons/DSC-0043-system-os-cartridge-switch-orchestrator/LSN-0053-game-switching-is-lifecycle-replacement-not-loader-work.md

id	ticket	title	created	tags
LSN-0053	system-os-cartridge-switch-orchestrator	Game Switching Is Lifecycle Replacement, Not Loader Work	2026-07-05	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.