VM Context Ownership for Resident Game and VM-Backed Shell
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
This commit is contained in:
@@ -1,96 +0,0 @@
|
||||
---
|
||||
id: PLN-0136
|
||||
ticket: foreground-stack-game-pause-shell-vm-backed
|
||||
title: Route Desktop Home Key Outside Guest Input
|
||||
status: done
|
||||
created: 2026-07-03
|
||||
ref_decisions: [DEC-0037]
|
||||
tags: [host, input, systemos, keyboard, lifecycle]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
`DEC-0037` makes desktop `Esc` the primary Home/SystemOS request and allows the
|
||||
physical `Home` key as an alias. This request must be intercepted by the
|
||||
host/SystemOS and must not appear as a guest pad button or input intrinsic.
|
||||
|
||||
This plan adds the host input route for the Home request without changing the
|
||||
guest-visible pad surface.
|
||||
|
||||
## Decisions of Origin
|
||||
|
||||
- `DEC-0037` - Foreground Stack and Game Pause Contract.
|
||||
|
||||
## Target
|
||||
|
||||
Route desktop `Esc` and optional physical `Home` key to a SystemOS Home request
|
||||
outside `InputSignals`.
|
||||
|
||||
## Scope
|
||||
|
||||
- Extend `crates/host/prometeu-host-desktop-winit/src/input.rs` or a nearby
|
||||
host input module with a host/system control signal separate from
|
||||
`prometeu_hal::InputSignals`.
|
||||
- Map `KeyCode::Escape` to Home/SystemOS request.
|
||||
- Map `KeyCode::Home` as an alias.
|
||||
- Ensure neither key mutates `start_signal`, `select_signal`, or any pad field.
|
||||
- Route the request through `crates/host/prometeu-host-desktop-winit/src/runner.rs`
|
||||
into firmware/SystemOS.
|
||||
- Add tests proving `Esc` and `Home` do not affect guest pad state.
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- No pause/resume lifecycle implementation.
|
||||
- No render ownership gating.
|
||||
- No guest-visible Home button.
|
||||
- No gamepad hardware Home mapping unless a future plan defines controller
|
||||
system controls separately.
|
||||
|
||||
## Execution Plan
|
||||
|
||||
1. Define host control state.
|
||||
Add a small host-only type such as `HostSystemControls` with a
|
||||
`home_requested` edge or event. Store it in `HostInputHandler` or in the
|
||||
runner next to the existing input handler.
|
||||
|
||||
2. Update keyboard handling.
|
||||
In `HostInputHandler::handle_event`, recognize `KeyCode::Escape` and
|
||||
`KeyCode::Home` on press. Set the host control event and return without
|
||||
modifying `InputSignals`.
|
||||
|
||||
3. Preserve pad mapping.
|
||||
Keep existing pad mappings unchanged:
|
||||
arrows, `A/D/W/S`, `Q/E`, `Z`, and Shift. Do not reuse `Start` or `Select`
|
||||
for Home.
|
||||
|
||||
4. Route to firmware/SystemOS.
|
||||
In `crates/host/prometeu-host-desktop-winit/src/runner.rs`, consume the
|
||||
host Home event before or during `about_to_wait` and call the firmware or
|
||||
SystemOS method introduced by `PLN-0137` / `PLN-0140`.
|
||||
|
||||
5. Add tests.
|
||||
Add host input tests for `Esc`, physical `Home`, and existing pad mappings.
|
||||
Tests must prove Home produces a system event and no guest pad mutation.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- Pressing desktop `Esc` emits a Home/SystemOS host control event.
|
||||
- Pressing physical `Home` emits the same event.
|
||||
- Neither key affects `InputSignals`.
|
||||
- Existing guest pad keyboard mappings still work.
|
||||
- The runner consumes the Home request as a system action.
|
||||
- The implementation does not add a guest syscall, intrinsic, or pad button.
|
||||
|
||||
## Tests / Validation
|
||||
|
||||
- Add unit tests in `prometeu-host-desktop-winit` for host input mapping.
|
||||
- Run `cargo test -p prometeu-host-desktop-winit input`.
|
||||
- Run `cargo test -p prometeu-hal input` if pad signal behavior changes.
|
||||
- Run `discussion validate`.
|
||||
|
||||
## Risks
|
||||
|
||||
- `Esc` may conflict with debugger or window-close expectations. Keep debugger
|
||||
start handling on `D` unchanged and do not map `Esc` to process exit.
|
||||
- Physical `Home` is not available on every keyboard, so it must remain an
|
||||
alias rather than the primary portable mapping.
|
||||
@@ -1,116 +0,0 @@
|
||||
---
|
||||
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.
|
||||
@@ -1,114 +0,0 @@
|
||||
---
|
||||
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.
|
||||
@@ -1,106 +0,0 @@
|
||||
---
|
||||
id: PLN-0139
|
||||
ticket: foreground-stack-game-pause-shell-vm-backed
|
||||
title: Validate Game Home Shell Game End To End
|
||||
status: done
|
||||
created: 2026-07-03
|
||||
ref_decisions: [DEC-0037]
|
||||
tags: [runtime, validation, firmware, host, lifecycle]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
`DEC-0037` is not complete until the product flow is proven end to end:
|
||||
a Game runs, the user requests Home, the Game is paused/suspended, Hub or a
|
||||
VM-backed Shell takes foreground, closing Shell returns to Hub, and the same
|
||||
Game can resume only after a valid current-epoch frame exists.
|
||||
|
||||
This plan adds final validation after the spec, SystemOS, VM, host input, and
|
||||
render/audio/input boundary plans are implemented.
|
||||
|
||||
## Decisions of Origin
|
||||
|
||||
- `DEC-0037` - Foreground Stack and Game Pause Contract.
|
||||
|
||||
## Target
|
||||
|
||||
Prove the complete `Game -> Home/Shell -> same Game` lifecycle and prevent
|
||||
regressions around guest input, foreground authority, and stale rendering.
|
||||
|
||||
## Scope
|
||||
|
||||
- Add integration-style tests for:
|
||||
- Game running to Home request;
|
||||
- pause notification and forced suspension;
|
||||
- Hub foreground while Game is resident;
|
||||
- VM-backed Shell foreground while Game is suspended;
|
||||
- Shell close returning to Hub;
|
||||
- resume request returning to same Game;
|
||||
- first-valid-frame visual restore;
|
||||
- host `Esc`/`Home` not entering guest input.
|
||||
- Add manual smoke instructions for desktop host.
|
||||
- Confirm direct `--run` and games-root Home launch remain separate.
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- No new implementation beyond tests and developer-facing validation notes.
|
||||
- No Game A -> Home -> Game B switching.
|
||||
- No performance tuning.
|
||||
- No polished UI.
|
||||
|
||||
## Execution Plan
|
||||
|
||||
1. Add firmware/SystemOS integration tests.
|
||||
Use the most stable existing seams in `crates/console/prometeu-firmware/src/firmware/firmware.rs`
|
||||
and `crates/console/prometeu-system` tests to drive Game foreground, Home
|
||||
request, Shell foreground, Shell close, and Game resume.
|
||||
|
||||
2. Add host input integration tests.
|
||||
Ensure `Esc` and physical `Home` create a host Home event and do not mutate
|
||||
guest `InputSignals`.
|
||||
|
||||
3. Add render publication validation.
|
||||
Assert stale submissions from the pre-pause Game epoch are rejected after
|
||||
Home takes foreground and that the Game is not visually restored until a new
|
||||
current-epoch submission exists.
|
||||
|
||||
4. Add audio/input boundary validation.
|
||||
Assert Game input is cleared or barriered across pause/resume. Assert Game
|
||||
audio pause follows Game suspension.
|
||||
|
||||
5. Add direct boot and games-root regression checks.
|
||||
Ensure direct `--run <cart>` remains independent from Home request handling
|
||||
and that games-root Home launch still enters the Game path.
|
||||
|
||||
6. Document manual smoke commands.
|
||||
Add or update developer-facing spec text with release-mode commands:
|
||||
- `cargo run --release -p prometeu-host-desktop-winit -- --run test-cartridges/stress-console`
|
||||
- `cargo run --release -p prometeu-host-desktop-winit -- --games-root test-cartridges`
|
||||
Include the expected `Esc -> Home -> Shell -> Hub -> resume Game` behavior
|
||||
once implemented.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- Automated tests cover `Game -> Home -> same Game`.
|
||||
- Automated tests cover `Game -> Home -> Shell -> Hub -> same Game`.
|
||||
- Tests prove Home request is host/SystemOS control, not guest pad input.
|
||||
- Tests prove suspended Game does not tick.
|
||||
- Tests prove stale render submissions are not presented.
|
||||
- Tests prove visual return waits for a current-epoch Game frame.
|
||||
- Direct `--run` and games-root Home launch regressions pass.
|
||||
|
||||
## Tests / Validation
|
||||
|
||||
- Run `cargo test -p prometeu-system`.
|
||||
- Run `cargo test -p prometeu-firmware`.
|
||||
- Run `cargo test -p prometeu-host-desktop-winit`.
|
||||
- Run any targeted render worker tests affected by ownership epoch changes.
|
||||
- Run `discussion validate`.
|
||||
|
||||
## Risks
|
||||
|
||||
- The current test seams may not expose enough host-driven lifecycle behavior.
|
||||
If needed, add narrow test-only helpers rather than testing through sleeps or
|
||||
real-time window loops.
|
||||
- End-to-end validation can become flaky if it depends on wall-clock timing.
|
||||
Use deterministic ticks and explicit state transitions.
|
||||
@@ -1,110 +0,0 @@
|
||||
---
|
||||
id: PLN-0140
|
||||
ticket: foreground-stack-game-pause-shell-vm-backed
|
||||
title: Deliver Game Pause Resume and Suspension
|
||||
status: done
|
||||
created: 2026-07-03
|
||||
ref_decisions: [DEC-0037]
|
||||
tags: [runtime, os, vm, lifecycle, pause, suspension]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
`DEC-0037` separates Game-visible `Paused` from OS-owned `Suspended`. When Home
|
||||
is requested during Game execution, SystemOS must notify the Game, give it a
|
||||
short bounded budget, then suspend the VM even if the Game does not cooperate.
|
||||
When returning, SystemOS must reactivate the VM and send a resume or
|
||||
foreground-restore notification before the visual owner returns to Game.
|
||||
|
||||
This plan implements the pause/resume and suspension mechanics after the
|
||||
foreground state model exists.
|
||||
|
||||
## Decisions of Origin
|
||||
|
||||
- `DEC-0037` - Foreground Stack and Game Pause Contract.
|
||||
|
||||
## Target
|
||||
|
||||
Add Game pause/resume lifecycle delivery and OS-enforced VM suspension for the
|
||||
same resident Game.
|
||||
|
||||
## Scope
|
||||
|
||||
- Add a Game lifecycle event model for pause and resume/foreground-restore.
|
||||
- Add a bounded pause reaction budget owned by SystemOS.
|
||||
- Suspend the Game VM after the budget even if the Game does not cooperate.
|
||||
- Ensure a suspended Game receives no normal gameplay ticks.
|
||||
- Reactivate the VM and deliver resume/foreground-restore before Game visual
|
||||
foreground restoration.
|
||||
- Integrate with `GameRunningStep` and VM runtime tick control.
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- No render first-valid-frame gating; that is in `PLN-0141`.
|
||||
- No host keyboard routing; that is in `PLN-0136`.
|
||||
- No new guest syscall.
|
||||
- No background execution.
|
||||
- No Game-to-Game switching.
|
||||
|
||||
## Execution Plan
|
||||
|
||||
1. Add lifecycle event representation.
|
||||
Define pause/resume events in the most local runtime lifecycle module,
|
||||
likely under `crates/console/prometeu-system/src/os/lifecycle.rs` or a new
|
||||
SystemOS lifecycle submodule. Events must be observable by the VM/runtime
|
||||
path without giving the Game authority over suspension.
|
||||
|
||||
2. Add pause transition state.
|
||||
Extend the foreground state from `PLN-0137` with a `PauseRequested` or
|
||||
equivalent transition state that records the target Game task and the
|
||||
remaining pause budget.
|
||||
|
||||
3. Gate VM ticks.
|
||||
Update `crates/console/prometeu-firmware/src/firmware/firmware_step_game_running.rs`
|
||||
and `crates/console/prometeu-system/src/services/vm_runtime/tick.rs` so a
|
||||
suspended Game does not receive normal ticks, normal input, or frame pacing.
|
||||
|
||||
4. Deliver pause notification.
|
||||
Add the mechanism that makes the pause event visible to the running Game
|
||||
before suspension. Use an existing VM event channel if present; otherwise add
|
||||
a narrow lifecycle-event queue owned by SystemOS/VM runtime.
|
||||
|
||||
5. Enforce the budget.
|
||||
Advance the pause budget on firmware ticks. When it expires, transition the
|
||||
Game task/process to suspended through SystemOS lifecycle regardless of Game
|
||||
cooperation.
|
||||
|
||||
6. Deliver resume notification.
|
||||
On return to the resident Game, transition from suspended to resume-requested,
|
||||
reactivate VM execution, deliver resume/foreground-restore, and leave visual
|
||||
restoration to the render boundary plan.
|
||||
|
||||
7. Add tests.
|
||||
Cover cooperative pause, non-cooperative forced suspension, no tick while
|
||||
suspended, resume notification delivery, and no Game-owned ability to cancel
|
||||
OS suspension.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- Game receives pause before suspension.
|
||||
- SystemOS suspends after a bounded budget even if the Game does not cooperate.
|
||||
- Suspended Game does not receive normal gameplay ticks.
|
||||
- Resume/foreground-restore is delivered before visual return to Game.
|
||||
- Game cannot prevent OS suspension through guest-visible behavior.
|
||||
- Existing debugger pause behavior remains distinct from lifecycle suspension.
|
||||
|
||||
## Tests / Validation
|
||||
|
||||
- Add unit tests in `prometeu-system` for lifecycle transition state.
|
||||
- Add firmware tests around `GameRunningStep` pause request and suspension.
|
||||
- Add VM runtime tests proving suspended state suppresses normal ticks.
|
||||
- Run `cargo test -p prometeu-system`.
|
||||
- Run `cargo test -p prometeu-firmware`.
|
||||
- Run `discussion validate`.
|
||||
|
||||
## Risks
|
||||
|
||||
- Debugger pause already exists in VM runtime. Keep debug pause separate from
|
||||
lifecycle pause/suspend.
|
||||
- A lifecycle event queue could become a general app event system. Keep this
|
||||
plan limited to pause/resume required by `DEC-0037`.
|
||||
-104
@@ -1,104 +0,0 @@
|
||||
---
|
||||
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.
|
||||
@@ -1,127 +0,0 @@
|
||||
---
|
||||
id: PLN-0142
|
||||
ticket: foreground-stack-game-pause-shell-vm-backed
|
||||
title: Deliver Game Lifecycle Events To VM Runtime
|
||||
status: done
|
||||
created: 2026-07-04
|
||||
ref_decisions: [DEC-0037]
|
||||
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
`DEC-0037` requires pause/resume to be Game-visible lifecycle events. The
|
||||
current implementation records `GameLifecycleEvent` values in SystemOS, but no
|
||||
runtime or VM execution path consumes them. Tests currently prove that the OS
|
||||
queue contains events, not that the Game/runtime can observe them before
|
||||
suspension or after resume.
|
||||
|
||||
## Objective
|
||||
|
||||
Deliver Game lifecycle pause/resume events from SystemOS into the VM runtime
|
||||
boundary in a deterministic, testable way, without exposing Home as guest pad
|
||||
input or a userland syscall.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Source decision: `DEC-0037`.
|
||||
- Fixes the lifecycle event delivery gap found after `PLN-0140` and
|
||||
`PLN-0141`.
|
||||
- `PLN-0143` depends on this plan if it needs to prove that the pause event is
|
||||
consumed before the pause budget expires.
|
||||
|
||||
## Scope
|
||||
|
||||
Included:
|
||||
|
||||
- Define the runtime-facing lifecycle event delivery API for `Pause` and
|
||||
`ResumeForeground`.
|
||||
- Move events from the SystemOS queue into the VM/runtime tick boundary.
|
||||
- Make delivered events observable in tests without creating a broad app event
|
||||
system.
|
||||
- Preserve the distinction between lifecycle pause and debugger pause.
|
||||
- Ensure events are delivered only to the resident Game task they target.
|
||||
|
||||
Excluded:
|
||||
|
||||
- No guest Home input, pad field, intrinsic, or syscall.
|
||||
- No general userland event bus.
|
||||
- No background execution while suspended.
|
||||
- No new Shell lifecycle event model.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Do not implement Game-to-Game switching.
|
||||
- Do not change renderer ownership policy except where tests need to assert
|
||||
lifecycle event ordering.
|
||||
- Do not add wall-clock timers or asynchronous callbacks.
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Add a narrow VM runtime lifecycle inbox.
|
||||
- What changes: introduce a small data structure for pending/delivered Game
|
||||
lifecycle events in `VirtualMachineRuntime`.
|
||||
- How it changes: add methods such as `queue_game_lifecycle_events`,
|
||||
`take_delivered_game_lifecycle_events`, or a more idiomatic local name
|
||||
that preserves deterministic frame-boundary delivery.
|
||||
- File(s): `crates/console/prometeu-system/src/services/vm_runtime/mod.rs`,
|
||||
`crates/console/prometeu-system/src/services/vm_runtime/tick.rs`, and
|
||||
focused tests under `crates/console/prometeu-system/src/services/vm_runtime/`.
|
||||
|
||||
2. Route SystemOS events into the VM facade before ticking.
|
||||
- What changes: `VmFacade::tick` must drain lifecycle events from SystemOS
|
||||
and pass only events targeted at the currently running resident Game into
|
||||
the VM runtime lifecycle inbox.
|
||||
- How it changes: use the existing `LifecycleFacade::take_game_lifecycle_events`
|
||||
or replace it with an equivalent internal method if borrowing requires a
|
||||
cleaner API. Do not leave events only observable through
|
||||
`pending_game_lifecycle_events`.
|
||||
- File(s): `crates/console/prometeu-system/src/os/facades/vm.rs`,
|
||||
`crates/console/prometeu-system/src/os/facades/lifecycle.rs`.
|
||||
|
||||
3. Expose deterministic test visibility.
|
||||
- What changes: tests must be able to assert that `Pause` and
|
||||
`ResumeForeground` reached the VM runtime boundary.
|
||||
- How it changes: add test-only or public diagnostic accessors on
|
||||
`VmFacade`/`VirtualMachineRuntime` for delivered lifecycle events, scoped
|
||||
to lifecycle validation rather than a guest ABI.
|
||||
- File(s): `crates/console/prometeu-system/src/os/facades/vm.rs`,
|
||||
`crates/console/prometeu-system/src/services/vm_runtime/tests.rs`.
|
||||
|
||||
4. Update firmware tests to assert delivery, not only queue presence.
|
||||
- What changes: existing firmware tests that inspect
|
||||
`pending_game_lifecycle_events` should assert VM-runtime delivery at the
|
||||
tick boundary.
|
||||
- How it changes: after a Game pause/resume flow, verify that the VM/runtime
|
||||
observed the lifecycle event in order.
|
||||
- File(s): `crates/console/prometeu-firmware/src/firmware/firmware.rs`.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] `Pause` is moved from SystemOS into the VM runtime boundary before
|
||||
suspension is allowed to complete.
|
||||
- [ ] `ResumeForeground` is moved into the VM runtime boundary before the Game
|
||||
is considered visually restored.
|
||||
- [ ] Tests fail if events remain only in `SystemOS.game_lifecycle_events`.
|
||||
- [ ] Lifecycle event delivery does not mutate `InputSignals`.
|
||||
- [ ] Debugger pause remains separate from lifecycle pause.
|
||||
|
||||
## Tests
|
||||
|
||||
- Unit tests in `prometeu-system` proving VM runtime lifecycle event delivery
|
||||
and drain semantics.
|
||||
- Firmware tests proving Home request delivers `Pause` to the VM/runtime before
|
||||
suspension.
|
||||
- Firmware tests proving resident Game resume delivers `ResumeForeground`
|
||||
before Game foreground restoration.
|
||||
- Run `cargo test -p prometeu-system`.
|
||||
- Run `cargo test -p prometeu-firmware`.
|
||||
- Run `discussion validate`.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `crates/console/prometeu-system/src/os/facades/vm.rs`
|
||||
- `crates/console/prometeu-system/src/os/facades/lifecycle.rs`
|
||||
- `crates/console/prometeu-system/src/services/vm_runtime/mod.rs`
|
||||
- `crates/console/prometeu-system/src/services/vm_runtime/tick.rs`
|
||||
- `crates/console/prometeu-firmware/src/firmware/firmware.rs`
|
||||
-122
@@ -1,122 +0,0 @@
|
||||
---
|
||||
id: PLN-0143
|
||||
ticket: foreground-stack-game-pause-shell-vm-backed
|
||||
title: Guarantee Cooperative Pause Budget Tick Before Suspension
|
||||
status: done
|
||||
created: 2026-07-04
|
||||
ref_decisions: [DEC-0037]
|
||||
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
`DEC-0037` requires a Game-visible `Paused` event followed by a bounded
|
||||
cooperative reaction budget before SystemOS imposes `Suspended`. The current
|
||||
implementation uses a one-tick budget and advances it before `vm.tick` in
|
||||
`GameRunningStep`, so the Game can be suspended without any runtime tick in
|
||||
which it could observe or react to pause.
|
||||
|
||||
## Objective
|
||||
|
||||
Guarantee at least one deterministic VM/runtime delivery point for the Game to
|
||||
observe pause before forced suspension, while preserving SystemOS authority to
|
||||
suspend the Game after the budget.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Source decision: `DEC-0037`.
|
||||
- Should be executed after or together with `PLN-0142`, because budget tests
|
||||
must prove delivered lifecycle events, not only queued OS events.
|
||||
|
||||
## Scope
|
||||
|
||||
Included:
|
||||
|
||||
- Fix pause budget ordering so the pause budget cannot expire before the VM
|
||||
runtime has a delivery point for `Pause`.
|
||||
- Define the budget in deterministic machine ticks/frames, not wall-clock time.
|
||||
- Ensure a Game receives no normal gameplay ticks after it reaches
|
||||
`PausedSuspended`.
|
||||
- Preserve the existing forced-suspension authority when the budget expires.
|
||||
- Update tests that currently assert no VM tick occurs immediately after Home.
|
||||
|
||||
Excluded:
|
||||
|
||||
- No guest-controlled cancellation of suspension.
|
||||
- No background execution after suspension.
|
||||
- No extension of the pause budget based on host timing.
|
||||
- No direct visual-return behavior; render restore gating remains covered by
|
||||
the existing render boundary work.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Do not add a general scheduler.
|
||||
- Do not make pause cooperation mandatory for suspension.
|
||||
- Do not conflate lifecycle pause with debugger pause.
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Redefine pause budget state transitions.
|
||||
- What changes: `ResidentGameState::PauseRequested` must represent a state
|
||||
in which one or more delivery ticks remain before `PausedSuspended`.
|
||||
- How it changes: adjust `ForegroundStack::advance_pause_budget` or split it
|
||||
into explicit methods such as `mark_pause_delivered` and
|
||||
`advance_pause_budget_after_delivery`.
|
||||
- File(s): `crates/console/prometeu-system/src/services/foreground.rs`.
|
||||
|
||||
2. Move budget advancement after lifecycle delivery.
|
||||
- What changes: `GameRunningStep::on_update` must not suspend before the VM
|
||||
runtime has a chance to receive and process the pause lifecycle event.
|
||||
- How it changes: reorder the GameRunning update so the event delivery path
|
||||
runs first, then the budget is advanced, and only a subsequent eligible
|
||||
boundary can force suspension.
|
||||
- File(s): `crates/console/prometeu-firmware/src/firmware/firmware_step_game_running.rs`,
|
||||
`crates/console/prometeu-system/src/os/facades/vm.rs`.
|
||||
|
||||
3. Preserve no-tick-after-suspended behavior.
|
||||
- What changes: once `ResidentGameState::PausedSuspended` and
|
||||
`TaskState::Suspended` are reached, the Game must not receive normal ticks,
|
||||
normal input, or frame pacing.
|
||||
- How it changes: keep the existing early transition to Hub after suspension
|
||||
expires, but ensure it occurs after the cooperative pause window rather
|
||||
than before it.
|
||||
- File(s): `crates/console/prometeu-firmware/src/firmware/firmware_step_game_running.rs`.
|
||||
|
||||
4. Update tests to match the corrected semantics.
|
||||
- What changes: tests must stop asserting that the first tick after Home does
|
||||
zero VM work purely because Home was requested.
|
||||
- How it changes: assert that the pause event was delivered during the
|
||||
cooperative window, then assert that a later deterministic tick forces
|
||||
suspension and no further Game ticks occur.
|
||||
- File(s): `crates/console/prometeu-firmware/src/firmware/firmware.rs`,
|
||||
`crates/console/prometeu-system/src/os/system_os.rs`.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] A Game receives a deterministic pause delivery point before SystemOS
|
||||
suspends it.
|
||||
- [ ] SystemOS still suspends the Game after the bounded budget even if the
|
||||
Game does not cooperate.
|
||||
- [ ] A suspended Game receives no normal gameplay ticks, normal Game input, or
|
||||
frame pacing.
|
||||
- [ ] Tests prove the order: Home request -> pause delivery -> budget expiry ->
|
||||
suspension.
|
||||
- [ ] Debugger pause behavior is unchanged.
|
||||
|
||||
## Tests
|
||||
|
||||
- Unit tests in `prometeu-system` for pause budget transitions.
|
||||
- Firmware tests for non-cooperative forced suspension after at least one
|
||||
delivered pause boundary.
|
||||
- Regression tests proving suspended Game tick count does not advance.
|
||||
- Run `cargo test -p prometeu-system foreground lifecycle`.
|
||||
- Run `cargo test -p prometeu-firmware pause`.
|
||||
- Run `discussion validate`.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `crates/console/prometeu-system/src/services/foreground.rs`
|
||||
- `crates/console/prometeu-system/src/os/facades/lifecycle.rs`
|
||||
- `crates/console/prometeu-system/src/os/facades/vm.rs`
|
||||
- `crates/console/prometeu-firmware/src/firmware/firmware_step_game_running.rs`
|
||||
- `crates/console/prometeu-firmware/src/firmware/firmware.rs`
|
||||
-124
@@ -1,124 +0,0 @@
|
||||
---
|
||||
id: PLN-0144
|
||||
ticket: foreground-stack-game-pause-shell-vm-backed
|
||||
title: Suspend Resident Game When Shell Takes Foreground
|
||||
status: done
|
||||
created: 2026-07-04
|
||||
ref_decisions: [DEC-0037]
|
||||
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
`DEC-0037` says a suspended resident Game must not receive normal gameplay
|
||||
ticks, normal Game input, or frame pacing while Hub/Shell owns foreground. The
|
||||
current `set_shell_foreground` path can mark the resident Game as
|
||||
`PausedSuspended` in the foreground stack while `TaskManager::set_foreground`
|
||||
only demotes the previous foreground Game task to `Background`. This creates a
|
||||
state mismatch if a Shell is opened while the Game has not already gone through
|
||||
the Home suspension path.
|
||||
|
||||
## Objective
|
||||
|
||||
Make Shell foreground acquisition either require an already suspended resident
|
||||
Game or perform the necessary OS-owned suspension consistently across
|
||||
foreground stack, task manager, and process manager.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Source decision: `DEC-0037`.
|
||||
- Can be implemented independently of `PLN-0142` and `PLN-0143`, but tests
|
||||
should be rerun with those fixes if they are executed first.
|
||||
|
||||
## Scope
|
||||
|
||||
Included:
|
||||
|
||||
- Close the mismatch between `ResidentGameState::PausedSuspended` and
|
||||
`TaskState::Background`.
|
||||
- Ensure Shell foreground cannot leave a resident Game running or backgrounded.
|
||||
- Cover both `create_vm_shell_task` and `create_native_shell_task` paths.
|
||||
- Preserve the rule that only one foreground Shell may exist.
|
||||
- Keep the normal Home -> Shell flow working.
|
||||
|
||||
Excluded:
|
||||
|
||||
- No direct Shell -> Game return behavior; v1 still returns Shell close to Hub.
|
||||
- No background Game execution.
|
||||
- No multiple resident Games.
|
||||
- No Shell persistence policy changes.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Do not broaden Shell lifecycle semantics.
|
||||
- Do not implement Game-to-Game switching.
|
||||
- Do not add UI controls for resume.
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Define the legal Shell foreground precondition.
|
||||
- What changes: decide in code whether Shell foreground requires the
|
||||
resident Game to already be `PausedSuspended`, or whether
|
||||
`set_shell_foreground_task` is responsible for suspending it.
|
||||
- How it changes: prefer centralizing the invariant in
|
||||
`LifecycleFacade::set_shell_foreground_task`, because it owns task/process
|
||||
transitions.
|
||||
- File(s): `crates/console/prometeu-system/src/os/facades/lifecycle.rs`,
|
||||
`crates/console/prometeu-system/src/services/foreground.rs`.
|
||||
|
||||
2. Synchronize task/process state when Shell takes foreground.
|
||||
- What changes: if a resident Game exists and is not already suspended,
|
||||
mark the Game task and process `Suspended` before or during Shell
|
||||
foreground transition.
|
||||
- How it changes: use `process_id_for_task` for the resident Game and call
|
||||
`task_manager.mark_suspended` and `process_manager.mark_suspended` in the
|
||||
same lifecycle operation that sets Shell foreground.
|
||||
- File(s): `crates/console/prometeu-system/src/os/facades/lifecycle.rs`.
|
||||
|
||||
3. Tighten foreground stack behavior.
|
||||
- What changes: `ForegroundStack::set_shell_foreground` must not silently
|
||||
hide invalid state transitions.
|
||||
- How it changes: either reject Shell foreground when the resident Game is
|
||||
still `Foreground`/`PauseRequested`, or return enough information for the
|
||||
lifecycle facade to suspend the resident Game explicitly.
|
||||
- File(s): `crates/console/prometeu-system/src/services/foreground.rs`.
|
||||
|
||||
4. Add regression tests for reachable session paths.
|
||||
- What changes: create tests that call `create_vm_shell_task` and
|
||||
`create_native_shell_task` while a Game task is foreground.
|
||||
- How it changes: assert foreground owner is Shell, resident Game remains
|
||||
recorded, Game task state is `Suspended`, and Game process state is
|
||||
`Suspended`.
|
||||
- File(s): `crates/console/prometeu-system/src/os/system_os.rs`,
|
||||
`crates/console/prometeu-firmware/src/firmware/firmware.rs` if the
|
||||
firmware Home/Shell path needs coverage.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] A Shell foreground transition cannot leave the resident Game in
|
||||
`TaskState::Background`.
|
||||
- [ ] Foreground stack state, task state, and process state agree that the
|
||||
resident Game is suspended while Shell is foreground.
|
||||
- [ ] `create_vm_shell_task` and `create_native_shell_task` both preserve the
|
||||
invariant.
|
||||
- [ ] Opening a second foreground Shell remains rejected.
|
||||
- [ ] Closing Shell still returns to Hub/Home, not directly to Game.
|
||||
|
||||
## Tests
|
||||
|
||||
- Unit tests in `prometeu-system` for `set_shell_foreground_task` with a
|
||||
resident foreground Game.
|
||||
- Session facade tests for VM Shell and native Shell creation while a Game is
|
||||
resident.
|
||||
- Existing firmware Shell close tests must continue to pass.
|
||||
- Run `cargo test -p prometeu-system foreground lifecycle shell`.
|
||||
- Run `cargo test -p prometeu-firmware shell`.
|
||||
- Run `discussion validate`.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `crates/console/prometeu-system/src/services/foreground.rs`
|
||||
- `crates/console/prometeu-system/src/os/facades/lifecycle.rs`
|
||||
- `crates/console/prometeu-system/src/os/facades/sessions.rs`
|
||||
- `crates/console/prometeu-system/src/os/system_os.rs`
|
||||
- `crates/console/prometeu-firmware/src/firmware/firmware.rs`
|
||||
@@ -1,149 +0,0 @@
|
||||
---
|
||||
id: PLN-0145
|
||||
ticket: foreground-stack-game-pause-shell-vm-backed
|
||||
title: Centralize Resident Game Resume Transition
|
||||
status: done
|
||||
created: 2026-07-04
|
||||
ref_decisions: [DEC-0037]
|
||||
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
`DEC-0037` requires returning to the same resident Game to reactivate the Game
|
||||
VM, restore render ownership, send a resume/foreground lifecycle notification,
|
||||
and clear or barrier pending Game input. That transition currently exists in
|
||||
more than one firmware path: `Firmware::resume_resident_game_from_home` and the
|
||||
Hub library click path that resumes the selected resident Game by `app_id`.
|
||||
|
||||
The behavior is correct, but the duplication is fragile. Any future change to
|
||||
resume ordering, input barriers, render ownership, or lifecycle event delivery
|
||||
could fix one path while leaving the other path stale.
|
||||
|
||||
## Objective
|
||||
|
||||
Create one firmware-owned resident Game resume helper and route every
|
||||
Home/Hub-to-Game resume path through it.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Source decision: `DEC-0037`.
|
||||
- Depends on the accepted v1 identity rule that `app_id` is unique for all
|
||||
games and may be used to decide whether a Hub game selection refers to the
|
||||
current resident Game.
|
||||
- Should preserve the behavior introduced by `PLN-0142`, `PLN-0143`, and
|
||||
`PLN-0144`.
|
||||
|
||||
## Scope
|
||||
|
||||
Included:
|
||||
|
||||
- Centralize resident Game resume orchestration in `Firmware`.
|
||||
- Preserve resume lifecycle event queuing through `LifecycleFacade::resume_task`.
|
||||
- Preserve render ownership transition back to `AppMode::Game`.
|
||||
- Preserve input barrier behavior across all Home/Hub-to-Game resume paths.
|
||||
- Preserve the Hub rule that selecting the same resident Game resumes it, while
|
||||
selecting a different Game remains blocked by v1 scope.
|
||||
- Keep tests proving same-task resume, lifecycle event delivery, and input
|
||||
barriering.
|
||||
|
||||
Excluded:
|
||||
|
||||
- No Game-to-Game switching.
|
||||
- No multiple resident Games.
|
||||
- No change to `app_id` uniqueness policy.
|
||||
- No direct Shell-to-Game close behavior.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Do not move foreground authority from SystemOS into firmware.
|
||||
- Do not change pause budget or suspend behavior.
|
||||
- Do not add UI affordances beyond the existing Hub game row selection.
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Introduce a single resident Game resume helper.
|
||||
- What changes: create a private firmware method that performs the complete
|
||||
resident Game resume operation and returns the target `TaskId` or a typed
|
||||
failure.
|
||||
- How it changes: move the shared sequence currently duplicated across
|
||||
`resume_resident_game_from_home` and `HubHomeStep`: read resident task,
|
||||
call `LifecycleFacade::resume_task`, transition VM render ownership to
|
||||
`AppMode::Game`, install `GameRunningStep`, clear state initialization,
|
||||
and arm the input barrier.
|
||||
- File(s): `crates/console/prometeu-firmware/src/firmware/firmware.rs`.
|
||||
|
||||
2. Route explicit resume through the helper.
|
||||
- What changes: `Firmware::resume_resident_game_from_home` becomes a thin
|
||||
wrapper around the centralized helper.
|
||||
- How it changes: preserve its public `bool` return contract for existing
|
||||
tests and call sites.
|
||||
- File(s): `crates/console/prometeu-firmware/src/firmware/firmware.rs`.
|
||||
|
||||
3. Route Hub same-game selection through the helper.
|
||||
- What changes: `HubHomeStep` must no longer hand-roll resume task, render
|
||||
ownership, and input clearing.
|
||||
- How it changes: expose a state transition request that lets the firmware
|
||||
perform the centralized helper, or restructure the Hub action handling so
|
||||
the parent `Firmware` owns this transition. Keep `HubHomeStep` responsible
|
||||
only for recognizing that the selected cartridge matches the resident
|
||||
`app_id`.
|
||||
- File(s): `crates/console/prometeu-firmware/src/firmware/firmware.rs`,
|
||||
`crates/console/prometeu-firmware/src/firmware/firmware_step_hub_home.rs`,
|
||||
`crates/console/prometeu-firmware/src/firmware/firmware_state.rs` if a new
|
||||
transition variant is needed.
|
||||
|
||||
4. Keep different-game launch blocked under v1.
|
||||
- What changes: selecting a different `app_id` while a resident Game exists
|
||||
continues to log and remain in Hub.
|
||||
- How it changes: keep the existing warning behavior, but ensure it does not
|
||||
duplicate resume side effects.
|
||||
- File(s): `crates/console/prometeu-firmware/src/firmware/firmware_step_hub_home.rs`.
|
||||
|
||||
5. Update regression tests.
|
||||
- What changes: tests should prove both explicit resume and Hub same-game
|
||||
selection use the same observable transition.
|
||||
- How it changes: assert same `TaskId`, foreground owner restored to Game,
|
||||
pending resume lifecycle event exists before the next Game tick, delivered
|
||||
resume event after the Game tick, and input barrier suppresses held input.
|
||||
- File(s): `crates/console/prometeu-firmware/src/firmware/firmware.rs`.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] There is exactly one implementation of the resident Game resume sequence.
|
||||
- [ ] `Firmware::resume_resident_game_from_home` preserves its external
|
||||
behavior.
|
||||
- [ ] Hub selection of the same resident Game resumes the existing `TaskId`
|
||||
without creating or loading a new Game task.
|
||||
- [ ] The resume path always queues and delivers the Game lifecycle
|
||||
`ResumeForeground` event.
|
||||
- [ ] The resume path always barriers held Game input.
|
||||
- [ ] Selecting a different Game while one Game is resident remains blocked in
|
||||
v1.
|
||||
|
||||
## Tests
|
||||
|
||||
- Unit/integration tests in `prometeu-firmware` for explicit resume from Home.
|
||||
- Unit/integration tests in `prometeu-firmware` for Hub same-game selection
|
||||
after Home suspension.
|
||||
- Regression assertion that held input does not leak into the Game immediately
|
||||
after resume.
|
||||
- Run `cargo test -p prometeu-firmware resident_game_resume`.
|
||||
- Run `cargo test -p prometeu-firmware hub_home_clicking_resident_game`.
|
||||
- Run `cargo test -p prometeu-system`.
|
||||
- Run `discussion validate`.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `crates/console/prometeu-firmware/src/firmware/firmware.rs`
|
||||
- `crates/console/prometeu-firmware/src/firmware/firmware_step_hub_home.rs`
|
||||
- `crates/console/prometeu-firmware/src/firmware/firmware_state.rs`
|
||||
|
||||
## Risks
|
||||
|
||||
- The current step/state architecture gives `HubHomeStep` a `PrometeuContext`
|
||||
but not direct access to private `Firmware` fields. If a new transition
|
||||
variant is introduced, it must stay narrow and must not turn state steps into
|
||||
owners of lifecycle authority.
|
||||
- Duplicating less logic must not accidentally weaken the input barrier that was
|
||||
added for Hub-to-Game transitions.
|
||||
@@ -1,119 +0,0 @@
|
||||
---
|
||||
id: PLN-0146
|
||||
ticket: foreground-stack-game-pause-shell-vm-backed
|
||||
title: Consolidate Lifecycle Process Lookup Helpers
|
||||
status: done
|
||||
created: 2026-07-04
|
||||
ref_decisions: [DEC-0037]
|
||||
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
`DEC-0037` depends on SystemOS lifecycle authority being internally
|
||||
consistent. The lifecycle facade now exposes both process state and process kind
|
||||
for a task so firmware can distinguish VM-backed Shell tasks from native Shell
|
||||
tasks. Both accessors repeat the same task-to-process lookup pattern.
|
||||
|
||||
The duplication is small, but this facade is now part of the foreground
|
||||
contract surface. Keeping lookup and error mapping in one place reduces the
|
||||
chance that future lifecycle accessors drift in behavior.
|
||||
|
||||
## Objective
|
||||
|
||||
Consolidate task-to-process lookup in `LifecycleFacade` behind one private
|
||||
helper, while preserving the public lifecycle facade behavior and errors.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Source decision: `DEC-0037`.
|
||||
- Depends on the process/task authority from SystemOS lifecycle work.
|
||||
- Can be implemented independently of `PLN-0145` and `PLN-0147`.
|
||||
|
||||
## Scope
|
||||
|
||||
Included:
|
||||
|
||||
- Add one private helper that resolves a `TaskId` to its backing process.
|
||||
- Route `process_state_for_task` and `process_kind_for_task` through that
|
||||
helper.
|
||||
- Preserve `LifecycleError::TaskNotFound` and
|
||||
`LifecycleError::ProcessNotFound` behavior exactly.
|
||||
- Keep the current process/task manager ownership boundaries intact.
|
||||
- Keep the current non-architectural cleanup in `set_foreground_task` if it is
|
||||
still present in the working tree.
|
||||
|
||||
Excluded:
|
||||
|
||||
- No new public process manager API.
|
||||
- No changes to task or process IDs.
|
||||
- No changes to Shell/Game lifecycle semantics.
|
||||
- No broader facade refactor outside lifecycle lookup.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Do not expose raw process manager access through SystemOS.
|
||||
- Do not change `ProcessKind` or `TaskKind` definitions.
|
||||
- Do not alter foreground stack behavior.
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Add a private lifecycle lookup helper.
|
||||
- What changes: add a private function near `process_id_for_task` that
|
||||
returns a process reference for a `TaskId`.
|
||||
- How it changes: the helper should call `process_id_for_task`, then
|
||||
retrieve the process from `process_manager`, returning
|
||||
`LifecycleError::ProcessNotFound(process_id)` if the process is missing.
|
||||
- File(s): `crates/console/prometeu-system/src/os/facades/lifecycle.rs`.
|
||||
|
||||
2. Route state and kind accessors through the helper.
|
||||
- What changes: `LifecycleFacade::process_state_for_task` and
|
||||
`LifecycleFacade::process_kind_for_task` stop duplicating the process
|
||||
manager lookup.
|
||||
- How it changes: both methods call the helper and map the process reference
|
||||
to `ProcessState` or `ProcessKind`.
|
||||
- File(s): `crates/console/prometeu-system/src/os/facades/lifecycle.rs`.
|
||||
|
||||
3. Preserve existing foreground code cleanup.
|
||||
- What changes: keep `set_foreground_task` as an expression-returning match
|
||||
rather than using redundant `return` statements.
|
||||
- How it changes: ensure formatting and clippy stay clean.
|
||||
- File(s): `crates/console/prometeu-system/src/os/facades/lifecycle.rs`.
|
||||
|
||||
4. Tighten tests around lookup behavior.
|
||||
- What changes: extend or keep tests proving VM Shell and native Shell
|
||||
process kinds are observable through lifecycle.
|
||||
- How it changes: add missing-task and missing-process coverage only if the
|
||||
helper changes the observable path enough to justify it.
|
||||
- File(s): `crates/console/prometeu-system/src/os/system_os.rs`.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] `process_state_for_task` and `process_kind_for_task` share one private
|
||||
task-to-process lookup implementation.
|
||||
- [ ] Missing task and missing process errors remain unchanged.
|
||||
- [ ] Existing lifecycle tests continue to pass.
|
||||
- [ ] Firmware can still distinguish `ProcessKind::VmShell` from
|
||||
`ProcessKind::NativeShell`.
|
||||
- [ ] Clippy reports no warnings for the touched crates.
|
||||
|
||||
## Tests
|
||||
|
||||
- Unit tests in `prometeu-system` for shell process kind lookup.
|
||||
- Existing lifecycle missing task/process tests must continue to pass.
|
||||
- Run `cargo test -p prometeu-system lifecycle process_kind`.
|
||||
- Run `cargo test -p prometeu-firmware shell`.
|
||||
- Run `cargo clippy -p prometeu-system -p prometeu-firmware --all-targets -- -D warnings`.
|
||||
- Run `discussion validate`.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `crates/console/prometeu-system/src/os/facades/lifecycle.rs`
|
||||
- `crates/console/prometeu-system/src/os/system_os.rs`
|
||||
|
||||
## Risks
|
||||
|
||||
- Over-generalizing the helper could leak process manager concepts outside the
|
||||
lifecycle facade. Keep it private and narrowly typed.
|
||||
- This is intentionally small cleanup. It must not become a broad SystemOS
|
||||
facade redesign.
|
||||
@@ -1,144 +0,0 @@
|
||||
---
|
||||
id: PLN-0147
|
||||
ticket: foreground-stack-game-pause-shell-vm-backed
|
||||
title: Move Native Shell Profile Update Into Hub
|
||||
status: done
|
||||
created: 2026-07-04
|
||||
ref_decisions: [DEC-0037]
|
||||
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
`DEC-0037` says a suspended Game must not receive normal gameplay ticks while
|
||||
Hub or Shell owns foreground. A recent fix made `ShellRunningStep` branch on
|
||||
`ProcessKind`: VM-backed Shell tasks use the VM-backed shell profile path, while
|
||||
native Shell tasks call `PrometeuHub::gui_update` and `PrometeuHub::render`
|
||||
without ticking the VM.
|
||||
|
||||
That behavior is correct, but the native Shell update sequence now lives in
|
||||
firmware rather than in the Hub profile API. This duplicates part of
|
||||
`PrometeuHub::update_shell_profile` and creates a drift risk if Shell close,
|
||||
render, or input rules change later.
|
||||
|
||||
## Objective
|
||||
|
||||
Move native Shell profile updating into `PrometeuHub` so `ShellRunningStep`
|
||||
chooses the correct profile API without reimplementing Hub behavior.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Source decision: `DEC-0037`.
|
||||
- Depends on the `ProcessKind::VmShell` vs `ProcessKind::NativeShell`
|
||||
distinction available through `LifecycleFacade::process_kind_for_task`.
|
||||
- May be implemented before or after `PLN-0146`, but should use the consolidated
|
||||
lookup helper if `PLN-0146` has already landed.
|
||||
|
||||
## Scope
|
||||
|
||||
Included:
|
||||
|
||||
- Add a Hub-owned native Shell update API that does not tick the VM.
|
||||
- Keep VM-backed Shell update behavior in the existing VM-backed profile path.
|
||||
- Keep Shell close handling consistent between native and VM-backed Shells.
|
||||
- Keep native Shell rendering in the Hub/Shell UI path.
|
||||
- Keep firmware responsible for choosing which profile applies to the current
|
||||
Shell task.
|
||||
- Preserve regression coverage that a suspended resident Game does not advance
|
||||
while native Shell is foreground.
|
||||
|
||||
Excluded:
|
||||
|
||||
- No change to VM-backed Shell execution semantics.
|
||||
- No change to native Shell UI content.
|
||||
- No direct Shell close to Game.
|
||||
- No multiple foreground Shells.
|
||||
- No background Game ticking.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Do not move foreground lifecycle authority into `PrometeuHub`.
|
||||
- Do not make native Shells VM tasks.
|
||||
- Do not introduce a general scheduler abstraction.
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Add a native Shell profile update method on `PrometeuHub`.
|
||||
- What changes: create `update_native_shell_profile` or an equivalent
|
||||
clearly named method that returns `SystemProfileUpdate`.
|
||||
- How it changes: the method calls `gui_update`, maps Start input to
|
||||
`SystemProfileAction::CloseShell` when a shell window is focused, calls
|
||||
`render`, and always returns `crash: None`.
|
||||
- File(s):
|
||||
`crates/console/prometeu-system/src/programs/prometeu_hub/prometeu_hub.rs`.
|
||||
|
||||
2. Keep the VM-backed Shell profile method explicitly VM-backed.
|
||||
- What changes: either keep `update_shell_profile` and document/name its VM
|
||||
tick behavior, or rename/split it if the codebase convention supports that
|
||||
without churn.
|
||||
- How it changes: ensure the VM-backed path is the only Hub profile update
|
||||
method that calls `os.vm().tick(...)`.
|
||||
- File(s):
|
||||
`crates/console/prometeu-system/src/programs/prometeu_hub/prometeu_hub.rs`.
|
||||
|
||||
3. Simplify `ShellRunningStep`.
|
||||
- What changes: remove manual native Shell `gui_update`, Start handling, and
|
||||
render calls from firmware.
|
||||
- How it changes: branch on `ProcessKind` and call the appropriate Hub
|
||||
profile method; keep crash handling only for the VM-backed method.
|
||||
- File(s):
|
||||
`crates/console/prometeu-firmware/src/firmware/firmware_step_shell_running.rs`.
|
||||
|
||||
4. Add Hub-level native profile tests.
|
||||
- What changes: prove native Shell profile update emits close on the close
|
||||
button and on Start, renders Shell UI, and does not tick the VM.
|
||||
- How it changes: use existing Hub/system test helpers where possible; assert
|
||||
VM tick index remains unchanged for native profile update.
|
||||
- File(s):
|
||||
`crates/console/prometeu-system/src/programs/prometeu_hub/prometeu_hub.rs`
|
||||
and/or `crates/console/prometeu-firmware/src/firmware/firmware.rs`.
|
||||
|
||||
5. Preserve end-to-end regression coverage.
|
||||
- What changes: keep the Game -> Home -> native Shell test asserting that
|
||||
repeated Shell frames do not advance the resident Game VM tick index.
|
||||
- How it changes: rerun the firmware regression added for native Shell
|
||||
foreground.
|
||||
- File(s): `crates/console/prometeu-firmware/src/firmware/firmware.rs`.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Native Shell update behavior is owned by `PrometeuHub`, not hand-coded in
|
||||
`ShellRunningStep`.
|
||||
- [ ] The native Shell profile update never calls `os.vm().tick(...)`.
|
||||
- [ ] VM-backed Shell update remains the only Shell profile path that ticks the
|
||||
VM runtime.
|
||||
- [ ] Start and close-button Shell close behavior remains unchanged for native
|
||||
Shells.
|
||||
- [ ] A suspended resident Game receives no normal gameplay ticks while native
|
||||
Shell is foreground.
|
||||
|
||||
## Tests
|
||||
|
||||
- Hub-level tests for native Shell profile close behavior.
|
||||
- Hub-level or firmware-level tests proving native Shell profile update does not
|
||||
tick the VM.
|
||||
- Existing firmware regression for Game -> Home -> native Shell repeated frames.
|
||||
- Run `cargo test -p prometeu-system native_shell shell_profile`.
|
||||
- Run `cargo test -p prometeu-firmware game_home_shell_hub_same_game_flow`.
|
||||
- Run `cargo test -p prometeu-firmware`.
|
||||
- Run `cargo test -p prometeu-system`.
|
||||
- Run `discussion validate`.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `crates/console/prometeu-system/src/programs/prometeu_hub/prometeu_hub.rs`
|
||||
- `crates/console/prometeu-firmware/src/firmware/firmware_step_shell_running.rs`
|
||||
- `crates/console/prometeu-firmware/src/firmware/firmware.rs`
|
||||
|
||||
## Risks
|
||||
|
||||
- Renaming the existing VM-backed shell profile method may create unnecessary
|
||||
churn. Prefer adding the native method and keeping call sites explicit unless
|
||||
the rename is small and clearly improves readability.
|
||||
- Hub APIs must remain UI/profile orchestration only; lifecycle close and task
|
||||
state changes still belong to firmware/SystemOS lifecycle.
|
||||
@@ -1,92 +0,0 @@
|
||||
---
|
||||
id: PLN-0148
|
||||
ticket: foreground-stack-game-pause-shell-vm-backed
|
||||
title: Introduce VM Session Registry and Identity
|
||||
status: done
|
||||
created: 2026-07-04
|
||||
ref_decisions: [DEC-0038]
|
||||
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
DEC-0038 requires every VM-backed process to own its own mutable VM context instead of sharing `Firmware.vm`. This plan introduces the identity and registry layer required before moving runtime state or changing cartridge loading.
|
||||
|
||||
The implementation must make VM session ownership explicit inside `SystemOS`. A VM-backed Game task and a VM-backed Shell task must be able to coexist as distinct sessions, even before all execution paths are migrated to session-owned VMs.
|
||||
|
||||
## Objective
|
||||
|
||||
Add a `VmSession` model and registry owned by `SystemOS`, keyed by a stable session identity tied to the owning task/process. The registry must support creating, retrieving, and validating VM sessions for VM-backed Game and Shell tasks.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Source decision: DEC-0038.
|
||||
- Existing foreground/task/process lifecycle from DEC-0037 remains authoritative.
|
||||
- Must be implemented before PLN-0149, PLN-0150, PLN-0151, and PLN-0152.
|
||||
|
||||
## Scope
|
||||
|
||||
- Add a session identity type, preferably `VmSessionId`, with a deliberate mapping from the owning `TaskId`.
|
||||
- Add a `VmSession` data structure containing at least:
|
||||
- owning `TaskId`;
|
||||
- owning process id or process lookup path;
|
||||
- `app_id`, title, version, and `AppMode`;
|
||||
- initial placeholder for the session-owned `VirtualMachine`;
|
||||
- initial placeholder for session-owned runtime state to be populated by PLN-0149.
|
||||
- Add a registry under `crates/console/prometeu-system/src/services/` or an equivalent existing services module.
|
||||
- Expose creation and lookup through `crates/console/prometeu-system/src/os/facades/sessions.rs`.
|
||||
- Update `SystemOS` construction in `crates/console/prometeu-system/src/os/system_os.rs` to own the registry.
|
||||
- Enforce V1 uniqueness:
|
||||
- at most one resident Game session;
|
||||
- one foreground Shell task at a time;
|
||||
- same `app_id` resident Game relaunch maps to the existing resident session rather than creating a second Game session.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Do not move all VM runtime fields yet; that is PLN-0149.
|
||||
- Do not route cartridge loading through sessions yet; that is PLN-0150.
|
||||
- Do not remove `Firmware.vm` yet.
|
||||
- Do not implement general background execution.
|
||||
- Do not allow Game-to-Game switching.
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Inspect `TaskId`, process ids, and `ProcessKind` definitions in `crates/console/prometeu-system/src/services/task/` and `crates/console/prometeu-system/src/services/process/`.
|
||||
2. Add the VM session module with a small API:
|
||||
- create session for an existing VM-backed task/process;
|
||||
- get immutable/mutable session by task id;
|
||||
- get resident Game session by `app_id`;
|
||||
- reject incompatible duplicate Game sessions.
|
||||
3. Wire the registry into `SystemOS`.
|
||||
4. Extend `SessionsFacade::create_vm_game_task` and `create_vm_shell_task` so task creation also creates a VM session record.
|
||||
5. Keep native Shell task creation out of the VM session registry.
|
||||
6. Add focused unit tests under `prometeu-system` for registry identity and duplicate handling.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- `SystemOS` owns a VM session registry.
|
||||
- Creating a VM Game task creates exactly one VM session associated with that task.
|
||||
- Creating a VM Shell task creates exactly one VM session associated with that task.
|
||||
- Creating a native Shell task creates no VM session.
|
||||
- Attempting to create a second resident Game session for a different `app_id` is rejected or routed through the existing lifecycle rejection path.
|
||||
- Relaunching the same resident Game can resolve the existing VM session by `app_id`.
|
||||
- No firmware state transition depends on the new registry yet except through task/session creation.
|
||||
|
||||
## Tests
|
||||
|
||||
- `cargo test -p prometeu-system`
|
||||
- Add unit tests for:
|
||||
- VM Game task creates a VM session;
|
||||
- VM Shell task creates a VM session;
|
||||
- native Shell task does not create a VM session;
|
||||
- lookup by `TaskId`;
|
||||
- same resident Game `app_id` resolves to the existing session;
|
||||
- different resident Game `app_id` remains blocked under V1.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `crates/console/prometeu-system/src/os/system_os.rs`
|
||||
- `crates/console/prometeu-system/src/os/facades/sessions.rs`
|
||||
- `crates/console/prometeu-system/src/services/mod.rs`
|
||||
- New or extended module under `crates/console/prometeu-system/src/services/`
|
||||
- `crates/console/prometeu-system/src/lib.rs` if exports are required
|
||||
@@ -1,99 +0,0 @@
|
||||
---
|
||||
id: PLN-0149
|
||||
ticket: foreground-stack-game-pause-shell-vm-backed
|
||||
title: Move VM Runtime State Into VM Sessions
|
||||
status: done
|
||||
created: 2026-07-04
|
||||
ref_decisions: [DEC-0038]
|
||||
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
DEC-0038 states that mutable VM context must belong to the VM-backed process session, not to firmware or a single global runtime slot. The current split has `Firmware.vm: VirtualMachine` and `SystemOS.vm_runtime: VirtualMachineRuntime`, which makes a suspended Game vulnerable to VM-backed Shell execution.
|
||||
|
||||
This plan migrates mutable per-application VM runtime state into the session model introduced by PLN-0148 while keeping global OS services global.
|
||||
|
||||
## Objective
|
||||
|
||||
Make each VM session own the state needed to suspend and later resume that VM-backed process without being overwritten by another VM-backed process.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Source decision: DEC-0038.
|
||||
- Requires PLN-0148.
|
||||
- Must precede full cartridge-loading and scheduler migration in PLN-0150 and PLN-0151.
|
||||
|
||||
## Scope
|
||||
|
||||
- Classify `VirtualMachineRuntime` fields into session-owned versus global OS-owned state.
|
||||
- Move session-owned fields into the `VmSession` context.
|
||||
- Keep global services in `SystemOS`, including:
|
||||
- `LogService`;
|
||||
- process/task/window managers;
|
||||
- foreground stack;
|
||||
- durable `MemcardService`;
|
||||
- global render publication authority or worker coordination that must remain host-facing.
|
||||
- Treat these as session-owned unless proven otherwise during implementation:
|
||||
- `VirtualMachine`;
|
||||
- current cartridge identity;
|
||||
- frame and tick counters;
|
||||
- lifecycle delivery bookkeeping;
|
||||
- crash report for that session;
|
||||
- pause/debug flags that apply to that session;
|
||||
- per-session open files, handles, and staging state used by VM syscalls.
|
||||
- Keep durable memcard contents keyed by `app_id`; do not turn save data into session-private durable storage.
|
||||
- Update `VmFacade` and VM runtime helpers so callers can operate on a selected session.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Do not redesign render workers beyond separating session-local render command state from global presentation authority.
|
||||
- Do not implement background execution.
|
||||
- Do not change syscall semantics except where required to route state through the active session.
|
||||
- Do not remove host debugger features; preserve or adapt their access path.
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Add an internal field-by-field classification comment or test-only assertion near `VirtualMachineRuntime` before moving fields.
|
||||
2. Introduce a session runtime/context type in the VM session module or by splitting `VirtualMachineRuntime` into:
|
||||
- session-local runtime;
|
||||
- global render/log/runtime services.
|
||||
3. Move `VirtualMachine` ownership from firmware placeholder/session stub into the session context.
|
||||
4. Move per-cartridge and per-frame state from `SystemOS.vm_runtime` into the session context.
|
||||
5. Move `open_files`, `next_handle`, and VM syscall staging state out of global `SystemOS` if they are VM-session specific.
|
||||
6. Update `VmRuntimeHost` in `crates/console/prometeu-system/src/services/vm_runtime/dispatch.rs` to receive session-local state plus references to required global services.
|
||||
7. Update `VmFacade` in `crates/console/prometeu-system/src/os/facades/vm.rs` with explicit session-targeted methods.
|
||||
8. Preserve temporary compatibility methods only where needed for existing host/debugger code, and mark them as active-session views rather than canonical global ownership.
|
||||
9. Add tests proving two VM sessions can hold different app identity and counters at the same time.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- No canonical VM state lives in `Firmware`.
|
||||
- `SystemOS` can hold at least two VM sessions with independent `VirtualMachine` and per-session runtime state.
|
||||
- VM session A and VM session B can have different `app_id`, title, frame counters, lifecycle delivery history, crash report, open file handles, and debug pause state.
|
||||
- Durable memcard contents remain shared by `app_id` according to the existing memcard contract.
|
||||
- Global render ownership remains controlled by SystemOS/host-facing runtime services, not by individual sessions.
|
||||
- Existing `prometeu-system` VM runtime tests still pass after adapting their setup.
|
||||
|
||||
## Tests
|
||||
|
||||
- `cargo test -p prometeu-system`
|
||||
- `cargo test -p prometeu-firmware`
|
||||
- Add tests for:
|
||||
- independent session app identity;
|
||||
- independent tick/logical-frame counters;
|
||||
- independent lifecycle delivery bookkeeping;
|
||||
- VM Shell session initialization does not mutate resident Game session identity;
|
||||
- session-scoped file handles do not collide across sessions.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `crates/console/prometeu-system/src/services/vm_runtime/`
|
||||
- VM session module introduced by PLN-0148
|
||||
- `crates/console/prometeu-system/src/os/facades/vm.rs`
|
||||
- `crates/console/prometeu-system/src/os/system_os.rs`
|
||||
- `crates/console/prometeu-system/src/os/facades/fs.rs`
|
||||
- `crates/console/prometeu-firmware/src/firmware/firmware.rs`
|
||||
- `crates/host/prometeu-host-desktop-winit/src/debugger.rs`
|
||||
- `crates/host/prometeu-host-desktop-winit/src/runner.rs`
|
||||
- `crates/host/prometeu-host-desktop-winit/src/stats.rs`
|
||||
@@ -1,90 +0,0 @@
|
||||
---
|
||||
id: PLN-0150
|
||||
ticket: foreground-stack-game-pause-shell-vm-backed
|
||||
title: Route Cartridge Loading Through VM Sessions
|
||||
status: done
|
||||
created: 2026-07-04
|
||||
ref_decisions: [DEC-0038]
|
||||
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
DEC-0038 requires cartridge loading to create or activate a VM-backed process session instead of initializing a single global VM. The current `LoadCartridgeStep` initializes `ctx.os.vm().initialize(ctx.vm, &cartridge)` before task/session ownership is selected.
|
||||
|
||||
This plan moves cartridge initialization behind session services so Game and VM-backed Shell loading cannot overwrite each other.
|
||||
|
||||
## Objective
|
||||
|
||||
Route Game and VM Shell cartridge loading through the VM session registry and initialize the cartridge inside the target session-owned VM context.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Source decision: DEC-0038.
|
||||
- Requires PLN-0148.
|
||||
- Requires enough of PLN-0149 to expose session-owned VM/runtime initialization.
|
||||
- Must precede the end-to-end coexistence validation in PLN-0152.
|
||||
|
||||
## Scope
|
||||
|
||||
- Replace direct global VM initialization in `LoadCartridgeStep`.
|
||||
- Add a session/facade operation that:
|
||||
- selects an existing resident Game session when the same `app_id` is relaunched;
|
||||
- rejects or reports different resident Game launches under V1;
|
||||
- creates a new VM Shell session for a Shell cartridge;
|
||||
- initializes the cartridge inside the selected session VM.
|
||||
- Keep asset manager initialization aligned with the foreground cartridge being launched.
|
||||
- Ensure `AppCrashesStep` receives initialization failures from the target session.
|
||||
- Update Hub cartridge selection logic so resume versus load is based on lifecycle/session identity, not global VM identity.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Do not implement multiple resident Games.
|
||||
- Do not implement background execution.
|
||||
- Do not redesign cartridge format or asset packaging.
|
||||
- Do not broaden Shell windowing behavior beyond the existing one-foreground-Shell model.
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Add a `load_vm_cartridge` or equivalent method to `SessionsFacade` or `VmFacade`.
|
||||
2. Make the method return an execution target:
|
||||
- existing Game task for same resident `app_id`;
|
||||
- new Game task for first Game launch;
|
||||
- new VM Shell task for Shell launch;
|
||||
- structured error/crash report for invalid VM initialization;
|
||||
- explicit lifecycle error for blocked second Game.
|
||||
3. Update `crates/console/prometeu-firmware/src/firmware/firmware_step_load_cartridge.rs` to call the facade method instead of initializing `ctx.vm`.
|
||||
4. Update `crates/console/prometeu-firmware/src/firmware/firmware_step_hub_home.rs` so same-Game relaunch checks session/lifecycle state rather than `ctx.os.vm().current_app_id()`.
|
||||
5. Preserve AppMode-based transition:
|
||||
- Game target transitions to `GameRunning`;
|
||||
- Shell target creates/focuses a window and transitions to `ShellRunning`.
|
||||
6. Adapt crash tests and resident-game relaunch tests in firmware.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- `LoadCartridgeStep` no longer initializes a global firmware VM.
|
||||
- Loading a Shell cartridge creates/initializes a Shell VM session.
|
||||
- Loading the first Game cartridge creates/initializes the resident Game VM session.
|
||||
- Clicking the same resident Game from Hub resumes the existing Game session without reinitializing it.
|
||||
- Attempting to load a different Game while one resident Game exists remains blocked under V1 with a controlled outcome.
|
||||
- VM initialization failure still transitions to `AppCrashesStep`.
|
||||
|
||||
## Tests
|
||||
|
||||
- `cargo test -p prometeu-firmware`
|
||||
- `cargo test -p prometeu-system`
|
||||
- Add or update firmware tests for:
|
||||
- first Game load creates one session and enters `GameRunning`;
|
||||
- same Game relaunch resumes existing task/session;
|
||||
- VM Shell load creates a distinct session;
|
||||
- Shell load does not change resident Game session app identity;
|
||||
- invalid cartridge reports `CrashReport::VmInit`.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `crates/console/prometeu-firmware/src/firmware/firmware_step_load_cartridge.rs`
|
||||
- `crates/console/prometeu-firmware/src/firmware/firmware_step_hub_home.rs`
|
||||
- `crates/console/prometeu-firmware/src/firmware/firmware.rs`
|
||||
- `crates/console/prometeu-system/src/os/facades/sessions.rs`
|
||||
- `crates/console/prometeu-system/src/os/facades/vm.rs`
|
||||
- VM session module introduced by PLN-0148
|
||||
@@ -1,92 +0,0 @@
|
||||
---
|
||||
id: PLN-0151
|
||||
ticket: foreground-stack-game-pause-shell-vm-backed
|
||||
title: Schedule Foreground VM Session Ticks
|
||||
status: done
|
||||
created: 2026-07-04
|
||||
ref_decisions: [DEC-0038]
|
||||
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
DEC-0038 separates session ownership from foreground ownership and states that V1 does not provide general background execution. The runtime therefore needs an explicit scheduler path that ticks the VM session eligible for foreground execution, while leaving suspended resident Game sessions intact.
|
||||
|
||||
## Objective
|
||||
|
||||
Make firmware and SystemOS tick the VM session associated with the current foreground VM-backed task, instead of ticking a global VM/runtime pair.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Source decision: DEC-0038.
|
||||
- Requires PLN-0148.
|
||||
- Requires PLN-0149.
|
||||
- Requires PLN-0150 for loaded cartridges to map to sessions.
|
||||
|
||||
## Scope
|
||||
|
||||
- Add scheduler/facade operations that tick a specific VM session by `TaskId`.
|
||||
- Update `GameRunningStep` to tick the Game session identified by its `task_id`.
|
||||
- Update `ShellRunningStep` to tick only VM-backed Shell sessions.
|
||||
- Ensure native Shell foreground state performs native profile updates without ticking any VM session.
|
||||
- Keep suspended Game sessions non-executing while Hub or Shell is foreground.
|
||||
- Preserve lifecycle event delivery:
|
||||
- pause/resume events go to the resident Game session;
|
||||
- Shell lifecycle events, if any, remain scoped to the Shell session.
|
||||
- Preserve host debugger pause/step behavior against the active VM session view.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Do not add background execution classes yet.
|
||||
- Do not allow multiple simultaneous VM ticks in one host frame.
|
||||
- Do not implement general service/player processes.
|
||||
- Do not change the 60 Hz firmware tick contract.
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Add `SystemOS` facade methods for:
|
||||
- ticking a VM session by task id;
|
||||
- querying whether a task is VM-backed;
|
||||
- exposing the active VM session to host/debugger tooling.
|
||||
2. Update `crates/console/prometeu-firmware/src/firmware/firmware_step_game_running.rs` to tick through the task/session facade.
|
||||
3. Update `crates/console/prometeu-firmware/src/firmware/firmware_step_shell_running.rs` to branch on process kind:
|
||||
- VM Shell ticks its VM session;
|
||||
- native Shell runs native profile logic only.
|
||||
4. Remove direct `ctx.vm` use from Game/Shell execution steps.
|
||||
5. Ensure resident Game pause budget can deliver one final pause tick and then stop ticking once suspended.
|
||||
6. Update host/debugger active VM access paths to resolve through the foreground session.
|
||||
7. Add regression tests for tick counters across Game, Hub, native Shell, and VM Shell transitions.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- A suspended Game session does not advance while Hub is foreground.
|
||||
- A suspended Game session does not advance while a Shell is foreground.
|
||||
- A VM Shell session advances while that VM Shell is foreground.
|
||||
- A native Shell does not tick any VM session.
|
||||
- Returning from Hub to resident Game resumes ticking the same Game session.
|
||||
- Host debugger and stats read the active VM session, not a stale global VM.
|
||||
|
||||
## Tests
|
||||
|
||||
- `cargo test -p prometeu-firmware`
|
||||
- `cargo test -p prometeu-system`
|
||||
- `cargo test -p prometeu-host-desktop-winit`
|
||||
- Add tests for:
|
||||
- Game tick count freezes after Home suspension;
|
||||
- VM Shell tick count advances independently;
|
||||
- native Shell does not advance Game tick count;
|
||||
- resume returns to same Game session tick counter;
|
||||
- active-session debugger snapshot uses foreground VM session.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `crates/console/prometeu-firmware/src/firmware/firmware_step_game_running.rs`
|
||||
- `crates/console/prometeu-firmware/src/firmware/firmware_step_shell_running.rs`
|
||||
- `crates/console/prometeu-firmware/src/firmware/prometeu_context.rs`
|
||||
- `crates/console/prometeu-firmware/src/firmware/firmware.rs`
|
||||
- `crates/console/prometeu-system/src/os/facades/vm.rs`
|
||||
- `crates/console/prometeu-system/src/os/facades/lifecycle.rs`
|
||||
- VM session module introduced by PLN-0148
|
||||
- `crates/host/prometeu-host-desktop-winit/src/debugger.rs`
|
||||
- `crates/host/prometeu-host-desktop-winit/src/runner.rs`
|
||||
- `crates/host/prometeu-host-desktop-winit/src/stats.rs`
|
||||
@@ -1,86 +0,0 @@
|
||||
---
|
||||
id: PLN-0152
|
||||
ticket: foreground-stack-game-pause-shell-vm-backed
|
||||
title: Validate Game and VM Shell Session Coexistence
|
||||
status: done
|
||||
created: 2026-07-04
|
||||
ref_decisions: [DEC-0038]
|
||||
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
DEC-0038 was motivated by the concrete failure mode where a resident Game is suspended, a Shell is opened, and Game logs or state unexpectedly continue under the wrong foreground owner. After VM sessions and scheduling are implemented, the system needs explicit regression coverage for this workflow.
|
||||
|
||||
## Objective
|
||||
|
||||
Add end-to-end and integration validation proving a resident Game VM session and a VM-backed Shell session can coexist without overwriting or ticking each other incorrectly.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Source decision: DEC-0038.
|
||||
- Requires PLN-0148, PLN-0149, PLN-0150, and PLN-0151.
|
||||
- Should be executed before closing the broader DEC-0038 implementation thread.
|
||||
|
||||
## Scope
|
||||
|
||||
- Add firmware-level regression tests for:
|
||||
- Game launch;
|
||||
- Home/SystemOS request;
|
||||
- Game pause/suspend;
|
||||
- VM Shell launch;
|
||||
- Shell foreground ticking;
|
||||
- Shell exit;
|
||||
- Hub return;
|
||||
- resident Game resume.
|
||||
- Add system-level tests for independent session state.
|
||||
- Add host-level tests only where active VM/debugger/stat routing cannot be covered at firmware/system level.
|
||||
- Verify logs from the stress cartridge or equivalent test cartridge do not appear while Game is suspended and Shell is foreground.
|
||||
- Verify Shell logs, frames, or tick counters belong to the Shell session.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Do not introduce new architecture in this plan.
|
||||
- Do not broaden background execution.
|
||||
- Do not rewrite Hub UI behavior except where required to exercise the flow.
|
||||
- Do not depend on manual desktop testing as the only evidence.
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Identify or add deterministic test cartridges/helpers that can emit per-session tick/log evidence.
|
||||
2. Add a firmware integration test for `Game -> Home -> VM Shell -> Hub -> same Game`.
|
||||
3. Capture Game session counters before Shell launch and after Shell foreground ticks.
|
||||
4. Assert the Game session counters and lifecycle delivery state remain stable while Shell is foreground.
|
||||
5. Assert the Shell session counters advance while Shell is foreground.
|
||||
6. Assert returning to the same Game resumes the same task/session and then advances the Game counter.
|
||||
7. Add a regression specifically covering the prior symptom: Game `stress` logs must not appear during Shell foreground execution.
|
||||
8. Run the relevant crate tests and record evidence in the plan completion notes when implemented.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- The failing manual scenario is covered by automated tests.
|
||||
- The Game session is suspended and non-ticking while VM Shell is foreground.
|
||||
- The VM Shell session ticks independently.
|
||||
- Returning to Hub and selecting the same Game resumes the resident Game session instead of creating a duplicate process/session.
|
||||
- No test relies on a single global `current_app_id` to infer correctness.
|
||||
|
||||
## Tests
|
||||
|
||||
- `cargo test -p prometeu-system`
|
||||
- `cargo test -p prometeu-firmware`
|
||||
- `cargo test -p prometeu-host-desktop-winit` if host active-session plumbing changed.
|
||||
- Optional manual smoke:
|
||||
- run `cargo run --bin prometeu-host-desktop-winit --profile release --manifest-path crates/host/prometeu-host-desktop-winit/Cargo.toml -- --games-root test-cartridges`;
|
||||
- open Stress Console;
|
||||
- press ESC/Home;
|
||||
- open VM-backed Shell;
|
||||
- verify no Stress logs appear while Shell is foreground;
|
||||
- return and resume Stress Console.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `crates/console/prometeu-firmware/src/firmware/firmware.rs` tests
|
||||
- `crates/console/prometeu-system/src/os/system_os.rs` tests
|
||||
- `crates/console/prometeu-system/src/services/vm_runtime/tests.rs`
|
||||
- `crates/host/prometeu-host-desktop-winit/src/runner.rs` tests if needed
|
||||
- `test-cartridges/` only if a deterministic VM Shell fixture is missing
|
||||
-82
@@ -1,82 +0,0 @@
|
||||
---
|
||||
id: PLN-0153
|
||||
ticket: foreground-stack-game-pause-shell-vm-backed
|
||||
title: Specify VM Session Ownership and Background-Ready Scheduling
|
||||
status: done
|
||||
created: 2026-07-04
|
||||
ref_decisions: [DEC-0038]
|
||||
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
DEC-0038 locks the runtime direction: VM context is session-owned, firmware orchestrates macro-state, and background execution is out of V1 but must remain a near-term compatible extension. The canonical specs must describe that contract in English so future implementation and debugging do not drift back to a single global VM model.
|
||||
|
||||
## Objective
|
||||
|
||||
Update canonical runtime specifications to document VM session ownership, foreground execution eligibility, render publication authority, and the background-ready shape of the scheduler without committing to background execution in this implementation batch.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Source decision: DEC-0038.
|
||||
- Should be informed by PLN-0148 through PLN-0151 once implementation names settle.
|
||||
- May be done before PLN-0152 if the implementation contract is already stable, but final wording must match implemented APIs.
|
||||
|
||||
## Scope
|
||||
|
||||
- Update the canonical specs under `docs/specs/runtime/` in English.
|
||||
- Document:
|
||||
- each VM-backed process owns one VM session;
|
||||
- VM sessions own mutable VM context;
|
||||
- foreground ownership and execution eligibility are separate concepts;
|
||||
- V1 executes only the foreground VM-backed task, except the existing pause handoff budget;
|
||||
- suspended resident Game sessions preserve VM context but do not tick;
|
||||
- VM-backed Shell sessions have their own VM context;
|
||||
- native Shell does not own a VM session;
|
||||
- durable app data remains keyed by `app_id`;
|
||||
- session-scoped handles and staging state are not durable app data;
|
||||
- global render publication remains SystemOS/host authority.
|
||||
- Add background-ready wording:
|
||||
- scheduler model can later mark sessions or service processes as eligible without changing ownership;
|
||||
- no current guarantee of background progress is introduced.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Do not write implementation plans into specs.
|
||||
- Do not document background execution as available.
|
||||
- Do not move normative text into `discussion/lessons/`.
|
||||
- Do not create new legacy docs paths.
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Locate the most relevant runtime specs, likely:
|
||||
- `docs/specs/runtime/09-events-and-concurrency.md`;
|
||||
- `docs/specs/runtime/12-firmware-pos-and-prometeuhub.md`;
|
||||
- `docs/specs/runtime/14-boot-profiles.md`;
|
||||
- `docs/specs/runtime/16-host-abi-and-syscalls.md` if host/debugger active VM views are affected.
|
||||
2. Add concise normative sections using `MUST`, `MUST NOT`, and `SHALL` where appropriate.
|
||||
3. Keep discussion history out of the spec; cite behavior, not agenda chronology.
|
||||
4. Align terminology with implemented type names from PLN-0148 through PLN-0151.
|
||||
5. Run discussion validation after edits and any repository tests required by touched docs tooling.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- Specs explicitly state that VM context is session-owned for VM-backed processes.
|
||||
- Specs explicitly state that native Shell does not own a VM session.
|
||||
- Specs distinguish foreground ownership from future execution eligibility.
|
||||
- Specs state that V1 does not support general background execution.
|
||||
- Specs preserve a future path for background-capable sessions/services without changing VM ownership.
|
||||
- No new framework artifacts are written outside `discussion/`.
|
||||
|
||||
## Tests
|
||||
|
||||
- `discussion validate`
|
||||
- Manual review of touched specs for English-only normative text.
|
||||
- Run repository doc checks if such a command exists; otherwise no code test is required for this plan.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `docs/specs/runtime/09-events-and-concurrency.md`
|
||||
- `docs/specs/runtime/12-firmware-pos-and-prometeuhub.md`
|
||||
- `docs/specs/runtime/14-boot-profiles.md`
|
||||
- `docs/specs/runtime/16-host-abi-and-syscalls.md` if active VM host/debugger wording is needed
|
||||
@@ -1,95 +0,0 @@
|
||||
---
|
||||
id: PLN-0154
|
||||
ticket: foreground-stack-game-pause-shell-vm-backed
|
||||
title: Route Debugger Operations Through VM Sessions
|
||||
status: done
|
||||
created: 2026-07-05
|
||||
ref_decisions: [DEC-0038]
|
||||
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
DEC-0038 requires VM-backed mutable execution state to be owned by VM sessions. Normal execution now ticks session-owned VMs, but desktop debugger commands still inspect and mutate `firmware.vm`, the transitional legacy VM. This leaves debugger state, breakpoints, single-step execution, PC snapshots, and stack snapshots inconsistent with the active VM session.
|
||||
|
||||
## Objective
|
||||
|
||||
Route host debugger operations through the active VM session rather than the legacy firmware VM. Debugger pause/resume/step/state/breakpoint operations must target the same VM context that foreground execution ticks.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Source decision: DEC-0038.
|
||||
- Builds on PLN-0148 through PLN-0152.
|
||||
- Should be implemented before PLN-0155 removes the legacy firmware VM bridge.
|
||||
|
||||
## Scope
|
||||
|
||||
- Add session-aware debugger accessors to `SystemOS`/`VmFacade`.
|
||||
- Expose active VM session inspection and mutation operations needed by the debugger:
|
||||
- PC;
|
||||
- operand stack preview;
|
||||
- insert breakpoint;
|
||||
- remove breakpoint;
|
||||
- list breakpoints;
|
||||
- single-instruction debug step;
|
||||
- active cartridge identity for handshake and state responses.
|
||||
- Update `crates/host/prometeu-host-desktop-winit/src/debugger.rs` so it no longer reads or mutates `firmware.vm` for active VM state.
|
||||
- Ensure debugger setup for direct debug boot initializes through normal cartridge/session loading or an explicit session-aware metadata path, not `os.vm().initialize(&mut firmware.vm, ...)`.
|
||||
- Keep pause/resume/step-frame control mapped to active VM session runtime state.
|
||||
- Add tests that would fail if debugger state came from the legacy VM while the session VM is active.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Do not remove `Firmware.vm`; that is PLN-0155.
|
||||
- Do not redesign the debugger protocol.
|
||||
- Do not add multi-client debugging.
|
||||
- Do not add background-session debugging beyond active/resident session semantics already supported by DEC-0038.
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Add focused `VmFacade` methods for active-session VM inspection:
|
||||
- `active_pc`;
|
||||
- `active_operand_stack_top`;
|
||||
- `insert_active_breakpoint`;
|
||||
- `remove_active_breakpoint`;
|
||||
- `active_breakpoints_list`;
|
||||
- `debug_step_active_session`.
|
||||
2. Define active-session resolution explicitly:
|
||||
- foreground VM session first;
|
||||
- resident Game session when Hub has foreground but a resident Game is the active debug target;
|
||||
- no legacy fallback for debugger mutation once a session exists.
|
||||
3. Update `HostDebugger::setup_boot_target` so debug cartridge metadata is loaded without initializing `firmware.vm` as canonical state.
|
||||
4. Update `HostDebugger::handle_command` for `Step`, `GetState`, `SetBreakpoint`, `ListBreakpoints`, and `ClearBreakpoint`.
|
||||
5. Update `HostDebugger::stream_events` breakpoint-hit PC reporting to read from the active session.
|
||||
6. Add tests under `crates/host/prometeu-host-desktop-winit/src/debugger.rs` proving debugger commands observe and mutate the session VM.
|
||||
7. Run the host, firmware, and system test suites.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- Debugger handshake reports cartridge identity from session/runtime state or preloaded metadata, not from a global VM initialized only for debugger setup.
|
||||
- `GetState` returns PC and stack data from the active VM session.
|
||||
- `Step` advances the active VM session, not `firmware.vm`.
|
||||
- Breakpoint commands mutate the active VM session.
|
||||
- Breakpoint-hit events report the active session PC.
|
||||
- No debugger command path directly reads or mutates `firmware.vm` for active VM execution state.
|
||||
- Existing debugger protocol tests pass.
|
||||
|
||||
## Tests
|
||||
|
||||
- `cargo test -p prometeu-host-desktop-winit`
|
||||
- `cargo test -p prometeu-firmware`
|
||||
- `cargo test -p prometeu-system`
|
||||
- `cargo clippy -p prometeu-host-desktop-winit -p prometeu-firmware -p prometeu-system --all-targets -- -D warnings`
|
||||
- Add tests for:
|
||||
- `GetState` reads session VM PC;
|
||||
- `Step` affects session VM;
|
||||
- breakpoint insert/list/remove uses session VM;
|
||||
- debugger setup does not initialize `firmware.vm` as the canonical app context.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `crates/host/prometeu-host-desktop-winit/src/debugger.rs`
|
||||
- `crates/console/prometeu-system/src/os/facades/vm.rs`
|
||||
- `crates/console/prometeu-system/src/services/vm_session.rs`
|
||||
- `crates/console/prometeu-firmware/src/firmware/firmware.rs`
|
||||
- Debugger-related tests in host and firmware crates
|
||||
@@ -1,89 +0,0 @@
|
||||
---
|
||||
id: PLN-0155
|
||||
ticket: foreground-stack-game-pause-shell-vm-backed
|
||||
title: Retire Legacy Firmware VM Runtime Bridge
|
||||
status: done
|
||||
created: 2026-07-05
|
||||
ref_decisions: [DEC-0038]
|
||||
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
DEC-0038 states that `Firmware.vm` must not remain the canonical owner of VM-backed app context. PLN-0148 through PLN-0152 moved normal cartridge loading and ticking toward VM sessions, but a transitional legacy bridge still initializes and exposes the old global VM/runtime path for compatibility.
|
||||
|
||||
## Objective
|
||||
|
||||
Remove the legacy firmware VM/runtime bridge from normal runtime architecture. After this plan, VM-backed app execution, initialization, active runtime queries, and host-facing inspection must resolve through VM sessions or explicitly global render/runtime services.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Source decision: DEC-0038.
|
||||
- Requires PLN-0154 so debugger operations no longer depend on `firmware.vm`.
|
||||
- Builds on PLN-0148 through PLN-0153.
|
||||
|
||||
## Scope
|
||||
|
||||
- Remove `Firmware.vm` from `crates/console/prometeu-firmware/src/firmware/firmware.rs` if all callsites have migrated.
|
||||
- Remove `PrometeuContext.vm` from `crates/console/prometeu-firmware/src/firmware/prometeu_context.rs`.
|
||||
- Remove `legacy_vm` from `SessionsFacade::load_vm_cartridge`.
|
||||
- Remove `initialize_legacy_active_vm`.
|
||||
- Remove or narrow global `VmFacade::initialize`, `tick`, `reset`, and `debug_step_instruction` methods that operate on caller-supplied `VirtualMachine`.
|
||||
- Keep global render ownership, render worker lifecycle, telemetry publication, and log service where they are global SystemOS responsibilities.
|
||||
- Preserve Hub/Home rendering behavior while avoiding any guest VM state stored in firmware.
|
||||
- Update direct boot, debug boot, reset, and load-cartridge tests to prove session ownership is the only app VM path.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Do not remove `VirtualMachineRuntime` itself.
|
||||
- Do not redesign render worker ownership.
|
||||
- Do not add background execution.
|
||||
- Do not change debugger protocol shape beyond the PLN-0154 migration.
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Use `rg` to list every remaining `firmware.vm`, `ctx.vm`, `legacy_vm`, and `os.vm().initialize/tick/reset/debug_step_instruction` callsite.
|
||||
2. Replace firmware context construction so state steps receive `SystemOS`, Hub, signals, platform, and boot target only.
|
||||
3. Replace reset behavior with session registry/runtime reset semantics:
|
||||
- clear VM sessions on firmware reset when booting fresh;
|
||||
- preserve only explicitly resident sessions during lifecycle flows, not reset.
|
||||
4. Update cartridge loading to initialize only the selected VM session.
|
||||
5. Split `VmFacade` into:
|
||||
- session-targeted VM execution/inspection methods;
|
||||
- global render/runtime authority methods.
|
||||
6. Delete compatibility methods that accept `&mut VirtualMachine` when no remaining production callsite exists.
|
||||
7. Add tests or assertions proving no production code path initializes or ticks a global firmware VM.
|
||||
8. Run full affected test suites and clippy.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- `Firmware` no longer owns `pub vm: VirtualMachine`.
|
||||
- `PrometeuContext` no longer carries a VM reference.
|
||||
- `LoadCartridgeStep` initializes only session-owned VM context.
|
||||
- `GameRunningStep` and VM-backed `ShellRunningStep` tick only sessions.
|
||||
- Debugger, stats, and host runner access active session state or global render services explicitly.
|
||||
- `rg "firmware\\.vm|ctx\\.vm|legacy_vm|os\\.vm\\(\\)\\.initialize\\(|os\\.vm\\(\\)\\.tick\\("` finds no production runtime dependency on the legacy global VM path.
|
||||
- Tests continue to prove Game resident + VM Shell coexistence.
|
||||
|
||||
## Tests
|
||||
|
||||
- `cargo test -p prometeu-system`
|
||||
- `cargo test -p prometeu-firmware`
|
||||
- `cargo test -p prometeu-host-desktop-winit`
|
||||
- `cargo clippy -p prometeu-system -p prometeu-firmware -p prometeu-host-desktop-winit --all-targets -- -D warnings`
|
||||
- Add or update tests for:
|
||||
- reset clears session-owned VM contexts appropriately;
|
||||
- direct boot creates session-owned VM context;
|
||||
- debug boot uses session-owned VM context;
|
||||
- no global VM tick path remains.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `crates/console/prometeu-firmware/src/firmware/firmware.rs`
|
||||
- `crates/console/prometeu-firmware/src/firmware/prometeu_context.rs`
|
||||
- `crates/console/prometeu-firmware/src/firmware/firmware_step_*.rs`
|
||||
- `crates/console/prometeu-system/src/os/facades/sessions.rs`
|
||||
- `crates/console/prometeu-system/src/os/facades/vm.rs`
|
||||
- `crates/host/prometeu-host-desktop-winit/src/debugger.rs`
|
||||
- `crates/host/prometeu-host-desktop-winit/src/runner.rs`
|
||||
- `crates/host/prometeu-host-desktop-winit/src/stats.rs`
|
||||
@@ -1,96 +0,0 @@
|
||||
---
|
||||
id: PLN-0156
|
||||
ticket: foreground-stack-game-pause-shell-vm-backed
|
||||
title: Harden VM Session Lifecycle Error Boundaries
|
||||
status: done
|
||||
created: 2026-07-05
|
||||
ref_decisions: [DEC-0038]
|
||||
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
DEC-0038 makes VM session services part of the runtime ownership boundary. Some current session creation paths still use `expect` for lifecycle failures and missing task/process/session invariants. That is acceptable for short-term scaffolding, but session services should expose typed errors at operational boundaries so callers can choose controlled crash, rejection, or recovery behavior.
|
||||
|
||||
## Objective
|
||||
|
||||
Replace operational `expect`/panic paths in VM session creation/loading with typed errors and controlled firmware outcomes. Keep internal invariant assertions only where impossible states have already been proven by prior checks.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Source decision: DEC-0038.
|
||||
- Builds on PLN-0148 through PLN-0152.
|
||||
- Can be implemented before or after PLN-0154.
|
||||
- Should be implemented before broadening VM session scheduling or adding background-capable processes.
|
||||
|
||||
## Scope
|
||||
|
||||
- Add or extend typed errors for session/lifecycle operations:
|
||||
- lifecycle rejection while creating Game/Shell task;
|
||||
- missing task for session creation;
|
||||
- missing process for session creation;
|
||||
- duplicate session;
|
||||
- VM-backed session missing during cartridge initialization;
|
||||
- foreground Shell already exists.
|
||||
- Convert `SessionsFacade::create_vm_shell_task` to a fallible equivalent and keep an infallible wrapper only for test/setup code if needed.
|
||||
- Convert `create_vm_session_for_task` to avoid `expect` for task/process lookup.
|
||||
- Convert `initialize_session_cartridge` to return typed missing-session errors instead of panicking.
|
||||
- Map session/lifecycle errors into controlled `CrashReport` or launch rejection behavior in firmware.
|
||||
- Preserve existing V1 policy:
|
||||
- one resident Game;
|
||||
- one foreground Shell;
|
||||
- no Game-to-Game switching;
|
||||
- native Shell creates no VM session.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Do not change DEC-0038 ownership semantics.
|
||||
- Do not add background execution.
|
||||
- Do not redesign the foreground stack.
|
||||
- Do not hide programmer invariants behind overly broad error swallowing.
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Introduce a `SessionError` or extend `VmSessionError` with operational cases that cross facade boundaries.
|
||||
2. Update `SessionsFacade` methods:
|
||||
- `try_create_vm_game_task`;
|
||||
- new `try_create_vm_shell_task`;
|
||||
- `load_vm_cartridge`;
|
||||
- `create_vm_session_for_task`;
|
||||
- `initialize_session_cartridge`.
|
||||
3. Update firmware loading paths to map typed session errors into:
|
||||
- controlled `CrashReport::VmPanic` for unrecoverable internal failures;
|
||||
- logged rejection and no state transition for unsupported lifecycle transitions where appropriate.
|
||||
4. Update tests that currently rely on panics or infallible creation.
|
||||
5. Add focused tests for:
|
||||
- duplicate foreground Shell rejection during VM Shell load;
|
||||
- missing task/process session creation errors;
|
||||
- missing VM session during initialization;
|
||||
- native Shell still creates no VM session.
|
||||
6. Run system, firmware, host tests and clippy.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- VM session facade operational failures are represented by typed errors.
|
||||
- `create_vm_shell_task` has a fallible path used by production cartridge loading.
|
||||
- VM Shell load does not panic when lifecycle rejects the Shell; it returns a controlled error/outcome.
|
||||
- Missing task/process/session conditions in session services return typed errors.
|
||||
- Existing tests for resident Game, native Shell, VM Shell, and Game/Shell coexistence still pass.
|
||||
- No new broad `unwrap`/`expect` appears in production session/lifecycle paths.
|
||||
|
||||
## Tests
|
||||
|
||||
- `cargo test -p prometeu-system`
|
||||
- `cargo test -p prometeu-firmware`
|
||||
- `cargo test -p prometeu-host-desktop-winit`
|
||||
- `cargo clippy -p prometeu-system -p prometeu-firmware -p prometeu-host-desktop-winit --all-targets -- -D warnings`
|
||||
- Add tests for controlled errors from session creation/loading edge cases.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `crates/console/prometeu-system/src/os/facades/sessions.rs`
|
||||
- `crates/console/prometeu-system/src/services/vm_session.rs`
|
||||
- `crates/console/prometeu-system/src/os/lifecycle.rs`
|
||||
- `crates/console/prometeu-firmware/src/firmware/firmware_step_load_cartridge.rs`
|
||||
- `crates/console/prometeu-firmware/src/firmware/firmware_step_hub_home.rs`
|
||||
- Related system and firmware tests
|
||||
Reference in New Issue
Block a user