prometeu-runtime/discussion/workflow/decisions/DEC-0037-foreground-stack-and-game-pause-contract.md

id	ticket	title	status	created	ref_agenda	tags
DEC-0037	foreground-stack-game-pause-shell-vm-backed	Foreground Stack and Game Pause Contract	accepted	2026-07-03	AGD-0041	runtime os lifecycle shell game vm foreground architecture

Status

Accepted.

Contexto

AGD-0041 defines the minimum lifecycle contract for Game -> Home/Shell -> same Game.

The issue is not only rendering. The render worker needs a single valid visual owner, but SystemOS must decide which VMs may exist, which owner receives input, which owner may tick, what happens to a Game when Home takes foreground, and how a VM-backed Shell app coexists with a paused Game.

This decision builds on:

• DSC-0031: runtime mode separation between Game and System/Shell;
• DSC-0032: SystemOS lifecycle/process/task authority;
• DSC-0035: task-owned Shell windows and Shell liveness;
• DSC-0036: Hub/Shell as a lifecycle proving surface;
• DSC-0040: render ownership/epoch and stale submission invalidation.

Decisao

PROMETEU MUST use a single-foreground-owner model for v1.

At most one Game MAY be resident at a time. At most one Shell app MAY be the foreground visual owner at a time.

The Hub MUST be treated as the root/special Shell owner for Home. A VM-backed Shell app MAY replace the Hub as the foreground visual owner, but the Hub remains the root/back-stack controller. In v1, closing a VM-backed Shell app MUST return to Hub/Home, not directly to the Game.

When the user requests Home while a Game is running, SystemOS MUST start a cooperative pause transition:

• the Game receives a pause lifecycle notification;
• the Game is given a short bounded budget to react;
• after that budget, SystemOS MAY suspend the Game VM even if the Game did not cooperate;
• the Game remains resident but MUST NOT receive normal gameplay ticks, normal game input, or frame pacing while suspended;
• the Shell/Hub foreground owner MAY execute according to Shell lifecycle rules.

Paused is the Game-visible lifecycle state/event. Suspended is the OS/scheduler operational state. A Game may observe pause/resume, but it MUST NOT control whether the OS suspends or resumes its VM.

When returning to the same Game, SystemOS MUST reactivate the Game VM and send a resume or foreground-restore lifecycle notification before restoring visual foreground. The Game MAY remain internally paused while it synchronizes. The system MUST keep Hub/Shell visible until the resumed Game produces a valid new render submission for the current ownership epoch.

Input pending for the Game MUST be drained or cleared across pause/resume boundaries. Game audio MUST pause with the Game VM in v1. Independent background audio policy is out of scope.

Render ownership MUST move with the foreground owner. Foreground transitions MUST invalidate stale render submissions through ownership epoch/generation so old Game frames cannot be presented after Shell takes foreground, and old Shell frames cannot be presented after the Game resumes.

On the desktop host, Esc MUST be the primary keyboard request for Home/SystemOS. The physical Home key MAY be supported as an alias. This Home request is a host/SystemOS control action and MUST NOT be exposed as a normal guest pad button or userland input capability.

Real background execution, multiple resident Games, multiple foreground Shells, Game-to-Game switching, Shell app persistence policy, memory eviction policy, and rich multitasking are out of scope for this decision.

Rationale

The chosen model preserves the expected console-like flow: a Game can be paused, Home can run, Shell apps can open, and the same Game can resume without turning the runtime into a general multitasking scheduler.

Separating Paused from Suspended keeps authority clear. Paused is the contract the Game can observe and react to. Suspended is the OS mechanism that prevents the paused Game from continuing to consume ticks, input, audio, and render ownership while another owner is foreground.

Keeping Hub as root/back-stack prevents VM-backed Shell apps from becoming independent lifecycle roots. Returning to Hub before resuming Game keeps v1 navigation deterministic and leaves more complex direct-return behavior for a future decision.

Keeping Hub/Shell visible until the Game submits a new valid frame avoids presenting stale pixels from the previous Game epoch. This aligns lifecycle state with the render ownership model from DSC-0040.

