prometeu-runtime/discussion/workflow/plans/PLN-0148-introduce-vm-session-registry-and-identity.md

id	ticket	title	status	created	ref_decisions	tags
PLN-0148	foreground-stack-game-pause-shell-vm-backed	Introduce VM Session Registry and Identity	done	2026-07-04	DEC-0038	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