115 lines
4.4 KiB
Markdown
115 lines
4.4 KiB
Markdown
---
|
|
id: PLN-0138
|
|
ticket: foreground-stack-game-pause-shell-vm-backed
|
|
title: Specify Foreground Pause and Home Contract
|
|
status: done
|
|
created: 2026-07-03
|
|
ref_decisions: [DEC-0037]
|
|
tags: [runtime, specs, lifecycle, input, renderer, foreground]
|
|
---
|
|
|
|
## Briefing
|
|
|
|
`DEC-0037` establishes the v1 foreground stack contract: one foreground visual
|
|
owner, one resident Game, one foreground Shell, Hub as root, Game-visible
|
|
pause/resume, OS-owned suspension, desktop `Esc` as Home/SystemOS request, and
|
|
render epoch invalidation across foreground transitions.
|
|
|
|
This plan updates the canonical runtime specs before implementation so code
|
|
plans cannot drift into guest-owned Home input, background execution, or stale
|
|
frame presentation.
|
|
|
|
## Decisions of Origin
|
|
|
|
- `DEC-0037` - Foreground Stack and Game Pause Contract.
|
|
|
|
## Target
|
|
|
|
Document the foreground, pause/suspend, Home request, input, audio, and render
|
|
ownership contract in the canonical runtime specs.
|
|
|
|
## Scope
|
|
|
|
- Update `docs/specs/runtime/12-firmware-pos-and-prometeuhub.md` with:
|
|
- Hub as root/special Shell owner;
|
|
- one foreground visual owner;
|
|
- one resident Game;
|
|
- one foreground Shell;
|
|
- `Game -> Home/Shell -> same Game` lifecycle;
|
|
- VM-backed Shell app return-to-Hub behavior.
|
|
- Update `docs/specs/runtime/06-input-peripheral.md` with:
|
|
- Home/SystemOS as host/system control, not pad input;
|
|
- desktop `Esc` as primary Home request;
|
|
- physical `Home` key as optional alias;
|
|
- input clear/barrier requirements across Game pause/resume.
|
|
- Update `docs/specs/runtime/09-events-and-concurrency.md` with:
|
|
- pause notification budget;
|
|
- OS-owned suspension after the budget;
|
|
- resume/foreground-restore notification before visual return.
|
|
- Update `docs/specs/runtime/14-boot-profiles.md` only to clarify that this
|
|
foreground contract is not Game-to-Game switching and does not change direct
|
|
`--run` or `--games-root` boot semantics.
|
|
- Update renderer-related spec text in the most local existing runtime spec if
|
|
present, otherwise add a short subsection to `12-firmware-pos-and-prometeuhub.md`
|
|
describing ownership epoch invalidation and first-valid-frame gating.
|
|
|
|
## Out of Scope
|
|
|
|
- No Rust implementation.
|
|
- No new guest ABI or pad button.
|
|
- No background execution policy.
|
|
- No Game A -> Home -> Game B switching.
|
|
- No memory eviction policy for resident Games.
|
|
|
|
## Execution Plan
|
|
|
|
1. Edit `12-firmware-pos-and-prometeuhub.md`.
|
|
Define foreground owner cardinality, Hub root ownership, Shell foreground
|
|
behavior, Game resident/suspended behavior, return-to-Hub from Shell, and the
|
|
requirement to keep Hub/Shell visible until a resumed Game submits a valid
|
|
current-epoch frame.
|
|
|
|
2. Edit `06-input-peripheral.md`.
|
|
State that Home/SystemOS is outside the guest-visible pad and input
|
|
intrinsic surface. Document desktop `Esc` as the primary host mapping and
|
|
physical `Home` as an optional alias.
|
|
|
|
3. Edit `09-events-and-concurrency.md`.
|
|
Add the pause/resume event ordering: Home request, pause notification,
|
|
bounded reaction budget, OS suspension, resume/foreground-restore
|
|
notification, first-valid-frame visual return.
|
|
|
|
4. Edit `14-boot-profiles.md`.
|
|
Cross-reference the foreground contract and explicitly keep direct boot,
|
|
games-root Home launch, and future Game-to-Game switching separate.
|
|
|
|
5. Run text checks.
|
|
Search for wording that implies Home is a guest input button, a guest ABI, or
|
|
background execution. Replace misleading text with the `DEC-0037` contract.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- Specs define `Paused` as Game-visible and `Suspended` as OS-owned.
|
|
- Specs state that desktop `Esc` is the primary Home request and is not guest
|
|
pad input.
|
|
- Specs state that the Game receives pause/resume notifications but does not
|
|
control OS suspension.
|
|
- Specs state that Hub is the root Shell owner and Shell app close returns to
|
|
Hub in v1.
|
|
- Specs state that visual return to Game waits for a valid current-epoch render
|
|
submission.
|
|
- Specs explicitly exclude background execution and Game-to-Game switching.
|
|
|
|
## Tests / Validation
|
|
|
|
- Run `discussion validate`.
|
|
- Run `rg -n "Home|Esc|Suspended|Paused|foreground|background execution" docs/specs/runtime`.
|
|
- Verify no edited spec describes Home/SystemOS as a guest-visible pad button.
|
|
|
|
## Risks
|
|
|
|
- The spec could accidentally reopen Game-to-Game switching; keep that scoped to
|
|
`DSC-0043 / AGD-0044`.
|
|
- The input spec could confuse physical keyboard mapping with VM input; keep
|
|
host/system controls outside the guest input surface.
|