VM Context Ownership for Resident Game and VM-Backed Shell
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good

This commit is contained in:
2026-07-05 00:36:15 +01:00
parent c34bbaf936
commit 6dc8cb5372
27 changed files with 147 additions and 3008 deletions
@@ -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`.
@@ -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`
@@ -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`
@@ -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
@@ -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