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

id	ticket	title	status	created	resolved	decision	tags
AGD-0003	system-run-cart	Agenda - System Run Cart	open	2026-03-27

Agenda - System Run Cart

Problema

A syscall system.run_cart existe na ABI pública, mas hoje não produz efeito real no runtime.

Isso cria uma falsa promessa de plataforma:

• o programa consegue declarar e chamar a syscall;
• 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.
• 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 de system.run_cart do ponto de vista:

• do guest;
• do runtime;
• do firmware;
• do host/cartridge loader.

Ao final da discussão, deve ficar claro se a syscall:

• permanece na ABI e ganha implementação completa; ou
• sai temporariamente da ABI até existir fluxo fechado.

O Que Precisa Ser Definido

1. Semântica da operação. O que significa "run cart": trocar imediatamente, agendar para o próximo frame, retornar ao firmware, reiniciar VM atual, ou apenas emitir uma intenção?

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?

3. Modelo de segurança. Quem pode chamar isso, sob qual capability, e com quais restrições para evitar que um app force navegação arbitrária do sistema?

4. Ponto de integração. Onde a transição vive: VirtualMachineRuntime, firmware, host, ou combinação dos três?

5. Efeitos observáveis. O que acontece com:

   • estado do app atual;
   • FS aberto;
   • assets carregados;
   • telemetria;
   • crash reports;
   • logs.

6. Contrato de erro. Quais falhas retornam trap ao guest e quais viram evento de sistema.

O Que Necessita Para Resolver

• fluxo fechado entre syscall -> runtime -> firmware -> loader -> novo app;
• modelo explícito para seleção do alvo;
• definição de lifecycle da troca de cartucho;
• testes de integração cobrindo transição bem-sucedida, alvo inválido, capability insuficiente e cleanup de estado.

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.

Critério de Saida Desta Agenda

Esta agenda só pode virar PR de implementação quando existir decisão escrita para:

• assinatura final da syscall;
• local canônico da troca de estado;
• política de erro;
• limpeza de recursos;
• cobertura mínima de testes de integração.