--- 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.