VM Context Ownership for Resident Game and VM-Backed Shell
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good

This commit is contained in:
2026-07-05 00:36:15 +01:00
parent c34bbaf936
commit 6dc8cb5372
27 changed files with 147 additions and 3008 deletions
@@ -1,191 +0,0 @@
---
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`.
@@ -1,199 +0,0 @@
---
id: DEC-0038
ticket: foreground-stack-game-pause-shell-vm-backed
title: VM Session Ownership for VM-Backed Processes
status: accepted
created: 2026-07-04
ref_agenda: AGD-0046
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
---
## Status
Open for review.
## Contexto
`DEC-0037` established the foreground stack and Game pause contract for
`Game -> Home/Shell -> same Game`. It requires a suspended resident Game to stop
receiving normal gameplay ticks, input, and frame pacing while remaining
resident for later resume.
The current implementation works for native Shell apps because native Shell
apps do not use the VM. It does not fully support VM-backed Shell coexistence:
`Firmware` owns a single global `VirtualMachine` (`Firmware.vm`), so loading a
VM-backed Shell can overwrite the suspended Game context that should remain
resident.
`AGD-0046` closes this gap by separating VM execution context ownership from
foreground ownership. A foreground owner decides who receives visual/input
authority. A VM execution context decides where PC, stack, heap, globals,
handles, cartridge identity, lifecycle delivery state, and VM-scoped runtime
state live.
## Decisao
PROMETEU MUST make VM execution context session-owned for VM-backed processes.
Every VM-backed process MUST have its own `VmSession` or equivalent
session-owned context. A VM-backed Game and a VM-backed Shell MUST NOT share the
same mutable `VirtualMachine` instance, stack, heap, PC, globals, open handles,
cartridge identity, or VM-scoped lifecycle state.
`Firmware.vm` MUST NOT remain the canonical owner of all VM-backed app context.
Firmware MAY continue to orchestrate macro states such as loading, Home, Shell,
and GameRunning, but it MUST delegate VM session creation, activation, lookup,
and ticking to SystemOS/session services.
For v1, the system MAY still enforce:
- at most one resident Game;
- at most one foreground Shell;
- no Game-to-Game switching;
- no general background execution.
Those restrictions MUST NOT be implemented by relying on a single global VM
context. They must be expressed as lifecycle/session policy.
Each VM-backed Shell MUST receive its own VM session. If future Shell
persistence allows more than one Shell app to remain in memory, each retained
VM-backed Shell MUST still have distinct mutable VM context.
A suspended resident Game MUST preserve its VM session. Suspension means the
session is not eligible for normal foreground ticks, normal Game input, or
normal frame pacing. It does not mean serializing, deleting, or overwriting the
VM context.
Foreground ownership and execution eligibility MUST be separate concepts:
- foreground ownership controls visual owner, primary input, render ownership,
and normal foreground frame pacing;
- execution eligibility controls which sessions may receive ticks or restricted
callbacks while not foreground.
Background execution, including music players or background services, is out of
scope for the first implementation of this decision. However, the session model
MUST be compatible with adding background-capable scheduling soon. The initial
model MUST NOT bake in assumptions that only the foreground session can ever be
eligible to execute.
Render ownership MUST remain a global SystemOS authority. VM sessions may
produce render submissions, but they MUST NOT decide whether those submissions
can be presented. SystemOS/render ownership policy remains responsible for
active owner, epoch/generation validity, stale submission rejection, and final
publication authority.
`LoadCartridgeStep` MUST stop initializing a global firmware VM directly as the
long-term model. Cartridge load/activation MUST be delegated to a sessions or
VM-session facade that can create a new VM session, activate an existing VM
session, or reject an unsupported transition according to lifecycle policy.
## Rationale
The foreground stack is already task/process-oriented. VM execution context must
follow the same ownership model. Otherwise the system can mark a Game as
resident and suspended while the only real VM context has already been reused
for a Shell.
Session ownership solves the actual coexistence problem without requiring VM
snapshot/restore. A suspended Game is simply a live session that is not scheduled
for normal ticks. A VM-backed Shell is another session with its own mutable
state.
Keeping background execution out of the first implementation avoids expanding
this work into a general scheduler. At the same time, making execution
eligibility separate from foreground ownership prevents an immediate future
background audio/player feature from requiring another foundational refactor.
Keeping render ownership global preserves the contract from `DEC-0037` and the
render ownership model from `DSC-0040`: sessions can generate frames, but only
the current foreground/render owner can publish valid current-epoch output.
## Invariantes / Contrato
- VM-backed mutable execution state is owned by a VM session, not by a global
firmware VM.
- A VM-backed Game and VM-backed Shell never share mutable VM context.
- A suspended resident Game retains its VM session.
- Suspension prevents normal foreground Game ticks/input/frame pacing; it does
not destroy or overwrite VM state.
- Native Shell apps do not require VM sessions.
- VM-backed Shell apps always require VM sessions.
- Each VM-backed Shell gets its own mutable VM session.
- Foreground ownership and execution eligibility are distinct.
- General background execution is out of scope for the initial implementation,
but the model must support adding it without replacing session ownership.
- SystemOS remains lifecycle and render ownership authority.
- Render ownership and stale frame rejection remain global policy, not per-VM
session policy.
- Cartridge load/activation must go through session services rather than
initializing one global firmware VM.
- V1 restrictions on one resident Game and one foreground Shell remain policy,
not a consequence of single-VM storage.
## Impactos
- **Runtime / SystemOS:** add a VM session model or equivalent service that
stores VM-backed process execution context and maps it to task/process
lifecycle.
- **Firmware:** remove `Firmware.vm` as the canonical VM context owner for all
apps. Firmware should request session creation/activation/tick from SystemOS.
- **VM:** support multiple distinct `VirtualMachine` instances or equivalent
isolated VM contexts in one OS lifetime.
- **Lifecycle:** task/process states must control session scheduling
eligibility without conflating foreground ownership with future background
execution.
- **Hub / Shell:** VM-backed Shell load must create or activate a Shell VM
session without overwriting a resident Game session.
- **Game:** Game pause/suspend/resume must preserve the Game VM session and
deliver lifecycle events to that session.
- **Renderer:** render manager stays global and validates ownership/epoch for
submissions produced by sessions.
- **FS / Memcard / Assets:** mutable handles and per-app runtime handles must
be evaluated for session scoping. Durable memcard/app data can remain keyed by
`app_id`; open handles and staging state should not accidentally leak across
sessions.
- **Tests:** add coverage proving VM-backed Shell creation does not overwrite a
suspended Game session, and that only eligible sessions tick.
## Alternativas Descartadas
- **Keep one global firmware VM and block VM-backed Shell when a Game is
resident:** rejected because it leaves `DEC-0037` incomplete and creates
divergent Shell behavior.
- **Serialize/snapshot the Game VM on suspension:** rejected because snapshot
correctness is harder than needed for v1 and would include VM, handles,
render state, assets, and side effects.
- **Hard-code two VM slots (`game_vm`, `shell_vm`):** rejected as a permanent
model because it encodes a short-term limit as architecture. It may only be
acceptable as an internal stepping stone if represented through the same
session abstraction.
- **Treat background-capable apps as hidden foreground owners:** rejected
because it would violate foreground ownership semantics and make render/input
authority ambiguous.
## Referencias
- Source agenda: `AGD-0046`
- Foreground stack and Game pause contract: `DEC-0037`
- Runtime mode separation: `DSC-0031`
- SystemOS lifecycle/process/task authority: `DSC-0032`
- VM render parallel execution boundary: `DSC-0040`
- Future Game-to-Game switching: `DSC-0043`
## Propagacao Necessaria
- Add implementation plans for introducing VM sessions and moving VM context
out of `Firmware`.
- Add implementation plans for separating VM-scoped runtime state from global
SystemOS/render state.
- Update runtime/firmware specs to describe session-owned VM context and the
distinction between foreground ownership and execution eligibility.
- Update tests for Game resident suspension, VM-backed Shell creation, and
session isolation.
- Keep future background execution as out of scope for first implementation,
but document that the model must support background-capable scheduling.
## Revision Log
- 2026-07-04: Initial decision draft from `AGD-0046`.