---
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`