prometeu-runtime/discussion/workflow/plans/PLN-0138-specify-foreground-pause-and-home-contract.md

id	ticket	title	status	created	ref_decisions	tags
PLN-0138	foreground-stack-game-pause-shell-vm-backed	Specify Foreground Pause and Home Contract	done	2026-07-03	DEC-0037	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.