prometeu-runtime/discussion/workflow/plans/PLN-0150-route-cartridge-loading-through-vm-sessions.md

id	ticket	title	status	created	ref_decisions	tags
PLN-0150	foreground-stack-game-pause-shell-vm-backed	Route Cartridge Loading Through VM Sessions	done	2026-07-04	DEC-0038	runtime os lifecycle shell game vm foreground architecture

Briefing

DEC-0038 requires cartridge loading to create or activate a VM-backed process session instead of initializing a single global VM. The current LoadCartridgeStep initializes ctx.os.vm().initialize(ctx.vm, &cartridge) before task/session ownership is selected.

This plan moves cartridge initialization behind session services so Game and VM-backed Shell loading cannot overwrite each other.

Objective

Route Game and VM Shell cartridge loading through the VM session registry and initialize the cartridge inside the target session-owned VM context.

Dependencies

• Source decision: DEC-0038.
• Requires PLN-0148.
• Requires enough of PLN-0149 to expose session-owned VM/runtime initialization.
• Must precede the end-to-end coexistence validation in PLN-0152.

Scope

• Replace direct global VM initialization in LoadCartridgeStep.
• Add a session/facade operation that:
  • selects an existing resident Game session when the same app_id is relaunched;
  • rejects or reports different resident Game launches under V1;
  • creates a new VM Shell session for a Shell cartridge;
  • initializes the cartridge inside the selected session VM.
• Keep asset manager initialization aligned with the foreground cartridge being launched.
• Ensure AppCrashesStep receives initialization failures from the target session.
• Update Hub cartridge selection logic so resume versus load is based on lifecycle/session identity, not global VM identity.

Non-Goals

• Do not implement multiple resident Games.
• Do not implement background execution.
• Do not redesign cartridge format or asset packaging.
• Do not broaden Shell windowing behavior beyond the existing one-foreground-Shell model.

Execution Method

1. Add a load_vm_cartridge or equivalent method to SessionsFacade or VmFacade.
2. Make the method return an execution target:
   • existing Game task for same resident app_id;
   • new Game task for first Game launch;
   • new VM Shell task for Shell launch;
   • structured error/crash report for invalid VM initialization;
   • explicit lifecycle error for blocked second Game.
3. Update crates/console/prometeu-firmware/src/firmware/firmware_step_load_cartridge.rs to call the facade method instead of initializing ctx.vm.
4. Update crates/console/prometeu-firmware/src/firmware/firmware_step_hub_home.rs so same-Game relaunch checks session/lifecycle state rather than ctx.os.vm().current_app_id().
5. Preserve AppMode-based transition:
   • Game target transitions to GameRunning;
   • Shell target creates/focuses a window and transitions to ShellRunning.
6. Adapt crash tests and resident-game relaunch tests in firmware.

Acceptance Criteria

• LoadCartridgeStep no longer initializes a global firmware VM.
• Loading a Shell cartridge creates/initializes a Shell VM session.
• Loading the first Game cartridge creates/initializes the resident Game VM session.
• Clicking the same resident Game from Hub resumes the existing Game session without reinitializing it.
• Attempting to load a different Game while one resident Game exists remains blocked under V1 with a controlled outcome.
• VM initialization failure still transitions to AppCrashesStep.

Tests

• cargo test -p prometeu-firmware
• cargo test -p prometeu-system
• Add or update firmware tests for:
  • first Game load creates one session and enters GameRunning;
  • same Game relaunch resumes existing task/session;
  • VM Shell load creates a distinct session;
  • Shell load does not change resident Game session app identity;
  • invalid cartridge reports CrashReport::VmInit.

Affected Artifacts

• crates/console/prometeu-firmware/src/firmware/firmware_step_load_cartridge.rs
• crates/console/prometeu-firmware/src/firmware/firmware_step_hub_home.rs
• crates/console/prometeu-firmware/src/firmware/firmware.rs
• crates/console/prometeu-system/src/os/facades/sessions.rs
• crates/console/prometeu-system/src/os/facades/vm.rs
• VM session module introduced by PLN-0148