Foreground Stack, Game Pause, and VM-Backed Shell Coexistence

This commit is contained in:
2026-07-03 22:52:08 +01:00
parent 4bc9ce2b73
commit 126bffa37d
21 changed files with 1023 additions and 1347 deletions
@@ -1,136 +0,0 @@
---
id: DEC-0035
ticket: system-run-cart
title: Remove Userland system.run_cart and Preserve Direct Boot
status: accepted
created: 2026-07-03
ref_agenda: AGD-0003
tags: []
---
## Status
Accepted.
## Contexto
`system.run_cart` existe na ABI publica, mas nao possui comportamento real de
troca de cartucho. Isso cria uma falsa promessa: um guest pode declarar/chamar
uma operacao que aparenta iniciar outro cartucho, enquanto o runtime retorna
sucesso vazio ou nao executa uma transicao completa.
A discussao fechou tres separacoes:
- boot direto por host/CLI/debug e necessario e deve permanecer;
- apps/userland nao devem iniciar cartuchos diretamente;
- troca `Game A -> Home -> Game B` exige um orquestrador de SystemOS proprio,
separado em `DSC-0043 / AGD-0044`.
`AGD-0041` permanece responsavel por `Game -> Home -> mesmo Game`, foreground,
pausa/suspensao e retorno ao mesmo Game.
## Decisao
`system.run_cart` MUST be removed from the userland guest ABI.
No app, cartridge, Shell app, or other userland guest code MAY directly request
cartridge boot through `system.run_cart`.
The platform MUST NOT preserve compatibility for the current userland
`system.run_cart` surface. It MUST NOT remain as a callable stub, reserved
guest syscall that returns success, or capability-gated userland escape hatch.
Direct boot MUST remain supported through host/CLI/debug or equivalent
single-game launch paths. This direct boot path is a host/system entrypoint,
not a guest syscall.
Internal cartridge loading MAY continue to use the existing loader path,
including directory cartridges and test fixtures. `.pmc` support is not required
by this decision.
If apps ever need to request navigation in the future, that MUST be designed as
a separate SystemOS-mediated surface with different naming and semantics. It
MUST NOT reintroduce userland `run_cart` as direct cartridge boot.
## Rationale
Direct cartridge boot is essential for development, debugging, automated tests,
and future distribution modes where the runtime launches as a single game. That
use case does not require a guest-visible syscall.
Userland cartridge boot would give app code authority over system navigation,
lifecycle, cleanup, target resolution, and failure policy. Those concerns belong
to SystemOS/firmware and later to the cartridge switch orchestrator, not to a VM
guest syscall.
Keeping a stub or compatibility surface would preserve the current ambiguity.
The public ABI should not advertise an operation that either does nothing or
looks like direct app-controlled navigation.
## Invariantes / Contrato
- Guest/userland MUST NOT expose or call `system.run_cart`.
- The public syscall registry, declarations, generated bindings, and docs MUST
stop presenting `system.run_cart` as an app-callable operation.
- Booting a cartridge directly MUST remain available from host/CLI/debug flows.
- Direct boot MUST enter the runtime with a selected cartridge target; it MUST
NOT depend on a guest syscall issued after VM startup.
- Loader code MAY remain reusable by host/firmware/SystemOS internals.
- Loader code MUST NOT become lifecycle orchestration authority.
- `Game -> Home -> same Game` remains owned by `AGD-0041`.
- `Game A -> Home -> Game B` remains owned by `DSC-0043 / AGD-0044`.
- `.pmc`, app catalog, launcher UX, marketplace/distribution, and full cartridge
replacement under Home are outside this decision.
## Impactos
- **Spec / ABI:** remove or retire `system.run_cart` from the userland syscall
surface. Any syscall table, PBS declarations, generated metadata, or docs
must stop advertising it to apps.
- **Runtime / VM:** guest dispatch must no longer treat `system.run_cart` as a
valid userland operation. If obsolete bytecode or declarations still reach the
runtime during migration, they must fail explicitly rather than report success.
- **Firmware / Host:** direct boot remains supported for command-line,
debugger, test harness, and future single-game launch flows.
- **SystemOS:** no new cart-switch orchestrator is required by this decision.
That work is deferred to `DSC-0043 / AGD-0044`.
- **Tooling:** tools must continue to support direct cartridge launch for
development and test workflows, without relying on a guest syscall.
- **Tests:** coverage must prove both sides: userland cannot declare/call
`system.run_cart`, and direct boot of a cartridge still works.
## Alternativas Descartadas
- **Implement `system.run_cart` as a normal syscall:** rejected because it gives
userland direct navigation authority and mixes guest execution with system
lifecycle.
- **Keep a compatibility stub:** rejected because no compatibility is required
and a stub preserves the false contract.
- **Make `system.run_cart` privileged but still guest-visible:** rejected for v1
because it keeps the ambiguous idea that some guest profile may directly boot
cartuchos.
- **Implement full `Home -> another Game` now:** rejected for this decision; it
requires SystemOS orchestration after the `AGD-0041` foreground contract.
## Referencias
- Agenda: `AGD-0003`
- Foreground/pause scope: `AGD-0041`
- Future cartridge switch orchestrator: `DSC-0043 / AGD-0044`
- Related lessons: `LSN-0041` SystemOS lifecycle authority, `LSN-0042`
SystemOS service ownership boundary, `LSN-0043` SystemOS domain facades.
## Propagacao Necessaria
- Remove `SystemRunCart` from userland ABI declarations and generated syscall
metadata.
- Remove or rewrite runtime dispatch paths that return success for
`system.run_cart`.
- Preserve host/CLI/debug direct boot paths and add regression tests for them.
- Add negative tests for guest/userland declaration or call attempts.
- Update any documentation/spec text that describes `system.run_cart` as
app-callable.
## Revision Log
- 2026-07-03: Initial draft from `AGD-0003`.
@@ -1,156 +0,0 @@
---
id: DEC-0036
ticket: system-run-cart
title: SystemOS Games Root and Home Game Launch
status: accepted
created: 2026-07-03
ref_agenda: AGD-0045
tags: []
---
## Status
Accepted.
## Contexto
`DEC-0035` removed `system.run_cart` from the userland guest ABI and preserved
direct host/CLI/debug cartridge boot. That decision intentionally did not
deliver the Home/SO product flow: pointing PROMETEU at a local games directory,
listing available games in Home, and launching a selected game by user action.
This decision defines the first system-owned replacement for userland
`run_cart`: a local games-root library discovered by the host/SystemOS and
exposed through a simple Home UI.
## Decisao
PROMETEU MUST support a host-provided games library root through
`--games-root <dir>`.
The games root is a directory containing game cartridge directories as immediate
children. V1 MUST scan only immediate child directories. Recursive discovery is
out of scope.
The v1 games library MUST include only cartridges whose manifest declares
`app_mode: Game`. Shell/System apps, `.pmc` packages, remote catalogs,
marketplace/distribution metadata, rich icons, search, and non-game apps are out
of scope.
The library MUST produce expandable internal entries, not UI-only summaries.
Each entry MUST retain enough internal data to launch the cartridge and to grow
as a catalog model. At minimum, each entry MUST include:
- loaded manifest data;
- `title`;
- `app_id`;
- `app_version`;
- internal cartridge path;
- operational discovery metadata, including a timestamp or equivalent discovery
marker.
The Home UI v1 SHOULD display only `title`, `app_id`, and `app_version`. It MAY
hide path and operational metadata.
Invalid cartridge candidates MUST be logged and omitted from the Home game list.
Selecting a listed Game in Home MUST immediately request a system-owned launch
through firmware/SystemOS, resulting in `LoadCartridge` for that cartridge. This
MUST NOT use a guest syscall and MUST NOT reintroduce userland `run_cart`.
If launch fails, the machine MUST return to or remain in Home and record an
error/log. A polished error UI is out of scope.
Booting directly with `--run <cart>` MUST remain separate and unchanged.
Returning from a running Game to Home is outside this decision and belongs to
`AGD-0041`. Switching from `Game A -> Home -> Game B` after a game is already
active belongs to `DSC-0043 / AGD-0044`.
## Rationale
The previous `run_cart` surface was wrong because it made cartridge launch look
like an app/userland capability. The desired behavior is still valid, but the
authority must live in the system: Home presents available games and the
firmware/SystemOS loads the selected cartridge.
Using `--games-root` keeps the v1 product model honest: this is a local game
library, not a general app root. Other app types can be introduced later without
forcing the first launcher model to pretend it is a full marketplace.
Immediate child scanning keeps discovery deterministic and testable. `.pmc` and
recursive layouts can be added after the directory-cartridge path is proven.
An expandable entry model avoids prematurely freezing the UI shape as the data
model. The UI is intentionally simple, but the catalog model needs room for
future metadata such as package origin, installation/discovery timestamps, rich
presentation fields, and packaged cartridge details.
## Invariantes / Contrato
- `--games-root <dir>` is the v1 host argument for a local games library.
- The games root is Game-only in v1.
- Discovery scans immediate child directories only.
- Directory candidates without valid Game cartridge metadata are logged and
omitted.
- Library entries are internal catalog records, not direct UI DTOs.
- The UI v1 displays a simple clickable list and may show only `title`,
`app_id`, and `app_version`.
- The internal entry retains cartridge path and loaded manifest data for launch.
- Home selection is a system action that enters firmware/SystemOS loading. It is
not a guest syscall.
- `--run <cart>` direct boot remains independent from `--games-root`.
- Return-to-Home and game-to-game switching are not implemented by this
decision.
## Impactos
- **Host:** add a `--games-root <dir>` argument and pass the resolved root into
runtime/firmware/SystemOS initialization.
- **SystemOS / Hub:** add a local game library model and expose entries to Home.
Home must render a minimal clickable list and emit a system-owned launch
action for a selected entry.
- **Firmware:** consume the Home launch action and transition to
`LoadCartridge` with the selected cartridge path.
- **Loader:** continue to validate complete directory cartridges. Discovery may
read manifest metadata, but full launch still uses the existing loader.
- **Runtime / VM:** no userland ABI is added. No guest syscall participates in
launch.
- **Specs / Docs:** document `--games-root`, Game-only v1 discovery, and the
distinction between direct boot, games library launch, and future game
switching.
- **Tests:** cover discovery, invalid omission/logging, Home action emission,
and the end-to-end path from games root selection to `GameRunning`.
## Alternativas Descartadas
- **List only, no launch:** rejected because it does not satisfy the product
goal of starting games from Home.
- **General app root:** rejected for v1 because Shell/System apps need separate
lifecycle and UI contracts.
- **Recursive discovery:** rejected for v1 to keep semantics deterministic.
- **`.pmc` discovery:** rejected for v1 because packed cartridge loading is a
separate open agenda.
- **Game-to-game switch now:** rejected because it depends on foreground and
cartridge-switch orchestration work in `AGD-0041` and `AGD-0044`.
## Referencias
- Source agenda: `AGD-0045`
- Userland run-cart removal: `DEC-0035`
- Foreground/Home return scope: `AGD-0041`
- Future cartridge switch orchestration: `DSC-0043 / AGD-0044`
## Propagacao Necessaria
- Add or update runtime specs for games-root discovery and Home launch.
- Add host CLI argument plumbing for `--games-root`.
- Add a catalog/library entry model.
- Add Hub/Home list rendering and click handling.
- Add firmware/SystemOS action routing to `LoadCartridge`.
- Add tests for discovery, invalid candidates, action emission, and
`games-root -> Home click -> GameRunning`.
## Revision Log
- 2026-07-03: Initial draft from `AGD-0045`.
@@ -0,0 +1,191 @@
---
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`.