104 lines
4.7 KiB
Markdown
104 lines
4.7 KiB
Markdown
---
|
|
id: PLN-0132
|
|
ticket: system-run-cart
|
|
title: Specify Games Root Home Launch Contract
|
|
status: done
|
|
created: 2026-07-03
|
|
ref_decisions: [DEC-0036]
|
|
tags: []
|
|
---
|
|
|
|
## 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](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/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](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/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](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/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](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/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`
|