implements PLN-0132
This commit is contained in:
@@ -39,6 +39,10 @@ The VM does not own the machine lifecycle. Firmware does.
|
||||
`Hub`, `Task(TaskId)`, and `Overlay`.
|
||||
- **Shell task window**: a `WindowManager` window whose owner is
|
||||
`WindowOwner::Task(TaskId)`.
|
||||
- **Games root**: a host-provided local directory used by Hub/Home to discover
|
||||
Game directory cartridges.
|
||||
- **Library entry**: an internal catalog record retained by Hub/SystemOS for a
|
||||
discovered cartridge.
|
||||
|
||||
## 3 POS Responsibilities
|
||||
|
||||
@@ -65,9 +69,20 @@ PrometeuHub is responsible for:
|
||||
- reading cartridge metadata needed for launch decisions;
|
||||
- deciding launch behavior based on `AppMode`;
|
||||
- managing the system window surface for system-mode apps.
|
||||
- presenting the host-provided local games library when `--games-root <dir>` is
|
||||
configured;
|
||||
- emitting system-owned launch actions for selected Home entries.
|
||||
|
||||
The Hub does not execute bytecode directly. It always delegates execution setup to POS.
|
||||
|
||||
For v1, the local games library is Game-only. Hub/Home must not expose Shell or
|
||||
System cartridges from the games root. The internal library entry must retain
|
||||
the loaded manifest data, `title`, `app_id`, `app_version`, the cartridge path,
|
||||
and discovery metadata such as a timestamp or equivalent discovery marker.
|
||||
|
||||
The Home UI may display only `title`, `app_id`, and `app_version`. Path and
|
||||
operational metadata may remain internal.
|
||||
|
||||
## 5 App Modes
|
||||
|
||||
### Game
|
||||
@@ -154,6 +169,16 @@ If VM initialization fails, firmware transitions to the crash path.
|
||||
|
||||
POS selects the cartridge and its execution context, but the cartridge's initial callable is not chosen by firmware metadata. Execution starts from the cartridge boot protocol defined in [`13-cartridge.md`](13-cartridge.md), currently `func_id = 0`.
|
||||
|
||||
When Home launches a discovered Game entry, the request is a system-owned action
|
||||
from PrometeuHub to POS/firmware. Firmware must load the selected cartridge
|
||||
through the normal cartridge loader and transition to `LoadCartridge` on
|
||||
success. This path must not use a guest syscall and must not reintroduce
|
||||
userland `run_cart`.
|
||||
|
||||
If the selected cartridge cannot be loaded, firmware must leave or return the
|
||||
machine in the Hub/Home flow and record the failure through diagnostics or
|
||||
logging. A polished Home error surface is not required by v1.
|
||||
|
||||
## 8 Firmware States
|
||||
|
||||
The current firmware state model includes:
|
||||
|
||||
@@ -175,10 +175,30 @@ Runtime loading policy:
|
||||
|
||||
This is the working runtime/dev form used by the current loader.
|
||||
|
||||
Directory cartridges are also the only form discovered by the v1 local Home
|
||||
games library. When a host provides `--games-root <dir>`, discovery scans only
|
||||
immediate child directories under that root. Each child directory is a candidate
|
||||
cartridge.
|
||||
|
||||
For the v1 Home games library:
|
||||
|
||||
- a candidate must have a valid `manifest.json`;
|
||||
- the manifest must declare `app_mode: "Game"`;
|
||||
- the library retains the loaded manifest data, `title`, `app_id`,
|
||||
`app_version`, the internal cartridge path, and discovery metadata;
|
||||
- invalid candidates are logged or reported as diagnostics and omitted from the
|
||||
Home list;
|
||||
- valid non-Game cartridges are omitted from the Game library.
|
||||
|
||||
Discovery reads metadata for cataloging. It does not replace the normal
|
||||
cartridge loader used when firmware starts the selected cartridge.
|
||||
|
||||
### Packaged `.pmc` form
|
||||
|
||||
This form is recognized conceptually by the loader boundary, but its actual load path is not implemented yet.
|
||||
|
||||
Packaged `.pmc` cartridges are not discovered by the v1 Home games library.
|
||||
|
||||
The cartridge spec therefore distinguishes:
|
||||
|
||||
- supported current load form;
|
||||
|
||||
@@ -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:
|
||||
|
||||
Reference in New Issue
Block a user