SystemOS Library Root and Home Game Launch

This commit is contained in:
2026-07-03 17:22:35 +01:00
parent 7307870414
commit 46b2fae514
7 changed files with 743 additions and 2 deletions
@@ -0,0 +1,103 @@
---
id: PLN-0132
ticket: system-run-cart
title: Specify Games Root Home Launch Contract
status: open
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`
@@ -0,0 +1,118 @@
---
id: PLN-0133
ticket: system-run-cart
title: Implement Games Root Library Discovery
status: open
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`
@@ -0,0 +1,104 @@
---
id: PLN-0134
ticket: system-run-cart
title: Wire Home Game List Launch Flow
status: open
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`
@@ -0,0 +1,99 @@
---
id: PLN-0135
ticket: system-run-cart
title: Validate Games Root Launch End To End
status: open
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`