Intrepid/prometeu-runtime
Intrepid/prometeu-runtime
4
0
Fork 0
Code Pull Requests Activity
prometeu-runtime/discussion/workflow/plans/PLN-0142-deliver-game-lifecycle-events-to-vm-runtime.md

5.2 KiB
Raw Blame History

id ticket title status created ref_decisions tags
PLN-0142 foreground-stack-game-pause-shell-vm-backed Deliver Game Lifecycle Events To VM Runtime open 2026-07-04
DEC-0037
runtime
os
lifecycle
shell
game
vm
foreground
architecture

Briefing

DEC-0037 requires pause/resume to be Game-visible lifecycle events. The current implementation records GameLifecycleEvent values in SystemOS, but no runtime or VM execution path consumes them. Tests currently prove that the OS queue contains events, not that the Game/runtime can observe them before suspension or after resume.

Objective

Deliver Game lifecycle pause/resume events from SystemOS into the VM runtime boundary in a deterministic, testable way, without exposing Home as guest pad input or a userland syscall.

Dependencies

  • Source decision: DEC-0037.
  • Fixes the lifecycle event delivery gap found after PLN-0140 and PLN-0141.
  • PLN-0143 depends on this plan if it needs to prove that the pause event is consumed before the pause budget expires.

Scope

Included:

  • Define the runtime-facing lifecycle event delivery API for Pause and ResumeForeground.
  • Move events from the SystemOS queue into the VM/runtime tick boundary.
  • Make delivered events observable in tests without creating a broad app event system.
  • Preserve the distinction between lifecycle pause and debugger pause.
  • Ensure events are delivered only to the resident Game task they target.

Excluded:

  • No guest Home input, pad field, intrinsic, or syscall.
  • No general userland event bus.
  • No background execution while suspended.
  • No new Shell lifecycle event model.

Non-Goals

  • Do not implement Game-to-Game switching.
  • Do not change renderer ownership policy except where tests need to assert lifecycle event ordering.
  • Do not add wall-clock timers or asynchronous callbacks.

Execution Method

  1. Add a narrow VM runtime lifecycle inbox.

    • What changes: introduce a small data structure for pending/delivered Game lifecycle events in VirtualMachineRuntime.
    • How it changes: add methods such as queue_game_lifecycle_events, take_delivered_game_lifecycle_events, or a more idiomatic local name that preserves deterministic frame-boundary delivery.
    • File(s): crates/console/prometeu-system/src/services/vm_runtime/mod.rs, crates/console/prometeu-system/src/services/vm_runtime/tick.rs, and focused tests under crates/console/prometeu-system/src/services/vm_runtime/.

  2. Route SystemOS events into the VM facade before ticking.

    • What changes: VmFacade::tick must drain lifecycle events from SystemOS and pass only events targeted at the currently running resident Game into the VM runtime lifecycle inbox.
    • How it changes: use the existing LifecycleFacade::take_game_lifecycle_events or replace it with an equivalent internal method if borrowing requires a cleaner API. Do not leave events only observable through pending_game_lifecycle_events.
    • File(s): crates/console/prometeu-system/src/os/facades/vm.rs, crates/console/prometeu-system/src/os/facades/lifecycle.rs.

  3. Expose deterministic test visibility.

    • What changes: tests must be able to assert that Pause and ResumeForeground reached the VM runtime boundary.
    • How it changes: add test-only or public diagnostic accessors on VmFacade/VirtualMachineRuntime for delivered lifecycle events, scoped to lifecycle validation rather than a guest ABI.
    • File(s): crates/console/prometeu-system/src/os/facades/vm.rs, crates/console/prometeu-system/src/services/vm_runtime/tests.rs.

  4. Update firmware tests to assert delivery, not only queue presence.

    • What changes: existing firmware tests that inspect pending_game_lifecycle_events should assert VM-runtime delivery at the tick boundary.
    • How it changes: after a Game pause/resume flow, verify that the VM/runtime observed the lifecycle event in order.
    • File(s): crates/console/prometeu-firmware/src/firmware/firmware.rs.

Acceptance Criteria

  • Pause is moved from SystemOS into the VM runtime boundary before suspension is allowed to complete.
  • ResumeForeground is moved into the VM runtime boundary before the Game is considered visually restored.
  • Tests fail if events remain only in SystemOS.game_lifecycle_events.
  • Lifecycle event delivery does not mutate InputSignals.
  • Debugger pause remains separate from lifecycle pause.

Tests

  • Unit tests in prometeu-system proving VM runtime lifecycle event delivery and drain semantics.
  • Firmware tests proving Home request delivers Pause to the VM/runtime before suspension.
  • Firmware tests proving resident Game resume delivers ResumeForeground before Game foreground restoration.
  • Run cargo test -p prometeu-system.
  • Run cargo test -p prometeu-firmware.
  • Run discussion validate.

Affected Artifacts

  • crates/console/prometeu-system/src/os/facades/vm.rs
  • crates/console/prometeu-system/src/os/facades/lifecycle.rs
  • crates/console/prometeu-system/src/services/vm_runtime/mod.rs
  • crates/console/prometeu-system/src/services/vm_runtime/tick.rs
  • crates/console/prometeu-firmware/src/firmware/firmware.rs