---
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.