105 lines
3.9 KiB
Markdown
105 lines
3.9 KiB
Markdown
---
|
|
id: PLN-0141
|
|
ticket: foreground-stack-game-pause-shell-vm-backed
|
|
title: Integrate Render Audio and Input Pause Boundaries
|
|
status: done
|
|
created: 2026-07-03
|
|
ref_decisions: [DEC-0037]
|
|
tags: [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.
|