192 lines
8.7 KiB
Markdown
192 lines
8.7 KiB
Markdown
---
|
|
id: DEC-0037
|
|
ticket: foreground-stack-game-pause-shell-vm-backed
|
|
title: Foreground Stack and Game Pause Contract
|
|
status: accepted
|
|
created: 2026-07-03
|
|
ref_agenda: AGD-0041
|
|
tags: [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`.
|