prometeu-runtime/discussion/workflow/plans/PLN-0141-integrate-render-audio-and-input-pause-boundaries.md

id	ticket	title	status	created	ref_decisions	tags
PLN-0141	foreground-stack-game-pause-shell-vm-backed	Integrate Render Audio and Input Pause Boundaries	done	2026-07-03	DEC-0037	runtime renderer audio input foreground lifecycle

Briefing

DEC-0037 requires foreground transitions to invalidate stale render submissions, keep Hub/Shell visible until the resumed Game publishes a valid current-epoch frame, clear or barrier Game input across pause/resume, and pause Game audio with the Game VM in v1.

This plan integrates those boundary effects after SystemOS foreground state and Game pause/resume mechanics exist.

Decisions of Origin

• DEC-0037 - Foreground Stack and Game Pause Contract.

Target

Make foreground transitions safe at the render, input, and audio boundaries.

Scope

• Advance render ownership epoch/generation whenever foreground owner changes.
• Discard stale Game frames after Shell/Hub takes foreground.
• Discard stale Shell frames after Game resumes.
• Keep Hub/Shell visible until a resumed Game publishes a valid current-epoch submission.
• Clear or barrier Game input across pause/resume boundaries.
• Pause Game audio with the Game VM in v1.
• Add telemetry/tests for stale discards and first-valid-frame gating.

Out of Scope

• No independent background audio policy.
• No overlay rendering policy.
• No Game-to-Game switch rendering.
• No full memory eviction behavior.

Execution Plan

1. Extend render ownership transition calls. Update crates/console/prometeu-system/src/services/vm_runtime/render_manager.rs and call sites in tick.rs so foreground owner changes explicitly advance ownership epoch/generation, not only app mode/app id changes.

2. Add foreground restore gating. Add state in SystemOS or firmware that records when visual return to Game is pending. The state must remain in Hub/Shell presentation until a current-epoch Game submission is observed.

3. Update host presentation selection. Update crates/host/prometeu-host-desktop-winit/src/runner.rs if necessary so should_present_worker_frame and fallback framebuffer presentation obey the foreground restore gate.

4. Add stale discard coverage. Extend render manager and render worker tests to prove stale submissions from the previous owner are discarded after epoch change.

5. Add input boundary clearing. Add a SystemOS or firmware input barrier when Game pause starts and when Game resume starts. The barrier must prevent held or pressed Game input from leaking across the lifecycle boundary.

6. Add audio pause integration. Ensure Game pause/suspend produces the existing host audio pause command path or a new explicit lifecycle audio pause signal. Keep this separate from debugger pause if the observable cause matters in tests.

7. Add tests. Cover stale frame discard, first-valid-frame visual return, input clearing, and Game audio pause/resume behavior.

Acceptance Criteria

• Foreground owner changes advance render ownership epoch/generation.
• Old Game frames cannot present after Hub/Shell takes foreground.
• Old Hub/Shell frames cannot present after Game resumes.
• Visual return to Game waits for a valid current-epoch Game submission.
• Game input does not leak across pause/resume boundaries.
• Game audio pauses with Game suspension in v1.

Tests / Validation

• Run cargo test -p prometeu-system render foreground.
• Run cargo test -p prometeu-firmware pause.
• Run cargo test -p prometeu-host-desktop-winit presentation.
• Run discussion validate.

Risks

• Existing render epoch logic may already key off app mode/app id. Foreground owner changes must be explicit so Shell/Hub and resumed Game cannot share a stale epoch by accident.
• Audio pause currently follows VM paused/debugger state in the host. Keep Game lifecycle pause distinct enough that tests can prove the decision contract.