VM Context Ownership for Resident Game and VM-Backed Shell
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
This commit is contained in:
@@ -1,178 +0,0 @@
|
||||
---
|
||||
id: AGD-0041
|
||||
ticket: foreground-stack-game-pause-shell-vm-backed
|
||||
title: Foreground Stack, Game Pause, and VM-Backed Shell Coexistence
|
||||
status: accepted
|
||||
created: 2026-06-05
|
||||
resolved: 2026-07-03
|
||||
decision: DEC-0037
|
||||
tags: [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
|
||||
|
||||
- [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
|
||||
|
||||
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.
|
||||
-186
@@ -1,186 +0,0 @@
|
||||
---
|
||||
id: AGD-0046
|
||||
ticket: foreground-stack-game-pause-shell-vm-backed
|
||||
title: VM Context Ownership for Resident Game and VM-Backed Shell
|
||||
status: accepted
|
||||
created: 2026-07-04
|
||||
resolved:
|
||||
decision: DEC-0038
|
||||
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
|
||||
---
|
||||
|
||||
## Contexto
|
||||
|
||||
`DEC-0037` define que o v1 deve suportar o fluxo `Game -> Home/Shell -> same
|
||||
Game`, com o Game residente pausado/suspenso enquanto Hub ou Shell possuem o
|
||||
foreground. A implementacao atual ja impede que Shell nativo ticke o Game
|
||||
suspenso, porque Shell nativo nao usa a VM.
|
||||
|
||||
A lacuna aparece quando o Shell tambem eh VM-backed. Hoje `Firmware` possui um
|
||||
unico `VirtualMachine` global (`Firmware.vm`). O Game residente e um Shell
|
||||
VM-backed competem por esse mesmo contexto. Se o Shell VM-backed inicializa uma
|
||||
nova cartridge nesse objeto, ele sobrescreve o contexto do Game que deveria
|
||||
permanecer residente/suspenso.
|
||||
|
||||
Isso significa que o modelo de foreground/task/process ja avancou, mas o modelo
|
||||
de contexto VM ainda esta acoplado ao firmware global.
|
||||
|
||||
## Problema
|
||||
|
||||
Precisamos decidir onde vive o contexto de execucao VM quando existem, ao mesmo
|
||||
tempo, um Game residente suspenso e um Shell VM-backed foreground.
|
||||
|
||||
O problema nao eh apenas pausar ticks. Para coexistencia real, cada VM-backed
|
||||
process precisa preservar seu proprio estado: PC, stack, heap, globals,
|
||||
cartridge identity, runtime services escopados, render ownership metadata e
|
||||
eventos lifecycle pendentes.
|
||||
|
||||
Enquanto `Firmware.vm` for unico, "suspender" um Game VM nao preserva o
|
||||
contexto se outra cartridge VM-backed for carregada.
|
||||
|
||||
## Pontos Criticos
|
||||
|
||||
- `DEC-0037` diz que um Game suspenso nao recebe ticks/input/frame pacing, mas
|
||||
continua residente para voltar ao mesmo Game.
|
||||
- Shell nativo nao precisa de VM context proprio, mas Shell VM-backed precisa.
|
||||
- `SystemOS` ja eh autoridade de lifecycle/process/task, entao eh candidato
|
||||
natural para possuir ou localizar contextos VM por sessao.
|
||||
- `Firmware` deve orquestrar macro estados, mas nao deveria ser dono unico do
|
||||
contexto de todos os processos VM-backed.
|
||||
- `VirtualMachineRuntime` contem estado atualmente misto: identidade da
|
||||
cartridge atual, render manager, lifecycle delivery, fs/memcard/open handles
|
||||
e telemetria. Precisamos separar o que eh global do OS do que eh por sessao
|
||||
VM-backed.
|
||||
- A solucao deve preservar a restricao v1: no maximo um Game residente e no
|
||||
maximo um Shell foreground. Ela nao deve abrir multitasking geral.
|
||||
- Game-to-Game switching continua fora desta agenda e pertence a `DSC-0043`.
|
||||
|
||||
## Opcoes
|
||||
|
||||
### Opcao A - Manter VM global no Firmware e bloquear Shell VM-backed com Game residente
|
||||
|
||||
- **Abordagem:** documentar que Shell VM-backed nao pode abrir enquanto um Game
|
||||
VM esta residente; apenas Shell nativo coexiste com Game suspenso.
|
||||
- **Pro:** menor implementacao imediata.
|
||||
- **Contra:** contradiz a intencao de coexistencia de VM-backed Shell em
|
||||
`DEC-0037` e deixa a arquitetura incompleta.
|
||||
- **Manutenibilidade:** baixa, porque o sistema teria regras diferentes para
|
||||
Shell nativo e Shell VM-backed sem uma fronteira clara de sessao.
|
||||
|
||||
### Opcao B - Serializar o Game VM ao suspender e restaurar ao resumir
|
||||
|
||||
- **Abordagem:** ao suspender Game, extrair snapshot do `VirtualMachine` e do
|
||||
runtime associado; ao resumir, restaurar snapshot depois do Shell VM-backed.
|
||||
- **Pro:** preserva a ideia de um unico VM executor ativo.
|
||||
- **Contra:** exige serializacao profunda e correta de todo o estado VM/runtime,
|
||||
incluindo handles, assets, render state e side effects. Isso eh muito mais
|
||||
complexo que a necessidade v1.
|
||||
- **Manutenibilidade:** baixa a media; snapshots viram contrato dificil e
|
||||
fragil antes de termos necessidade de hibernacao real.
|
||||
|
||||
### Opcao C - Tornar o contexto VM propriedade da sessao/processo VM-backed
|
||||
|
||||
- **Abordagem:** cada processo VM-backed possui seu proprio `VirtualMachine` e
|
||||
seu contexto runtime VM-scoped. O scheduler/firmware seleciona qual sessao
|
||||
recebe tick conforme foreground/lifecycle. Game suspenso simplesmente deixa
|
||||
de ser tickado, mas seu contexto permanece armazenado na sessao Game.
|
||||
- **Pro:** alinha com task/process/lifecycle, suporta Game residente + Shell
|
||||
VM-backed sem sobrescrever contexto, e prepara o terreno para futuras sessoes
|
||||
sem implementar multitasking geral agora.
|
||||
- **Contra:** exige separar estado hoje concentrado em `Firmware.vm` e
|
||||
`SystemOS.vm_runtime`, decidindo o que eh global do OS e o que eh por sessao.
|
||||
- **Manutenibilidade:** alta, porque a posse do contexto acompanha o processo
|
||||
que executa a VM.
|
||||
|
||||
### Opcao D - Criar apenas dois slots VM fixos: Game VM e Shell VM
|
||||
|
||||
- **Abordagem:** manter um slot `game_vm` e um slot `shell_vm`, em vez de uma VM
|
||||
por processo/sessao.
|
||||
- **Pro:** mais simples que uma tabela geral de sessoes.
|
||||
- **Contra:** codifica uma limitacao acidental. Ainda precisariamos decidir
|
||||
ownership, runtime scoped state e lifecycle por slot. Pode virar refactor
|
||||
duplo quando mais de um Shell ou Game switching aparecer.
|
||||
- **Manutenibilidade:** media; aceitavel como stepping stone somente se modelado
|
||||
internamente como sessao, nao como campos especiais permanentes.
|
||||
|
||||
## Sugestao / Recomendacao
|
||||
|
||||
Seguir a Opcao C: contexto VM deve pertencer a uma sessao/processo VM-backed,
|
||||
nao ao `Firmware` global.
|
||||
|
||||
Para v1, a implementacao pode continuar limitada a uma sessao Game residente e
|
||||
uma sessao Shell foreground, mas o modelo deve ser "session-owned VM context".
|
||||
Isso permite que Shell VM-backed rode enquanto o Game fica suspenso sem perder
|
||||
PC/stack/heap/estado runtime.
|
||||
|
||||
O firmware deve deixar de possuir a VM como estado global de todos os apps e
|
||||
passar a pedir ao SystemOS/runtime scheduler o contexto VM ativo para o owner
|
||||
foreground. `SystemOS` deve continuar sendo a autoridade de lifecycle; o
|
||||
runtime deve separar estado VM-scoped de estado global de OS/render/telemetria
|
||||
conforme necessario.
|
||||
|
||||
## Perguntas em Aberto
|
||||
|
||||
- [ ] Qual objeto deve representar a sessao VM-backed: `Process`, novo
|
||||
`VmSession`, ou uma tabela separada ligada a `ProcessId`/`TaskId`?
|
||||
- [ ] Quais campos de `VirtualMachineRuntime` sao por sessao VM-backed e quais
|
||||
devem permanecer globais em `SystemOS`?
|
||||
- [ ] O render manager fica global por foreground owner ou dentro de cada
|
||||
contexto VM com handoff global?
|
||||
- [ ] Handles de FS, memcard, assets e open files devem ser por sessao,
|
||||
por app_id, ou globais com namespace por processo?
|
||||
- [ ] Como `LoadCartridgeStep` deve mudar: criar sessao VM nova, ativar sessao
|
||||
existente, ou delegar tudo para uma facade de sessions?
|
||||
- [ ] Como preservar os testes e invariantes de `DEC-0037` durante a migracao
|
||||
incremental sem abrir multitasking geral?
|
||||
- [ ] Como processos background-capable, como um player de musica, entram no
|
||||
modelo sem confundir foreground visual ownership com elegibilidade de
|
||||
execucao?
|
||||
- [ ] Cada Shell VM-backed deve ter uma VM propria, mesmo quando existe mais de
|
||||
um Shell em memoria no futuro?
|
||||
|
||||
## Criterio para Encerrar
|
||||
|
||||
Esta agenda pode virar decision quando definirmos:
|
||||
|
||||
- o proprietario canonico do contexto VM;
|
||||
- a fronteira entre estado VM-scoped e estado global do OS;
|
||||
- como firmware seleciona/ticka a sessao VM ativa;
|
||||
- como Game residente suspenso e Shell VM-backed foreground coexistem;
|
||||
- quais restricoes v1 permanecem explicitamente fora de escopo.
|
||||
|
||||
## Discussion
|
||||
|
||||
- 2026-07-04: Aberta a partir da observacao de que Shell nativo coexiste com
|
||||
Game suspenso, mas Shell VM-backed ainda conflita com o `Firmware.vm` unico.
|
||||
- 2026-07-04: Discussao adicional separou foreground ownership de background
|
||||
execution. A recomendacao atual eh que todo processo VM-backed tenha sua
|
||||
propria `VmSession`; processos background-capable devem ser modelados como
|
||||
sessoes com classe/politica de scheduling propria, nao como foreground owners.
|
||||
|
||||
## Resolution
|
||||
|
||||
Resolvido em 2026-07-04:
|
||||
|
||||
- O modelo deve seguir a Opcao C: todo processo VM-backed deve possuir uma
|
||||
`VmSession` propria, ligada ao lifecycle/task/process, em vez de depender de
|
||||
um `Firmware.vm` global.
|
||||
- Cada Shell VM-backed deve ter sua propria sessao VM. Ele pode compartilhar a
|
||||
engine/runtime e caches imutaveis, mas nao stack, heap, PC, globals, handles
|
||||
ou identidade mutavel de execucao.
|
||||
- O Game residente suspenso preserva seu contexto porque sua `VmSession`
|
||||
continua viva; ele apenas deixa de ser elegivel para ticks normais enquanto
|
||||
Hub/Shell possui foreground.
|
||||
- Foreground ownership e background execution sao conceitos separados.
|
||||
Foreground ownership decide input visual, render ownership e frame pacing
|
||||
normal. Execution eligibility decide quais sessoes podem receber ticks sem
|
||||
serem foreground.
|
||||
- Background execution, como player de musica ou background services, nao entra
|
||||
na primeira implementacao desta agenda. Mesmo assim, o modelo de `VmSession`
|
||||
deve ser obrigatoriamente compativel com essa evolucao em um futuro proximo.
|
||||
- Render ownership permanece autoridade global do SystemOS. Sessoes VM-backed
|
||||
produzem frames, mas nao decidem se podem apresentar.
|
||||
- `LoadCartridgeStep` nao deve inicializar uma VM global diretamente. Ele deve
|
||||
delegar criacao/ativacao de sessao para uma facade de sessions/scheduler.
|
||||
|
||||
Esta agenda esta pronta para virar decision normativa.
|
||||
Reference in New Issue
Block a user