diff --git a/discussion/index.ndjson b/discussion/index.ndjson index 33362bb2..b8bebcd9 100644 --- a/discussion/index.ndjson +++ b/discussion/index.ndjson @@ -1,4 +1,4 @@ -{"type":"meta","next_id":{"DSC":44,"AGD":45,"DEC":36,"PLN":132,"LSN":51,"CLSN":1}} +{"type":"meta","next_id":{"DSC":44,"AGD":46,"DEC":37,"PLN":136,"LSN":51,"CLSN":1}} {"type":"discussion","id":"DSC-0043","status":"open","ticket":"system-os-cartridge-switch-orchestrator","title":"SystemOS Cartridge Switch Orchestrator","created_at":"2026-07-03","updated_at":"2026-07-03","tags":["runtime","os","lifecycle","game","cartridge","architecture"],"agendas":[{"id":"AGD-0044","file":"AGD-0044-systemos-cartridge-switch-orchestrator.md","status":"open","created_at":"2026-07-03","updated_at":"2026-07-03"}],"decisions":[],"plans":[],"lessons":[]} {"type":"discussion","id":"DSC-0039","status":"abandoned","ticket":"render-pipeline-family-and-future-3d","title":"Render Pipeline Family and Future 3D","created_at":"2026-06-04","updated_at":"2026-06-04","tags":["gfx","renderer","runtime","architecture","pipeline"],"agendas":[{"id":"AGD-0039","file":"AGD-0039-render-pipeline-family-and-future-3d.md","status":"abandoned","created_at":"2026-06-04","updated_at":"2026-06-04","_override_reason":"User explicitly chose to close this agenda without a new decision because DSC-0038 already established enough architecture for future extension, and 3D is intentionally deferred."}],"decisions":[],"plans":[],"lessons":[],"_override_reason":"User explicitly chose to close this agenda without a new decision because DSC-0038 already established enough architecture for future extension, and 3D is intentionally deferred."} {"type":"discussion","id":"DSC-0040","status":"done","ticket":"vm-render-parallel-execution-boundary","title":"VM and Render Parallel Execution Boundary","created_at":"2026-06-04","updated_at":"2026-06-06","tags":["runtime","renderer","vm","concurrency","architecture","perf"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0048","file":"discussion/lessons/DSC-0040-vm-render-parallel-execution-boundary/LSN-0048-render-workers-need-a-closed-packet-contract.md","status":"done","created_at":"2026-06-06","updated_at":"2026-06-06"}]} @@ -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"}],"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"}],"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"]}],"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-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/agendas/AGD-0045-systemos-library-root-home-game-launch.md b/discussion/workflow/agendas/AGD-0045-systemos-library-root-home-game-launch.md new file mode 100644 index 00000000..3f1980f7 --- /dev/null +++ b/discussion/workflow/agendas/AGD-0045-systemos-library-root-home-game-launch.md @@ -0,0 +1,161 @@ +--- +id: AGD-0045 +ticket: system-run-cart +title: SystemOS Library Root and Home Game Launch +status: accepted +created: 2026-07-03 +resolved: +decision: +tags: [runtime, os, hub, cartridge, launcher, library, game, architecture] +--- + +## Contexto + +A `DEC-0035` fechou que `system.run_cart` nao deve existir como syscall +userland e que boot direto por host/CLI/debug deve permanecer. + +Isso resolveu a autoridade negativa, mas ainda nao resolveu a experiencia +desejada para o SO: apontar o runtime para um diretorio raiz de biblioteca, +fazer a Home listar os cartuchos encontrados ali e permitir que o usuario clique +em um jogo para carrega-lo. + +O objetivo pratico e um "Switch feio": uma lista simples na Home, sem UX final, +sem marketplace e sem catalogo rico, mas capaz de provar que o SO, e nao o +guest, escolhe e carrega um cartucho a partir de uma biblioteca local. + +## Problema + +Hoje temos dois caminhos separados: + +- boot direto por `--run ` funciona e carrega um cartucho unico; +- Hub/Home existe, mas mostra acoes fixas de Shell nativo e nao lista jogos de + uma biblioteca real. + +Sem uma biblioteca de cartuchos visivel para o SO, o usuario nao consegue +iniciar jogos a partir da Home. Isso deixa a agenda `system-run-cart` incompleta +do ponto de vista de produto: removemos o `run_cart` userland, mas ainda falta a +alternativa correta, que e o SO iniciar cartuchos por acao de usuario. + +## Pontos Criticos + +- O root da biblioteca deve ser fornecido pelo host como `--games-root `. +- O scan inicial deve cobrir subdiretorios imediatos com `manifest.json`. +- O loader de diretorio existente deve continuar sendo a autoridade para validar + cartucho completo; a biblioteca pode ler metadados minimos para listagem. +- A Home pode mostrar uma lista feia/clicavel; polimento visual fica fora. +- O clique em um Game deve iniciar `LoadCartridge` pelo firmware/SystemOS, nao + por syscall guest. +- V1 nao precisa tratar retorno de um Game para Home, porque isso pertence a + `AGD-0041`. +- `.pmc`, outros tipos de app, catalogo remoto, marketplace, icones, busca e + metadados ricos ficam fora. + +## Opcoes + +### Opcao A - Biblioteca apenas para listagem + +- **Abordagem:** adicionar `--games-root`, escanear manifestos e mostrar jogos + na Home, mas sem permitir launch ainda. +- **Pro:** baixa complexidade; prova descoberta/catalogo local. +- **Contra:** nao entrega o objetivo principal de carregar jogo pela Home. +- **Manutenibilidade:** boa, mas valor funcional limitado. + +### Opcao B - Home lista biblioteca e carrega Game quando nao ha Game ativo + +- **Abordagem:** adicionar `--games-root`, escanear cartuchos locais, renderizar + lista simples na Home e permitir clique para carregar um Game via + `LoadCartridge`. A primeira versao cobre Home inicial/sem Game residente. +- **Pro:** entrega o fluxo desejado sem abrir troca completa entre jogos. +- **Contra:** exige passar biblioteca/acao selecionada entre host, Hub, + firmware e loader. +- **Manutenibilidade:** boa se a fronteira ficar clara: biblioteca descobre, + Hub escolhe, firmware carrega. + +### Opcao C - Biblioteca mais troca completa entre jogos + +- **Abordagem:** Home lista biblioteca e tambem permite `Game A -> Home -> + Game B` ja no primeiro passo. +- **Pro:** cobre a experiencia final. +- **Contra:** mistura biblioteca com pausa, fechamento, cleanup e falha de load; + depende de `AGD-0041` e `AGD-0044`. +- **Manutenibilidade:** baixa para v1. + +## Sugestao / Recomendacao + +Recomendo a Opcao B. + +O v1 deve permitir: + +- host recebe `--games-root `; +- o SO/Hub recebe uma lista de cartuchos descobertos; +- a Home mostra uma lista simples/clicavel de jogos; +- clicar em um Game carrega o cartucho via firmware `LoadCartridge`; +- boot direto por `--run ` continua separado e intacto; +- nenhum guest/app chama `run_cart`; +- o escopo v1 acontece na Home inicial; retorno de Game para Home fica para + `AGD-0041`, e troca `Game A -> Home -> Game B` fica para `AGD-0044`. + +Detalhes aceitos para v1: + +- scan apenas de subdiretorios imediatos; +- somente cartuchos `app_mode: Game`; +- `.pmc` fica para futuro; +- cartuchos invalidos sao logados e omitidos da lista; +- o modelo interno deve ser uma entry de biblioteca expansivel, nao apenas um + summary de UI. A entry pode manter o manifest carregado em memoria, path + interno necessario para launch e metadados operacionais como instante de + descoberta/instalacao. A UI v1 mostra apenas `title`, `app_id` e + `app_version`, mas futuros metadados ingeridos pela biblioteca poderao ser + usados pelo catalogo e pela propria UI; +- clique carrega imediatamente, sem confirmacao; +- falha de load volta para Home e registra log/erro. + +Essa agenda deve produzir a alternativa correta ao `run_cart` userland: uma +acao de sistema, iniciada pela Home, que carrega cartucho escolhido pelo usuario +a partir de uma biblioteca local. + +## Perguntas em Aberto + +- [x] O argumento deve se chamar `--games-root`. +- [x] A biblioteca deve escanear apenas subdiretorios imediatos. +- [x] A listagem v1 deve incluir apenas `app_mode: Game`. +- [x] O scan deve logar cartuchos invalidos e omiti-los da lista. +- [x] O Hub/SystemOS deve receber uma entry de biblioteca expansivel, capaz de + manter o manifest carregado, path interno para launch e metadados + operacionais como timestamp de descoberta/instalacao. A UI v1 so precisa + mostrar `title`, `app_id` e `app_version`. +- [x] O clique deve carregar imediatamente, sem confirmacao. +- [x] Se um cartucho falha ao carregar, o sistema volta para Home e registra + erro/log. +- [x] Retorno de Game para Home nao pertence a esta agenda; fica para + `AGD-0041`. +- [x] O teste minimo deve provar o fluxo `games-root -> Home list -> click -> + LoadCartridge -> GameRunning`? + +## Criterio para Encerrar + +A agenda pode virar decisao quando estiver claro: + +- nome e semantica do argumento de host para root da biblioteca; +- escopo do scan e metadados minimos; +- fronteira entre biblioteca, Hub, firmware e loader; +- politica v1 para cartuchos invalidos; +- regra v1 para launch quando nao ha Game ativo; +- fronteira explicita com `AGD-0041` e `AGD-0044`; +- testes minimos para discovery e launch pela Home. + +## Discussao + +- 2026-07-03: Agenda criada como continuacao da `DSC-0004` apos a `DEC-0035`. + A decisao anterior removeu `run_cart` userland; esta agenda define o caminho + correto para o SO/Home carregar jogos a partir de uma biblioteca local. +- 2026-07-03: Respostas aceitas: usar `--games-root`, escanear apenas + subdiretorios imediatos, listar somente Games, deixar `.pmc` e outros apps + para depois, logar/omitir invalidos, usar summary com `title`, `app_id` e + `app_version`, carregar imediatamente no clique, e deixar retorno para Home + sob responsabilidade da `AGD-0041`. +- 2026-07-03: Modelo de dados refinado: a biblioteca deve produzir entries + expansíveis, nao somente summaries de UI. Cada entry pode manter manifest em + memoria, path interno de launch e metadados operacionais como timestamp de + descoberta/instalacao; a UI v1 escolhe quais campos mostrar, mas o modelo + deve permitir que metadados futuros sejam ingeridos e usados pelo catalogo/UI. diff --git a/discussion/workflow/decisions/DEC-0036-systemos-games-root-and-home-game-launch.md b/discussion/workflow/decisions/DEC-0036-systemos-games-root-and-home-game-launch.md new file mode 100644 index 00000000..ed7eda2c --- /dev/null +++ b/discussion/workflow/decisions/DEC-0036-systemos-games-root-and-home-game-launch.md @@ -0,0 +1,156 @@ +--- +id: DEC-0036 +ticket: system-run-cart +title: SystemOS Games Root and Home Game Launch +status: accepted +created: 2026-07-03 +ref_agenda: AGD-0045 +tags: [] +--- + +## Status + +Accepted. + +## Contexto + +`DEC-0035` removed `system.run_cart` from the userland guest ABI and preserved +direct host/CLI/debug cartridge boot. That decision intentionally did not +deliver the Home/SO product flow: pointing PROMETEU at a local games directory, +listing available games in Home, and launching a selected game by user action. + +This decision defines the first system-owned replacement for userland +`run_cart`: a local games-root library discovered by the host/SystemOS and +exposed through a simple Home UI. + +## Decisao + +PROMETEU MUST support a host-provided games library root through +`--games-root `. + +The games root is a directory containing game cartridge directories as immediate +children. V1 MUST scan only immediate child directories. Recursive discovery is +out of scope. + +The v1 games library MUST include only cartridges whose manifest declares +`app_mode: Game`. Shell/System apps, `.pmc` packages, remote catalogs, +marketplace/distribution metadata, rich icons, search, and non-game apps are out +of scope. + +The library MUST produce expandable internal entries, not UI-only summaries. +Each entry MUST retain enough internal data to launch the cartridge and to grow +as a catalog model. At minimum, each entry MUST include: + +- loaded manifest data; +- `title`; +- `app_id`; +- `app_version`; +- internal cartridge path; +- operational discovery metadata, including a timestamp or equivalent discovery + marker. + +The Home UI v1 SHOULD display only `title`, `app_id`, and `app_version`. It MAY +hide path and operational metadata. + +Invalid cartridge candidates MUST be logged and omitted from the Home game list. + +Selecting a listed Game in Home MUST immediately request a system-owned launch +through firmware/SystemOS, resulting in `LoadCartridge` for that cartridge. This +MUST NOT use a guest syscall and MUST NOT reintroduce userland `run_cart`. + +If launch fails, the machine MUST return to or remain in Home and record an +error/log. A polished error UI is out of scope. + +Booting directly with `--run ` MUST remain separate and unchanged. + +Returning from a running Game to Home is outside this decision and belongs to +`AGD-0041`. Switching from `Game A -> Home -> Game B` after a game is already +active belongs to `DSC-0043 / AGD-0044`. + +## Rationale + +The previous `run_cart` surface was wrong because it made cartridge launch look +like an app/userland capability. The desired behavior is still valid, but the +authority must live in the system: Home presents available games and the +firmware/SystemOS loads the selected cartridge. + +Using `--games-root` keeps the v1 product model honest: this is a local game +library, not a general app root. Other app types can be introduced later without +forcing the first launcher model to pretend it is a full marketplace. + +Immediate child scanning keeps discovery deterministic and testable. `.pmc` and +recursive layouts can be added after the directory-cartridge path is proven. + +An expandable entry model avoids prematurely freezing the UI shape as the data +model. The UI is intentionally simple, but the catalog model needs room for +future metadata such as package origin, installation/discovery timestamps, rich +presentation fields, and packaged cartridge details. + +## Invariantes / Contrato + +- `--games-root ` is the v1 host argument for a local games library. +- The games root is Game-only in v1. +- Discovery scans immediate child directories only. +- Directory candidates without valid Game cartridge metadata are logged and + omitted. +- Library entries are internal catalog records, not direct UI DTOs. +- The UI v1 displays a simple clickable list and may show only `title`, + `app_id`, and `app_version`. +- The internal entry retains cartridge path and loaded manifest data for launch. +- Home selection is a system action that enters firmware/SystemOS loading. It is + not a guest syscall. +- `--run ` direct boot remains independent from `--games-root`. +- Return-to-Home and game-to-game switching are not implemented by this + decision. + +## Impactos + +- **Host:** add a `--games-root ` argument and pass the resolved root into + runtime/firmware/SystemOS initialization. +- **SystemOS / Hub:** add a local game library model and expose entries to Home. + Home must render a minimal clickable list and emit a system-owned launch + action for a selected entry. +- **Firmware:** consume the Home launch action and transition to + `LoadCartridge` with the selected cartridge path. +- **Loader:** continue to validate complete directory cartridges. Discovery may + read manifest metadata, but full launch still uses the existing loader. +- **Runtime / VM:** no userland ABI is added. No guest syscall participates in + launch. +- **Specs / Docs:** document `--games-root`, Game-only v1 discovery, and the + distinction between direct boot, games library launch, and future game + switching. +- **Tests:** cover discovery, invalid omission/logging, Home action emission, + and the end-to-end path from games root selection to `GameRunning`. + +## Alternativas Descartadas + +- **List only, no launch:** rejected because it does not satisfy the product + goal of starting games from Home. +- **General app root:** rejected for v1 because Shell/System apps need separate + lifecycle and UI contracts. +- **Recursive discovery:** rejected for v1 to keep semantics deterministic. +- **`.pmc` discovery:** rejected for v1 because packed cartridge loading is a + separate open agenda. +- **Game-to-game switch now:** rejected because it depends on foreground and + cartridge-switch orchestration work in `AGD-0041` and `AGD-0044`. + +## Referencias + +- Source agenda: `AGD-0045` +- Userland run-cart removal: `DEC-0035` +- Foreground/Home return scope: `AGD-0041` +- Future cartridge switch orchestration: `DSC-0043 / AGD-0044` + +## Propagacao Necessaria + +- Add or update runtime specs for games-root discovery and Home launch. +- Add host CLI argument plumbing for `--games-root`. +- Add a catalog/library entry model. +- Add Hub/Home list rendering and click handling. +- Add firmware/SystemOS action routing to `LoadCartridge`. +- Add tests for discovery, invalid candidates, action emission, and + `games-root -> Home click -> GameRunning`. + +## Revision Log + +- 2026-07-03: Initial draft from `AGD-0045`. 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 new file mode 100644 index 00000000..c0b42a60 --- /dev/null +++ b/discussion/workflow/plans/PLN-0132-specify-games-root-home-launch-contract.md @@ -0,0 +1,103 @@ +--- +id: PLN-0132 +ticket: system-run-cart +title: Specify Games Root Home Launch Contract +status: open +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 `, 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 ` 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 ` 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 ` 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 ` 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 ` 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` diff --git a/discussion/workflow/plans/PLN-0133-implement-games-root-library-discovery.md b/discussion/workflow/plans/PLN-0133-implement-games-root-library-discovery.md new file mode 100644 index 00000000..40bee690 --- /dev/null +++ b/discussion/workflow/plans/PLN-0133-implement-games-root-library-discovery.md @@ -0,0 +1,118 @@ +--- +id: PLN-0133 +ticket: system-run-cart +title: Implement Games Root Library Discovery +status: open +created: 2026-07-03 +ref_decisions: [DEC-0036] +tags: [] +--- + +## Briefing + +`DEC-0036` requires a host-provided games root and an expandable internal +library model before Home can render or launch games. This plan implements the +library discovery and host plumbing only; UI launch wiring is handled by +`PLN-0134`. + +## Objective + +Add a tested games-root discovery model that scans immediate child directory +cartridges, filters to valid Game manifests, records diagnostics for invalid +candidates, and carries enough metadata for Home rendering and later launch. + +## Dependencies + +- Source decision: `DEC-0036`. +- `PLN-0132` should be completed first so code follows the documented contract. +- Existing cartridge manifest and directory loader behavior in the console + crates. +- Existing host CLI and `HostRunner` boot setup. + +## Scope + +- Add `--games-root ` to the desktop host CLI. +- Pass the optional games root into the host runner / firmware initialization + path without changing direct `--run` or `--debug` boot behavior. +- Add a SystemOS-owned games library model for directory cartridge discovery. +- Scan only immediate child directories of the root. +- Read and retain manifest data for each valid candidate. +- Include only candidates whose manifest declares `app_mode: Game`. +- Retain internal cartridge path and operational discovery metadata on each + entry. +- Emit diagnostics for invalid, unreadable, or non-Game candidates and omit + them from the returned entries. +- Keep discovery independent from full cartridge launch: discovery reads + metadata; launch still uses the existing loader in `PLN-0134`. + +## Non-Goals + +- No Home list rendering. +- No click handling or `LoadCartridge` transition. +- No `.pmc` discovery. +- No recursive scan. +- No Shell/System app catalog. +- No marketplace metadata, icons, search, sorting UI, or polished errors. +- No new guest syscall. + +## Execution Method + +1. Introduce a library/discovery module in the SystemOS side, preferably under + `crates/console/prometeu-system/src/services/` unless the existing module + layout has a more local owner. +2. Define an internal entry type with at least: + - loaded cartridge manifest data; + - `title`; + - `app_id`; + - `app_version`; + - internal cartridge path; + - discovery metadata, using `SystemTime` or another explicit discovery + marker. +3. Define discovery diagnostics that can be logged by the caller and asserted in + tests. +4. Implement a scanner that: + - accepts an optional root path; + - returns an empty library when no root is configured; + - iterates only immediate child directories; + - parses `manifest.json` using structured manifest types, not ad hoc string + matching; + - filters to `app_mode: Game`; + - sorts entries deterministically for stable Home presentation and tests. +5. Add `--games-root ` to + [crates/host/prometeu-host-desktop-winit/src/lib.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/host/prometeu-host-desktop-winit/src/lib.rs) + and pass the path into + [crates/host/prometeu-host-desktop-winit/src/runner.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/host/prometeu-host-desktop-winit/src/runner.rs). +6. Store or expose the discovered library to firmware/SystemOS in a way that + `PLN-0134` can consume without re-scanning inside the Home click path. +7. Add focused unit tests using temporary cartridge roots with: + - one valid Game directory cartridge; + - one valid non-Game cartridge; + - one invalid directory; + - one nested directory that must not be discovered. + +## Acceptance Criteria + +- `--games-root ` is accepted by the desktop host CLI. +- Absence of `--games-root` leaves existing Hub boot behavior unchanged. +- Direct `--run ` and `--debug ` behavior remains unchanged. +- Discovery returns only immediate valid Game directory cartridges. +- Each library entry retains manifest data, path, title, app id, app version, + and discovery metadata. +- Invalid candidates are represented in diagnostics and excluded from entries. +- Discovery does not fully load or boot cartridge programs. + +## Tests + +- Add and run focused games-library discovery tests in the owning console crate. +- Run `cargo test -p prometeu-system` if the library lives in + `prometeu-system`. +- Run `cargo test -p prometeu-host-desktop-winit` for CLI/runner plumbing. +- Run `discussion validate`. + +## Affected Artifacts + +- `crates/console/prometeu-system/src/services/` +- `crates/console/prometeu-system/src/lib.rs` or module exports as needed +- `crates/host/prometeu-host-desktop-winit/src/lib.rs` +- `crates/host/prometeu-host-desktop-winit/src/runner.rs` +- `discussion/workflow/plans/PLN-0133-implement-games-root-library-discovery.md` diff --git a/discussion/workflow/plans/PLN-0134-wire-home-game-list-launch-flow.md b/discussion/workflow/plans/PLN-0134-wire-home-game-list-launch-flow.md new file mode 100644 index 00000000..9de5076e --- /dev/null +++ b/discussion/workflow/plans/PLN-0134-wire-home-game-list-launch-flow.md @@ -0,0 +1,104 @@ +--- +id: PLN-0134 +ticket: system-run-cart +title: Wire Home Game List Launch Flow +status: open +created: 2026-07-03 +ref_decisions: [DEC-0036] +tags: [] +--- + +## Briefing + +After `PLN-0133`, SystemOS can discover a local Game library but Home still +does not present or launch those entries. This plan wires the discovered +library into Prometeu Hub/Home and routes a selected game to firmware +`LoadCartridge`. + +## Objective + +Make Home display a minimal clickable games list and launch the selected Game +through a system-owned firmware/SystemOS path, without reintroducing userland +`run_cart`. + +## Dependencies + +- Source decision: `DEC-0036`. +- `PLN-0132` for documented contract. +- `PLN-0133` for `--games-root` plumbing and the internal library entry model. +- Existing Prometeu Hub Home profile and firmware state transitions. + +## Scope + +- Provide the discovered games library to Prometeu Hub/Home. +- Render a minimal Home list showing `title`, `app_id`, and `app_version`. +- Add Home hit-testing/click handling for game entries. +- Extend the system profile action model with a system-owned game launch action. +- Handle that action in firmware/SystemOS by loading the selected cartridge via + the existing cartridge loader and entering `LoadCartridge`. +- On load failure, log/record the error and keep or return the machine to Home. +- Preserve existing native shell launch behavior. + +## Non-Goals + +- No polished launcher UI. +- No icons, screenshots, search, filtering, or marketplace metadata. +- No return-to-Home while a Game is running. +- No Game A -> Home -> Game B foreground orchestration. +- No `.pmc` launch support. +- No guest syscall. +- No direct-boot behavior changes. + +## Execution Method + +1. Extend the SystemOS/Hub action type currently represented by + `SystemProfileAction::LaunchNativeShell` with a game-launch action that + carries a stable reference to the selected library entry or cartridge path. +2. Update the Prometeu Hub state in + [crates/console/prometeu-system/src/programs/prometeu_hub.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system/src/programs/prometeu_hub.rs) + or its local modules to accept the discovered game entries. +3. Render the Home games list with stable dimensions and simple clickable rows. + Rows must display only `title`, `app_id`, and `app_version` for v1. +4. Add hit-testing so selecting a row emits the game-launch action immediately. +5. Update + [crates/console/prometeu-firmware/src/firmware/steps/firmware_step_hub_home.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-firmware/src/firmware/steps/firmware_step_hub_home.rs) + to consume the new action. +6. In the firmware action handler: + - call the existing cartridge loader for the selected path; + - on success, return `FirmwareState::LoadCartridge(...)`; + - on failure, log/record the error and remain in the Home path. +7. Ensure shell launch still works exactly as before. +8. Add unit or integration tests for: + - Home list presentation data; + - click-to-action emission; + - firmware action handling success; + - firmware action handling failure. + +## Acceptance Criteria + +- Starting the host with `--games-root ` exposes valid Game entries in + Home. +- The Home list displays `title`, `app_id`, and `app_version`. +- Clicking a listed Game routes through a system action and enters + `LoadCartridge`. +- The launch path does not use a guest syscall and does not mention + `system.run_cart`. +- Invalid or failing launch paths remain in Home and record an error. +- Existing native shell Home actions continue to work. +- Direct `--run` remains separate and unchanged. + +## Tests + +- Run `cargo test -p prometeu-system` for Hub action and presentation behavior. +- Run `cargo test -p prometeu-firmware` for firmware transition behavior. +- Run `cargo test -p prometeu-host-desktop-winit` if runner integration changes. +- Run `discussion validate`. + +## Affected Artifacts + +- `crates/console/prometeu-system/src/programs/prometeu_hub.rs` +- `crates/console/prometeu-system/src/services/` +- `crates/console/prometeu-firmware/src/firmware/steps/firmware_step_hub_home.rs` +- `crates/console/prometeu-firmware/src/firmware/firmware.rs` +- `crates/host/prometeu-host-desktop-winit/src/runner.rs` +- `discussion/workflow/plans/PLN-0134-wire-home-game-list-launch-flow.md` diff --git a/discussion/workflow/plans/PLN-0135-validate-games-root-launch-end-to-end.md b/discussion/workflow/plans/PLN-0135-validate-games-root-launch-end-to-end.md new file mode 100644 index 00000000..cfd16935 --- /dev/null +++ b/discussion/workflow/plans/PLN-0135-validate-games-root-launch-end-to-end.md @@ -0,0 +1,99 @@ +--- +id: PLN-0135 +ticket: system-run-cart +title: Validate Games Root Launch End To End +status: open +created: 2026-07-03 +ref_decisions: [DEC-0036] +tags: [] +--- + +## Briefing + +`PLN-0132` through `PLN-0134` specify, discover, display, and launch games +from a local games root. This plan closes the slice by adding end-to-end +validation evidence and manual smoke instructions for the product behavior the +user wants: point the SO at a directory, click a listed game, and boot it. + +## Objective + +Prove the complete `--games-root -> Home list -> click -> LoadCartridge -> +GameRunning` path while preserving direct `--run` boot and the absence of +userland `run_cart`. + +## Dependencies + +- Source decision: `DEC-0036`. +- `PLN-0132`, `PLN-0133`, and `PLN-0134` must be complete. +- Existing test cartridge fixtures, especially `test-cartridges/stress-console`. + +## Scope + +- Add automated integration coverage for the full games-root Home launch path + where the existing host/firmware test seams allow it. +- Add or document a minimal local games-root fixture using existing directory + cartridges. +- Validate invalid-candidate omission at the end-to-end boundary. +- Validate direct `--run` still works after games-root wiring. +- Capture manual smoke-test commands for release-mode functional verification. + +## Non-Goals + +- No new product UI polish. +- No screenshot automation unless the existing test harness already supports it + cleanly. +- No return-to-Home after a running Game. +- No Game A -> Home -> Game B orchestration. +- No `.pmc` validation. +- No broad performance tuning beyond confirming release-mode smoke behavior. + +## Execution Method + +1. Add an integration-style firmware or host test that constructs a games root + with a valid Game directory cartridge and boots to Hub/Home with that root. +2. Drive the Home selection path through the same action path used by user + input, not by calling the cartridge loader directly. +3. Assert that the machine reaches `LoadCartridge` or `GameRunning`, depending + on the most stable observable state available in the test harness. +4. Add a negative case with an invalid candidate and assert it is omitted or + reported as a diagnostic without appearing in Home. +5. Add a regression assertion that no public guest syscall named + `system.run_cart` is required by this path. +6. Re-run direct boot tests or add a small regression test proving + `--run test-cartridges/stress-console` remains independent from + `--games-root`. +7. Record manual smoke commands in the relevant spec or developer-facing doc: + - `cargo run --release -p prometeu-host-desktop-winit -- --games-root test-cartridges` + - `cargo run --release -p prometeu-host-desktop-winit -- --run test-cartridges/stress-console` + +## Acceptance Criteria + +- Automated tests cover a valid games-root Home launch path. +- Automated tests cover invalid candidate omission or diagnostics at the + end-to-end boundary. +- Automated or documented validation proves direct `--run` still works. +- Manual smoke instructions use release mode for realistic interactive speed. +- Validation evidence shows no guest syscall participates in launch. +- `discussion validate` passes. + +## Tests + +- Run `cargo test -p prometeu-system`. +- Run `cargo test -p prometeu-firmware`. +- Run `cargo test -p prometeu-host-desktop-winit`. +- Run `cargo test -p prometeu-hal syscalls` to keep the removed syscall surface + guarded. +- Manually smoke test: + `cargo run --release -p prometeu-host-desktop-winit -- --games-root test-cartridges`. +- Manually smoke test: + `cargo run --release -p prometeu-host-desktop-winit -- --run test-cartridges/stress-console`. +- Run `discussion validate`. + +## Affected Artifacts + +- `crates/console/prometeu-system/` +- `crates/console/prometeu-firmware/` +- `crates/host/prometeu-host-desktop-winit/` +- `crates/console/prometeu-hal/src/syscalls/tests.rs` +- Runtime specs or developer docs containing smoke commands +- `discussion/workflow/plans/PLN-0135-validate-games-root-launch-end-to-end.md`