97 lines
4.4 KiB
Markdown
97 lines
4.4 KiB
Markdown
---
|
|
id: PLN-0156
|
|
ticket: foreground-stack-game-pause-shell-vm-backed
|
|
title: Harden VM Session Lifecycle Error Boundaries
|
|
status: done
|
|
created: 2026-07-05
|
|
ref_decisions: [DEC-0038]
|
|
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
|
|
---
|
|
|
|
## Briefing
|
|
|
|
DEC-0038 makes VM session services part of the runtime ownership boundary. Some current session creation paths still use `expect` for lifecycle failures and missing task/process/session invariants. That is acceptable for short-term scaffolding, but session services should expose typed errors at operational boundaries so callers can choose controlled crash, rejection, or recovery behavior.
|
|
|
|
## Objective
|
|
|
|
Replace operational `expect`/panic paths in VM session creation/loading with typed errors and controlled firmware outcomes. Keep internal invariant assertions only where impossible states have already been proven by prior checks.
|
|
|
|
## Dependencies
|
|
|
|
- Source decision: DEC-0038.
|
|
- Builds on PLN-0148 through PLN-0152.
|
|
- Can be implemented before or after PLN-0154.
|
|
- Should be implemented before broadening VM session scheduling or adding background-capable processes.
|
|
|
|
## Scope
|
|
|
|
- Add or extend typed errors for session/lifecycle operations:
|
|
- lifecycle rejection while creating Game/Shell task;
|
|
- missing task for session creation;
|
|
- missing process for session creation;
|
|
- duplicate session;
|
|
- VM-backed session missing during cartridge initialization;
|
|
- foreground Shell already exists.
|
|
- Convert `SessionsFacade::create_vm_shell_task` to a fallible equivalent and keep an infallible wrapper only for test/setup code if needed.
|
|
- Convert `create_vm_session_for_task` to avoid `expect` for task/process lookup.
|
|
- Convert `initialize_session_cartridge` to return typed missing-session errors instead of panicking.
|
|
- Map session/lifecycle errors into controlled `CrashReport` or launch rejection behavior in firmware.
|
|
- Preserve existing V1 policy:
|
|
- one resident Game;
|
|
- one foreground Shell;
|
|
- no Game-to-Game switching;
|
|
- native Shell creates no VM session.
|
|
|
|
## Non-Goals
|
|
|
|
- Do not change DEC-0038 ownership semantics.
|
|
- Do not add background execution.
|
|
- Do not redesign the foreground stack.
|
|
- Do not hide programmer invariants behind overly broad error swallowing.
|
|
|
|
## Execution Method
|
|
|
|
1. Introduce a `SessionError` or extend `VmSessionError` with operational cases that cross facade boundaries.
|
|
2. Update `SessionsFacade` methods:
|
|
- `try_create_vm_game_task`;
|
|
- new `try_create_vm_shell_task`;
|
|
- `load_vm_cartridge`;
|
|
- `create_vm_session_for_task`;
|
|
- `initialize_session_cartridge`.
|
|
3. Update firmware loading paths to map typed session errors into:
|
|
- controlled `CrashReport::VmPanic` for unrecoverable internal failures;
|
|
- logged rejection and no state transition for unsupported lifecycle transitions where appropriate.
|
|
4. Update tests that currently rely on panics or infallible creation.
|
|
5. Add focused tests for:
|
|
- duplicate foreground Shell rejection during VM Shell load;
|
|
- missing task/process session creation errors;
|
|
- missing VM session during initialization;
|
|
- native Shell still creates no VM session.
|
|
6. Run system, firmware, host tests and clippy.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- VM session facade operational failures are represented by typed errors.
|
|
- `create_vm_shell_task` has a fallible path used by production cartridge loading.
|
|
- VM Shell load does not panic when lifecycle rejects the Shell; it returns a controlled error/outcome.
|
|
- Missing task/process/session conditions in session services return typed errors.
|
|
- Existing tests for resident Game, native Shell, VM Shell, and Game/Shell coexistence still pass.
|
|
- No new broad `unwrap`/`expect` appears in production session/lifecycle paths.
|
|
|
|
## Tests
|
|
|
|
- `cargo test -p prometeu-system`
|
|
- `cargo test -p prometeu-firmware`
|
|
- `cargo test -p prometeu-host-desktop-winit`
|
|
- `cargo clippy -p prometeu-system -p prometeu-firmware -p prometeu-host-desktop-winit --all-targets -- -D warnings`
|
|
- Add tests for controlled errors from session creation/loading edge cases.
|
|
|
|
## Affected Artifacts
|
|
|
|
- `crates/console/prometeu-system/src/os/facades/sessions.rs`
|
|
- `crates/console/prometeu-system/src/services/vm_session.rs`
|
|
- `crates/console/prometeu-system/src/os/lifecycle.rs`
|
|
- `crates/console/prometeu-firmware/src/firmware/firmware_step_load_cartridge.rs`
|
|
- `crates/console/prometeu-firmware/src/firmware/firmware_step_hub_home.rs`
|
|
- Related system and firmware tests
|