Using Esc as desktop Home makes the control available on compact keyboards. Supporting the physical Home key as an alias is acceptable, but the portable contract cannot depend on it.

Invariantes / Contrato

• There is exactly one foreground visual owner at a time.
• V1 supports at most one resident Game.
• V1 supports at most one foreground Shell app.
• Hub/Home is the root Shell owner and back-stack controller.
• VM-backed Shell apps follow Shell lifecycle, not Game loop lifecycle.
• A paused Game may remain resident, but a suspended Game does not receive normal gameplay ticks, normal game input, or frame pacing.
• Pause/resume are cooperative Game-visible lifecycle events.
• Suspend/resume scheduling authority belongs to SystemOS.
• SystemOS may suspend a Game after the pause budget even if the Game does not cooperate.
• Input is cleared or barriered across Game pause/resume boundaries.
• Game audio pauses with the Game VM in v1.
• Foreground transitions advance render ownership epoch/generation.
• Visual foreground returns to Game only after a valid current-epoch Game render submission exists.
• Desktop Esc is a host/SystemOS Home request; physical Home may alias it.
• Home/SystemOS is not a guest pad button and is not userland input.
• Background execution and general multitasking are explicitly excluded.

Impactos

• Spec: runtime lifecycle, firmware/Hub, input, and render ownership specs must document foreground ownership, pause/suspend semantics, Home key mapping, and stale frame invalidation.
• Runtime / SystemOS: SystemOS needs explicit foreground owner, Hub root, Shell foreground, Game paused, and Game suspended state.
• VM: VM execution must support pause/resume lifecycle delivery and OS-owned suspension of ticks.
• Firmware: firmware should observe macro transitions such as GameRunning, Hub/Home, Shell foreground, pause request, and resume request without owning every internal OS detail.
• Host: host must route desktop Esc and optional physical Home to a SystemOS Home request instead of guest pad input.
• Input: Game input must be drained or barriered during pause/resume and Home/SystemOS must stay outside the guest-visible pad ABI.
• Audio: v1 audio follows Game pause/suspend and does not continue as independent background audio.
• Renderer: render publication must reject stale submissions after ownership epoch changes and keep previous foreground visible until the resumed Game publishes a valid current-epoch frame.
• Tests: coverage must prove pause budget behavior, non-foreground VM non-execution, input clearing, host Home routing, Shell return-to-Hub, and stale render rejection.

Alternativas Descartadas

• Terminate Game when entering Shell: rejected because it makes Game -> Shell -> Game a reload rather than a pause/resume flow.
• Real background execution now: rejected because it pulls in scheduler, budget, energy, audio, input, IO, memory, and persistence policy beyond v1.
• Multiple resident Games: rejected for v1 because Game-to-Game switching is owned by DSC-0043 / AGD-0044.
• Expose Home as guest input: rejected because Home changes system foreground authority and must not be handled as ordinary game input.
• Return directly from Shell app to Game in v1: rejected to keep Hub as the deterministic root/back-stack owner.

Referencias

• Source agenda: AGD-0041
• Runtime mode separation: DSC-0031
• SystemOS lifecycle authority: DSC-0032
• Shell task/window lifecycle: DSC-0035
• Hub UI direction: DSC-0036
• Render ownership and stale submission handling: DSC-0040
• Future Game A -> Home -> Game B switching: DSC-0043 / AGD-0044

Propagacao Necessaria

• Update canonical runtime specs for foreground ownership and pause/suspend.
• Specify desktop Home request mapping in host/input documentation.
• Add plan(s) for SystemOS foreground stack state and Game pause/suspend.
• Add plan(s) for VM lifecycle event delivery and forced suspension budget.
• Add plan(s) for host Esc/Home routing outside guest pad input.
• Add plan(s) for render epoch integration during Game/Shell transitions.
• Add tests covering lifecycle, input, host routing, and render publication invariants.

Revision Log

• 2026-07-03: Initial decision from AGD-0041.