162 lines
7.0 KiB
Markdown
162 lines
7.0 KiB
Markdown
---
|
|
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 <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
|
|
|
|
- [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.
|