91 lines
4.2 KiB
Markdown
91 lines
4.2 KiB
Markdown
---
|
|
id: PLN-0150
|
|
ticket: foreground-stack-game-pause-shell-vm-backed
|
|
title: Route Cartridge Loading Through VM Sessions
|
|
status: open
|
|
created: 2026-07-04
|
|
ref_decisions: [DEC-0038]
|
|
tags: [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
|