VM Context Ownership for Resident Game and VM-Backed Shell
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
This commit is contained in:
@@ -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`.
|
||||
-199
@@ -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`.
|
||||
Reference in New Issue
Block a user