Foreground Stack, Game Pause, and VM-Backed Shell Coexistence

This commit is contained in:
2026-07-03 22:52:08 +01:00
parent 4bc9ce2b73
commit 126bffa37d
21 changed files with 1023 additions and 1347 deletions
@@ -1,90 +0,0 @@
---
id: PLN-0129
ticket: system-run-cart
title: Remove Userland Run Cart ABI Surface
status: done
created: 2026-07-03
ref_decisions: [DEC-0035]
tags: []
---
## Briefing
`DEC-0035` removes `system.run_cart` from the userland guest ABI. This plan
covers the public ABI, syscall registry/declaration surface, generated metadata,
and documentation/spec propagation. It does not change runtime dispatch behavior
or direct boot tests; those are covered by `PLN-0130` and `PLN-0131`.
## Objective
Remove `system.run_cart` from every app-callable/userland ABI surface while
preserving non-guest direct boot entrypoints.
## Dependencies
- Source decision: `DEC-0035`.
- Must stay scoped away from `AGD-0041` and `AGD-0044`.
- Coordinate with `PLN-0130` so runtime dispatch does not retain a callable
success path after the declaration is removed.
## Scope
- Remove or retire `Syscall::SystemRunCart` from userland-visible syscall
declarations in `crates/console/prometeu-hal/src/syscalls.rs`.
- Remove the `system.run_cart` registry entry from
`crates/console/prometeu-hal/src/syscalls/domains/system.rs` and
`crates/console/prometeu-hal/src/syscalls/registry.rs`, unless implementation
discovers an internal-only registry distinct from guest ABI.
- Remove generated/static bytecode or VM-facing declarations that expose
`system.run_cart`, including known references in
`crates/console/prometeu-bytecode/src/model.rs` and
`crates/console/prometeu-vm/src/virtual_machine.rs` if they include it.
- Update docs/specs that mention `system.run_cart` as app-callable.
- Update `AGD-0004` references only if they become factually misleading after
removal; do not close or reinterpret that agenda.
## Non-Goals
- Do not implement `Home -> another Game`.
- Do not add a replacement app navigation syscall.
- Do not implement `.pmc`.
- Do not change direct host/CLI/debug boot behavior.
- Do not add compatibility stubs for obsolete guest code.
## Execution Method
1. Search for `SystemRunCart`, `run_cart`, and `"system", "run_cart"` across
`crates/`, `docs/`, and `discussion/`.
2. Remove `system.run_cart` from userland syscall domain declarations and
lookup/name registries.
3. Remove generated/static guest-facing metadata entries that advertise
`system.run_cart`.
4. Update docs/specs to state that cartridges are booted by host/system paths,
not by guest syscall.
5. Compile the workspace or targeted crates to find stale references.
## Acceptance Criteria
- No userland ABI declaration advertises `system.run_cart`.
- No generated guest metadata exposes `run_cart` as callable.
- Documentation/spec text no longer describes app-callable cartridge boot.
- Any retained code path is clearly internal-only and is not reachable through
guest syscall lookup.
## Tests
- Add or update syscall registry tests to assert `system.run_cart` is absent
from the public/userland registry.
- Run targeted tests for `prometeu-hal`, `prometeu-bytecode`, and
`prometeu-vm` if available.
- Run repository validation commands used for syscall declaration consistency.
## Affected Artifacts
- `crates/console/prometeu-hal/src/syscalls.rs`
- `crates/console/prometeu-hal/src/syscalls/domains/system.rs`
- `crates/console/prometeu-hal/src/syscalls/registry.rs`
- `crates/console/prometeu-bytecode/src/model.rs`
- `crates/console/prometeu-vm/src/virtual_machine.rs`
- `docs/specs/runtime/`
- `discussion/workflow/agendas/AGD-0004-system-fault-semantics-and-control-surface.md`
@@ -1,79 +0,0 @@
---
id: PLN-0130
ticket: system-run-cart
title: Remove Runtime Run Cart Stub Dispatch
status: done
created: 2026-07-03
ref_decisions: [DEC-0035]
tags: []
---
## Briefing
`DEC-0035` forbids a callable userland `system.run_cart` stub. This plan covers
runtime and VM dispatch cleanup so obsolete calls cannot silently succeed.
Public ABI removal is handled by `PLN-0129`; direct boot preservation is handled
by `PLN-0131`.
## Objective
Remove the runtime no-op dispatch path for `SystemRunCart` and ensure stale or
obsolete userland attempts fail explicitly rather than returning success.
## Dependencies
- Source decision: `DEC-0035`.
- Depends on the ABI direction in `PLN-0129`, but can be implemented in the same
PR if the public enum/registry removal and dispatch cleanup move together.
## Scope
- Remove the `Syscall::SystemRunCart => return Ok(())` path from
`crates/console/prometeu-system/src/services/vm_runtime/dispatch.rs`.
- Update any match arms made unreachable or obsolete by removing
`SystemRunCart`.
- Ensure stale numeric syscall ids or stale bytecode declarations fail with the
repository's existing unknown/invalid syscall behavior.
- Add negative coverage for userland attempts to invoke the removed operation,
using the closest existing VM runtime syscall tests.
## Non-Goals
- Do not implement a replacement navigation operation.
- Do not implement the `Home -> another Game` orchestrator.
- Do not alter direct host/CLI/debug cartridge boot paths.
- Do not change `system.has_cart` behavior unless required by compile fallout.
## Execution Method
1. Inspect `dispatch.rs` for all `SystemRunCart` match arms.
2. Remove the no-op success path and any unreachable arms tied only to
`SystemRunCart`.
3. If the public enum variant is removed by `PLN-0129`, update exhaustiveness
and registry mapping accordingly.
4. Add or update VM runtime tests that demonstrate `system.run_cart` is not
callable from guest/userland.
5. Run targeted runtime tests and compile checks.
## Acceptance Criteria
- There is no runtime path where a guest `system.run_cart` call returns `Ok(())`.
- Stale/obsolete attempts fail explicitly through existing invalid syscall or
declaration validation behavior.
- `system.has_cart` and unrelated system syscalls keep their current behavior.
- Runtime dispatch remains exhaustive and clear after removing `SystemRunCart`.
## Tests
- Add a negative test in `crates/console/prometeu-system/src/services/vm_runtime`
for stale userland `run_cart` attempts, if the test harness can express it.
- Run `cargo test` for `prometeu-system` and any impacted syscall crates.
- Run a workspace compile/test command if targeted tests reveal cross-crate enum
fallout.
## Affected Artifacts
- `crates/console/prometeu-system/src/services/vm_runtime/dispatch.rs`
- `crates/console/prometeu-system/src/services/vm_runtime/tests.rs`
- `crates/console/prometeu-hal/src/syscalls.rs`
- `crates/console/prometeu-hal/src/syscalls/registry.rs`
@@ -1,83 +0,0 @@
---
id: PLN-0131
ticket: system-run-cart
title: Preserve Direct Cartridge Boot Coverage
status: done
created: 2026-07-03
ref_decisions: [DEC-0035]
tags: []
---
## Briefing
`DEC-0035` removes userland `system.run_cart`, but direct cartridge boot remains
mandatory for development, debugging, automated tests, and future single-game
launch scenarios. This plan protects that path while the guest syscall is
removed.
## Objective
Preserve and test host/CLI/debug direct cartridge boot without relying on a
guest syscall.
## Dependencies
- Source decision: `DEC-0035`.
- Can be implemented after or alongside `PLN-0129` and `PLN-0130`.
- Must not depend on `.pmc`, app catalog, launcher UX, `AGD-0041`, or
`AGD-0044`.
## Scope
- Identify direct boot entrypoints in `crates/tools/prometeu-cli/src/main.rs`,
`crates/host/prometeu-host-desktop-winit/src/lib.rs`,
`crates/host/prometeu-host-desktop-winit/src/debugger.rs`, and firmware
cartridge loading code.
- Add or preserve tests showing a cartridge can be loaded directly into
firmware/runtime from host or CLI paths.
- Ensure these paths do not call or require `system.run_cart`.
- Document the distinction between direct boot and guest navigation where
runtime specs describe boot behavior.
## Non-Goals
- Do not implement `Home -> another Game`.
- Do not add app-callable navigation.
- Do not require `.pmc`.
- Do not redesign cartridge loader internals beyond what is required to keep
direct boot working.
## Execution Method
1. Trace the CLI/debug direct boot path from cartridge path argument through
loader, firmware `load_cartridge`, and runtime initialization.
2. Add regression tests at the lowest practical layer proving direct boot still
reaches `GameRunning` for a valid game cartridge.
3. Add a guard or assertion that direct boot does not depend on `system.run_cart`
metadata.
4. Update docs/specs to describe direct boot as host/system-controlled.
5. Run targeted CLI/firmware/host tests.
## Acceptance Criteria
- A valid game cartridge can still boot directly from host/CLI/debug paths.
- Direct boot does not depend on `system.run_cart` being in the guest syscall
registry.
- Existing debugger/handshake metadata that reports cartridge info still works.
- The direct boot behavior is documented as host/system entry, not guest ABI.
## Tests
- Add or preserve firmware tests around `load_cartridge` and `GameRunning`.
- Add or preserve host/CLI tests for cartridge path boot when practical.
- Run `cargo test` for `prometeu-firmware`, `prometeu-host-desktop-winit`, and
`prometeu-cli` where available.
## Affected Artifacts
- `crates/tools/prometeu-cli/src/main.rs`
- `crates/host/prometeu-host-desktop-winit/src/lib.rs`
- `crates/host/prometeu-host-desktop-winit/src/debugger.rs`
- `crates/console/prometeu-firmware/src/firmware/firmware.rs`
- `crates/console/prometeu-firmware/src/firmware/firmware_step_load_cartridge.rs`
- `docs/specs/runtime/`
@@ -1,103 +0,0 @@
---
id: PLN-0132
ticket: system-run-cart
title: Specify Games Root Home Launch Contract
status: done
created: 2026-07-03
ref_decisions: [DEC-0036]
tags: []
---
## Briefing
`DEC-0036` establishes a new system-owned game library launch path:
the host receives `--games-root <dir>`, SystemOS/Home lists valid Game
directory cartridges from that root, and selecting one starts the cartridge
through firmware loading rather than a guest syscall.
This plan updates the normative specs before code is changed.
## Objective
Document the v1 games-root and Home launch contract in the canonical runtime
specs so implementation plans cannot drift back into userland `run_cart` or
general app-library semantics.
## Dependencies
- Source decision: `DEC-0036`.
- Prior decision: `DEC-0035`, which removed userland `system.run_cart` and
preserved direct `--run` boot.
- This plan must be completed before `PLN-0133`, `PLN-0134`, and `PLN-0135`.
## Scope
- Update the runtime specs to define `--games-root <dir>` as the v1 local games
library root.
- Specify that discovery scans only immediate child directories.
- Specify that v1 library discovery includes only valid directory cartridges
with `app_mode: Game`.
- Specify that `.pmc`, recursive discovery, Shell/System apps, marketplace
metadata, rich presentation, search, and non-game apps are out of scope.
- Specify the internal library entry contract: loaded manifest data, `title`,
`app_id`, `app_version`, internal cartridge path, and discovery metadata.
- Specify that Home v1 may display only `title`, `app_id`, and `app_version`.
- Specify that selecting a Home game emits a system-owned launch request that
transitions through firmware/SystemOS into `LoadCartridge`.
- Specify that invalid candidates are logged and omitted.
- Specify that launch failure remains or returns to Home and logs the failure.
- Reaffirm that direct `--run <cart>` boot remains independent and unchanged.
## Non-Goals
- No Rust implementation.
- No Home UI changes.
- No `.pmc` discovery or packaged-cartridge spec changes.
- No recursive library layout.
- No return-to-Home behavior for a running Game.
- No Game A -> Home -> Game B orchestration.
- No guest syscall or userland ABI addition.
## Execution Method
1. Update [docs/specs/runtime/14-boot-profiles.md](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/docs/specs/runtime/14-boot-profiles.md) with:
- direct `--run` boot remaining a single-cartridge boot profile;
- `--games-root <dir>` as a SystemOS/Home library profile;
- the distinction between direct boot, Home launch, and future game-switch
orchestration.
2. Update [docs/specs/runtime/12-firmware-pos-and-prometeuhub.md](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/docs/specs/runtime/12-firmware-pos-and-prometeuhub.md) with:
- Home's responsibility to display the local games library;
- the system-owned launch action boundary;
- failure handling that leaves the machine in Home and records an error.
3. Update [docs/specs/runtime/13-cartridge.md](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/docs/specs/runtime/13-cartridge.md) with:
- directory-cartridge discovery requirements for library candidates;
- Game-only filtering by manifest `app_mode`;
- invalid candidate omission and diagnostics.
4. Update [docs/specs/runtime/16-host-abi-and-syscalls.md](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/docs/specs/runtime/16-host-abi-and-syscalls.md) only if needed to reinforce that no guest syscall owns cartridge launch.
5. Keep all spec text in English.
## Acceptance Criteria
- The specs define `--games-root <dir>` and do not describe it as a generic app
root.
- The specs state that v1 scans immediate child directories only.
- The specs state that only valid Game directory cartridges enter the Home list.
- The specs state that Home launch is system-owned and enters `LoadCartridge`.
- The specs preserve `--run <cart>` as a separate direct boot path.
- The specs explicitly exclude `.pmc`, recursive discovery, return-to-Home, and
game-switch orchestration from this implementation slice.
- No spec reintroduces userland `run_cart`.
## Tests
- Run `discussion validate`.
- Run targeted text checks for `--games-root`, `LoadCartridge`, and absence of
`system.run_cart` as an active public launch mechanism in edited specs.
## Affected Artifacts
- `docs/specs/runtime/12-firmware-pos-and-prometeuhub.md`
- `docs/specs/runtime/13-cartridge.md`
- `docs/specs/runtime/14-boot-profiles.md`
- `docs/specs/runtime/16-host-abi-and-syscalls.md`
- `discussion/workflow/plans/PLN-0132-specify-games-root-home-launch-contract.md`
@@ -1,118 +0,0 @@
---
id: PLN-0133
ticket: system-run-cart
title: Implement Games Root Library Discovery
status: done
created: 2026-07-03
ref_decisions: [DEC-0036]
tags: []
---
## Briefing
`DEC-0036` requires a host-provided games root and an expandable internal
library model before Home can render or launch games. This plan implements the
library discovery and host plumbing only; UI launch wiring is handled by
`PLN-0134`.
## Objective
Add a tested games-root discovery model that scans immediate child directory
cartridges, filters to valid Game manifests, records diagnostics for invalid
candidates, and carries enough metadata for Home rendering and later launch.
## Dependencies
- Source decision: `DEC-0036`.
- `PLN-0132` should be completed first so code follows the documented contract.
- Existing cartridge manifest and directory loader behavior in the console
crates.
- Existing host CLI and `HostRunner` boot setup.
## Scope
- Add `--games-root <PATH>` to the desktop host CLI.
- Pass the optional games root into the host runner / firmware initialization
path without changing direct `--run` or `--debug` boot behavior.
- Add a SystemOS-owned games library model for directory cartridge discovery.
- Scan only immediate child directories of the root.
- Read and retain manifest data for each valid candidate.
- Include only candidates whose manifest declares `app_mode: Game`.
- Retain internal cartridge path and operational discovery metadata on each
entry.
- Emit diagnostics for invalid, unreadable, or non-Game candidates and omit
them from the returned entries.
- Keep discovery independent from full cartridge launch: discovery reads
metadata; launch still uses the existing loader in `PLN-0134`.
## Non-Goals
- No Home list rendering.
- No click handling or `LoadCartridge` transition.
- No `.pmc` discovery.
- No recursive scan.
- No Shell/System app catalog.
- No marketplace metadata, icons, search, sorting UI, or polished errors.
- No new guest syscall.
## Execution Method
1. Introduce a library/discovery module in the SystemOS side, preferably under
`crates/console/prometeu-system/src/services/` unless the existing module
layout has a more local owner.
2. Define an internal entry type with at least:
- loaded cartridge manifest data;
- `title`;
- `app_id`;
- `app_version`;
- internal cartridge path;
- discovery metadata, using `SystemTime` or another explicit discovery
marker.
3. Define discovery diagnostics that can be logged by the caller and asserted in
tests.
4. Implement a scanner that:
- accepts an optional root path;
- returns an empty library when no root is configured;
- iterates only immediate child directories;
- parses `manifest.json` using structured manifest types, not ad hoc string
matching;
- filters to `app_mode: Game`;
- sorts entries deterministically for stable Home presentation and tests.
5. Add `--games-root <PATH>` to
[crates/host/prometeu-host-desktop-winit/src/lib.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/host/prometeu-host-desktop-winit/src/lib.rs)
and pass the path into
[crates/host/prometeu-host-desktop-winit/src/runner.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/host/prometeu-host-desktop-winit/src/runner.rs).
6. Store or expose the discovered library to firmware/SystemOS in a way that
`PLN-0134` can consume without re-scanning inside the Home click path.
7. Add focused unit tests using temporary cartridge roots with:
- one valid Game directory cartridge;
- one valid non-Game cartridge;
- one invalid directory;
- one nested directory that must not be discovered.
## Acceptance Criteria
- `--games-root <PATH>` is accepted by the desktop host CLI.
- Absence of `--games-root` leaves existing Hub boot behavior unchanged.
- Direct `--run <cart>` and `--debug <cart>` behavior remains unchanged.
- Discovery returns only immediate valid Game directory cartridges.
- Each library entry retains manifest data, path, title, app id, app version,
and discovery metadata.
- Invalid candidates are represented in diagnostics and excluded from entries.
- Discovery does not fully load or boot cartridge programs.
## Tests
- Add and run focused games-library discovery tests in the owning console crate.
- Run `cargo test -p prometeu-system` if the library lives in
`prometeu-system`.
- Run `cargo test -p prometeu-host-desktop-winit` for CLI/runner plumbing.
- Run `discussion validate`.
## Affected Artifacts
- `crates/console/prometeu-system/src/services/`
- `crates/console/prometeu-system/src/lib.rs` or module exports as needed
- `crates/host/prometeu-host-desktop-winit/src/lib.rs`
- `crates/host/prometeu-host-desktop-winit/src/runner.rs`
- `discussion/workflow/plans/PLN-0133-implement-games-root-library-discovery.md`
@@ -1,104 +0,0 @@
---
id: PLN-0134
ticket: system-run-cart
title: Wire Home Game List Launch Flow
status: done
created: 2026-07-03
ref_decisions: [DEC-0036]
tags: []
---
## Briefing
After `PLN-0133`, SystemOS can discover a local Game library but Home still
does not present or launch those entries. This plan wires the discovered
library into Prometeu Hub/Home and routes a selected game to firmware
`LoadCartridge`.
## Objective
Make Home display a minimal clickable games list and launch the selected Game
through a system-owned firmware/SystemOS path, without reintroducing userland
`run_cart`.
## Dependencies
- Source decision: `DEC-0036`.
- `PLN-0132` for documented contract.
- `PLN-0133` for `--games-root` plumbing and the internal library entry model.
- Existing Prometeu Hub Home profile and firmware state transitions.
## Scope
- Provide the discovered games library to Prometeu Hub/Home.
- Render a minimal Home list showing `title`, `app_id`, and `app_version`.
- Add Home hit-testing/click handling for game entries.
- Extend the system profile action model with a system-owned game launch action.
- Handle that action in firmware/SystemOS by loading the selected cartridge via
the existing cartridge loader and entering `LoadCartridge`.
- On load failure, log/record the error and keep or return the machine to Home.
- Preserve existing native shell launch behavior.
## Non-Goals
- No polished launcher UI.
- No icons, screenshots, search, filtering, or marketplace metadata.
- No return-to-Home while a Game is running.
- No Game A -> Home -> Game B foreground orchestration.
- No `.pmc` launch support.
- No guest syscall.
- No direct-boot behavior changes.
## Execution Method
1. Extend the SystemOS/Hub action type currently represented by
`SystemProfileAction::LaunchNativeShell` with a game-launch action that
carries a stable reference to the selected library entry or cartridge path.
2. Update the Prometeu Hub state in
[crates/console/prometeu-system/src/programs/prometeu_hub.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system/src/programs/prometeu_hub.rs)
or its local modules to accept the discovered game entries.
3. Render the Home games list with stable dimensions and simple clickable rows.
Rows must display only `title`, `app_id`, and `app_version` for v1.
4. Add hit-testing so selecting a row emits the game-launch action immediately.
5. Update
[crates/console/prometeu-firmware/src/firmware/steps/firmware_step_hub_home.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-firmware/src/firmware/steps/firmware_step_hub_home.rs)
to consume the new action.
6. In the firmware action handler:
- call the existing cartridge loader for the selected path;
- on success, return `FirmwareState::LoadCartridge(...)`;
- on failure, log/record the error and remain in the Home path.
7. Ensure shell launch still works exactly as before.
8. Add unit or integration tests for:
- Home list presentation data;
- click-to-action emission;
- firmware action handling success;
- firmware action handling failure.
## Acceptance Criteria
- Starting the host with `--games-root <dir>` exposes valid Game entries in
Home.
- The Home list displays `title`, `app_id`, and `app_version`.
- Clicking a listed Game routes through a system action and enters
`LoadCartridge`.
- The launch path does not use a guest syscall and does not mention
`system.run_cart`.
- Invalid or failing launch paths remain in Home and record an error.
- Existing native shell Home actions continue to work.
- Direct `--run` remains separate and unchanged.
## Tests
- Run `cargo test -p prometeu-system` for Hub action and presentation behavior.
- Run `cargo test -p prometeu-firmware` for firmware transition behavior.
- Run `cargo test -p prometeu-host-desktop-winit` if runner integration changes.
- Run `discussion validate`.
## Affected Artifacts
- `crates/console/prometeu-system/src/programs/prometeu_hub.rs`
- `crates/console/prometeu-system/src/services/`
- `crates/console/prometeu-firmware/src/firmware/steps/firmware_step_hub_home.rs`
- `crates/console/prometeu-firmware/src/firmware/firmware.rs`
- `crates/host/prometeu-host-desktop-winit/src/runner.rs`
- `discussion/workflow/plans/PLN-0134-wire-home-game-list-launch-flow.md`
@@ -1,99 +0,0 @@
---
id: PLN-0135
ticket: system-run-cart
title: Validate Games Root Launch End To End
status: done
created: 2026-07-03
ref_decisions: [DEC-0036]
tags: []
---
## Briefing
`PLN-0132` through `PLN-0134` specify, discover, display, and launch games
from a local games root. This plan closes the slice by adding end-to-end
validation evidence and manual smoke instructions for the product behavior the
user wants: point the SO at a directory, click a listed game, and boot it.
## Objective
Prove the complete `--games-root -> Home list -> click -> LoadCartridge ->
GameRunning` path while preserving direct `--run` boot and the absence of
userland `run_cart`.
## Dependencies
- Source decision: `DEC-0036`.
- `PLN-0132`, `PLN-0133`, and `PLN-0134` must be complete.
- Existing test cartridge fixtures, especially `test-cartridges/stress-console`.
## Scope
- Add automated integration coverage for the full games-root Home launch path
where the existing host/firmware test seams allow it.
- Add or document a minimal local games-root fixture using existing directory
cartridges.
- Validate invalid-candidate omission at the end-to-end boundary.
- Validate direct `--run` still works after games-root wiring.
- Capture manual smoke-test commands for release-mode functional verification.
## Non-Goals
- No new product UI polish.
- No screenshot automation unless the existing test harness already supports it
cleanly.
- No return-to-Home after a running Game.
- No Game A -> Home -> Game B orchestration.
- No `.pmc` validation.
- No broad performance tuning beyond confirming release-mode smoke behavior.
## Execution Method
1. Add an integration-style firmware or host test that constructs a games root
with a valid Game directory cartridge and boots to Hub/Home with that root.
2. Drive the Home selection path through the same action path used by user
input, not by calling the cartridge loader directly.
3. Assert that the machine reaches `LoadCartridge` or `GameRunning`, depending
on the most stable observable state available in the test harness.
4. Add a negative case with an invalid candidate and assert it is omitted or
reported as a diagnostic without appearing in Home.
5. Add a regression assertion that no public guest syscall named
`system.run_cart` is required by this path.
6. Re-run direct boot tests or add a small regression test proving
`--run test-cartridges/stress-console` remains independent from
`--games-root`.
7. Record manual smoke commands in the relevant spec or developer-facing doc:
- `cargo run --release -p prometeu-host-desktop-winit -- --games-root test-cartridges`
- `cargo run --release -p prometeu-host-desktop-winit -- --run test-cartridges/stress-console`
## Acceptance Criteria
- Automated tests cover a valid games-root Home launch path.
- Automated tests cover invalid candidate omission or diagnostics at the
end-to-end boundary.
- Automated or documented validation proves direct `--run` still works.
- Manual smoke instructions use release mode for realistic interactive speed.
- Validation evidence shows no guest syscall participates in launch.
- `discussion validate` passes.
## Tests
- Run `cargo test -p prometeu-system`.
- Run `cargo test -p prometeu-firmware`.
- Run `cargo test -p prometeu-host-desktop-winit`.
- Run `cargo test -p prometeu-hal syscalls` to keep the removed syscall surface
guarded.
- Manually smoke test:
`cargo run --release -p prometeu-host-desktop-winit -- --games-root test-cartridges`.
- Manually smoke test:
`cargo run --release -p prometeu-host-desktop-winit -- --run test-cartridges/stress-console`.
- Run `discussion validate`.
## Affected Artifacts
- `crates/console/prometeu-system/`
- `crates/console/prometeu-firmware/`
- `crates/host/prometeu-host-desktop-winit/`
- `crates/console/prometeu-hal/src/syscalls/tests.rs`
- Runtime specs or developer docs containing smoke commands
- `discussion/workflow/plans/PLN-0135-validate-games-root-launch-end-to-end.md`
@@ -0,0 +1,96 @@
---
id: PLN-0136
ticket: foreground-stack-game-pause-shell-vm-backed
title: Route Desktop Home Key Outside Guest Input
status: open
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.
@@ -0,0 +1,116 @@
---
id: PLN-0137
ticket: foreground-stack-game-pause-shell-vm-backed
title: Implement SystemOS Foreground Stack State
status: open
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.
@@ -0,0 +1,114 @@
---
id: PLN-0138
ticket: foreground-stack-game-pause-shell-vm-backed
title: Specify Foreground Pause and Home Contract
status: open
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.
@@ -0,0 +1,106 @@
---
id: PLN-0139
ticket: foreground-stack-game-pause-shell-vm-backed
title: Validate Game Home Shell Game End To End
status: open
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.
@@ -0,0 +1,110 @@
---
id: PLN-0140
ticket: foreground-stack-game-pause-shell-vm-backed
title: Deliver Game Pause Resume and Suspension
status: open
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`.
@@ -0,0 +1,104 @@
---
id: PLN-0141
ticket: foreground-stack-game-pause-shell-vm-backed
title: Integrate Render Audio and Input Pause Boundaries
status: open
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.