Intrepid/prometeu-runtime
Intrepid/prometeu-runtime
4
0
Fork 0
Code Pull Requests Activity
prometeu-runtime/discussion/workflow/plans/PLN-0155-retire-legacy-firmware-vm-runtime-bridge.md

4.5 KiB
Raw Blame History

id ticket title status created ref_decisions tags
PLN-0155 foreground-stack-game-pause-shell-vm-backed Retire Legacy Firmware VM Runtime Bridge open 2026-07-05
DEC-0038
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