--- id: AGD-0003 ticket: system-run-cart title: Agenda - System Run Cart status: accepted created: 2026-03-27 resolved: decision: tags: [] --- # Agenda - System Run Cart ## Problema `system.run_cart` existe na ABI pública, mas hoje não produz efeito real no runtime. Isso expõe duas questões: a superfície atual é um placebo e, mesmo quando houver fluxo real, rodar cartuchos não deve ser uma operação userland. A autoridade para iniciar cartuchos deve pertencer ao sistema/firmware. Isso cria uma falsa promessa de plataforma: - o programa consegue declarar e chamar uma operação que aparenta iniciar cartuchos; - o loader aceita sua existência; - o runtime retorna sucesso vazio; - nenhuma troca de cartucho, transição de firmware, validação de alvo ou política de segurança ocorre. ## Dor - A ABI expõe uma capability de sistema que, na prática, nao existe. - Mesmo se implementada, a operação não deve ser uma syscall userland comum: apps não devem iniciar cartuchos diretamente. - O guest pode acreditar que solicitou uma troca de app quando nada aconteceu. - Isso corrói a confiabilidade da plataforma: a interface pública deixa de ser contrato e vira placebo. - Qualquer ferramenta, SDK ou documentação construída sobre essa syscall passa a modelar um comportamento inexistente. ## Alvo da Discussao Definir o contrato real da troca de cartucho iniciada pelo sistema do ponto de vista: - do guest; - do runtime; - do firmware; - do host/cartridge loader. Ao final da discussão, deve ficar claro se a superfície atual: - permanece apenas como mecanismo interno do sistema e sai da ABI userland; ou - permanece na ABI somente como superfície privilegiada impossível de chamar por apps comuns; ou - sai temporariamente da ABI até existir fluxo fechado. Esta discussao nao deve depender do fechamento previo do formato `.pmc`. Para o primeiro fluxo fechado, `system.run_cart` pode resolver um alvo por um loader ja disponivel, incluindo cartucho em diretorio ou fixture de teste. O suporte ao artefato empacotado `.pmc` permanece responsabilidade da `DSC-0003 / packed-cartridge-loader-pmc` e nao deve bloquear a prova inicial de troca `Shell/Hub -> Game`. Tambem precisa ficar claro que `run_cart`, se existir, nao e o orquestrador da troca. No boot direto por linha de comando, carregar um cartucho e simples porque o runtime nasce ja apontado para aquele jogo. Com o SO em execucao, o caso real e diferente: pode haver um Game residente/rodando, o usuario volta para Home, e o sistema decide iniciar outro Game. Nesse caso o SO precisa orquestrar fechamento/suspensao descartada do app atual, limpeza de estado, resolucao do novo alvo, carregamento e transicao para o proximo estado de firmware. O carregador de cartucho e apenas uma etapa desse fluxo. A direcao preferida e que a orquestracao de troca de cartucho viva no SystemOS. Porem, essa agenda nao deve capturar o caso `Game -> Home -> mesmo Game`: esse e o escopo da `AGD-0041`, que precisa fechar foreground, pausa/suspensao e retorno ao mesmo Game. A troca `Home -> outro Game`, com fechamento do jogo atual e carregamento de outro cartucho, pode merecer uma agenda propria depois da `AGD-0041`, derivada do contrato de foreground que ela fechar. ## O Que Precisa Ser Definido 1. Semântica da operação. O que significa "run cart" quando existe SO: trocar imediatamente, agendar para o próximo frame, iniciar uma transicao orquestrada pelo sistema, ou apenas carregar bytes de cartucho como etapa interna? 2. Origem do alvo. Como o guest identifica o cartucho alvo: id numérico, nome canônico, path virtual, handle, manifesto, ou nenhum argumento nesta primeira versão? Para v1, uma opcao aceitavel e limitar a resolucao a alvos conhecidos pelo host/test harness e carregaveis pelo loader de diretorio, deixando `.pmc` fora do caminho critico. 3. Modelo de segurança. Nenhum app/userland deve chamar `run_cart`. O sistema/firmware e o caminho host/CLI/debug devem ser as unicas autoridades para iniciar cartuchos. Se apps precisarem solicitar navegacao no futuro, isso deve ser uma superficie nova e mediada pelo sistema. 4. Ponto de integração. Onde a transição vive: `VirtualMachineRuntime`, firmware, host, SystemOS, ou combinação dos três? Para esta agenda, a decisao minima e separar o boot direto host/CLI/debug da ABI guest. A orquestracao `Home -> outro Game` pertence a `DSC-0043 / AGD-0044`. 5. Efeitos observáveis. O que acontece quando um guest tenta chamar a superficie removida, e como ferramentas/boot direto continuam carregando cartuchos sem depender de uma syscall userland? 6. Contrato de erro. Remocao da ABI significa erro de build/declaracao, syscall desconhecida, ou bloqueio em registro/capability ate a limpeza completa das declaracoes? ## O Que Necessita Para Resolver - remocao de `system.run_cart` da ABI userland; - definicao de que boot direto continua por caminho host/CLI/debug, nao por syscall guest; - separacao explicita entre boot direto, loader interno e orquestracao `Home -> outro Game` da `DSC-0043 / AGD-0044`; - testes garantindo que guest/userland nao pode declarar/chamar `run_cart`; - testes garantindo que boot direto de cartucho continua funcional. ## Fora de Escopo - catálogo completo de apps instalados; - UX final do launcher/hub; - resolução remota ou download de cartuchos; - política de marketplace/distribuição. - obrigatoriedade de boot a partir de `.pmc` no primeiro fluxo funcional. ## Sugestao / Recomendacao Recomendo remover `system.run_cart` da ABI userland para v1. Nao ha necessidade de compatibilidade com a superficie atual: ela nao deve permanecer como stub, syscall reservada chamavel por guest, nem sucesso vazio. Rodar cartuchos deve ser uma operacao interna do SystemOS/firmware ou do caminho host/CLI/debug, nunca uma syscall de app. O boot direto deve continuar existindo porque e o fluxo essencial para testar cartuchos em desenvolvimento e tambem representa o modo futuro de executar um jogo unico, como em uma integracao tipo Steam. Recomendo tambem separar dois conceitos: - **boot direto:** usado por linha de comando/debug, inicia o runtime ja com um cartucho alvo e pode continuar simples; - **troca via SO:** fluxo orquestrado pelo SystemOS, que fecha o app atual quando necessario, limpa estado cartridge-scoped, resolve o proximo alvo e so entao chama o carregador. Essa agenda nao deve implementar o fluxo `Game -> Home -> mesmo Game`; esse trabalho pertence a `AGD-0041`. Depois dela, a troca `Home -> outro Game` deve ser aberta ou refinada como discussao propria, porque adiciona fechamento do jogo atual, limpeza cartridge-scoped, resolucao de novo alvo e falhas de load. Se a plataforma precisar de uma ação solicitável por apps no futuro, ela deve ser modelada separadamente como pedido de navegação mediado pelo sistema, com nome e erros que não prometam boot direto. ## Respostas Atuais - `system.run_cart` deve ser removido da ABI userland. - Nao precisamos manter compatibilidade com a superficie atual. - Nao deve existir syscall publica para app iniciar cartucho. - Boot direto por linha de comando, host, debug ou fluxo equivalente de jogo unico deve permanecer. - O carregamento interno pode continuar usando loader ja disponivel, incluindo cartucho em diretorio/fixture. - `.pmc`, catalogo, UX final de launcher e troca `Game A -> Home -> Game B` ficam fora desta agenda. - Se no futuro apps precisarem pedir navegacao, isso deve ser uma nova superficie mediada pelo sistema, nao a volta de `run_cart` userland. ## Critério de Saida Desta Agenda Esta agenda só pode virar PR de implementação quando existir decisão escrita para: - retirada da superfície userland atual; - preservacao explicita do boot direto host/CLI/debug; - comportamento esperado para declaracao/chamada guest obsoleta; - fronteira com `AGD-0041` e `AGD-0044`; - cobertura minima de testes para remocao userland e boot direto. ## Discussao - 2026-07-03: A agenda deve ser aberta antes da `AGD-0041` como habilitadora de validacao do ciclo `Shell/Hub -> Game`. Ficou definido como premissa de agenda que o primeiro `system.run_cart` testavel nao depende de `.pmc`; ele pode usar cartucho em diretorio ou fixture resolvida pelo host/test harness. - 2026-07-03: Direcao ajustada: `run_cart` nao deve ser uma operacao userland. A autoridade de iniciar cartuchos deve pertencer ao sistema/firmware; apps podem, no maximo, solicitar navegacao por uma superficie separada e mediada. - 2026-07-03: Direcao refinada: `run_cart` simples nao resolve o caso com SO. Boot direto por linha de comando continua sendo um caminho simples, mas iniciar outro jogo a partir do Home exige um orquestrador do SO/firmware que fecha o app atual, limpa estado e so entao carrega o novo cartucho. - 2026-07-03: Escopo refinado: `Game -> Home -> mesmo Game` pertence a `AGD-0041`. A agenda atual nao deve absorver esse trabalho. Depois da `AGD-0041`, a troca `Home -> outro Game` pode ser aberta ou refinada como agenda propria para o orquestrador de troca de cartucho no SystemOS. - 2026-07-03: A troca `Game A -> Home -> Game B` foi separada para `DSC-0043 / AGD-0044`, mantendo esta agenda focada na superficie `run_cart`/loader e sua remocao ou restricao como operacao userland. - 2026-07-03: Direcao aceita para esta agenda: remover `system.run_cart` da ABI userland sem necessidade de compatibilidade, manter boot direto para CLI/debug/teste de cartuchos e futuro modo de jogo unico, e deixar navegacao mediada por apps para uma superficie futura separada se ela vier a existir.