System Run Cart

This commit is contained in:
2026-07-03 09:56:02 +01:00
parent 23d3ed641e
commit 2ab5c43334
7 changed files with 670 additions and 28 deletions
@@ -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.