From f49accc796353bd3fc2da152fffe24f580f60300 Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Fri, 3 Jul 2026 17:23:49 +0100 Subject: [PATCH] implements PLN-0132 --- discussion/index.ndjson | 2 +- ...specify-games-root-home-launch-contract.md | 2 +- .../12-firmware-pos-and-prometeuhub.md | 25 +++++++++++++++ docs/specs/runtime/13-cartridge.md | 20 ++++++++++++ docs/specs/runtime/14-boot-profiles.md | 32 +++++++++++++++++++ 5 files changed, 79 insertions(+), 2 deletions(-) diff --git a/discussion/index.ndjson b/discussion/index.ndjson index b8bebcd9..141796e0 100644 --- a/discussion/index.ndjson +++ b/discussion/index.ndjson @@ -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":[]} diff --git a/discussion/workflow/plans/PLN-0132-specify-games-root-home-launch-contract.md b/discussion/workflow/plans/PLN-0132-specify-games-root-home-launch-contract.md index c0b42a60..7bd714c1 100644 --- a/discussion/workflow/plans/PLN-0132-specify-games-root-home-launch-contract.md +++ b/discussion/workflow/plans/PLN-0132-specify-games-root-home-launch-contract.md @@ -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: [] diff --git a/docs/specs/runtime/12-firmware-pos-and-prometeuhub.md b/docs/specs/runtime/12-firmware-pos-and-prometeuhub.md index a4b90b86..86a25bab 100644 --- a/docs/specs/runtime/12-firmware-pos-and-prometeuhub.md +++ b/docs/specs/runtime/12-firmware-pos-and-prometeuhub.md @@ -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 ` 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: diff --git a/docs/specs/runtime/13-cartridge.md b/docs/specs/runtime/13-cartridge.md index 4c921315..6f8c1158 100644 --- a/docs/specs/runtime/13-cartridge.md +++ b/docs/specs/runtime/13-cartridge.md @@ -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 `, 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; diff --git a/docs/specs/runtime/14-boot-profiles.md b/docs/specs/runtime/14-boot-profiles.md index 134f15f9..826bac52 100644 --- a/docs/specs/runtime/14-boot-profiles.md +++ b/docs/specs/runtime/14-boot-profiles.md @@ -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 `, 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 ` and `--debug ` are direct cartridge boot profiles. They +select one cartridge before normal Hub/Home interaction and remain independent +from the local library. + +`--games-root ` 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: