prometeu-runtime/discussion/workflow/plans/PLN-0149-move-vm-runtime-state-into-vm-sessions.md

id	ticket	title	status	created	ref_decisions	tags
PLN-0149	foreground-stack-game-pause-shell-vm-backed	Move VM Runtime State Into VM Sessions	done	2026-07-04	DEC-0038	runtime os lifecycle shell game vm foreground architecture

Briefing

DEC-0038 states that mutable VM context must belong to the VM-backed process session, not to firmware or a single global runtime slot. The current split has Firmware.vm: VirtualMachine and SystemOS.vm_runtime: VirtualMachineRuntime, which makes a suspended Game vulnerable to VM-backed Shell execution.

This plan migrates mutable per-application VM runtime state into the session model introduced by PLN-0148 while keeping global OS services global.

Objective

Make each VM session own the state needed to suspend and later resume that VM-backed process without being overwritten by another VM-backed process.

Dependencies

• Source decision: DEC-0038.
• Requires PLN-0148.
• Must precede full cartridge-loading and scheduler migration in PLN-0150 and PLN-0151.

Scope

• Classify VirtualMachineRuntime fields into session-owned versus global OS-owned state.
• Move session-owned fields into the VmSession context.
• Keep global services in SystemOS, including:
  • LogService;
  • process/task/window managers;
  • foreground stack;
  • durable MemcardService;
  • global render publication authority or worker coordination that must remain host-facing.
• Treat these as session-owned unless proven otherwise during implementation:
  • VirtualMachine;
  • current cartridge identity;
  • frame and tick counters;
  • lifecycle delivery bookkeeping;
  • crash report for that session;
  • pause/debug flags that apply to that session;
  • per-session open files, handles, and staging state used by VM syscalls.
• Keep durable memcard contents keyed by app_id; do not turn save data into session-private durable storage.
• Update VmFacade and VM runtime helpers so callers can operate on a selected session.

Non-Goals

• Do not redesign render workers beyond separating session-local render command state from global presentation authority.
• Do not implement background execution.
• Do not change syscall semantics except where required to route state through the active session.
• Do not remove host debugger features; preserve or adapt their access path.

Execution Method

1. Add an internal field-by-field classification comment or test-only assertion near VirtualMachineRuntime before moving fields.
2. Introduce a session runtime/context type in the VM session module or by splitting VirtualMachineRuntime into:
   • session-local runtime;
   • global render/log/runtime services.
3. Move VirtualMachine ownership from firmware placeholder/session stub into the session context.
4. Move per-cartridge and per-frame state from SystemOS.vm_runtime into the session context.
5. Move open_files, next_handle, and VM syscall staging state out of global SystemOS if they are VM-session specific.
6. Update VmRuntimeHost in crates/console/prometeu-system/src/services/vm_runtime/dispatch.rs to receive session-local state plus references to required global services.
7. Update VmFacade in crates/console/prometeu-system/src/os/facades/vm.rs with explicit session-targeted methods.
8. Preserve temporary compatibility methods only where needed for existing host/debugger code, and mark them as active-session views rather than canonical global ownership.
9. Add tests proving two VM sessions can hold different app identity and counters at the same time.

Acceptance Criteria

• No canonical VM state lives in Firmware.
• SystemOS can hold at least two VM sessions with independent VirtualMachine and per-session runtime state.
• VM session A and VM session B can have different app_id, title, frame counters, lifecycle delivery history, crash report, open file handles, and debug pause state.
• Durable memcard contents remain shared by app_id according to the existing memcard contract.
• Global render ownership remains controlled by SystemOS/host-facing runtime services, not by individual sessions.
• Existing prometeu-system VM runtime tests still pass after adapting their setup.

Tests

• cargo test -p prometeu-system
• cargo test -p prometeu-firmware
• Add tests for:
  • independent session app identity;
  • independent tick/logical-frame counters;
  • independent lifecycle delivery bookkeeping;
  • VM Shell session initialization does not mutate resident Game session identity;
  • session-scoped file handles do not collide across sessions.

Affected Artifacts

• crates/console/prometeu-system/src/services/vm_runtime/
• VM session module introduced by PLN-0148
• crates/console/prometeu-system/src/os/facades/vm.rs
• crates/console/prometeu-system/src/os/system_os.rs
• crates/console/prometeu-system/src/os/facades/fs.rs
• crates/console/prometeu-firmware/src/firmware/firmware.rs
• crates/host/prometeu-host-desktop-winit/src/debugger.rs
• crates/host/prometeu-host-desktop-winit/src/runner.rs
• crates/host/prometeu-host-desktop-winit/src/stats.rs