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

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