93 lines
4.4 KiB
Markdown
93 lines
4.4 KiB
Markdown
---
|
|
id: PLN-0148
|
|
ticket: foreground-stack-game-pause-shell-vm-backed
|
|
title: Introduce VM Session Registry and Identity
|
|
status: done
|
|
created: 2026-07-04
|
|
ref_decisions: [DEC-0038]
|
|
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
|
|
---
|
|
|
|
## Briefing
|
|
|
|
DEC-0038 requires every VM-backed process to own its own mutable VM context instead of sharing `Firmware.vm`. This plan introduces the identity and registry layer required before moving runtime state or changing cartridge loading.
|
|
|
|
The implementation must make VM session ownership explicit inside `SystemOS`. A VM-backed Game task and a VM-backed Shell task must be able to coexist as distinct sessions, even before all execution paths are migrated to session-owned VMs.
|
|
|
|
## Objective
|
|
|
|
Add a `VmSession` model and registry owned by `SystemOS`, keyed by a stable session identity tied to the owning task/process. The registry must support creating, retrieving, and validating VM sessions for VM-backed Game and Shell tasks.
|
|
|
|
## Dependencies
|
|
|
|
- Source decision: DEC-0038.
|
|
- Existing foreground/task/process lifecycle from DEC-0037 remains authoritative.
|
|
- Must be implemented before PLN-0149, PLN-0150, PLN-0151, and PLN-0152.
|
|
|
|
## Scope
|
|
|
|
- Add a session identity type, preferably `VmSessionId`, with a deliberate mapping from the owning `TaskId`.
|
|
- Add a `VmSession` data structure containing at least:
|
|
- owning `TaskId`;
|
|
- owning process id or process lookup path;
|
|
- `app_id`, title, version, and `AppMode`;
|
|
- initial placeholder for the session-owned `VirtualMachine`;
|
|
- initial placeholder for session-owned runtime state to be populated by PLN-0149.
|
|
- Add a registry under `crates/console/prometeu-system/src/services/` or an equivalent existing services module.
|
|
- Expose creation and lookup through `crates/console/prometeu-system/src/os/facades/sessions.rs`.
|
|
- Update `SystemOS` construction in `crates/console/prometeu-system/src/os/system_os.rs` to own the registry.
|
|
- Enforce V1 uniqueness:
|
|
- at most one resident Game session;
|
|
- one foreground Shell task at a time;
|
|
- same `app_id` resident Game relaunch maps to the existing resident session rather than creating a second Game session.
|
|
|
|
## Non-Goals
|
|
|
|
- Do not move all VM runtime fields yet; that is PLN-0149.
|
|
- Do not route cartridge loading through sessions yet; that is PLN-0150.
|
|
- Do not remove `Firmware.vm` yet.
|
|
- Do not implement general background execution.
|
|
- Do not allow Game-to-Game switching.
|
|
|
|
## Execution Method
|
|
|
|
1. Inspect `TaskId`, process ids, and `ProcessKind` definitions in `crates/console/prometeu-system/src/services/task/` and `crates/console/prometeu-system/src/services/process/`.
|
|
2. Add the VM session module with a small API:
|
|
- create session for an existing VM-backed task/process;
|
|
- get immutable/mutable session by task id;
|
|
- get resident Game session by `app_id`;
|
|
- reject incompatible duplicate Game sessions.
|
|
3. Wire the registry into `SystemOS`.
|
|
4. Extend `SessionsFacade::create_vm_game_task` and `create_vm_shell_task` so task creation also creates a VM session record.
|
|
5. Keep native Shell task creation out of the VM session registry.
|
|
6. Add focused unit tests under `prometeu-system` for registry identity and duplicate handling.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- `SystemOS` owns a VM session registry.
|
|
- Creating a VM Game task creates exactly one VM session associated with that task.
|
|
- Creating a VM Shell task creates exactly one VM session associated with that task.
|
|
- Creating a native Shell task creates no VM session.
|
|
- Attempting to create a second resident Game session for a different `app_id` is rejected or routed through the existing lifecycle rejection path.
|
|
- Relaunching the same resident Game can resolve the existing VM session by `app_id`.
|
|
- No firmware state transition depends on the new registry yet except through task/session creation.
|
|
|
|
## Tests
|
|
|
|
- `cargo test -p prometeu-system`
|
|
- Add unit tests for:
|
|
- VM Game task creates a VM session;
|
|
- VM Shell task creates a VM session;
|
|
- native Shell task does not create a VM session;
|
|
- lookup by `TaskId`;
|
|
- same resident Game `app_id` resolves to the existing session;
|
|
- different resident Game `app_id` remains blocked under V1.
|
|
|
|
## Affected Artifacts
|
|
|
|
- `crates/console/prometeu-system/src/os/system_os.rs`
|
|
- `crates/console/prometeu-system/src/os/facades/sessions.rs`
|
|
- `crates/console/prometeu-system/src/services/mod.rs`
|
|
- New or extended module under `crates/console/prometeu-system/src/services/`
|
|
- `crates/console/prometeu-system/src/lib.rs` if exports are required
|