prometeu-runtime/discussion/workflow/agendas/AGD-0003-system-run-cart.md

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