System Run Cart
This commit is contained in:
@@ -2,7 +2,7 @@
|
||||
id: AGD-0003
|
||||
ticket: system-run-cart
|
||||
title: Agenda - System Run Cart
|
||||
status: open
|
||||
status: accepted
|
||||
created: 2026-03-27
|
||||
resolved:
|
||||
decision:
|
||||
@@ -13,11 +13,14 @@ tags: []
|
||||
|
||||
## Problema
|
||||
|
||||
A syscall `system.run_cart` existe na ABI pública, mas hoje não produz efeito real no runtime.
|
||||
`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 a syscall;
|
||||
- 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.
|
||||
@@ -25,56 +28,92 @@ Isso cria uma falsa promessa de plataforma:
|
||||
## 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 de `system.run_cart` do ponto de vista:
|
||||
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 syscall:
|
||||
Ao final da discussão, deve ficar claro se a superfície atual:
|
||||
|
||||
- permanece na ABI e ganha implementação completa; ou
|
||||
- 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": trocar imediatamente, agendar para o próximo frame, retornar ao firmware, reiniciar VM atual, ou apenas emitir uma intençã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.
|
||||
Quem pode chamar isso, sob qual capability, e com quais restrições para evitar que um app force navegação arbitrária do sistema?
|
||||
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, ou combinação dos três?
|
||||
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 com:
|
||||
- estado do app atual;
|
||||
- FS aberto;
|
||||
- assets carregados;
|
||||
- telemetria;
|
||||
- crash reports;
|
||||
- logs.
|
||||
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.
|
||||
Quais falhas retornam trap ao guest e quais viram evento de sistema.
|
||||
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
|
||||
|
||||
- fluxo fechado entre syscall -> runtime -> firmware -> loader -> novo app;
|
||||
- modelo explícito para seleção do alvo;
|
||||
- definição de lifecycle da troca de cartucho;
|
||||
- testes de integração cobrindo transição bem-sucedida, alvo inválido, capability insuficiente e cleanup de estado.
|
||||
- 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
|
||||
|
||||
@@ -82,13 +121,82 @@ Ao final da discussão, deve ficar claro se a syscall:
|
||||
- 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:
|
||||
|
||||
- assinatura final da syscall;
|
||||
- local canônico da troca de estado;
|
||||
- política de erro;
|
||||
- limpeza de recursos;
|
||||
- cobertura mínima de testes de integração.
|
||||
- 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.
|
||||
|
||||
@@ -0,0 +1,145 @@
|
||||
---
|
||||
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.
|
||||
Reference in New Issue
Block a user