prometeu-runtime/discussion/workflow/plans/PLN-0132-specify-games-root-home-launch-contract.md

id	ticket	title	status	created	ref_decisions	tags
PLN-0132	system-run-cart	Specify Games Root Home Launch Contract	done	2026-07-03	DEC-0036

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 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 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 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 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