Intrepid/prometeu-runtime
Intrepid/prometeu-runtime
4
0
Fork 0
Code Pull Requests Activity
prometeu-runtime/discussion/workflow/plans/PLN-0140-deliver-game-pause-resume-and-suspension.md
bQUARKz 1b29b2f985
implements PLN-0140
2026-07-03 23:10:03 +01:00

4.2 KiB
Raw Blame History

id ticket title status created ref_decisions tags
PLN-0140 foreground-stack-game-pause-shell-vm-backed Deliver Game Pause Resume and Suspension done 2026-07-03
DEC-0037
runtime
os
vm
lifecycle
pause
suspension

Briefing

DEC-0037 separates Game-visible Paused from OS-owned Suspended. When Home is requested during Game execution, SystemOS must notify the Game, give it a short bounded budget, then suspend the VM even if the Game does not cooperate. When returning, SystemOS must reactivate the VM and send a resume or foreground-restore notification before the visual owner returns to Game.

This plan implements the pause/resume and suspension mechanics after the foreground state model exists.

Decisions of Origin

  • DEC-0037 - Foreground Stack and Game Pause Contract.

Target

Add Game pause/resume lifecycle delivery and OS-enforced VM suspension for the same resident Game.

Scope

  • Add a Game lifecycle event model for pause and resume/foreground-restore.
  • Add a bounded pause reaction budget owned by SystemOS.
  • Suspend the Game VM after the budget even if the Game does not cooperate.
  • Ensure a suspended Game receives no normal gameplay ticks.
  • Reactivate the VM and deliver resume/foreground-restore before Game visual foreground restoration.
  • Integrate with GameRunningStep and VM runtime tick control.

Out of Scope

  • No render first-valid-frame gating; that is in PLN-0141.
  • No host keyboard routing; that is in PLN-0136.
  • No new guest syscall.
  • No background execution.
  • No Game-to-Game switching.

Execution Plan

  1. Add lifecycle event representation. Define pause/resume events in the most local runtime lifecycle module, likely under crates/console/prometeu-system/src/os/lifecycle.rs or a new SystemOS lifecycle submodule. Events must be observable by the VM/runtime path without giving the Game authority over suspension.

  2. Add pause transition state. Extend the foreground state from PLN-0137 with a PauseRequested or equivalent transition state that records the target Game task and the remaining pause budget.

  3. Gate VM ticks. Update crates/console/prometeu-firmware/src/firmware/firmware_step_game_running.rs and crates/console/prometeu-system/src/services/vm_runtime/tick.rs so a suspended Game does not receive normal ticks, normal input, or frame pacing.

  4. Deliver pause notification. Add the mechanism that makes the pause event visible to the running Game before suspension. Use an existing VM event channel if present; otherwise add a narrow lifecycle-event queue owned by SystemOS/VM runtime.

  5. Enforce the budget. Advance the pause budget on firmware ticks. When it expires, transition the Game task/process to suspended through SystemOS lifecycle regardless of Game cooperation.

  6. Deliver resume notification. On return to the resident Game, transition from suspended to resume-requested, reactivate VM execution, deliver resume/foreground-restore, and leave visual restoration to the render boundary plan.

  7. Add tests. Cover cooperative pause, non-cooperative forced suspension, no tick while suspended, resume notification delivery, and no Game-owned ability to cancel OS suspension.

Acceptance Criteria

  • Game receives pause before suspension.
  • SystemOS suspends after a bounded budget even if the Game does not cooperate.
  • Suspended Game does not receive normal gameplay ticks.
  • Resume/foreground-restore is delivered before visual return to Game.
  • Game cannot prevent OS suspension through guest-visible behavior.
  • Existing debugger pause behavior remains distinct from lifecycle suspension.

Tests / Validation

  • Add unit tests in prometeu-system for lifecycle transition state.
  • Add firmware tests around GameRunningStep pause request and suspension.
  • Add VM runtime tests proving suspended state suppresses normal ticks.
  • Run cargo test -p prometeu-system.
  • Run cargo test -p prometeu-firmware.
  • Run discussion validate.

Risks

  • Debugger pause already exists in VM runtime. Keep debug pause separate from lifecycle pause/suspend.
  • A lifecycle event queue could become a general app event system. Keep this plan limited to pause/resume required by DEC-0037.