128 lines
5.2 KiB
Markdown
128 lines
5.2 KiB
Markdown
---
|
|
id: PLN-0142
|
|
ticket: foreground-stack-game-pause-shell-vm-backed
|
|
title: Deliver Game Lifecycle Events To VM Runtime
|
|
status: done
|
|
created: 2026-07-04
|
|
ref_decisions: [DEC-0037]
|
|
tags: [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`
|