prometeu-runtime/discussion/workflow/decisions/DEC-0036-systemos-games-root-and-home-game-launch.md

id	ticket	title	status	created	ref_agenda	tags
DEC-0036	system-run-cart	SystemOS Games Root and Home Game Launch	accepted	2026-07-03	AGD-0045

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.