90 lines
4.5 KiB
Markdown
90 lines
4.5 KiB
Markdown
---
|
|
id: PLN-0155
|
|
ticket: foreground-stack-game-pause-shell-vm-backed
|
|
title: Retire Legacy Firmware VM Runtime Bridge
|
|
status: open
|
|
created: 2026-07-05
|
|
ref_decisions: [DEC-0038]
|
|
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
|
|
---
|
|
|
|
## Briefing
|
|
|
|
DEC-0038 states that `Firmware.vm` must not remain the canonical owner of VM-backed app context. PLN-0148 through PLN-0152 moved normal cartridge loading and ticking toward VM sessions, but a transitional legacy bridge still initializes and exposes the old global VM/runtime path for compatibility.
|
|
|
|
## Objective
|
|
|
|
Remove the legacy firmware VM/runtime bridge from normal runtime architecture. After this plan, VM-backed app execution, initialization, active runtime queries, and host-facing inspection must resolve through VM sessions or explicitly global render/runtime services.
|
|
|
|
## Dependencies
|
|
|
|
- Source decision: DEC-0038.
|
|
- Requires PLN-0154 so debugger operations no longer depend on `firmware.vm`.
|
|
- Builds on PLN-0148 through PLN-0153.
|
|
|
|
## Scope
|
|
|
|
- Remove `Firmware.vm` from `crates/console/prometeu-firmware/src/firmware/firmware.rs` if all callsites have migrated.
|
|
- Remove `PrometeuContext.vm` from `crates/console/prometeu-firmware/src/firmware/prometeu_context.rs`.
|
|
- Remove `legacy_vm` from `SessionsFacade::load_vm_cartridge`.
|
|
- Remove `initialize_legacy_active_vm`.
|
|
- Remove or narrow global `VmFacade::initialize`, `tick`, `reset`, and `debug_step_instruction` methods that operate on caller-supplied `VirtualMachine`.
|
|
- Keep global render ownership, render worker lifecycle, telemetry publication, and log service where they are global SystemOS responsibilities.
|
|
- Preserve Hub/Home rendering behavior while avoiding any guest VM state stored in firmware.
|
|
- Update direct boot, debug boot, reset, and load-cartridge tests to prove session ownership is the only app VM path.
|
|
|
|
## Non-Goals
|
|
|
|
- Do not remove `VirtualMachineRuntime` itself.
|
|
- Do not redesign render worker ownership.
|
|
- Do not add background execution.
|
|
- Do not change debugger protocol shape beyond the PLN-0154 migration.
|
|
|
|
## Execution Method
|
|
|
|
1. Use `rg` to list every remaining `firmware.vm`, `ctx.vm`, `legacy_vm`, and `os.vm().initialize/tick/reset/debug_step_instruction` callsite.
|
|
2. Replace firmware context construction so state steps receive `SystemOS`, Hub, signals, platform, and boot target only.
|
|
3. Replace reset behavior with session registry/runtime reset semantics:
|
|
- clear VM sessions on firmware reset when booting fresh;
|
|
- preserve only explicitly resident sessions during lifecycle flows, not reset.
|
|
4. Update cartridge loading to initialize only the selected VM session.
|
|
5. Split `VmFacade` into:
|
|
- session-targeted VM execution/inspection methods;
|
|
- global render/runtime authority methods.
|
|
6. Delete compatibility methods that accept `&mut VirtualMachine` when no remaining production callsite exists.
|
|
7. Add tests or assertions proving no production code path initializes or ticks a global firmware VM.
|
|
8. Run full affected test suites and clippy.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- `Firmware` no longer owns `pub vm: VirtualMachine`.
|
|
- `PrometeuContext` no longer carries a VM reference.
|
|
- `LoadCartridgeStep` initializes only session-owned VM context.
|
|
- `GameRunningStep` and VM-backed `ShellRunningStep` tick only sessions.
|
|
- Debugger, stats, and host runner access active session state or global render services explicitly.
|
|
- `rg "firmware\\.vm|ctx\\.vm|legacy_vm|os\\.vm\\(\\)\\.initialize\\(|os\\.vm\\(\\)\\.tick\\("` finds no production runtime dependency on the legacy global VM path.
|
|
- Tests continue to prove Game resident + VM Shell coexistence.
|
|
|
|
## 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 or update tests for:
|
|
- reset clears session-owned VM contexts appropriately;
|
|
- direct boot creates session-owned VM context;
|
|
- debug boot uses session-owned VM context;
|
|
- no global VM tick path remains.
|
|
|
|
## Affected Artifacts
|
|
|
|
- `crates/console/prometeu-firmware/src/firmware/firmware.rs`
|
|
- `crates/console/prometeu-firmware/src/firmware/prometeu_context.rs`
|
|
- `crates/console/prometeu-firmware/src/firmware/firmware_step_*.rs`
|
|
- `crates/console/prometeu-system/src/os/facades/sessions.rs`
|
|
- `crates/console/prometeu-system/src/os/facades/vm.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`
|