implements PLN-0132

This commit is contained in:
2026-07-03 17:23:49 +01:00
parent 46b2fae514
commit f49accc796
5 changed files with 79 additions and 2 deletions
+32
View File
@@ -18,6 +18,9 @@ enum BootTarget {
This is a firmware/host orchestration contract, not a guest-visible ABI.
The local Home games library is not a separate firmware boot target. It is host
configuration consumed by the Hub profile after boot.
## 2 Boot Modes
### Hub
@@ -27,6 +30,10 @@ When the boot target is `Hub`:
- firmware boots into the Hub flow;
- no cartridge is auto-launched.
If the host also provides `--games-root <dir>`, the Hub may discover and render
valid Game cartridges from that root. Selecting one is a system-owned Home
action that requests cartridge loading after the Hub is already running.
### Cartridge
When the boot target is `Cartridge`:
@@ -59,6 +66,7 @@ Typical host-facing boot intents are:
- default start -> enter Hub;
- run cartridge -> boot with cartridge target;
- debug cartridge -> boot with cartridge target plus debug mode parameters.
- games-root start -> enter Hub with a local Game library for Home.
The CLI is an entry surface for boot target selection; the firmware contract remains the same underneath.
@@ -67,6 +75,30 @@ direct cartridge boot surfaces. Direct boot is not requested by guest bytecode
through a `system.run_cart` syscall or any other app-callable cartridge boot
ABI.
`--run <cart>` and `--debug <cart>` are direct cartridge boot profiles. They
select one cartridge before normal Hub/Home interaction and remain independent
from the local library.
`--games-root <dir>` is a Hub/Home library configuration. It does not
auto-launch a cartridge and does not create a guest-visible launch API.
The v1 games root contract is:
- the root contains directory cartridges as immediate child directories;
- recursive discovery is not performed;
- only valid cartridges whose manifest declares `app_mode: "Game"` are listed;
- Shell/System apps, packaged `.pmc` cartridges, remote catalogs, marketplace
metadata, search, icons, and rich presentation are outside this profile;
- invalid candidates are logged and omitted from the Home list;
- Home entries may display only `title`, `app_id`, and `app_version`;
- selecting a Home entry requests firmware/SystemOS loading for that cartridge
and transitions through `LoadCartridge`;
- launch failure leaves or returns the machine to Home and records an error.
Game-to-game switching after a game is already active is not part of this boot
profile. That orchestration belongs to the foreground/home and cartridge switch
contracts.
## 5 Firmware State Relationship
Boot target selection feeds into firmware states such as: