Foreground Stack, Game Pause, and VM-Backed Shell Coexistence
This commit is contained in:
@@ -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`.
|
||||
+104
@@ -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.
|
||||
Reference in New Issue
Block a user