prometeu-runtime/discussion/workflow/agendas/AGD-0045-systemos-library-root-home-game-launch.md

id	ticket	title	status	created	resolved	decision	tags
AGD-0045	system-run-cart	SystemOS Library Root and Home Game Launch	accepted	2026-07-03			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 <cart> 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 <dir>.
• 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 <dir>;
• 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 <cart> 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

• O argumento deve se chamar --games-root.
• A biblioteca deve escanear apenas subdiretorios imediatos.
• A listagem v1 deve incluir apenas app_mode: Game.
• O scan deve logar cartuchos invalidos e omiti-los da lista.
• 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.
• O clique deve carregar imediatamente, sem confirmacao.
• Se um cartucho falha ao carregar, o sistema volta para Home e registra erro/log.
• Retorno de Game para Home nao pertence a esta agenda; fica para AGD-0041.
• 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.