Foreground Stack, Game Pause, and VM-Backed Shell Coexistence

This commit is contained in:
2026-07-03 22:52:08 +01:00
parent 4bc9ce2b73
commit 126bffa37d
21 changed files with 1023 additions and 1347 deletions
@@ -1,202 +0,0 @@
---
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.
@@ -2,10 +2,10 @@
id: AGD-0041
ticket: foreground-stack-game-pause-shell-vm-backed
title: Foreground Stack, Game Pause, and VM-Backed Shell Coexistence
status: open
status: accepted
created: 2026-06-05
resolved:
decision:
resolved: 2026-07-03
decision: DEC-0037
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
---
@@ -99,16 +99,49 @@ Isso preserva o ciclo `Game -> Home/Shell -> Game` sem transformar o runtime em
## Perguntas em Aberto
- [ ] Qual e o nome canonico dos estados de Game fora do foreground: `Paused`, `Suspended`, ambos, ou outro?
- [ ] Ao apertar Home, o Game deve receber um evento/interrupt/trap de pausa antes de parar de executar?
- [ ] O Hub e um Shell especial sempre presente ou uma task Shell comum?
- [ ] Um app Shell VM-backed pode substituir o Hub no foreground ou o Hub permanece como owner raiz?
- [ ] Quando o Shell VM-backed fecha, o retorno vai sempre para Hub ou pode voltar diretamente ao Game?
- [ ] O input do Game e drenado/limpo ao pausar e ao retomar?
- [ ] Audio do Game pausa junto com a VM ou tem politica propria?
- [ ] Existe limite de memoria/residencia para manter Game pausado enquanto Shell app roda?
- [ ] O retorno ao Game exige novo frame antes de trocar a superficie, ou a tela pode manter Hub/Shell ate a primeira submission valida?
- [ ] Quais eventos de lifecycle precisam ser visiveis para firmware, OS, VM e host?
- [x] Qual e o nome canonico dos estados de Game fora do foreground: `Paused`, `Suspended`, ambos, ou outro?
- [x] Ao apertar Home, o Game deve receber um evento/interrupt/trap de pausa antes de parar de executar?
- [x] O Hub e um Shell especial sempre presente ou uma task Shell comum?
- [x] Um app Shell VM-backed pode substituir o Hub no foreground ou o Hub permanece como owner raiz?
- [x] Quando o Shell VM-backed fecha, o retorno vai sempre para Hub ou pode voltar diretamente ao Game?
- [x] O input do Game e drenado/limpo ao pausar e ao retomar?
- [x] Audio do Game pausa junto com a VM ou tem politica propria?
- [x] Existe limite de memoria/residencia para manter Game pausado enquanto Shell app roda?
- [x] O retorno ao Game exige novo frame antes de trocar a superficie, ou a tela pode manter Hub/Shell ate a primeira submission valida?
- [x] Quais eventos de lifecycle precisam ser visiveis para firmware, OS, VM e host?
## Resolucao
Fica aceito o modelo `Game -> Home/Shell -> mesmo Game` com foreground unico e
residencia limitada:
- somente um Game pode estar residente por vez;
- somente um Shell pode ser foreground por vez;
- Hub e o Shell root/especial e permanece owner raiz/back-stack;
- um Shell VM-backed pode assumir o foreground visual, mas segue lifecycle de
Shell e nao herda politica de game loop;
- fechar um Shell VM-backed retorna ao Hub em v1;
- background execution real fica fora de escopo;
- no host desktop, `Esc` e a tecla principal para solicitar Home/SystemOS e a
tecla fisica `Home` pode existir como alias;
- a acao Home/SystemOS e interceptada pelo host/SystemOS e nao entra no pad
logico visivel ao Game;
- `Paused` e o estado/evento cooperativo visivel ao Game;
- `Suspended` e o estado operacional imposto pelo OS/scheduler;
- ao sair do foreground, o OS notifica o Game para pausar e concede um budget
curto de reacao;
- se o Game nao reagir ao pause dentro do budget, o OS suspende a VM mesmo
assim;
- ao retornar, o OS reativa a VM, notifica o Game para resume/foreground
restore e permite que o Game sincronize antes de voltar ao gameplay;
- input pendente do Game e drenado/limpo nas fronteiras de pause/resume;
- audio do Game pausa junto com a VM em v1;
- retorno ao Game deve manter Hub/Shell visivel ate a primeira render submission
valida do Game retomado;
- render ownership muda junto com o foreground owner e invalida submissions
antigas via epoch/generation;
- firmware observa transicoes macro; OS observa lifecycle completo; VM observa
pause/resume; host observa owner/render epoch e estado de apresentacao.
## Criterio para Encerrar
@@ -124,3 +157,22 @@ A agenda pode ser encerrada quando tivermos uma decisao clara sobre:
## Discussao
- 2026-06-05: Agenda criada a partir da `DSC-0040`, quando o caso de Shell VM-backed aberto sobre um Game pausado mostrou que a discussao pertence ao lifecycle/SystemOS, nao apenas ao render worker.
- 2026-07-03: Direcao provisoria aceita para as perguntas 2-10:
Game deve receber evento de pausa com budget curto antes da suspensao; Hub e
Shell root/especial; Shell VM-backed pode assumir foreground visual, mas Hub
permanece como owner raiz/back-stack; fechar Shell VM-backed retorna ao Hub em
v1; input do Game deve ser drenado/limpo em pause/resume; audio do Game pausa
junto com VM em v1; apenas um Game pausado residente e permitido; retorno ao
Game deve manter Hub/Shell visivel ate a primeira submission valida; firmware
ve transicoes macro, OS ve lifecycle completo, VM ve pause/resume, host ve
owner/render epoch e estado de apresentacao.
- 2026-07-03: Pergunta 1 permanece aberta para esclarecer se `Paused` e
`Suspended` sao estados distintos, nomes para camadas diferentes, ou se v1
deve expor somente um deles.
- 2026-07-03: Direcao proposta para pergunta 1: `Paused` e o estado/evento
cooperativo visivel ao Game; `Suspended` e o estado operacional imposto pelo
OS. Ao sair do foreground, o OS notifica o Game para pausar e concede um
budget curto de reacao; se o Game nao reagir, o OS suspende a VM mesmo assim.
Ao retornar, o OS notifica o Game antes de recoloca-lo no foreground visual,
permitindo sincronizacao/revalidacao. O Game nao controla a suspensao, mas
pode observar `pause`/`resume` para ajustar seu estado interno.
@@ -1,161 +0,0 @@
---
id: AGD-0045
ticket: system-run-cart
title: SystemOS Library Root and Home Game Launch
status: accepted
created: 2026-07-03
resolved:
decision:
tags: [runtime, os, hub, cartridge, launcher, library, game, architecture]
---
## Contexto
A `DEC-0035` fechou que `system.run_cart` nao deve existir como syscall
userland e que boot direto por host/CLI/debug deve permanecer.
Isso resolveu a autoridade negativa, mas ainda nao resolveu a experiencia
desejada para o SO: apontar o runtime para um diretorio raiz de biblioteca,
fazer a Home listar os cartuchos encontrados ali e permitir que o usuario clique
em um jogo para carrega-lo.
O objetivo pratico e um "Switch feio": uma lista simples na Home, sem UX final,
sem marketplace e sem catalogo rico, mas capaz de provar que o SO, e nao o
guest, escolhe e carrega um cartucho a partir de uma biblioteca local.
## Problema
Hoje temos dois caminhos separados:
- boot direto por `--run <cart>` funciona e carrega um cartucho unico;
- Hub/Home existe, mas mostra acoes fixas de Shell nativo e nao lista jogos de
uma biblioteca real.
Sem uma biblioteca de cartuchos visivel para o SO, o usuario nao consegue
iniciar jogos a partir da Home. Isso deixa a agenda `system-run-cart` incompleta
do ponto de vista de produto: removemos o `run_cart` userland, mas ainda falta a
alternativa correta, que e o SO iniciar cartuchos por acao de usuario.
## Pontos Criticos
- O root da biblioteca deve ser fornecido pelo host como `--games-root <dir>`.
- O scan inicial deve cobrir subdiretorios imediatos com `manifest.json`.
- O loader de diretorio existente deve continuar sendo a autoridade para validar
cartucho completo; a biblioteca pode ler metadados minimos para listagem.
- A Home pode mostrar uma lista feia/clicavel; polimento visual fica fora.
- O clique em um Game deve iniciar `LoadCartridge` pelo firmware/SystemOS, nao
por syscall guest.
- V1 nao precisa tratar retorno de um Game para Home, porque isso pertence a
`AGD-0041`.
- `.pmc`, outros tipos de app, catalogo remoto, marketplace, icones, busca e
metadados ricos ficam fora.
## Opcoes
### Opcao A - Biblioteca apenas para listagem
- **Abordagem:** adicionar `--games-root`, escanear manifestos e mostrar jogos
na Home, mas sem permitir launch ainda.
- **Pro:** baixa complexidade; prova descoberta/catalogo local.
- **Contra:** nao entrega o objetivo principal de carregar jogo pela Home.
- **Manutenibilidade:** boa, mas valor funcional limitado.
### Opcao B - Home lista biblioteca e carrega Game quando nao ha Game ativo
- **Abordagem:** adicionar `--games-root`, escanear cartuchos locais, renderizar
lista simples na Home e permitir clique para carregar um Game via
`LoadCartridge`. A primeira versao cobre Home inicial/sem Game residente.
- **Pro:** entrega o fluxo desejado sem abrir troca completa entre jogos.
- **Contra:** exige passar biblioteca/acao selecionada entre host, Hub,
firmware e loader.
- **Manutenibilidade:** boa se a fronteira ficar clara: biblioteca descobre,
Hub escolhe, firmware carrega.
### Opcao C - Biblioteca mais troca completa entre jogos
- **Abordagem:** Home lista biblioteca e tambem permite `Game A -> Home ->
Game B` ja no primeiro passo.
- **Pro:** cobre a experiencia final.
- **Contra:** mistura biblioteca com pausa, fechamento, cleanup e falha de load;
depende de `AGD-0041` e `AGD-0044`.
- **Manutenibilidade:** baixa para v1.
## Sugestao / Recomendacao
Recomendo a Opcao B.
O v1 deve permitir:
- host recebe `--games-root <dir>`;
- o SO/Hub recebe uma lista de cartuchos descobertos;
- a Home mostra uma lista simples/clicavel de jogos;
- clicar em um Game carrega o cartucho via firmware `LoadCartridge`;
- boot direto por `--run <cart>` continua separado e intacto;
- nenhum guest/app chama `run_cart`;
- o escopo v1 acontece na Home inicial; retorno de Game para Home fica para
`AGD-0041`, e troca `Game A -> Home -> Game B` fica para `AGD-0044`.
Detalhes aceitos para v1:
- scan apenas de subdiretorios imediatos;
- somente cartuchos `app_mode: Game`;
- `.pmc` fica para futuro;
- cartuchos invalidos sao logados e omitidos da lista;
- o modelo interno deve ser uma entry de biblioteca expansivel, nao apenas um
summary de UI. A entry pode manter o manifest carregado em memoria, path
interno necessario para launch e metadados operacionais como instante de
descoberta/instalacao. A UI v1 mostra apenas `title`, `app_id` e
`app_version`, mas futuros metadados ingeridos pela biblioteca poderao ser
usados pelo catalogo e pela propria UI;
- clique carrega imediatamente, sem confirmacao;
- falha de load volta para Home e registra log/erro.
Essa agenda deve produzir a alternativa correta ao `run_cart` userland: uma
acao de sistema, iniciada pela Home, que carrega cartucho escolhido pelo usuario
a partir de uma biblioteca local.
## Perguntas em Aberto
- [x] O argumento deve se chamar `--games-root`.
- [x] A biblioteca deve escanear apenas subdiretorios imediatos.
- [x] A listagem v1 deve incluir apenas `app_mode: Game`.
- [x] O scan deve logar cartuchos invalidos e omiti-los da lista.
- [x] O Hub/SystemOS deve receber uma entry de biblioteca expansivel, capaz de
manter o manifest carregado, path interno para launch e metadados
operacionais como timestamp de descoberta/instalacao. A UI v1 so precisa
mostrar `title`, `app_id` e `app_version`.
- [x] O clique deve carregar imediatamente, sem confirmacao.
- [x] Se um cartucho falha ao carregar, o sistema volta para Home e registra
erro/log.
- [x] Retorno de Game para Home nao pertence a esta agenda; fica para
`AGD-0041`.
- [x] O teste minimo deve provar o fluxo `games-root -> Home list -> click ->
LoadCartridge -> GameRunning`?
## Criterio para Encerrar
A agenda pode virar decisao quando estiver claro:
- nome e semantica do argumento de host para root da biblioteca;
- escopo do scan e metadados minimos;
- fronteira entre biblioteca, Hub, firmware e loader;
- politica v1 para cartuchos invalidos;
- regra v1 para launch quando nao ha Game ativo;
- fronteira explicita com `AGD-0041` e `AGD-0044`;
- testes minimos para discovery e launch pela Home.
## Discussao
- 2026-07-03: Agenda criada como continuacao da `DSC-0004` apos a `DEC-0035`.
A decisao anterior removeu `run_cart` userland; esta agenda define o caminho
correto para o SO/Home carregar jogos a partir de uma biblioteca local.
- 2026-07-03: Respostas aceitas: usar `--games-root`, escanear apenas
subdiretorios imediatos, listar somente Games, deixar `.pmc` e outros apps
para depois, logar/omitir invalidos, usar summary com `title`, `app_id` e
`app_version`, carregar imediatamente no clique, e deixar retorno para Home
sob responsabilidade da `AGD-0041`.
- 2026-07-03: Modelo de dados refinado: a biblioteca deve produzir entries
expansíveis, nao somente summaries de UI. Cada entry pode manter manifest em
memoria, path interno de launch e metadados operacionais como timestamp de
descoberta/instalacao; a UI v1 escolhe quais campos mostrar, mas o modelo
deve permitir que metadados futuros sejam ingeridos e usados pelo catalogo/UI.