implements PLN-0132
This commit is contained in:
parent
46b2fae514
commit
f49accc796
SSH Key Fingerprint:
SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
@ -14,7 +14,7 @@
|
||||
{"type":"discussion","id":"DSC-0001","status":"done","ticket":"legacy-runtime-learn-import","title":"Import legacy runtime learn into discussion lessons","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["migration","tech-debt"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0001","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0001-prometeu-learn-index.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0002","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0002-historical-asset-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0003","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0003-historical-audio-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0004","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0004-historical-cartridge-boot-protocol-and-manifest-authority.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0005","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0005-historical-game-memcard-slots-surface-and-semantics.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0006","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0006-historical-gfx-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0007","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0007-historical-retired-fault-and-input-decisions.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0008","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0008-historical-vm-core-and-assets.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0009","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0009-mental-model-asset-management.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0010","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0010-mental-model-audio.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0011","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0011-mental-model-gfx.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0012","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0012-mental-model-input.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0013","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0013-mental-model-observability-and-debugging.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0014","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0014-mental-model-portability-and-cross-platform.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0015","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0015-mental-model-save-memory-and-memcard.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0016","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0016-mental-model-status-first-and-fault-thinking.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0017","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0017-mental-model-time-and-cycles.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0018","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0018-mental-model-touch.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
|
||||
{"type":"discussion","id":"DSC-0002","status":"done","ticket":"runtime-edge-test-plan","title":"Agenda - Runtime Edge Test Plan","created_at":"2026-03-27","updated_at":"2026-04-21","tags":[],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0037","file":"discussion/lessons/DSC-0002-runtime-edge-test-plan/LSN-0037-domain-gates-must-be-owned-by-the-repository.md","status":"done","created_at":"2026-04-21","updated_at":"2026-04-21"}]}
|
||||
{"type":"discussion","id":"DSC-0003","status":"open","ticket":"packed-cartridge-loader-pmc","title":"Agenda - Packed Cartridge Loader PMC","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0002","file":"AGD-0002-packed-cartridge-loader-pmc.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0004","status":"in_progress","ticket":"system-run-cart","title":"Agenda - System Run Cart","created_at":"2026-03-27","updated_at":"2026-07-03","tags":[],"agendas":[{"id":"AGD-0003","file":"AGD-0003-system-run-cart.md","status":"accepted","created_at":"2026-03-27","updated_at":"2026-07-03"},{"id":"AGD-0045","file":"AGD-0045-systemos-library-root-home-game-launch.md","status":"accepted","created_at":"2026-07-03","updated_at":"2026-07-03"}],"decisions":[{"id":"DEC-0035","file":"DEC-0035-remove-userland-system-run-cart-and-preserve-direct-boot.md","status":"accepted","created_at":"2026-07-03","updated_at":"2026-07-03","ref_agenda":"AGD-0003"},{"id":"DEC-0036","file":"DEC-0036-systemos-games-root-and-home-game-launch.md","status":"accepted","created_at":"2026-07-03","updated_at":"2026-07-03","ref_agenda":"AGD-0045"}],"plans":[{"id":"PLN-0129","file":"PLN-0129-remove-userland-run-cart-abi-surface.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0035"]},{"id":"PLN-0130","file":"PLN-0130-remove-runtime-run-cart-stub-dispatch.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0035"]},{"id":"PLN-0131","file":"PLN-0131-preserve-direct-cartridge-boot-coverage.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0035"]},{"id":"PLN-0132","file":"PLN-0132-specify-games-root-home-launch-contract.md","status":"open","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0036"]},{"id":"PLN-0133","file":"PLN-0133-implement-games-root-library-discovery.md","status":"open","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0036"]},{"id":"PLN-0134","file":"PLN-0134-wire-home-game-list-launch-flow.md","status":"open","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0036"]},{"id":"PLN-0135","file":"PLN-0135-validate-games-root-launch-end-to-end.md","status":"open","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0036"]}],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0004","status":"in_progress","ticket":"system-run-cart","title":"Agenda - System Run Cart","created_at":"2026-03-27","updated_at":"2026-07-03","tags":[],"agendas":[{"id":"AGD-0003","file":"AGD-0003-system-run-cart.md","status":"accepted","created_at":"2026-03-27","updated_at":"2026-07-03"},{"id":"AGD-0045","file":"AGD-0045-systemos-library-root-home-game-launch.md","status":"accepted","created_at":"2026-07-03","updated_at":"2026-07-03"}],"decisions":[{"id":"DEC-0035","file":"DEC-0035-remove-userland-system-run-cart-and-preserve-direct-boot.md","status":"accepted","created_at":"2026-07-03","updated_at":"2026-07-03","ref_agenda":"AGD-0003"},{"id":"DEC-0036","file":"DEC-0036-systemos-games-root-and-home-game-launch.md","status":"accepted","created_at":"2026-07-03","updated_at":"2026-07-03","ref_agenda":"AGD-0045"}],"plans":[{"id":"PLN-0129","file":"PLN-0129-remove-userland-run-cart-abi-surface.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0035"]},{"id":"PLN-0130","file":"PLN-0130-remove-runtime-run-cart-stub-dispatch.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0035"]},{"id":"PLN-0131","file":"PLN-0131-preserve-direct-cartridge-boot-coverage.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0035"]},{"id":"PLN-0132","file":"PLN-0132-specify-games-root-home-launch-contract.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0036"]},{"id":"PLN-0133","file":"PLN-0133-implement-games-root-library-discovery.md","status":"open","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0036"]},{"id":"PLN-0134","file":"PLN-0134-wire-home-game-list-launch-flow.md","status":"open","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0036"]},{"id":"PLN-0135","file":"PLN-0135-validate-games-root-launch-end-to-end.md","status":"open","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0036"]}],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0005","status":"open","ticket":"system-fault-semantics-and-control-surface","title":"Agenda - System Fault Semantics and Control Surface","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0004","file":"AGD-0004-system-fault-semantics-and-control-surface.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0006","status":"open","ticket":"vm-owned-random-service","title":"Agenda - VM-Owned Random Service","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0005","file":"AGD-0005-vm-owned-random-service.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0007","status":"open","ticket":"app-home-filesystem-surface-and-semantics","title":"Agenda - App Home Filesystem Surface and Semantics","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0006","file":"AGD-0006-app-home-filesystem-surface-and-semantics.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
id: PLN-0132
|
||||
ticket: system-run-cart
|
||||
title: Specify Games Root Home Launch Contract
|
||||
status: open
|
||||
status: done
|
||||
created: 2026-07-03
|
||||
ref_decisions: [DEC-0036]
|
||||
tags: []
|
||||
|
||||
@ -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:
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user