prometeu-runtime/discussion/workflow/agendas/AGD-0041-foreground-stack-game-pause-shell-vm-backed.md

id	ticket	title	status	created	resolved	decision	tags
AGD-0041	foreground-stack-game-pause-shell-vm-backed	Foreground Stack, Game Pause, and VM-Backed Shell Coexistence	accepted	2026-06-05	2026-07-03	DEC-0037	runtime os lifecycle shell game vm foreground architecture

Contexto

Durante a discussao da DSC-0040 sobre separar VM e render worker, surgiu um caso que nao pertence somente ao render: Game -> Shell -> Game.

O caso minimo e:

• um Game esta rodando;
• o usuario aperta Home;
• o Game deve sair do foreground sem ser encerrado;
• o Hub/Shell assume a tela;
• o usuario pode abrir um app Shell, inclusive VM-backed;
• depois o usuario retorna ao mesmo Game.

O render worker precisa saber qual visual owner pode apresentar frames, mas a decisao principal e de lifecycle: quais VMs existem, quais podem executar, o que significa pausar um Game, e como Shell apps coexistem com um Game pausado.

Material relacionado:

• DSC-0031: separacao entre perfis Game e System/Shell.
• DSC-0032: SystemOS como autoridade de lifecycle/process/task.
• DSC-0035: janelas Shell pertencem a tasks e definem liveness do app.
• DSC-0036: Hub/Shell prova fatias de lifecycle.
• DSC-0040: render ownership/epoch durante transicoes e paralelismo VM/render.

Problema

Precisamos definir o contrato de foreground para impedir ambiguidades como:

• Game pausado continuando a executar frames logicos enquanto Shell esta no foreground;
• Shell VM-backed competindo com Game por pacing, input, superficie ou render ownership;
• multiplos Shells foreground ou multiplos Games ativos sem uma politica explicita;
• retorno ao Game sem clareza sobre estado pausado, input, render invalidation e retomada da VM.

Sem esse contrato, a separacao VM/render da DSC-0040 pode ficar tecnicamente correta, mas o SystemOS ainda pode permitir estados incoerentes.

Pontos Criticos

• Existe apenas um foreground visual owner por vez.
• Background execution e outro assunto e deve ficar fora da primeira decisao, salvo se for necessario definir uma proibicao explicita.
• Shell VM-backed nao deve herdar politica de game loop so por usar VM.
• Game pausado provavelmente deve reter estado, mas nao deve consumir frames logicos.
• O Hub/Shell precisa ser capaz de rodar enquanto o Game esta suspenso.
• A transicao deve invalidar render submissions antigas para impedir present de frames obsoletos.
• O modelo precisa caber no SystemOS/lifecycle existente, nao diretamente no render worker.

Opcoes

Opcao A - Foreground unico, Game suspenso, Shell unico

• Abordagem: permitir no maximo um Game carregado e no maximo um Shell foreground; ao apertar Home, o Game entra em estado pausado/suspenso e Shell/Hub assume o foreground. Shell VM-backed pode executar apenas enquanto for o foreground Shell.
• Pro: modelo simples, previsivel e alinhado com console; reduz concorrencia real entre VMs; combina com a regra de render ownership unico.
• Contra: nao cobre multitarefa/background; futuras features de overlay ou apps persistentes precisarao expandir o contrato.
• Manutenibilidade: alta; SystemOS pode modelar uma pilha pequena de foreground/suspended sem virar scheduler generico.

Opcao B - Multiplas VMs residentes, somente foreground executa

• Abordagem: permitir que Game e Shell VM-backed coexistam como VMs residentes, mas somente a entidade foreground executa. O Game pausado fica residente, sem tick; Shell VM-backed roda sob lifecycle Shell.
• Pro: preserva estado e permite retorno rapido; nao exige background execution.
• Contra: precisa contrato claro de memoria, ownership de input, foco, cancelamento e fechamento.
• Manutenibilidade: boa se os estados forem explicitos; ruim se a residencia for confundida com execucao em background.

Opcao C - Encerrar Game ao entrar no Shell VM-backed

• Abordagem: Home fecha/salva o Game antes de abrir Shell VM-backed, evitando coexistencia.
• Pro: simplifica o runtime.
• Contra: quebra a expectativa de console moderno; torna Game -> Shell -> Game um reload, nao uma pausa.
• Manutenibilidade: simples no curto prazo, mas provavelmente gera mais excecoes e UX ruim depois.

Opcao D - Background real desde ja

• Abordagem: permitir Game pausado ou Shell apps rodando em background com politicas de prioridade.
• Pro: cobre casos futuros ricos.
• Contra: amplia demais escopo: scheduler, budget, energia, audio, input, IO e memoria.
• Manutenibilidade: baixa para v1; mistura a decisao de foreground com multitarefa real.

Sugestao / Recomendacao

Recomendo seguir com a combinacao das opcoes A e B:

• somente um Game residente por vez;
• somente um Shell foreground por vez;
• Game pode ficar pausado/suspenso enquanto Shell esta foreground;
• Shell VM-backed pode existir junto com Game pausado, mas segue lifecycle Shell;
• somente o owner foreground executa VM/tick/event loop conforme sua politica;
• background execution fica explicitamente fora de escopo;
• render ownership muda junto com foreground owner e deve invalidar submissions antigas via epoch/generation, conforme DSC-0040.

Isso preserva o ciclo Game -> Home/Shell -> Game sem transformar o runtime em multitarefa geral agora.

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?

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

A agenda pode ser encerrada quando tivermos uma decisao clara sobre:

• cardinalidade de Games e Shells residentes/foreground;
• semantica de Game pausado/suspenso;
• politica de execucao para Shell VM-backed durante Game pausado;
• regra de foreground visual owner e render invalidation;
• comportamento minimo do ciclo Game -> Shell -> Game;
• itens explicitamente fora de escopo, especialmente background execution real.

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.