157 lines
6.3 KiB
Markdown
157 lines
6.3 KiB
Markdown
---
|
|
id: DEC-0036
|
|
ticket: system-run-cart
|
|
title: SystemOS Games Root and Home Game Launch
|
|
status: accepted
|
|
created: 2026-07-03
|
|
ref_agenda: AGD-0045
|
|
tags: []
|
|
---
|
|
|
|
## Status
|
|
|
|
Accepted.
|
|
|
|
## Contexto
|
|
|
|
`DEC-0035` removed `system.run_cart` from the userland guest ABI and preserved
|
|
direct host/CLI/debug cartridge boot. That decision intentionally did not
|
|
deliver the Home/SO product flow: pointing PROMETEU at a local games directory,
|
|
listing available games in Home, and launching a selected game by user action.
|
|
|
|
This decision defines the first system-owned replacement for userland
|
|
`run_cart`: a local games-root library discovered by the host/SystemOS and
|
|
exposed through a simple Home UI.
|
|
|
|
## Decisao
|
|
|
|
PROMETEU MUST support a host-provided games library root through
|
|
`--games-root <dir>`.
|
|
|
|
The games root is a directory containing game cartridge directories as immediate
|
|
children. V1 MUST scan only immediate child directories. Recursive discovery is
|
|
out of scope.
|
|
|
|
The v1 games library MUST include only cartridges whose manifest declares
|
|
`app_mode: Game`. Shell/System apps, `.pmc` packages, remote catalogs,
|
|
marketplace/distribution metadata, rich icons, search, and non-game apps are out
|
|
of scope.
|
|
|
|
The library MUST produce expandable internal entries, not UI-only summaries.
|
|
Each entry MUST retain enough internal data to launch the cartridge and to grow
|
|
as a catalog model. At minimum, each entry MUST include:
|
|
|
|
- loaded manifest data;
|
|
- `title`;
|
|
- `app_id`;
|
|
- `app_version`;
|
|
- internal cartridge path;
|
|
- operational discovery metadata, including a timestamp or equivalent discovery
|
|
marker.
|
|
|
|
The Home UI v1 SHOULD display only `title`, `app_id`, and `app_version`. It MAY
|
|
hide path and operational metadata.
|
|
|
|
Invalid cartridge candidates MUST be logged and omitted from the Home game list.
|
|
|
|
Selecting a listed Game in Home MUST immediately request a system-owned launch
|
|
through firmware/SystemOS, resulting in `LoadCartridge` for that cartridge. This
|
|
MUST NOT use a guest syscall and MUST NOT reintroduce userland `run_cart`.
|
|
|
|
If launch fails, the machine MUST return to or remain in Home and record an
|
|
error/log. A polished error UI is out of scope.
|
|
|
|
Booting directly with `--run <cart>` MUST remain separate and unchanged.
|
|
|
|
Returning from a running Game to Home is outside this decision and belongs to
|
|
`AGD-0041`. Switching from `Game A -> Home -> Game B` after a game is already
|
|
active belongs to `DSC-0043 / AGD-0044`.
|
|
|
|
## Rationale
|
|
|
|
The previous `run_cart` surface was wrong because it made cartridge launch look
|
|
like an app/userland capability. The desired behavior is still valid, but the
|
|
authority must live in the system: Home presents available games and the
|
|
firmware/SystemOS loads the selected cartridge.
|
|
|
|
Using `--games-root` keeps the v1 product model honest: this is a local game
|
|
library, not a general app root. Other app types can be introduced later without
|
|
forcing the first launcher model to pretend it is a full marketplace.
|
|
|
|
Immediate child scanning keeps discovery deterministic and testable. `.pmc` and
|
|
recursive layouts can be added after the directory-cartridge path is proven.
|
|
|
|
An expandable entry model avoids prematurely freezing the UI shape as the data
|
|
model. The UI is intentionally simple, but the catalog model needs room for
|
|
future metadata such as package origin, installation/discovery timestamps, rich
|
|
presentation fields, and packaged cartridge details.
|
|
|
|
## Invariantes / Contrato
|
|
|
|
- `--games-root <dir>` is the v1 host argument for a local games library.
|
|
- The games root is Game-only in v1.
|
|
- Discovery scans immediate child directories only.
|
|
- Directory candidates without valid Game cartridge metadata are logged and
|
|
omitted.
|
|
- Library entries are internal catalog records, not direct UI DTOs.
|
|
- The UI v1 displays a simple clickable list and may show only `title`,
|
|
`app_id`, and `app_version`.
|
|
- The internal entry retains cartridge path and loaded manifest data for launch.
|
|
- Home selection is a system action that enters firmware/SystemOS loading. It is
|
|
not a guest syscall.
|
|
- `--run <cart>` direct boot remains independent from `--games-root`.
|
|
- Return-to-Home and game-to-game switching are not implemented by this
|
|
decision.
|
|
|
|
## Impactos
|
|
|
|
- **Host:** add a `--games-root <dir>` argument and pass the resolved root into
|
|
runtime/firmware/SystemOS initialization.
|
|
- **SystemOS / Hub:** add a local game library model and expose entries to Home.
|
|
Home must render a minimal clickable list and emit a system-owned launch
|
|
action for a selected entry.
|
|
- **Firmware:** consume the Home launch action and transition to
|
|
`LoadCartridge` with the selected cartridge path.
|
|
- **Loader:** continue to validate complete directory cartridges. Discovery may
|
|
read manifest metadata, but full launch still uses the existing loader.
|
|
- **Runtime / VM:** no userland ABI is added. No guest syscall participates in
|
|
launch.
|
|
- **Specs / Docs:** document `--games-root`, Game-only v1 discovery, and the
|
|
distinction between direct boot, games library launch, and future game
|
|
switching.
|
|
- **Tests:** cover discovery, invalid omission/logging, Home action emission,
|
|
and the end-to-end path from games root selection to `GameRunning`.
|
|
|
|
## Alternativas Descartadas
|
|
|
|
- **List only, no launch:** rejected because it does not satisfy the product
|
|
goal of starting games from Home.
|
|
- **General app root:** rejected for v1 because Shell/System apps need separate
|
|
lifecycle and UI contracts.
|
|
- **Recursive discovery:** rejected for v1 to keep semantics deterministic.
|
|
- **`.pmc` discovery:** rejected for v1 because packed cartridge loading is a
|
|
separate open agenda.
|
|
- **Game-to-game switch now:** rejected because it depends on foreground and
|
|
cartridge-switch orchestration work in `AGD-0041` and `AGD-0044`.
|
|
|
|
## Referencias
|
|
|
|
- Source agenda: `AGD-0045`
|
|
- Userland run-cart removal: `DEC-0035`
|
|
- Foreground/Home return scope: `AGD-0041`
|
|
- Future cartridge switch orchestration: `DSC-0043 / AGD-0044`
|
|
|
|
## Propagacao Necessaria
|
|
|
|
- Add or update runtime specs for games-root discovery and Home launch.
|
|
- Add host CLI argument plumbing for `--games-root`.
|
|
- Add a catalog/library entry model.
|
|
- Add Hub/Home list rendering and click handling.
|
|
- Add firmware/SystemOS action routing to `LoadCartridge`.
|
|
- Add tests for discovery, invalid candidates, action emission, and
|
|
`games-root -> Home click -> GameRunning`.
|
|
|
|
## Revision Log
|
|
|
|
- 2026-07-03: Initial draft from `AGD-0045`.
|