SystemOS Library Root and Home Game Launch
This commit is contained in:
@@ -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`
|
||||
Reference in New Issue
Block a user