---
id: AGD-0044
ticket: system-os-cartridge-switch-orchestrator
title: SystemOS Cartridge Switch Orchestrator
status: open
created: 2026-07-03
resolved:
decision:
tags: [runtime, os, lifecycle, game, cartridge, architecture]
---

## Contexto

A `AGD-0041` cobre o caso `Game -> Home/Shell -> mesmo Game`: o usuario sai do
foreground do jogo, o SO assume a tela, Shell/Hub pode rodar, e depois o mesmo
Game e retomado.

Existe um segundo caso, diferente, que nao deve ser escondido dentro da
`AGD-0041`: `Game A -> Home -> Game B`.

Nesse fluxo, o usuario esta com um Game rodando, aperta Home, volta para o SO e
pede para iniciar outro jogo. O SystemOS nao deve simplesmente chamar um loader
por cima do estado atual. Ele precisa orquestrar a substituicao do app corrente:
fechar ou descartar o Game residente, limpar estado cartridge-scoped, resolver o
novo alvo, carregar o proximo cartucho e entrar no novo estado de firmware.

Essa agenda tambem se relaciona com a `AGD-0003 / system-run-cart`: `run_cart`,
se existir, nao e userland e nao e o orquestrador. O carregador de cartucho e
apenas uma etapa dentro de uma transicao comandada pelo SystemOS.

## Problema

Sem um orquestrador explicito de troca de cartucho no SystemOS, a plataforma
pode cair em estados incoerentes:

- carregar um novo Game sem fechar corretamente o Game anterior;
- reaproveitar estado VM, assets, input, audio, render ou telemetria do cartucho
  anterior;
- misturar boot direto por linha de comando com troca de app sob o SO;
- deixar o loader decidir lifecycle, quando ele deveria apenas materializar o
  cartucho alvo;
- tentar implementar `Home -> outro Game` antes de existir o contrato de
  foreground/pausa definido pela `AGD-0041`.

## Pontos Criticos

- Esta agenda deve ser executada depois da `AGD-0041`.
- `Game -> Home -> mesmo Game` fica fora desta agenda.
- O SystemOS deve ser a autoridade da troca entre cartuchos sob o SO.
- O loader nao deve possuir politica de fechamento, pausa, foreground ou
  cleanup.
- Boot direto por CLI/debug continua sendo caminho separado e mais simples.
- A troca para outro Game deve tratar falha de load sem deixar o sistema em
  estado parcialmente substituido.
- `.pmc`, catalogo completo e UX final de launcher continuam fora de escopo,
  salvo se forem necessarios para definir o contrato minimo.

## Opcoes

### Opcao A - Adiar tudo para depois da AGD-0041

- **Abordagem:** manter esta agenda como registro de escopo futuro; primeiro
  fechar e implementar o contrato `Game -> Home -> mesmo Game`.
- **Pro:** evita misturar pausa/resume com substituicao de cartucho; reduz risco
  de reabrir arquitetura durante a `AGD-0041`.
- **Contra:** a plataforma continua sem troca `Home -> outro Game` ate uma etapa
  posterior.
- **Manutenibilidade:** alta, porque cada agenda fecha um eixo de lifecycle.

### Opcao B - Definir agora o contrato conceitual, implementar depois

- **Abordagem:** fechar uma decisao curta ja dizendo que o orquestrador pertence
  ao SystemOS, que `run_cart` nao e userland, e que a execucao depende da
  `AGD-0041`; o plano de codigo fica para depois.
- **Pro:** reduz ambiguidade enquanto trabalhamos na `AGD-0041`.
- **Contra:** pode produzir uma decisao com pouca evidencia operacional antes
  do contrato de foreground estar fechado.
- **Manutenibilidade:** boa se a decisao for claramente marcada como dependente
  da `AGD-0041`.

### Opcao C - Implementar o orquestrador completo agora

- **Abordagem:** tentar resolver `Game A -> Home -> Game B` antes ou junto da
  `AGD-0041`.
- **Pro:** ataca o fluxo final diretamente.
- **Contra:** mistura pausa/resume, fechamento, cleanup, resolucao de alvo e
  falha de load em uma unica frente; alto risco de contrato instavel.
- **Manutenibilidade:** baixa para v1, porque a troca completa depende do
  contrato de foreground ainda aberto.

## Sugestao / Recomendacao

Recomendo a Opcao A agora, com esta agenda aberta como marcador explicito de
escopo futuro.

A ordem preferida passa a ser:

1. fechar a `AGD-0041` para definir foreground, pausa/suspensao, Shell no
   foreground e retorno ao mesmo Game;
2. voltar para esta agenda e decidir o contrato do orquestrador de troca de
   cartucho no SystemOS;
3. so entao planejar a execucao de `Game A -> Home -> Game B`.

Se durante a `AGD-0041` aparecer uma decisao que exige antecipar parte do
orquestrador, esta agenda deve ser reaberta/atualizada com a dependencia
concreta em vez de esconder a troca de cartucho dentro da agenda de foreground.

## Perguntas em Aberto

- [ ] Depois da `AGD-0041`, qual estado representa um Game que sera descartado
  em vez de retomado?
- [ ] O fechamento do Game atual e observavel para o firmware/game, ou e uma
  destruicao interna do SystemOS?
- [ ] Quais estados cartridge-scoped devem ser limpos antes do novo load: VM,
  assets, FS handles, input, audio, render ownership, telemetry, logs?
- [ ] Se o novo cartucho falha ao carregar, o sistema volta ao Home, mostra uma
  tela de erro, ou tenta preservar o Game anterior?
- [ ] Como a resolucao do novo alvo e representada sem depender de catalogo
  completo ou `.pmc`?
- [ ] Qual evidencia minima prova `Game A -> Home -> Game B` sem depender de UX
  final de launcher?

## Criterio para Encerrar

A agenda pode virar decisao quando:

- a `AGD-0041` tiver fechado o contrato de foreground/pausa/resume;
- estiver claro que o orquestrador pertence ao SystemOS;
- `run_cart`/loader estiver limitado a etapa interna, nao userland;
- existir regra para fechar/descartar o Game atual;
- existir contrato de limpeza de estado cartridge-scoped;
- existir politica para falha de carregamento do novo Game;
- houver criterio de teste minimo para `Game A -> Home -> Game B`.

## Discussao

- 2026-07-03: Agenda criada a partir da separacao entre `AGD-0041`
  (`Game -> Home -> mesmo Game`) e `AGD-0003` (`run_cart`/loader nao userland).
  O novo escopo cobre a troca posterior `Game A -> Home -> Game B`, com
  orquestracao pelo SystemOS depois que o contrato de foreground estiver
  fechado.

## Resolution

Ainda em aberto.