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