SystemOS Cartridge Switch Orchestrator

This commit is contained in:
2026-07-05 01:03:02 +01:00
parent 313b896e7b
commit 0ffb3467b1
9 changed files with 775 additions and 22 deletions
@@ -2,7 +2,7 @@
id: AGD-0044
ticket: system-os-cartridge-switch-orchestrator
title: SystemOS Cartridge Switch Orchestrator
status: open
status: accepted
created: 2026-07-03
resolved:
decision:
@@ -90,35 +90,58 @@ pode cair em estados incoerentes:
## Sugestao / Recomendacao
Recomendo a Opcao A agora, com esta agenda aberta como marcador explicito de
escopo futuro.
`DSC-0041` foi fechada e o contrato de foreground/pausa/resume ja existe. A
recomendacao agora deixa de ser adiar e passa a ser fechar uma decisao curta
para o orquestrador de troca `Game A -> Home -> Game B`.
A ordem preferida passa a ser:
O contrato sugerido e:
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.
- trocar para outro Game e uma substituicao controlada, nao uma pausa/resume;
- o Game residente anterior e fechado/descartado;
- a VM session do Game anterior e removida;
- o novo Game sempre recebe uma VM session nova e zerada;
- se o novo load falhar, o sistema volta ao Home/Hub com diagnostico e nao
tenta preservar o Game anterior em v1;
- o loader continua sendo etapa interna, sem possuir politica de lifecycle;
- a evidencia minima deve usar dois cartuchos distintos, incluindo um cartucho
simplista `dummy-boy` alem do stress test.
## Perguntas em Aberto
- [ ] Depois da `AGD-0041`, qual estado representa um Game que sera descartado
- [x] 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
- Resposta: fechamento/encerramento controlado, nao `PausedSuspended`. O Game
anterior deixa de ser resident/resumable e sua VM session e removida.
- [x] 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,
- Resposta: deve ser observavel como uma transicao de lifecycle/firmware, mas
nao cooperativo nem bloqueante para o Game. O SystemOS tem autoridade para
encerrar e descartar a sessao. Pode ser emitido um evento de encerramento
para permitir save/flush cooperativo quando existir esse mecanismo, mas a
troca nao deve depender da resposta do Game.
- [x] 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
- Resposta: a troca nao reaproveita VM. O Game anterior e encerrado, sua VM
session e descartada, e o novo Game recebe VM/session nova e zerada. Devem
ser limpos ou reatribuídos os estados cartridge-scoped ligados a VM,
handles abertos, input pendente/barreiras, audio do app, render ownership,
telemetry/debug/crash state do app. Logs historicos podem permanecer como
observabilidade.
- [x] 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
- Resposta: o Game anterior ja foi encerrado. Se o novo load falha, a sessao
parcial do novo Game e descartada e o sistema volta ao Home/Hub com
diagnostico. Preservar o Game anterior fica fora de escopo em v1.
- [x] 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
- Resposta: para o contrato minimo, o alvo pode ser um path/entrada ja
resolvido pelo Hub/game library atual. O contrato nao depende de `.pmc` nem
de catalogo final.
- [x] Qual evidencia minima prova `Game A -> Home -> Game B` sem depender de UX
final de launcher?
- Resposta: criar um cartucho `dummy-boy` ao lado do stress test. O teste deve
provar `Stress -> Home -> Dummy Boy`, com troca de VM session, identidade de
cartridge distinta e render observavel do novo Game.
## Criterio para Encerrar
@@ -139,7 +162,17 @@ A agenda pode virar decisao quando:
O novo escopo cobre a troca posterior `Game A -> Home -> Game B`, com
orquestracao pelo SystemOS depois que o contrato de foreground estiver
fechado.
- 2026-07-05: Apos fechamento de `DSC-0041`, a discussao convergiu para troca
destrutiva simples em v1: ao iniciar outro Game, o Game residente anterior e
encerrado, sua VM session e removida, e o novo Game recebe VM session nova.
Falha de load volta ao Home/Hub com diagnostico. A evidencia minima deve
incluir um novo cartucho `dummy-boy` que desenha um quadrado com cores
oscilando, alem do stress test.
- 2026-07-05: Refinamento: o encerramento do Game anterior pode emitir evento
cooperativo para save/flush, mas esse evento nao e uma permissao nem uma
barreira obrigatoria. O SystemOS continua com autoridade para concluir a troca
e remover a VM session anterior.
## Resolution
Ainda em aberto.
Pronta para virar decisao, pendente confirmacao explicita do usuario.