100 lines
5.0 KiB
Markdown
100 lines
5.0 KiB
Markdown
---
|
|
id: PLN-0149
|
|
ticket: foreground-stack-game-pause-shell-vm-backed
|
|
title: Move VM Runtime State Into VM Sessions
|
|
status: done
|
|
created: 2026-07-04
|
|
ref_decisions: [DEC-0038]
|
|
tags: [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`
|