117 lines
4.1 KiB
Markdown
117 lines
4.1 KiB
Markdown
---
|
|
id: PLN-0137
|
|
ticket: foreground-stack-game-pause-shell-vm-backed
|
|
title: Implement SystemOS Foreground Stack State
|
|
status: done
|
|
created: 2026-07-03
|
|
ref_decisions: [DEC-0037]
|
|
tags: [runtime, os, lifecycle, foreground, shell, game]
|
|
---
|
|
|
|
## Briefing
|
|
|
|
`DEC-0037` requires SystemOS to own foreground authority. The system must know
|
|
which owner is foreground, keep Hub/Home as root, allow only one resident Game,
|
|
allow only one foreground Shell, and return from VM-backed Shell apps to Hub in
|
|
v1.
|
|
|
|
This plan implements the SystemOS state model only. It does not yet deliver
|
|
Game pause/resume events, host keyboard routing, or render/audio/input boundary
|
|
changes.
|
|
|
|
## Decisions of Origin
|
|
|
|
- `DEC-0037` - Foreground Stack and Game Pause Contract.
|
|
|
|
## Target
|
|
|
|
Add an explicit SystemOS foreground stack model that can represent Hub, a
|
|
foreground Shell task, and a paused/suspended resident Game.
|
|
|
|
## Scope
|
|
|
|
- Add or extend SystemOS-owned foreground state under
|
|
`crates/console/prometeu-system/src/os/` or
|
|
`crates/console/prometeu-system/src/services/`.
|
|
- Represent v1 foreground owners:
|
|
- Hub/Home root;
|
|
- Shell task foreground;
|
|
- Game foreground;
|
|
- Game paused/suspended resident.
|
|
- Enforce at most one resident Game and at most one foreground Shell.
|
|
- Keep Hub as root/back-stack controller.
|
|
- Ensure Shell close returns to Hub/Home in v1.
|
|
- Expose focused queries through existing or new facades, likely
|
|
`crates/console/prometeu-system/src/os/facades/lifecycle.rs` and
|
|
`crates/console/prometeu-system/src/os/facades/sessions.rs`.
|
|
|
|
## Out of Scope
|
|
|
|
- No VM pause/resume event delivery.
|
|
- No host `Esc`/`Home` keyboard mapping.
|
|
- No render epoch implementation.
|
|
- No Game-to-Game switching.
|
|
- No background execution.
|
|
- No memory eviction for the resident Game.
|
|
|
|
## Execution Plan
|
|
|
|
1. Define foreground model types.
|
|
Add enums/structs for foreground owner and resident Game state in the most
|
|
local SystemOS module. The model must distinguish Game foreground, Game
|
|
paused/suspended, Hub foreground, and Shell task foreground.
|
|
|
|
2. Add SystemOS storage.
|
|
Store the foreground model in `SystemOS` from
|
|
`crates/console/prometeu-system/src/os/system_os.rs` with initialization to
|
|
Hub/Home root.
|
|
|
|
3. Wire lifecycle facade operations.
|
|
Extend lifecycle/session facades so firmware can request:
|
|
- set Game foreground;
|
|
- request Home from Game;
|
|
- set Shell foreground from Hub;
|
|
- close Shell and return to Hub;
|
|
- query current foreground owner;
|
|
- query resident Game task.
|
|
|
|
4. Enforce cardinality.
|
|
Add checks that reject a second resident Game and a second foreground Shell
|
|
with typed lifecycle errors. Use existing `LifecycleError` style or add
|
|
precise variants.
|
|
|
|
5. Integrate existing Shell close behavior.
|
|
Update `crates/console/prometeu-firmware/src/firmware/firmware_step_shell_running.rs`
|
|
only where needed so closing a Shell task routes through the foreground model
|
|
and ends in `FirmwareState::HubHome`.
|
|
|
|
6. Add tests.
|
|
Cover initial Hub foreground, Game foreground registration, Home request
|
|
moving Game to resident paused/suspended state, Shell foreground activation,
|
|
Shell close returning to Hub, and cardinality rejection.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- SystemOS has an explicit foreground owner model.
|
|
- Hub/Home is the initialized root foreground owner.
|
|
- Only one resident Game can exist in v1.
|
|
- Only one Shell task can be foreground in v1.
|
|
- VM-backed Shell close returns to Hub/Home.
|
|
- Foreground queries are available to firmware and later plans.
|
|
- No implementation path enables background execution.
|
|
|
|
## Tests / Validation
|
|
|
|
- Add focused unit tests in `prometeu-system` around the new model and facade.
|
|
- Run `cargo test -p prometeu-system lifecycle foreground`.
|
|
- Run `cargo test -p prometeu-firmware shell`.
|
|
- Run `discussion validate`.
|
|
|
|
## Risks
|
|
|
|
- Existing `TaskState::Foreground` and `TaskState::Suspended` may look like the
|
|
complete model. Do not overload them until foreground ownership and Hub root
|
|
authority are explicit.
|
|
- Shell windows already have focus semantics. Keep window focus as visual/task
|
|
evidence, not the sole source of SystemOS foreground truth.
|