prometeu-runtime/discussion/workflow/plans/PLN-0133-implement-games-root-library-discovery.md

id	ticket	title	status	created	ref_decisions	tags
PLN-0133	system-run-cart	Implement Games Root Library Discovery	done	2026-07-03	DEC-0036

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 and pass the path into 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