discussion/index.ndjson

@@ -1,4 +1,4 @@
-{"type":"meta","next_id":{"DSC":31,"AGD":31,"DEC":23,"PLN":46,"LSN":40,"CLSN":1}}
+{"type":"meta","next_id":{"DSC":32,"AGD":32,"DEC":24,"PLN":46,"LSN":40,"CLSN":1}}
 {"type":"discussion","id":"DSC-0023","status":"done","ticket":"perf-full-migration-to-atomic-telemetry","title":"Agenda - [PERF] Full Migration to Atomic Telemetry","created_at":"2026-04-10","updated_at":"2026-04-10","tags":["perf","runtime","telemetry"],"agendas":[{"id":"AGD-0021","file":"workflow/agendas/AGD-0021-full-migration-to-atomic-telemetry.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}],"decisions":[{"id":"DEC-0008","file":"workflow/decisions/DEC-0008-full-migration-to-atomic-telemetry.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10"}],"plans":[{"id":"PLN-0007","file":"workflow/plans/PLN-0007-full-migration-to-atomic-telemetry.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}],"lessons":[{"id":"LSN-0028","file":"lessons/DSC-0023-perf-full-migration-to-atomic-telemetry/LSN-0028-converging-to-single-atomic-telemetry-source.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
 {"type":"discussion","id":"DSC-0020","status":"done","ticket":"jenkins-gitea-integration","title":"Jenkins Gitea Integration and Relocation","created_at":"2026-04-07","updated_at":"2026-04-07","tags":["ci","jenkins","gitea"],"agendas":[{"id":"AGD-0018","file":"workflow/agendas/AGD-0018-jenkins-gitea-integration-and-relocation.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"decisions":[{"id":"DEC-0003","file":"workflow/decisions/DEC-0003-jenkins-gitea-strategy.md","status":"accepted","created_at":"2026-04-07","updated_at":"2026-04-07"}],"plans":[{"id":"PLN-0003","file":"workflow/plans/PLN-0003-jenkins-gitea-execution.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"lessons":[{"id":"LSN-0021","file":"lessons/DSC-0020-jenkins-gitea-integration/LSN-0021-jenkins-gitea-integration.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}]}
 {"type":"discussion","id":"DSC-0021","status":"done","ticket":"asset-entry-codec-enum-with-metadata","title":"Asset Entry Codec Enum Contract","created_at":"2026-04-09","updated_at":"2026-04-09","tags":["asset","runtime","codec","metadata"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0024","file":"lessons/DSC-0021-asset-entry-codec-enum-contract/LSN-0024-string-on-the-wire-enum-in-runtime.md","status":"done","created_at":"2026-04-09","updated_at":"2026-04-09"}]}
@@ -29,3 +29,4 @@
 {"type":"discussion","id":"DSC-0018","status":"done","ticket":"asset-load-asset-id-int-contract","title":"Asset Load Asset ID Int Contract","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["asset","runtime","abi"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0019","file":"lessons/DSC-0018-asset-load-asset-id-int-contract/LSN-0019-asset-load-id-abi-convergence.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
 {"type":"discussion","id":"DSC-0019","status":"done","ticket":"jenkinsfile-correction","title":"Jenkinsfile Correction and Relocation","created_at":"2026-04-07","updated_at":"2026-04-07","tags":["ci","jenkins"],"agendas":[{"id":"AGD-0017","file":"workflow/agendas/AGD-0017-jenkinsfile-correction.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"decisions":[{"id":"DEC-0002","file":"workflow/decisions/DEC-0002-jenkinsfile-strategy.md","status":"accepted","created_at":"2026-04-07","updated_at":"2026-04-07"}],"plans":[{"id":"PLN-0002","file":"workflow/plans/PLN-0002-jenkinsfile-execution.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"lessons":[{"id":"LSN-0020","file":"lessons/DSC-0019-jenkins-ci-standardization/LSN-0020-jenkins-standard-relocation.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}]}
 {"type":"discussion","id":"DSC-0030","status":"done","ticket":"internal-viewport-270p","title":"Agenda - Internal Viewport 270p (480x270)","created_at":"2026-04-27","updated_at":"2026-04-28","tags":["gfx","runtime","viewport","resolution","frame-composer","host"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0039","file":"lessons/DSC-0030-internal-viewport-270p/LSN-0039-resolution-baseline-changes-are-runtime-wide-contracts.md","status":"done","created_at":"2026-04-28","updated_at":"2026-04-28"}]}
+{"type":"discussion","id":"DSC-0031","status":"open","ticket":"runtime-mode-separation-game-system","title":"Agenda - Runtime Mode Separation: Game and System","created_at":"2026-05-11","updated_at":"2026-05-14","tags":["runtime","firmware","hub","system-apps","game-mode","scheduler"],"agendas":[{"id":"AGD-0031","file":"AGD-0031-runtime-mode-separation-game-system.md","status":"accepted","created_at":"2026-05-11","updated_at":"2026-05-14"}],"decisions":[{"id":"DEC-0023","file":"DEC-0023-system-pipeline-separation.md","status":"accepted","created_at":"2026-05-14","updated_at":"2026-05-14"}],"plans":[],"lessons":[]}

discussion/workflow/agendas/AGD-0031-runtime-mode-separation-game-system.md

@@ -0,0 +1,336 @@
+---
+id: AGD-0031
+ticket: runtime-mode-separation-game-system
+title: Agenda - Runtime Mode Separation: Game and System
+status: accepted
+created: 2026-05-11
+resolved: 2026-05-14
+decision: DEC-0023
+tags: [runtime, firmware, hub, system-apps, game-mode, scheduler]
+---
+
+## Contexto
+
+O Prometeu precisa separar corretamente modos operacionais diferentes. A pergunta inicial nasceu a partir de tween/UI, mas a discussao revelou que o ponto central nao e animacao: e a diferenca entre pipeline de jogo e pipeline de sistema/app.
+
+O estado atual tem algumas separacoes de render/composicao, mas ainda mistura pipeline de app de sistema com pipeline de jogo:
+
+- `FrameComposer` e o dono da composicao canonica de cenas, camera e sprites.
+- `Gfx` executa raster e efeitos globais como fade de scene/HUD.
+- primitivas `gfx.*` sao drenadas como overlay final, fora do contrato canonico de jogo.
+- o `PrometeuHub` tem uma UI simples baseada em `WindowManager`, com janelas estaticas e renderizacao imediata por `fill_rect`.
+- a VM ja tem `FrameSync`, entao o tempo logico natural para animacao e por frame, nao por relogio de host.
+
+O objetivo agora e definir uma separacao correta entre:
+
+- modo jogo;
+- modo sistema/Hub;
+- apps Prometeu rodando dentro do ambiente do Hub.
+
+Atualizacao da discussao: ha uma separacao importante entre UI de jogos e UI do sistema Prometeu. Para jogos, a direcao preferida e nao criar syscalls especificas de UI; um framework/biblioteca pode compor UI usando as primitivas existentes de sprites, cena, input e frame sync. Para o PrometeuHub e apps do Prometeu, a UI do sistema pode ter uma camada propria. Se essa camada for exportada para devs criarem apps do Prometeu, ela nao deve ser tratada como API de jogo comum, e talvez nem como syscall tradicional.
+
+Atualizacao adicional: apps do Prometeu podem ser escritos em PBS, como jogos, mas isso nao implica que usem o mesmo pipeline de jogo. A linguagem/formato de programa pode ser comum, enquanto o modo de execucao muda: hub e apps do sistema podem rodar a 30 Hz, 24 Hz ou em um modelo mais orientado a invalidacao/eventos, e devem compartilhar o mesmo ambiente de UI do PrometeuHub.
+
+Atualizacao de retomada: a direcao preferida agora e reaproveitar a mesma VM e linguagens afins para apps de sistema, mas com perfil de biblioteca/capacidades separado. Apps `system` nao devem importar nem depender da stdlib de jogos: nada de `FrameComposer`, `Gfx` ou `Input` como superficie publica. `Logs` talvez possa existir como servico comum ou adaptado. `fs` provavelmente precisa existir de forma diferenciada: mais filesystem de app/sistema e menos modelo de memory card de jogo.
+
+Atualizacao sobre manifest/tooling: nao precisamos introduzir um novo `target`. O `manifest.json` ja possui o campo `app_mode`/`AppMode`, que e exatamente o discriminante de perfil desta discussao: `Game` ou `System`. O compiler deve usar esse modo para escolher/injetar a stdlib correta durante a compilacao, e o Studio tambem deve usar essa informacao para orientar projeto, build, validacao e UX. Internamente, `Logs` pode enderecar o mesmo servico/runtime, mas do ponto de vista do Studio e da autoria deve existir via stdlib de perfil, mesmo que o conteudo inicial seja equivalente. O contrato minimo de `fs` para `System` pertence a uma agenda especifica; esta agenda deve apenas fixar que `Game` e `System` terao recursos expostos de forma diferenciada.
+
+Leitura do estado atual do codigo: o firmware e tickado pelo host uma vez por frame, com comentario explicito de 60 Hz. O `PrometeuHub` shell em si nao roda via `VirtualMachineRuntime::tick`; `HubHomeStep` chama `hub.gui_update(...)`, depois `hub.render(...)`, e por fim `present()`. Porem, quando existe uma janela focada de app `System`, `HubHomeStep` chama `ctx.os.tick(ctx.vm, ctx.signals, ctx.hw)`, que e o mesmo caminho usado por `GameRunningStep` para jogos. Portanto, hoje o Hub shell e direto no firmware, mas apps de sistema dentro do Hub compartilham o pipeline de VM/logical-frame dos jogos.
+
+Direcao ajustada: esse comportamento atual esta errado para apps Prometeu. Apps nao devem ser tratados como jogos rodando dentro de uma janela. Eles devem ter um pipeline especifico de app, com userland proprio dentro do Hub, acesso a diretivas de janelas/componentes, servicos de disco, perifericos e capacidades de sistema. A analogia operacional e mais proxima de um ambiente de apps tipo Android do que de um cartucho de jogo.
+
+Direcao de fechamento da agenda: o sistema de janelas, UI e apps `System` deve ser tratado como dominio proprio do Prometeu Runtime/Hub, separado do pipeline de jogo. Mesmo que, no futuro, apps PBS usem syscalls para criar janelas, componentes e receber eventos, a syscall sera apenas transporte. O contrato real sera uma ABI especifica do perfil `System`, diferente da ABI de jogos com `Gfx`, `Input`, banks, sprites e memory cards.
+
+A primeira fatia de trabalho nao deve construir o `WindowManager` completo. O escopo desta agenda e separar o pipeline: o caminho de jogo fica intocado, e `System` passa a ter um pipeline especifico do Runtime/Hub que encaminha execucao, eventos e renderizacao para o dominio do `WindowManager`. Esse pipeline deve seguir a inspiracao operacional do Android: apps de sistema vivem em um ambiente de janelas/UI gerenciado pelo sistema, nao em um loop de jogo dentro de uma janela.
+
+Somente depois que esse pipeline interno e o modelo do `WindowManager` amadurecerem, o dominio deve ser exposto para apps `System` por meio de ABI publica propria e stdlib/framework PBS de perfil `System`. Assim, PBS pode construir apps de sistema usando janelas, componentes, eventos, lifecycle e filesystem de app, sem herdar `FrameComposer`, `Gfx` ou `Input` do perfil de jogo.
+
+## Problema
+
+Hoje `AppMode::System` ainda cai no caminho de execucao da VM usado por jogos quando ha uma janela focada no Hub. Isso transforma app de sistema em "jogo dentro de uma janela", quando o modelo desejado e outro: apps Prometeu devem rodar em um userland proprio do Hub, com pipeline, pacing, lifecycle, janelas/componentes, disco/perifericos e capacidades de sistema.
+
+O risco e resolver sintomas de UI antes de corrigir o modo operacional:
+
+- se entrar em `Gfx`, mistura politica de UI com raster;
+- se entrar em `FrameComposer`, mistura estado de interface com composicao canonica de jogo;
+- se virar syscall publica cedo demais, congela ABI antes de sabermos quais propriedades realmente precisam ser animadas;
+- se ficar apenas no hub sem modelo claro, pode virar duplicacao quando outras UIs precisarem da mesma mecanica.
+- se tratarmos apps do Prometeu como jogos, forçamos uma API de sistema dentro do contrato de cartucho.
+- se acoplarmos PBS a um unico modo de execucao, perdemos a chance de ter perfis diferentes para jogo, hub e app sem duplicar linguagem/tooling.
+- se apps de sistema continuarem usando `VirtualMachineRuntime::tick` como jogos, o Hub vira apenas um wrapper visual em vez de um ambiente operacional real.
+- se a API de apps for desenhada como syscalls de jogo, ela tende a misturar contrato de cartucho com contrato de userland do sistema.
+- se apps `system` herdarem a stdlib de jogos, `FrameComposer`, `Gfx` e `Input` vazam para um dominio onde a UI, o roteamento de input e a composicao pertencem ao Hub/sistema.
+- se `fs` for apenas memory card, apps de sistema ficam artificialmente limitados; se for FS amplo demais, quebramos isolamento e capacidade.
+- se a primeira entrega tentar construir todo o WindowManager em vez de separar o pipeline, o escopo explode e mistura decisao arquitetural com desenho completo de UI.
+- se a primeira entrega tentar abrir ABI publica PBS antes do pipeline interno amadurecer, congelamos uma superficie de System sem saber se o modelo de Hub funciona.
+- se tratarmos syscalls futuras como contrato conceitual em vez de transporte, repetimos o erro de deixar o mecanismo de chamada definir a arquitetura.
+
+## Pontos Criticos
+
+- O tempo deve ser deterministico e baseado em frames logicos, provavelmente avançado em `FrameSync`/`begin_frame`.
+- A primeira entrega deve animar estado de UI do sistema, nao definir ainda um framework visual completo.
+- O tween deve produzir valores simples (`i32`, `u8`, talvez alpha/fade), deixando renderizacao para o dono atual da UI.
+- Precisa haver politica de termino: remover tween concluido, clamping no valor final e comportamento se o alvo for substituido durante a animacao.
+- O contrato precisa decidir se o controle e interno ao firmware/hub ou exposto a cartuchos via syscall.
+- A discussao deve separar tres superficies: jogos, PrometeuHub, e apps do Prometeu.
+- PBS deve ser tratado como meio de autoria/execucao, nao como sinonimo de "jogo a 60 Hz".
+- Apps do Prometeu precisam de um perfil de frame pacing proprio, provavelmente mais lento e/ou dirigido por invalidacao.
+- Apps do Prometeu precisam de um userland proprio no Hub, com lifecycle, janela, componentes, disco/perifericos e capacidades de sistema.
+- O pipeline atual de `AppMode::System` usando o mesmo `ctx.os.tick(...)` de jogos deve ser tratado como comportamento transitorio ou incorreto, nao como contrato.
+- A VM e as linguagens podem ser comuns entre jogos e apps system, mas a stdlib/capability set nao deve ser comum.
+- Apps system nao devem receber `FrameComposer`, `Gfx` ou `Input` como bibliotecas publicas; essas superficies pertencem ao perfil de jogo.
+- Input de app system deve chegar via eventos/componentes/foco do Hub, nao via snapshot de controle de jogo.
+- Render de app system deve passar pela UI/compositor do sistema, nao pelo compositor canonico de jogo.
+- Persistencia de app system deve ser filesystem orientado a app/capacidades, enquanto jogos continuam com memory card/save slots quando esse for o contrato de portabilidade.
+- `Logs` pode ser candidato a servico transversal, mas precisa preservar fonte, permissao, quota e visibilidade por perfil.
+- O `app_mode`/`AppMode` ja existente no `manifest.json` deve ser a fonte de verdade do perfil de autoria/build: `Game` ou `System`.
+- O compiler deve resolver/injetar stdlib conforme `app_mode`; o Studio deve ler o mesmo campo para orientar capacidades, templates, validacao e UX.
+- `Logs` pode usar o mesmo servico runtime internamente, mas deve ser exposto pela stdlib adequada ao perfil.
+- O contrato detalhado de `fs` de `System` fica fora desta agenda e deve continuar na agenda especifica de filesystem; aqui basta fixar que `System` nao usa mem cards de `Game`.
+- `System` nao tera banks, `Gfx`, nem acesso ao `fs` via mem cards de `Game`; tera controles de janelas, componentes e APIs de ambiente, em um modelo mais proximo de apps Android.
+- Syscall futura para apps PBS `System` deve ser tratada como transporte; o contrato real sera a ABI publica do perfil `System`.
+- A primeira fatia deve ser interna ao Runtime/Hub e cobrir a separacao de pipeline para `System`, roteando o caminho de app/system para o dominio do `WindowManager` sem alterar o pipeline de jogo.
+- Nenhuma API publica PBS de System deve ser congelada ate o modelo interno provar que funciona como ambiente operacional.
+
+## Opcoes
+
+### Opcao A - Tween interno no PrometeuHub / firmware
+
+Criar um pequeno motor de tween no dominio de UI do sistema, usado pelo `WindowManager` ou por um `UiAnimationController`.
+
+- Pro: menor risco arquitetural; nao muda ABI publica; suficiente para transicoes do hub.
+- Pro: esforco baixo e testavel com unidade pura.
+- Contra: cartuchos nao ganham API de animacao.
+- Contra: pode precisar ser promovido depois se a mesma necessidade aparecer no runtime publico.
+
+Estimativa: 1 a 2 dias para MVP util, incluindo testes.
+
+### Opcao B - Servico runtime interno compartilhavel
+
+Criar um controlador generico em `prometeu-system` ou `prometeu-drivers`, mas ainda sem syscall publica. O hub consome esse servico; outras superficies internas podem reutilizar.
+
+- Pro: separa interpolacao de renderizacao e prepara expansao.
+- Pro: ainda evita congelar ABI publica.
+- Contra: exige mais cuidado com ownership, handles e ciclo de vida.
+- Contra: precisa decidir onde o servico vive sem violar a fronteira `FrameComposer`/`Gfx`.
+
+Estimativa: 3 a 5 dias para uma versao solida com handles, cancelamento/substituicao e testes.
+
+### Opcao C - API publica de tween via syscall
+
+Adicionar dominio ou chamadas publicas para criar/consultar/cancelar tweens a partir de bytecode/cartuchos.
+
+- Pro: vira capacidade da plataforma, nao so do hub.
+- Pro: cartuchos ganham uma primitiva de UI/animacao deterministica.
+- Contra: alto custo de contrato: ABI, caps, custos de syscall, tipos aceitos, persistencia de handles, erros e compatibilidade futura.
+- Contra: requer decisao e plano antes de mexer em spec/code.
+
+Estimativa: 1 a 2 semanas para contrato, spec, implementacao, testes VM/syscall e exemplos minimos. Esta opcao nao deve ser prioridade enquanto a separacao de modos estiver aberta.
+
+### Opcao D - Framework de UI para jogos sobre primitivas existentes
+
+Manter tween e widgets de jogo em uma biblioteca/framework, sem nova syscall de UI. O framework usa `FrameSync`, input, sprites, cenas, camera e/ou primitivas de desenho ja existentes.
+
+- Pro: evita congelar UI de jogo no ABI do runtime.
+- Pro: permite evoluir ergonomia, layout, widgets e easing fora do nucleo.
+- Pro: respeita que jogos costumam precisar de UIs estilizadas, nao de um toolkit de sistema.
+- Contra: exige SDK/framework separado e exemplos bons.
+- Contra: nao resolve por si so a UI do PrometeuHub.
+
+Estimativa: 2 a 4 dias para uma primeira biblioteca pequena de tween/layout immediate-mode para jogos, assumindo que ela roda no lado de autor/cartridge tooling e nao exige ABI nova.
+
+### Opcao E - Toolkit de UI para PrometeuHub/apps do sistema
+
+Criar uma camada propria para UI do PrometeuHub e possiveis apps do Prometeu. Essa camada pode ser exportada para devs de apps do sistema, mas nao precisa ser o mesmo contrato de cartuchos/jogos.
+
+- Pro: modela corretamente apps do Prometeu como software do ambiente, nao como jogos.
+- Pro: permite componentes mais "sistema": janelas, foco, navegacao, temas, transicoes.
+- Contra: precisa definir modelo de app do Prometeu, permissao/capacidade e packaging.
+- Contra: se exportada cedo, vira contrato de plataforma do mesmo jeito, apenas fora do dominio de jogos.
+
+Estimativa: 1 a 2 semanas para um toolkit minimo de apps do Prometeu, porque isso puxa mais que tween: ciclo de vida de app, foco, janelas, input routing e superficie de extensao.
+
+### Opcao F - PBS comum com perfis de execucao diferentes
+
+Permitir que jogos e apps do Prometeu sejam escritos em PBS, mas declarar perfis distintos:
+
+- perfil de jogo: frame loop de jogo, alvo 60 Hz, primitivas de jogo e framework opcional de UI;
+- perfil de hub/app: ambiente UI do Prometeu, pacing menor como 30 Hz/24 Hz ou invalidacao, janelas/foco/input routing de sistema;
+- contrato comum: bytecode/VM/tooling basico;
+- contrato divergente: capacidades, syscalls permitidas, scheduler/pacing, lifecycle e UI services.
+
+- Pro: reaproveita linguagem, compilador, VM e parte do tooling.
+- Pro: modela apps como programas PBS sem fingir que sao jogos.
+- Pro: permite reduzir custo de CPU/bateria no hub e em apps sem prejudicar jogos.
+- Contra: exige manifest/perfil de execucao e regras claras de capacidades.
+- Contra: precisa cuidado para nao criar duas plataformas incompatíveis sob o mesmo nome PBS.
+
+Estimativa: 1 a 2 semanas para especificar e implementar um primeiro perfil de app/hub se limitado a pacing/lifecycle/UI basica; mais se incluir packaging, permissao e distribuicao.
+
+### Opcao G - Userland de apps Prometeu dentro do Hub
+
+Criar um pipeline especifico para apps Prometeu:
+
+- apps continuam podendo ser escritos em PBS;
+- o loader reconhece um perfil de app, diferente de jogo;
+- o Hub hospeda processos/apps com lifecycle proprio;
+- o scheduler de apps usa pacing proprio, como 30 Hz, 24 Hz ou invalidacao;
+- apps acessam um toolkit de janelas/componentes e servicos de sistema;
+- disco, perifericos e capacidades passam por APIs de userland/app, nao pelo contrato de jogo puro;
+- o pipeline de jogo continua separado, otimizado para frame loop, input e composicao de jogo.
+
+- Pro: modela corretamente o Prometeu como ambiente operacional, nao apenas launcher.
+- Pro: permite UI de sistema rica, apps multitarefa ou semi-multitarefa, foco, janela, permissao e lifecycle.
+- Pro: evita contaminar jogos com APIs de sistema e evita limitar apps ao modelo de cartucho.
+- Contra: e uma decisao arquitetural maior que tween; tween vira apenas uma peca do toolkit.
+- Contra: exige contrato de manifest/perfil, scheduler, capacidades, armazenamento e input routing.
+
+Estimativa: 2 a 4 semanas para um primeiro userland minimo de apps dentro do Hub, dependendo do quanto de disco/perifericos/componentes entrar no MVP. Um spike vertical menor poderia levar 1 semana: carregar um app PBS em perfil `prometeu-app`, abrir janela, rodar a 30 Hz e acessar uma API minima de janela/input/disco.
+
+### Opcao H - VM comum com stdlib/capabilities por perfil
+
+Manter a mesma VM e linguagens afins para jogos e apps system, mas declarar uma fronteira forte no nivel de perfil:
+
+- perfil `game`: stdlib de jogo com `FrameComposer`, `Gfx`, `Input`, frame sync de jogo e persistencia tipo memory card/save slots;
+- perfil `system-app`: mesma VM/bytecode quando possivel, mas stdlib propria para janela, componentes, eventos, lifecycle, logs e filesystem de app;
+- `manifest.json` declara `app_mode: Game` ou `app_mode: System`, reaproveitando o contrato existente;
+- o compiler usa `app_mode` para resolver/injetar a stdlib correta;
+- o Studio usa `app_mode` para UX, templates, validacao e informacao de capacidades;
+- servicos comuns so entram quando o contrato for realmente transversal, como talvez `Logs`, sempre com fonte/capacidade/quotas por perfil;
+- `fs` deixa de ser uma abstracao unica: jogos continuam no modelo portavel de saves/memory card, apps system recebem uma superficie diferenciada, cujo contrato detalhado pertence a agenda especifica de filesystem.
+
+- Pro: reaproveita VM, compilador, linguagem e tooling sem herdar a semantica de jogo.
+- Pro: impede que APIs de render/input de jogo contaminem o modelo de UI do sistema.
+- Pro: permite que apps system tenham armazenamento e lifecycle coerentes com software de sistema.
+- Pro: torna o perfil visivel no projeto fonte e no Studio, nao apenas no loader/runtime.
+- Contra: exige manifest/perfil, resolucao de imports por perfil e matriz de capacidades.
+- Contra: cria duas stdlibs que precisam ser documentadas e testadas sem parecerem plataformas desconectadas.
+- Contra: `fs` ainda depende de outra agenda para fechar o contrato minimo de System.
+
+Estimativa: 1 a 2 semanas para fechar contrato e implementar o primeiro corte se o escopo for perfil/imports/capabilities basicas; mais se incluir FS completo, empacotamento e multitarefa.
+
+### Opcao I - Pipeline System interno antes da ABI publica
+
+Tratar janelas, UI e apps `System` como dominio interno proprio do Runtime/Hub antes de qualquer exposicao publica para PBS, mas sem tentar construir o WindowManager completo nesta agenda:
+
+- separar o pipeline de `System` do pipeline de jogo;
+- manter o pipeline de jogo intocado;
+- encaminhar apps `System` para um caminho do Runtime/Hub orientado ao `WindowManager`;
+- usar o modelo Android como inspiracao: ambiente de apps/janelas gerenciado pelo sistema, nao loop de jogo em janela;
+- manter tudo como contrato interno enquanto o desenho ainda estiver mudando;
+- quando o modelo estiver estavel, publicar uma ABI de perfil `System` e uma stdlib/framework PBS;
+- permitir que a ABI publica use syscalls como transporte, mas sem confundir syscall com o contrato conceitual;
+- manter a ABI de jogos separada, com `Gfx`, `Input`, banks, sprites e memory cards fora do perfil `System`.
+
+- Pro: permite evoluir o modelo operacional do Hub sem congelar ABI prematura.
+- Pro: separa claramente pipeline de jogo e pipeline de sistema.
+- Pro: reduz a primeira fatia para a fronteira arquitetural que hoje esta errada.
+- Pro: cria base real para apps System antes de expor promessas a devs PBS.
+- Contra: adia apps PBS de System publicos ate o Runtime/Hub provar o modelo.
+- Contra: nao entrega ainda WindowManager completo, arvore de componentes rica ou lifecycle final.
+- Contra: exige disciplina para nao deixar detalhes internos virarem contrato acidental.
+
+Estimativa: 3 a 5 dias para separar e rotear o pipeline System internamente, assumindo que o WindowManager existente e usado como destino inicial. Mais tempo so entra quando formos amadurecer componentes, lifecycle, invalidacao rica e transicoes.
+
+## Sugestao / Recomendacao
+
+Comecar pela separacao de modos e pelo territorio-pipeline do Runtime/Hub, nao por tween nem por ABI publica:
+
+1. Definir `game mode` como pipeline de cartucho/jogo, com frame loop e alvo 60 Hz.
+2. Definir `system mode` como ambiente do Hub, com pacing proprio e UI de sistema.
+3. Definir `prometeu app mode` como PBS/VM comum quando possivel, rodando em userland do Hub, nao no pipeline de jogo.
+4. Definir stdlib/capabilities por perfil: `system-app` nao recebe `FrameComposer`, `Gfx` ou `Input`; recebe APIs de sistema para janela/componentes/eventos/lifecycle.
+5. Reaproveitar `app_mode`/`AppMode` em `manifest.json` como discriminante de autoria/build: `Game` ou `System`.
+6. Fazer o compiler e o Studio resolverem stdlib/capabilities a partir desse `app_mode`.
+7. Separar armazenamento por perfil: jogos usam memory card/save slots; apps system nao usam mem cards de jogo e terao contrato de filesystem proprio, definido em agenda especifica.
+8. Separar primeiro o pipeline interno de `System` no Runtime/Hub, roteando esse caminho para o dominio do `WindowManager` e mantendo o pipeline de jogo intocado.
+9. Amadurecer `WindowManager`, componentes, lifecycle, invalidacao e transicoes em etapas posteriores, sobre esse pipeline ja separado.
+10. So depois expor uma ABI publica de perfil `System` e stdlib/framework PBS; syscalls futuras serao transporte, nao o contrato conceitual.
+11. Depois disso, tratar tween como componente do toolkit de UI do sistema ou como biblioteca de jogo, conforme o modo.
+
+A recomendacao atual passa a ser uma combinacao das Opcoes G, H e I: userland de apps Prometeu dentro do Hub, sobre a mesma VM/languages quando isso for util, com stdlib/capacidades diferentes do perfil de jogo, e com pipeline System separado antes de virar ABI publica. Isso evita duplicar a maquina de execucao, impede que apps system sejam apenas "jogos em janelas", e evita congelar uma API PBS antes do modelo operacional existir.
+
+Para `Logs`, a recomendacao e separar autoria de implementacao: internamente o runtime pode usar o mesmo servico de log, mas a API que o dev enxerga vem da stdlib do perfil. Assim o Studio pode apresentar contrato e ergonomia de `Game` e `System` separadamente sem forcar duplicacao interna prematura.
+
+A Opcao E so deve virar decisao quando houver uma decisao anterior sobre apps do Prometeu: o que sao, como rodam, que permissoes tem e se compartilham ou nao o mesmo empacotamento de cartuchos. Essa decisao agora parece necessaria antes de tratar tween/UI como trabalho de implementacao, porque o lugar correto do tween depende do userland de apps.
+
+Modelo sugerido para a primeira fatia:
+
+- identificar o ponto atual em que `AppMode::System` entra no mesmo tick/pipeline de jogo;
+- criar caminho separado para `System` no Runtime/Hub;
+- manter `GameRunningStep` e o pipeline de jogo sem alteracao conceitual;
+- rotear execucao/eventos/renderizacao de `System` para o dominio do `WindowManager`;
+- bloquear uso de `FrameComposer`, `Gfx`, `Input`, banks e mem cards no perfil `System`;
+- deixar componentes, lifecycle rico, invalidacao detalhada e transicoes como evolucao posterior;
+- nao publicar ABI PBS de System nesta fase.
+
+Se o objetivo for expor System UI para PBS, a agenda deve virar decisao e plano primeiro; a decisao deve deixar claro que a exposicao publica vem depois da maturacao interna do Runtime/Hub.
+
+## Perguntas em Aberto
+
+- [x] O alvo inicial e apenas a UI do sistema PrometeuHub ou tambem APIs para cartuchos? Direcao atual: primeira fatia interna ao Runtime/Hub; nada de API publica PBS/cartucho agora.
+- [x] Quais propriedades precisam ser animadas no primeiro uso: posicao, tamanho, alpha/fade, cor, camera, sprites? Direcao atual: animacoes/transicoes sao detalhe interno de System UI e nao entram como contrato publico inicial.
+- [x] A animacao deve sobreviver a troca/remocao de janela ou deve ser cancelada junto com o elemento? Direcao atual: isso pertence ao lifecycle interno de janela/componente, nao a ABI publica agora.
+- [x] Precisamos de easing nominal estavel no contrato agora, ou curvas podem ser internas enquanto estiver no hub? Direcao atual: internas enquanto estiver no Hub.
+- [x] Existe requisito de serializacao/replay/debug para inspecionar tweens ativos? Direcao atual: nao para esta decisao; pode aparecer depois como tooling/debug interno.
+- [x] Apps do Prometeu devem declarar um perfil PBS proprio no manifesto? Direcao atual: sim, via `manifest.json app_mode: System`.
+- [x] Quais syscalls/capacidades sao permitidas para apps do Prometeu em comparacao com jogos? Direcao atual: nao congelar syscalls publicas agora; System tera ABI propria depois, sem `Gfx`, `Input`, banks, sprites e mem cards.
+- [x] O hub e os apps compartilham exatamente o mesmo toolkit de UI ou o hub tem privilegios/componentes internos adicionais? Direcao atual: primeiro amadurecer toolkit interno do Hub; exposicao para apps System vem depois como ABI/framework de perfil.
+- [x] Apps Prometeu usam a mesma VM/runtime de jogos com outro scheduler, ou um runtime/userland separado sobre a mesma VM? Direcao atual: mesma VM/languages quando possivel, mas userland/pipeline/stdlib/capabilities de System separados.
+- [x] Como o manifest distingue jogo, app Prometeu e possiveis servicos/background tasks? Direcao atual: `app_mode: Game` ou `app_mode: System`; servicos/background ficam fora desta agenda.
+- [x] Apps system devem usar a mesma VM/languages ou uma VM separada? Direcao atual: mesma VM/languages quando possivel, com perfil separado.
+- [x] Apps system devem herdar a stdlib dos jogos? Direcao atual: nao; sem `FrameComposer`, `Gfx` e `Input`.
+- [x] Qual e a forma exata de resolver/importar stdlib por perfil no manifesto/tooling? Direcao atual: `manifest.json` ja declara `app_mode: Game` ou `app_mode: System`; compiler injeta stdlib por `app_mode`; Studio consome o mesmo campo.
+- [x] `Logs` sera servico transversal ou API separada por perfil? Direcao atual: runtime pode usar o mesmo servico internamente; autoria/Studio usam stdlib de perfil.
+- [x] O contrato minimo de filesystem para app system deve ser fechado nesta agenda? Direcao atual: nao; agenda especifica de `fs` fecha detalhes, esta agenda fixa apenas a separacao Game/System.
+- [x] Qual e o nome final do modo de sistema no manifest? Direcao atual: usar o `AppMode::System` existente.
+- [x] O discriminante de perfil tambem deve existir no pacote/manifest compilado, ou apenas no projeto fonte e metadados de build? Direcao atual: ja existe no `manifest.json` como `app_mode`.
+- [x] Qual e o conjunto minimo de APIs de System para substituir banks/Gfx/Input/mem cards? Direcao atual: esta agenda nao define API publica; primeira fatia separa o pipeline e aponta `System` para o dominio do `WindowManager`.
+- [x] O pacing de apps deve ser fixo, como 30 Hz/24 Hz, ou dirigido por invalidacao com limite maximo? Direcao atual: a primeira decisao exige dominio System separado e invalidacao interna; pacing exato fica para plano/implementacao.
+- [x] Apps podem rodar em paralelo com o Hub e entre si, ou o MVP permite apenas um app focado? Direcao atual: nao bloqueia a decisao de separacao; MVP pode ser definido no plano.
+- [x] Como isolamento, permissoes e quota de recursos sao expressos para apps? Direcao atual: nao bloquear esta agenda; deve ser tratado junto da ABI publica System e do contrato de capacidades.
+
+## Resolucao Proposta
+
+A agenda esta pronta para virar decisao com o seguinte territorio:
+
+- `Game` e `System` sao perfis distintos do Prometeu Runtime, discriminados pelo `manifest.json app_mode`/`AppMode` existente.
+- Apps `System` podem usar a mesma VM/languages que jogos quando isso for util, mas nao herdam a stdlib/ABI de jogo.
+- A ABI de jogo continua dona de `FrameComposer`, `Gfx`, `Input`, banks, sprites e memory cards.
+- O dominio `System` pertence ao Runtime/Hub e deve ter pipeline proprio antes de amadurecer o WindowManager completo.
+- A primeira fatia segmenta o pipeline atual: `Game` continua no caminho de jogo existente; `System` passa para um caminho especifico do Runtime/Hub orientado ao `WindowManager`.
+- Syscalls futuras para PBS `System` sao apenas transporte; o contrato publico real sera uma ABI especifica do perfil `System`.
+- A ABI publica e a stdlib/framework PBS de `System` so devem ser abertas depois que o modelo interno do Runtime/Hub provar que funciona.
+- `Logs` pode compartilhar implementacao runtime, mas deve ser exposto por stdlib de perfil.
+- `fs` de `System` fica fora desta decisao detalhada; esta agenda fixa apenas que `System` nao usa mem cards de `Game` e que o contrato de filesystem pertence a agenda propria.
+- A primeira fatia de trabalho deve ser interna ao Runtime/Hub, limitada a separacao de pipeline, e nao deve congelar API publica PBS.
+
+## Criterio para Encerrar
+
+A agenda pode virar decisao quando estiver claro:
+
+- se o escopo e framework de jogos, UI interna do hub, ou toolkit exportado para apps do Prometeu;
+- se apps PBS terao perfil de execucao separado do perfil de jogo;
+- se apps Prometeu terao userland proprio dentro do Hub;
+- se apps system terao stdlib/capabilities separadas da stdlib de jogos;
+- se `manifest.json app_mode` sera o discriminante de `Game` vs `System` para compiler e Studio;
+- se a agenda de `fs` sera referenciada como dona do contrato detalhado de filesystem de System;
+- se a primeira fatia sera interna ao Runtime/Hub, sem ABI publica PBS e sem construir o WindowManager completo;
+- se syscalls futuras serao tratadas como transporte para ABI System, nao como contrato conceitual;
+- se o pipeline de jogo deve ficar intocado enquanto `System` ganha caminho proprio inspirado no modelo Android;
+- qual evidencia de teste sera exigida.
+
+## Estimativa Resumida
+
+- Separacao normativa dos modos jogo/sistema/app: 1 a 2 dias para decisao bem fechada.
+- Spike vertical de pipeline de app Prometeu separado: cerca de 1 semana.
+- Userland minimo de apps Prometeu dentro do Hub: 2 a 4 semanas.
+- MVP interno no hub: 1 a 2 dias.
+- Servico interno reutilizavel: 3 a 5 dias.
+- Framework de UI/tween para jogos sem syscall nova: 2 a 4 dias para primeira versao pequena.
+- API publica/runtime ABI para jogos: nao recomendada agora; se insistirmos, 1 a 2 semanas.
+- Toolkit exportavel para apps do Prometeu: 1 a 2 semanas, dependendo do modelo de app.
+- Perfil PBS de app/hub com pacing proprio e ambiente UI compartilhado: 1 a 2 semanas para o primeiro contrato minimo.
+- Userland minimo de apps Prometeu dentro do Hub: 2 a 4 semanas; spike vertical reduzido em torno de 1 semana.
+- VM comum com stdlib/capabilities por perfil: 1 a 2 semanas para contrato inicial e primeiro corte de imports/capabilities.
+- Primeira fatia interna de separacao do pipeline System no Runtime/Hub: 3 a 5 dias para segmentar o caminho e rotear para o dominio do WindowManager; mais tempo so para evoluir WindowManager, componentes, lifecycle e transicoes.

discussion/workflow/decisions/DEC-0023-system-pipeline-separation.md

@@ -0,0 +1,137 @@
+---
+id: DEC-0023
+ticket: runtime-mode-separation-game-system
+title: Decision - System Pipeline Separation
+status: open
+created: 2026-05-14
+accepted:
+agenda: AGD-0031
+plans: []
+tags: [runtime, firmware, hub, system-apps, game-mode, scheduler, abi]
+---
+
+## Status
+
+Open for review.
+
+This decision is derived from `AGD-0031` and is ready to be locked once the wording below is accepted. It does not authorize implementation until a follow-up plan exists.
+
+## Contexto
+
+Prometeu currently distinguishes `AppMode::Game` and `AppMode::System` in the manifest/runtime model, but the execution path for focused `System` apps still falls through the same VM tick/pipeline used by games. That makes a system app behave like a game running inside a window.
+
+The desired model is different: `System` apps belong to the Prometeu Runtime/Hub domain. They should be hosted by a system UI/window environment, inspired by Android-style app hosting, rather than by the game frame pipeline.
+
+The existing `manifest.json app_mode` / `AppMode` field is the profile discriminator:
+
+- `Game` identifies the game/cartridge profile.
+- `System` identifies the system app/runtime Hub profile.
+
+No new `target` field is required for this decision.
+
+## Decisao
+
+Prometeu MUST treat `Game` and `System` as distinct runtime profiles with distinct pipelines.
+
+The existing game pipeline MUST remain conceptually intact for this decision. Work derived from this decision MUST NOT redesign `GameRunningStep`, canonical game composition, `FrameComposer`, `Gfx`, game input, banks, sprites, or memory-card semantics except where a minimal guard is required to prevent `System` from entering the game path.
+
+`System` MUST get a dedicated Runtime/Hub pipeline. The first implementation slice MUST separate the current `AppMode::System` path from the game tick/pipeline and route system execution, events, and rendering toward the Runtime/Hub `WindowManager` domain.
+
+This decision MUST NOT require building the complete `WindowManager`, a full component tree, final lifecycle semantics, rich invalidation, transitions, or the public PBS `System` ABI. Those are later stages built on top of the separated pipeline.
+
+Future PBS calls for creating windows, components, receiving events, or interacting with system UI MAY use syscalls as the transport mechanism. That syscall mechanism MUST NOT be treated as the conceptual contract. The public contract, when introduced, SHALL be a `System` profile ABI distinct from the game ABI.
+
+## Rationale
+
+The current behavior collapses `System` into the game runtime model. That creates the wrong boundary: system UI becomes a game inside a window, and game APIs become tempting shortcuts for system apps.
+
+Keeping the game pipeline untouched reduces risk. The game pipeline already has established ownership around game frame composition, game input, banks, sprites, and memory-card style persistence. The first useful architectural correction is to stop routing `System` apps through that path.
+
+Creating a separate `System` pipeline first gives the Runtime/Hub a stable territory where `WindowManager`, app focus, events, component models, lifecycle, invalidation, transitions, and eventual PBS exposure can evolve without freezing public API too early.
+
+Treating future syscalls as transport avoids letting the call mechanism define the architecture. The important contract is the profile-specific ABI: game apps use game surfaces, while system apps use system surfaces.
+
+## Invariantes / Contrato
+
+- `manifest.json app_mode` / `AppMode` SHALL remain the discriminator for `Game` versus `System`.
+- `Game` SHALL continue to use the game pipeline.
+- `System` SHALL use a Runtime/Hub pipeline dedicated to system UI/app hosting.
+- The first implementation slice SHALL segment pipeline routing only; it SHALL NOT attempt to complete the WindowManager.
+- The `System` pipeline SHALL be oriented toward the `WindowManager` domain.
+- The `Game` profile SHALL retain ownership of `FrameComposer`, `Gfx`, game `Input`, banks, sprites, and memory-card style persistence.
+- The `System` profile MUST NOT inherit the game stdlib or game ABI.
+- `System` MUST NOT use `FrameComposer`, `Gfx`, game `Input`, banks, sprites, or game memory cards as public profile surfaces.
+- `System` APIs exposed later to PBS SHALL be part of a dedicated `System` ABI and stdlib/framework.
+- Future `System` syscalls SHALL be transport for the `System` ABI, not the ABI's conceptual boundary.
+- `Logs` MAY share runtime implementation internally, but author-facing APIs SHALL be resolved through the profile-specific stdlib.
+- Detailed `System` filesystem semantics are out of scope for this decision and SHALL remain owned by the dedicated filesystem agenda.
+
+## Technical Specification
+
+The implementation plan derived from this decision should target the current point where `AppMode::System` enters the same tick/pipeline as `Game`.
+
+The first slice should:
+
+- identify the focused `System` app path currently sharing the game tick;
+- introduce a distinct Runtime/Hub step or dispatch branch for `System`;
+- keep the game-running path behaviorally unchanged;
+- route `System` execution/events/rendering to a Runtime/Hub-owned path oriented around the existing `WindowManager`;
+- enforce or preserve profile gates so `System` cannot use game-only surfaces;
+- leave full component modeling, final lifecycle, public PBS ABI, and rich animation/transition semantics for later decisions/plans.
+
+The output of the first slice should be an architectural split that future plans can extend. It is acceptable if the `System` path is initially minimal, provided it no longer behaves as a game pipeline in a window.
+
+## Constraints
+
+- This decision is not a public PBS API decision.
+- This decision is not a complete WindowManager design.
+- This decision is not the `System` filesystem contract.
+- This decision is not a scheduler/multitasking contract for multiple concurrent apps.
+- This decision does not change the canonical game rendering model.
+- This decision must be implemented through a plan before spec or code changes.
+
+## Impactos
+
+### Runtime / Firmware
+
+Runtime and firmware must stop treating focused `System` apps as regular game ticks. The Runtime/Hub must gain a separated path that can host system app execution under the system UI domain.
+
+### Host
+
+Host behavior should remain unchanged except where it observes the runtime state transition or presentation output of the separated `System` pipeline.
+
+### VM / Language
+
+The VM and PBS-like languages may remain shared across profiles. Sharing VM/language does not imply sharing stdlib, ABI, lifecycle, input, rendering, or storage semantics.
+
+### Studio / Tooling
+
+Studio and compiler tooling should use the existing `manifest.json app_mode` value to select profile-specific stdlib/capability behavior. No new `target` field is introduced by this decision.
+
+### Specs
+
+Any future canonical specification update must describe profile separation and state that `System` uses a Runtime/Hub pipeline distinct from the game pipeline. Public `System` ABI details must wait until the internal pipeline and WindowManager model are mature enough to expose.
+
+### Filesystem
+
+The only filesystem statement locked here is negative: `System` must not use game memory cards as its public storage model. The positive `System` filesystem contract remains delegated to the existing filesystem agenda.
+
+## Referencias
+
+- `AGD-0031` - Runtime Mode Separation: Game and System.
+- `manifest.json app_mode` / `AppMode::{Game,System}`.
+- Existing game-frame ownership lessons around `FrameComposer`, `Gfx`, overlays, and memory-card-style persistence.
+- Existing filesystem agenda for app/system filesystem semantics.
+
+## Propagacao Necessaria
+
+- A plan must be created for the first pipeline-separation implementation slice.
+- The plan must explicitly protect the game pipeline from unrelated redesign.
+- The plan must define tests/evidence that `System` no longer enters the game tick path.
+- Compiler/Studio follow-up work must align stdlib/capability resolution with `app_mode`.
+- A later decision or plan must define public `System` ABI exposure only after the internal Runtime/Hub pipeline is proven.
+- The filesystem agenda must remain the owner of detailed `System` filesystem semantics.
+
+## Revision Log
+
+- 2026-05-14: Initial draft from `AGD-0031`.