diff --git a/discussion/index.ndjson b/discussion/index.ndjson index 41e283dd..7819370f 100644 --- a/discussion/index.ndjson +++ b/discussion/index.ndjson @@ -1,4 +1,5 @@ -{"type":"meta","next_id":{"DSC":38,"AGD":38,"DEC":30,"PLN":73,"LSN":47,"CLSN":1}} +{"type":"meta","next_id":{"DSC":39,"AGD":39,"DEC":31,"PLN":87,"LSN":47,"CLSN":1}} +{"type":"discussion","id":"DSC-0038","status":"in_progress","ticket":"render-frame-packet-boundary","title":"Logical Render Pipelines and Command Packets","created_at":"2026-05-25","updated_at":"2026-05-25","tags":["gfx","renderer","runtime","frame-composer","architecture","ui","pipeline"],"agendas":[{"id":"AGD-0038","file":"AGD-0038-renderframepacket-boundary-for-classic-2d-renderer.md","status":"accepted","created_at":"2026-05-25","updated_at":"2026-05-25"}],"decisions":[{"id":"DEC-0030","file":"DEC-0030-logical-render-pipeline-command-boundary.md","status":"accepted","created_at":"2026-05-25","updated_at":"2026-05-25","ref_agenda":"AGD-0038"}],"plans":[{"id":"PLN-0073","file":"PLN-0073-render-contract-specs.md","status":"open","created_at":"2026-05-25","updated_at":"2026-05-25","ref_decisions":["DEC-0030"]},{"id":"PLN-0074","file":"PLN-0074-hal-render-submission-types.md","status":"open","created_at":"2026-05-25","updated_at":"2026-05-25","ref_decisions":["DEC-0030"]},{"id":"PLN-0075","file":"PLN-0075-rendermanager-core.md","status":"open","created_at":"2026-05-25","updated_at":"2026-05-25","ref_decisions":["DEC-0030"]},{"id":"PLN-0076","file":"PLN-0076-capabilities-and-abi-domain-split.md","status":"open","created_at":"2026-05-25","updated_at":"2026-05-25","ref_decisions":["DEC-0030"]},{"id":"PLN-0077","file":"PLN-0077-composer-buffer-and-game2d-packet.md","status":"open","created_at":"2026-05-25","updated_at":"2026-05-25","ref_decisions":["DEC-0030"]},{"id":"PLN-0078","file":"PLN-0078-classic2d-game-renderer-consumer.md","status":"open","created_at":"2026-05-25","updated_at":"2026-05-25","ref_decisions":["DEC-0030"]},{"id":"PLN-0079","file":"PLN-0079-gfx2d-primitive-domain.md","status":"open","created_at":"2026-05-25","updated_at":"2026-05-25","ref_decisions":["DEC-0030"]},{"id":"PLN-0080","file":"PLN-0080-shell-ui-packet-and-gfxui-domain.md","status":"open","created_at":"2026-05-25","updated_at":"2026-05-25","ref_decisions":["DEC-0030"]},{"id":"PLN-0081","file":"PLN-0081-shell-hub-migration.md","status":"open","created_at":"2026-05-25","updated_at":"2026-05-25","ref_decisions":["DEC-0030"]},{"id":"PLN-0082","file":"PLN-0082-frame-publication-and-present-boundary.md","status":"open","created_at":"2026-05-25","updated_at":"2026-05-25","ref_decisions":["DEC-0030"]},{"id":"PLN-0083","file":"PLN-0083-fade-removal.md","status":"open","created_at":"2026-05-25","updated_at":"2026-05-25","ref_decisions":["DEC-0030"]},{"id":"PLN-0084","file":"PLN-0084-host-debug-overlay-removal.md","status":"open","created_at":"2026-05-25","updated_at":"2026-05-25","ref_decisions":["DEC-0030"]},{"id":"PLN-0085","file":"PLN-0085-pbs-stdlib-and-syscall-declarations.md","status":"open","created_at":"2026-05-25","updated_at":"2026-05-25","ref_decisions":["DEC-0030"]},{"id":"PLN-0086","file":"PLN-0086-end-to-end-render-boundary-validation.md","status":"open","created_at":"2026-05-25","updated_at":"2026-05-25","ref_decisions":["DEC-0030"]}],"lessons":[]} {"type":"discussion","id":"DSC-0035","status":"done","ticket":"task-owned-shell-windows","title":"Agenda - Task-Owned Shell Windows","created_at":"2026-05-15","updated_at":"2026-05-15","tags":["runtime","os","task","window-manager","shell","lifecycle"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0044","file":"discussion/lessons/DSC-0035-task-owned-shell-windows/LSN-0044-task-window-liveness-belongs-to-the-task.md","status":"done","created_at":"2026-05-15","updated_at":"2026-05-15"}]} {"type":"discussion","id":"DSC-0034","status":"done","ticket":"system-os-domain-facades","title":"Agenda - SystemOS Domain Facades","created_at":"2026-05-15","updated_at":"2026-05-15","tags":["runtime","os","services","api-surface","lifecycle","fs"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0043","file":"discussion/lessons/DSC-0034-system-os-domain-facades/LSN-0043-systemos-domain-facades.md","status":"done","created_at":"2026-05-15","updated_at":"2026-05-15"}]} {"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":"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":"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":"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":"discussion/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"}]} diff --git a/discussion/workflow/agendas/AGD-0038-renderframepacket-boundary-for-classic-2d-renderer.md b/discussion/workflow/agendas/AGD-0038-renderframepacket-boundary-for-classic-2d-renderer.md new file mode 100644 index 00000000..69feada6 --- /dev/null +++ b/discussion/workflow/agendas/AGD-0038-renderframepacket-boundary-for-classic-2d-renderer.md @@ -0,0 +1,446 @@ +--- +id: AGD-0038 +ticket: render-frame-packet-boundary +title: Logical Render Pipelines and Command Packets +status: accepted +created: 2026-05-25 +resolved: +decision: +tags: [gfx, renderer, runtime, frame-composer, architecture, ui, pipeline] +--- + +# Agenda - Logical Render Pipelines and Command Packets + +## Contexto + +Depois da migracao para RGBA8888, o proximo passo arquitetural do renderer nao deve ser GPU, 3D, multiplos backends ou troca dinamica complexa de pipeline. O objetivo imediato e separar melhor tres responsabilidades: + +1. pipelines logicos produzem comandos de alto nivel; +2. uma implementacao de hardware/render surface consome esses comandos; +3. o framebuffer RGBA8888 atual continua sendo a superficie final no desktop. + +A direcao desejada agora e explicitar pelo menos dois pipelines logicos: + +```text +Game 2D Pipeline + scene + sprites + HUD + -> Game2DFramePacket / Game2DCommandSet + -> hardware/render implementation + -> framebuffer RGBA8888 + +Prometeu UI Pipeline + shell/home/system UI/windows + -> UiFramePacket / UiCommandSet + -> hardware/render implementation + -> framebuffer RGBA8888 +``` + +Esses pipelines podem funcionar de formas totalmente diferentes. O ponto comum nao deve ser uma API unica pobre que force tudo a parecer igual. O ponto comum deve ser a fronteira operacional: cada pipeline publica seu proprio conjunto logico de comandos para uma implementacao de hardware/superficie. + +Com isso, se depois surgir um pipeline 3D, outro pipeline 2D, ou um renderer especializado para hardware barato/DIY, o trabalho fica concentrado no novo pipeline e/ou no consumidor de comandos, sem reabrir a VM inteira. + +## Problema + +Hoje o runtime ainda mistura producao logica de frame com desenho imediato no `Gfx`/framebuffer. + +O codigo ja tem separacoes parciais: + +- `FrameComposer` coordena scene binding, camera, cache/resolver e sprites do jogo. +- `Gfx` rasteriza em `back`, faz `present()` para `front`, e expoe `front_buffer()` para o host. +- `VirtualMachineRuntime` chama `hw.render_frame()` quando o frame logico termina. +- Prometeu Hub, splash/crash e varias chamadas `gfx.*` ainda desenham diretamente via `gfx_mut()`. +- O host desktop copia o `front_buffer()` RGBA8888 para `pixels`. + +O limite atual ainda e "codigo logico chama renderer", nao "pipeline publica comandos para uma implementacao". + +Isso cria custo futuro: + +- o pipeline 2D de jogo fica preso ao formato operacional atual de `Gfx`; +- a UI do Prometeu fica misturada ao mesmo caminho imperativo de primitives; +- um futuro pipeline 3D teria que disputar o mesmo contrato em vez de definir sua propria saida logica; +- hardware barato/DIY teria que emular detalhes de `Gfx` em vez de consumir um command set adequado; +- testes ficam presos a pixels finais mesmo quando o que interessa e o pacote logico produzido. + +## Pontos Criticos + +### 1. Pipeline nao e backend + +Pipeline deve significar "modelo logico de producao de comandos". Backend/implementacao deve significar "como esses comandos viram pixels/superficie". + +Nao queremos agora: + +- registry sofisticado de backends; +- troca dinamica de pipeline; +- GPU backend; +- 3D; +- refatoracao agressiva de asset pipeline; +- mudanca visual. + +Queremos uma fronteira para que esses itens possam existir depois sem contaminar o passo atual. + +### 2. Game 2D e Prometeu UI nao precisam compartilhar o mesmo command set + +O pipeline 2D de jogos naturalmente fala de scene/cache/camera/sprites/HUD. + +O pipeline de UI do Prometeu naturalmente fala de janelas, paineis, texto, retangulos, estados de foco, home/shell/system UI, talvez layout e clipping. + +Forcar ambos a um `RenderCommand` generico demais no v1 pode criar uma abstracao fraca. A agenda deve decidir se o contrato comum sera: + +- um enum top-level de pacotes por pipeline; ou +- uma trait de submissao ao hardware; ou +- um `FrameSubmission` que contem command sets tipados por dominio. + +### 3. `FrameComposer` continua sendo bom candidato para o Game 2D Pipeline + +`FrameComposer` ja e o ponto natural para produzir o pacote de jogo: + +- scene binding; +- camera; +- cache/resolver; +- sprites por frame; +- HUD/primitives de jogo quando aplicavel. + +O menor corte para jogo ainda parece ser transformar `FrameComposer.render_frame(&mut dyn GfxBridge)` em uma producao de `Game2DFramePacket`, consumida em seguida pelo renderer Classic2D atual. + +### 4. Prometeu UI precisa sair do desenho direto, mas talvez nao no mesmo PR + +Prometeu Hub e system UI hoje usam `hw.gfx_mut()` diretamente. Isso e exatamente o tipo de acoplamento que a arquitetura quer remover, mas migrar UI junto com Game 2D pode deixar a primeira mudanca grande demais. + +A decisao precisa escolher entre: + +- definir os dois contratos agora e implementar em fases; +- implementar primeiro Game 2D e registrar UI como segundo plan; +- ou implementar um envelope comum e dois producers minimos no mesmo plano. + +### 5. HUD pertence ao pipeline 2D de jogo, nao ao Prometeu UI por padrao + +Para esta agenda, "HUD" significa HUD do jogo como parte do frame de jogo: overlays do cart/gameplay, texto/debug de jogo e primitives 2D associadas ao jogo. + +Prometeu UI significa UI do sistema: hub, shell, janelas, home, crash/splash se forem tratados como telas do sistema. + +Essa separacao evita confundir UI de jogo com UI do console. + +### 6. A implementacao inicial ainda pode ser uma so + +Mesmo com dois pipelines logicos, a implementacao inicial pode continuar sendo o `Gfx`/Classic2D atual gravando em RGBA8888. O ganho arquitetural nao exige multiplos backends. Exige que a entrada da implementacao deixe de ser acesso direto ao framebuffer e passe a ser submissao de comandos logicos. + +### 7. A fronteira deve preparar VM e render pipeline paralelos + +Render thread nao e objetivo do v1, mas a fronteira nao deve impedir que a VM e o renderer rodem em paralelo depois. + +Isso implica que a submissao de frame deve ser tratada como um snapshot fechado do trabalho de render daquele frame. Depois de publicada, a VM nao deve continuar mutando estruturas que o renderer precisa ler. A implementacao inicial pode consumir o snapshot imediatamente e no mesmo thread, mas o contrato deve evitar dependencias como `&mut Hardware`, `&mut Gfx`, ou acesso mutavel ao estado vivo da VM durante a rasterizacao. + +Para o v1, isso sugere: + +- `RenderSubmission` deve carregar `frame_id`, `app_mode` e dados suficientes para identificar a ordem de publicacao; +- command sets pequenos devem preferir dados owned ou buffers owned pelo produtor ate a publicacao; +- referencias pesadas, como cache/assets, devem ser read-only e ter ownership compartilhado ou lifetime claramente limitado; +- a camada de hardware/render surface deve ser a unica dona de publicacao/present; +- a VM deve produzir/submeter comandos, nao desenhar nem esperar acesso ao framebuffer; +- testes devem conseguir validar o packet/submission sem depender apenas do framebuffer final. + +### 8. Deve existir um `RenderManager` acima dos pipelines + +Mesmo evitando registry sofisticado de backends no v1, a arquitetura precisa de uma camada acima dos pipelines individuais. Essa camada nao deve ser "mais um pipeline"; ela deve coordenar: + +- qual `AppMode` esta ativo (`Game` ou `Shell`); +- quais command buffers/submissions estao validos para esse modo; +- transicoes entre modos; +- publicacao da superficie; +- politica de latest frame; +- capacidades disponiveis por modo. + +Motivacao principal: transicoes entre Shell e Game nao pertencem completamente a nenhum dos dois pipelines. Exemplo: o Shell UI pode executar uma transicao visual de saida ao abrir um jogo, mas depois que o Game 2D assume, o Shell UI ja nao existe mais para executar a transicao de entrada do jogo. Isso sugere uma base comum de render/control plane acima dos pipelines, capaz de manter transicoes e estado de superficie durante a troca de modo. + +Essa camada deve se chamar `RenderManager`. O nome indica coordenacao de render, nao implementacao de desenho. A decisao precisa separar com cuidado: + +- `RenderManager` como abstracao/runtime contract de coordenacao; +- host/render-surface implementation como adaptador local que sabe publicar em uma superficie real. + +O `RenderManager` coordena pipelines e superficie, mas nao produz comandos de jogo/UI e nao deve conter detalhes de host desktop. + +### 9. Command buffers e submissions sao conceitos diferentes + +Cada dominio/pipeline acumula estado e comandos em seu proprio buffer mutavel durante o frame logico. Exemplos: + +- `ComposerBuffer` para scene, camera e sprites; +- `Gfx2dBuffer` para primitivas 2D de jogo; +- `GfxUiBuffer` para primitivas de Shell UI; +- `ComposerBuffer` tambem cobre HUD do Game 2D no v1. + +No fechamento do frame, o `RenderManager` transforma esses buffers na `RenderSubmission` valida para o `AppMode` atual. + +Depois do fechamento, a submission e um snapshot fechado. Produtores logicos nao podem continuar mutando a submission fechada. Essa regra deve ser cravada agora porque e a base para VM e render pipeline rodarem em paralelo no futuro. + +Politica de backlog: nao existe fila infinita. A regra canonica e `latest complete submission wins`. + +## Opcoes + +### Opcao A - Dois command sets tipados, uma implementacao Classic2D inicial + +**Abordagem:** + +- Criar `Game2DFramePacket` para scene/sprites/HUD. +- Criar `UiFramePacket` para Prometeu UI/system UI. +- Criar um envelope simples, por exemplo `RenderSubmission`, que identifica qual pacote esta sendo submetido. +- Fazer a implementacao Classic2D atual consumir os pacotes e continuar escrevendo no framebuffer RGBA8888. +- Implementar em fases: primeiro Game 2D, depois Prometeu UI, ou ambos com producers minimos se o plano ficar pequeno o suficiente. + +**Pro:** + +- preserva modelos logicos diferentes para jogo e UI; +- evita uma command list generica demais; +- prepara 3D ou outros pipelines sem forcar eles a parecerem com 2D; +- deixa claro que pipeline e backend sao coisas diferentes. + +**Con:** + +- cria mais tipos no inicio; +- precisa definir como o hardware recebe pacotes heterogeneos; +- se so Game 2D for migrado no primeiro plan, UI continua acoplada por um tempo. + +**Maintainability:** + +Alta. Esta opcao combina com a direcao de longo prazo sem exigir varios backends agora. + +### Opcao B - Um `RenderCommand` universal para tudo + +**Abordagem:** + +- Criar uma display list unica com comandos como `Clear`, `DrawSprite`, `DrawText`, `FillRect`, `SceneCache`, `Window`, `Transition`. +- Fazer Game 2D e Prometeu UI emitirem a mesma lista. + +**Pro:** + +- facil de passar por uma unica fila; +- simples para logging/replay inicial; +- reduz o numero de tipos. + +**Con:** + +- tende a virar um denominador comum fraco; +- mistura semantica de jogo, UI de sistema e futuros pipelines; +- pode forcar o pipeline 3D futuro a um contrato 2D inadequado; +- aumenta chance de reabrir a arquitetura quando outro pipeline surgir. + +**Maintainability:** + +Media a baixa como arquitetura principal. Pode ser util internamente dentro de um pipeline, mas nao como contrato unico do runtime. + +### Opcao C - Trait comum de pipeline, sem pacote explicito + +**Abordagem:** + +- Definir algo como `RenderPipeline` com metodo `render(&mut HardwareSurface)`. +- Game 2D e UI implementam a trait, mas continuam desenhando por callbacks imediatos. + +**Pro:** + +- pequena mudanca inicial; +- organiza nomes e ownership; +- reduz um pouco o acoplamento por modulo. + +**Con:** + +- nao cria pacote logico observavel; +- continua misturando producao e execucao; +- nao ajuda tanto render thread, replay, testes de comandos ou hardware alternativo. + +**Maintainability:** + +Insuficiente se virar a decisao final. Pode ser uma API auxiliar, mas nao substitui command packets. + +### Opcao D - Definir todos os pipelines e backend abstraction agora + +**Abordagem:** + +- Criar pipeline registry, backend interfaces, CPU/GPU abstractions, surfaces, scheduling, command queues e talvez render thread. + +**Pro:** + +- parece completo no papel; +- antecipa muitos cenarios futuros. + +**Con:** + +- grande demais para o objetivo atual; +- alto risco de abstrair sem uso real; +- pode atrasar a estabilizacao do 2D atual; +- tende a introduzir nomes e contratos que depois precisarao ser quebrados. + +**Maintainability:** + +Baixa para o momento atual. Melhor deixar essa camada emergir depois de pelo menos dois pipelines reais funcionando. + +## Sugestao / Recomendacao + +A recomendacao atual e a Opcao A: definir dois pipelines logicos com command sets proprios e uma implementacao Classic2D inicial. + +Modelo recomendado: + +```text +Game2DPipeline + produces Game2DFramePacket + owns/uses FrameComposer concepts: + scene/cache/camera + sprites + game HUD + HUD/primitives + +PrometeuUiPipeline + produces UiFramePacket + owns/uses system UI concepts: + home/hub + shell windows + panels/rects/text + focus/input visual state + +RenderHardware / RenderSurface implementation + consumes typed submissions: + Game2D(Game2DFramePacket) + PrometeuUi(UiFramePacket) + future: Game3D(...), Custom2D(...), etc. + writes to current RGBA8888 framebuffer for now + +RenderManager + owns current AppMode render routing + closes per-domain command buffers into a submission + manages mode transitions + keeps only the latest complete submission + owns publish/present policy through the render surface +``` + +O primeiro plano de execucao pode ser incremental: + +1. Definir nomes e contratos dos pacotes sem criar backend registry. +2. Migrar o Game 2D path para `Game2DFramePacket -> Classic2D`. +3. Manter comportamento pixel-level identico. +4. Em seguida migrar Prometeu UI para `UiFramePacket -> Classic2D`. +5. So depois discutir outros backends, render thread ou 3D. + +Se quisermos reduzir ainda mais risco, a decisao pode determinar que o primeiro PR implementa apenas o Game 2D packet, mas ja reserva a arquitetura e nomes para `UiFramePacket`. O importante e nao fingir que Prometeu UI e apenas "mais primitives gfx" dentro do pipeline de jogo. + +## Riscos + +- **Abstracao comum errada:** um command set universal pode parecer simples agora, mas virar bloqueio para UI e 3D depois. +- **Escopo grande demais:** migrar Game 2D, UI, firmware screens e host presentation em um unico PR aumenta risco de regressao visual. +- **Dual path permanente:** se `gfx_mut()` continuar como escape hatch normal, a fronteira de comandos nao vira contrato real. +- **Ownership/lifetime dos pacotes:** pacotes borrowed reduzem copia no v1; pacotes owned ajudam render thread futura. A decisao precisa declarar o alvo do primeiro passo. +- **HUD ambiguo:** HUD de jogo e UI do Prometeu precisam ficar separados por contrato, mesmo que ambos sejam 2D. +- **Present/publication:** `present()` precisa ser tratado como publicacao de superficie, nao como parte aleatoria de cada produtor logico. +- **Asset/cache leakage:** command packets devem referenciar recursos logicos/resolvidos sem copiar asset pipeline nem expor detalhes demais do `Gfx`. +- **Paralelismo futuro:** se o packet v1 depender de estado mutavel vivo da VM/hardware, uma render thread futura exigira nova quebra arquitetural. A submissao precisa parecer um snapshot fechado mesmo quando consumida sincronicamente no v1. +- **Transicoes entre modos:** se Shell e Game forem totalmente independentes sem uma coordenacao mestre, efeitos de transicao e manutencao de superficie ficam sem dono claro. +- **Backpressure:** render futuro nao deve acumular fila infinita. A politica aceita e manter somente a submissao completa mais recente. +- **Abstracao vs host:** `RenderManager` deve ser contrato runtime/abstracao de coordenacao. Host desktop/render surface deve ser implementacao local separada, sem vazar detalhes para os pipelines. +- **HUD ownership:** HUD nao deve ficar escondido dentro de `Gfx2D`. `Gfx2D` deve conter apenas primitivas. No v1, HUD pertence explicitamente ao `composer`. + +## Arquivos / Areas Provavelmente Afetados em uma Plan Futura + +Nucleo Game 2D: + +- `crates/console/prometeu-hal/src/` para tipos compartilhados de packet/submission, se virarem contrato de hardware. +- `crates/console/prometeu-hal/src/lib.rs` para exportar novos modulos. +- `crates/console/prometeu-drivers/src/frame_composer.rs` para produzir `Game2DFramePacket`. +- `crates/console/prometeu-drivers/src/gfx.rs` para consumir `Game2DFramePacket` no Classic2D atual. +- `crates/console/prometeu-drivers/src/hardware.rs` para conectar pipeline/submission/implementacao. +- `crates/console/prometeu-hal/src/hardware_bridge.rs` para reduzir acesso direto a `GfxBridge` no fluxo de frame. + +Nucleo Prometeu UI: + +- `crates/console/prometeu-system/src/programs/prometeu_hub/prometeu_hub.rs` +- `crates/console/prometeu-system/src/services/windows/*` +- `crates/console/prometeu-firmware/src/firmware/firmware_step_splash_screen.rs` +- `crates/console/prometeu-firmware/src/firmware/firmware_step_crash_screen.rs` +- possivelmente um novo modulo de UI commands em `prometeu-hal` ou `prometeu-system`. + +Possivel, mas deve ser minimizado no primeiro passo: + +- `crates/console/prometeu-system/src/services/vm_runtime/dispatch.rs` se `gfx.*` primitives forem convertidas em command submission. +- `crates/console/prometeu-hal/src/gfx_bridge.rs` se a ponte antiga for estreitada. +- `crates/host/prometeu-host-desktop-winit/src/runner.rs` se o acesso ao framebuffer for encapsulado, mas host presentation idealmente fica igual no v1. + +## Perguntas em Aberto + +- [x] O primeiro plano deve implementar Game 2D e Prometeu UI juntos, ou apenas Game 2D com contrato preparado para UI? + - Resposta: faseado. O primeiro plano deve priorizar Game 2D, mas o contrato deve nomear Prometeu UI como pipeline separado desde o inicio. +- [x] O contrato comum deve ser um enum `RenderSubmission`, uma trait de submissao, ou uma fila tipada por pipeline? + - Resposta: `AppMode` e `RenderSubmission` devem andar juntos. `AppMode::Game` e `AppMode::Shell` podem ter cadencias e pipelines diferentes; alguns renderers pertencem a um modo e nao ao outro. O envelope inicial pode ser um `RenderSubmission` tipado por modo/pipeline, sem registry dinamico. +- [x] `Game2DFramePacket` deve incluir HUD de jogo no v1 ou apenas reservar o campo? + - Resposta: deve incluir HUD de jogo no v1. O pipeline 2D de jogos abrange scene, sprites e HUD. +- [x] `UiFramePacket` deve representar UI em comandos baixos (`rect`, `text`, `clip`) ou em comandos mais semanticos (`window`, `panel`, `button`)? + - Resposta: comandos de UI podem ser diferentes dos comandos Game 2D, mas widget/layout deve ficar fora da implementacao do host. No host, `UiFramePacket` pode ser reduzido a diretivas semelhantes ou equivalentes as primitivas finais de desenho. +- [x] Pacotes v1 devem ser borrowed, owned, ou hibridos? + - Resposta: hibridos. O modelo precisa suportar transicoes de modo, como clicar no jogo, sair da UI, abrir o jogo e alternar entre `Game` e `Shell`, sem exigir copia pesada de todo recurso. +- [x] Onde fica `present()` no novo modelo: no hardware/render surface, no consumidor Classic2D, ou temporariamente no firmware? + - Resposta: `present()` pertence a implementacao de hardware/render surface quando ela precisa publicar/trocar buffers. Ele faz sentido em um blit/double-buffer path como Game 2D, mas nao deve ser parte obrigatoria do path canonico de todos os pipelines. +- [x] O acesso publico a `gfx.*` deve virar submissao de comandos, ser mantido como debug overlay temporario, ou ser separado em outra discussao? + - Resposta: separar apenas as primitivas de desenho por contrato de pipeline. O que ja e `composer.*` deve continuar no dominio `composer`, porque scene, camera, sprites, HUD e orquestracao de frame sao um contrato mais alto nivel do Game 2D, nao primitivas `gfx2d`. `Gfx2D` deve conter somente primitivas. O atual `gfx.*` deve ser dividido em primitivas apropriadas para Game e Shell, por exemplo `gfx2d.*` para primitivas do Game 2D e `gfxui.*` para Prometeu UI/Shell. As stdlibs podem continuar expondo nomes de alto nivel como `gfx`, desde que apontem para syscalls diferentes por `AppMode`. +- [x] A agenda aberta `DSC-0011` de dirty regions deve depender desta fronteira antes de continuar? + - Resposta: sim. `DSC-0011` vem depois desta fronteira, para nao otimizar o acoplamento errado. +- [x] O v1 precisa implementar render thread? + - Resposta: nao. Mas o v1 deve preparar a fronteira para isso: `RenderSubmission` deve ser um snapshot fechado por `frame_id`/`AppMode`, sem exigir `&mut Hardware` ou framebuffer mutavel no produtor logico. O consumo pode continuar sincrono na primeira implementacao. +- [x] Quem e dono do frame builder? + - Resposta: cada dominio/pipeline deve ter seus proprios buffers de comando/estado. O fechamento do frame deve ser centralizado no host/render coordinator, que transforma esses buffers na `RenderSubmission` valida para o `AppMode` atual. +- [x] Qual e a ordem de composicao Game 2D? + - Resposta: scene e sprites intercalam por `layer` inteiro usando os 4 layers disponiveis do Game 2D, normalmente como `sprite -> scene -> sprite -> scene -> ...` conforme ordenacao por layer. Depois vem um layer de HUD sobre tudo e entao publish. Transicoes visuais devem pertencer ao `RenderManager`, nao ao Game 2D frame path. +- [x] Como lidar com transicoes Game/Shell? + - Resposta: a arquitetura precisa de um `RenderManager` acima dos pipelines. Ele gerencia troca de modo, manutencao da superficie, capacidades ativas e transicoes que nao pertencem integralmente nem ao Shell UI nem ao Game 2D. +- [x] Qual politica de backpressure para render paralelo futuro? + - Resposta: sem fila infinita. Manter somente a submissao completa mais recente. +- [x] Capabilities devem ser separadas? + - Resposta: sim. O contrato deve prever capabilities separadas para `composer`, `gfx2d` e `gfxui`, reforcando o isolamento por `AppMode`. +- [x] O host debug overlay deve continuar? + - Resposta: nao como parte desta arquitetura. O overlay atual pode ser removido por completo em uma execucao futura; se um console/debug UI voltar a ser necessario, deve ser rediscutido como produto proprio, nao como overlay host-owned herdado. +- [x] Fade deve permanecer em algum contrato? + - Resposta: nao. Fade deve sair completamente. Ele era uma ideia de hardware inicial e nao deve permanecer como campo de packet, syscall ou habito de implementacao. Transicoes visuais futuras pertencem ao `RenderManager`, nao a `composer`, `gfx2d` ou `gfxui`. +- [x] HUD deve ser dominio proprio ou parte do `composer`? + - Resposta: HUD fica dentro de `composer` no v1, por ser parte alta do frame Game 2D junto de scene, camera e sprites. `Gfx2D` continua limitado a primitivas. + +## Criterio para Encerrar + +Esta agenda pode virar decisao quando houver consenso sobre: + +- quais pipelines existem no v1; +- qual command set pertence ao Game 2D; +- qual command set pertence a Prometeu UI; +- qual e a fronteira comum entre pipeline e implementacao de hardware/superficie; +- o que fica explicitamente fora de escopo; +- estrategia de migracao incremental sem mudanca visual; +- testes de equivalencia esperados. + +## Discussion + +Atualizacao de 2026-05-25: + +O foco nao deve ser apenas "introduzir `RenderFramePacket` para Classic2D". O foco deve ser separar pipelines logicos por dominio. Game 2D e Prometeu UI podem ter modelos de comando distintos, mas ambos devem submeter comandos a uma implementacao de hardware/render surface. + +A menor refatoracao segura provavelmente continua partindo do Game 2D, porque `FrameComposer` ja concentra scene/cache/sprites. Mas a decisao deve nomear Prometeu UI como pipeline separado desde agora, para evitar que a UI do sistema vire uma extensao acidental do pipeline de jogo. + +Respostas fechadas em discussao: + +- `AppMode::Game` e `AppMode::Shell` continuam sendo os modos canonicos atuais; nao ha rename para `System`. +- `RenderSubmission` deve ser coerente com `AppMode`, porque a atualizacao de frame e os renderers disponiveis podem diferir entre Game e Shell. +- `composer.*` deve continuar representando scene, camera, sprites, HUD e orquestracao de frame do Game 2D. +- `Gfx2D` deve representar apenas primitivas/drawing commands do pipeline Game 2D. +- `GfxUI` deve representar primitivas/drawing commands do pipeline Prometeu UI/Shell. +- As stdlibs PBS de Game e Shell podem usar nomes parecidos em alto nivel, inclusive `gfx`, mas devem mapear para dominios ABI diferentes conforme `AppMode`. +- O host/render implementation pode reduzir command sets diferentes a diretivas locais parecidas, mas widget/layout nao deve morar no host. +- `present()` e publicacao de superficie, nao parte obrigatoria de todo pipeline logico. +- `DSC-0011` deve aguardar esta fronteira. +- Render thread futura nao deve ser implementada agora, mas a fronteira deve nascer compativel com VM e renderer rodando em paralelo: submissions fechadas, leitura imutavel de recursos compartilhados e publicacao isolada na render surface. +- Buffers de comando/estado devem pertencer aos dominios/pipelines; o fechamento em `RenderSubmission` deve ser centralizado no `RenderManager`. +- `RenderManager` e abstracao/runtime contract; host/render-surface implementation e adaptador local separado. +- Game 2D intercalara scene e sprites por layer. HUD fica acima de tudo e pertence ao `composer` no v1, ainda com contrato minimo e evolutivo. +- Fade sai completamente. Transicoes de entrada/saida entre Shell e Game pertencem ao `RenderManager`. +- Backpressure futuro: latest complete submission wins. +- Capabilities devem ser separadas para `composer`, `gfx2d` e `gfxui`. +- O debug overlay host-owned atual nao deve ser preservado como requisito; pode ser removido quando a execucao chegar nessa area. + +## Resolution + +As perguntas principais de escopo foram respondidas. A agenda ainda precisa ser aceita explicitamente antes de virar decisao normativa. + +## Next Step + +Fechar as perguntas sobre escopo do v1. Se a direcao de dois pipelines logicos for aceita, transformar esta agenda em uma decisao normativa antes de qualquer plan ou alteracao de codigo. diff --git a/discussion/workflow/decisions/DEC-0030-logical-render-pipeline-command-boundary.md b/discussion/workflow/decisions/DEC-0030-logical-render-pipeline-command-boundary.md new file mode 100644 index 00000000..49683c13 --- /dev/null +++ b/discussion/workflow/decisions/DEC-0030-logical-render-pipeline-command-boundary.md @@ -0,0 +1,236 @@ +--- +id: DEC-0030 +ticket: render-frame-packet-boundary +title: Logical Render Pipeline Command Boundary +status: accepted +created: 2026-05-25 +ref_agenda: AGD-0038 +tags: [gfx, renderer, runtime, frame-composer, architecture, ui, pipeline] +--- + +# Decision - Logical Render Pipeline Command Boundary + +## Status + +Accepted. + +## Contexto + +Prometeu ja concluiu a migracao do framebuffer/runtime para RGBA8888. O proximo passo do renderer nao e introduzir GPU, 3D, multiplos backends, troca dinamica complexa de pipeline ou render thread. O objetivo imediato e criar uma fronteira arquitetural limpa entre: + +- producao logica de comandos de render; +- fechamento/publicacao de frame; +- coordenacao entre `AppMode::Game` e `AppMode::Shell`; +- rasterizacao/publicacao em uma superficie real. + +O estado atual ainda acopla codigo logico ao `Gfx`/framebuffer. `FrameComposer` ja centraliza parte da orquestracao do frame de jogo, mas ainda desenha por `GfxBridge`. Prometeu Hub, shell/system UI, splash/crash e primitivas `gfx.*` tambem acessam desenho imperativo direto. Essa decisao normatiza a nova fronteira de comandos e o papel de cada dominio. + +## Decisao + +Prometeu MUST separar render pipeline logico de render implementation. + +O runtime SHALL introduce a `RenderManager` as the runtime-level render coordination abstraction. `RenderManager` MUST NOT be a host-specific renderer and MUST NOT contain desktop presentation details. Host/render-surface implementations SHALL adapt `RenderManager` submissions to the local hardware or host surface. + +The canonical render flow SHALL be: + +```text +domain buffers during logical frame +-> RenderManager closes buffers +-> RenderSubmission snapshot +-> render surface / implementation consumes submission +-> RGBA8888 surface publication +``` + +The v1 logical render domains are: + +- `composer.*` for Game 2D high-level frame composition: scene, camera, sprites, HUD, and Game 2D frame orchestration. +- `gfx2d.*` for Game 2D primitives only. +- `gfxui.*` for Shell UI primitives. + +The v1 app modes are: + +- `AppMode::Game`, which SHALL route to Game 2D submissions. +- `AppMode::Shell`, which SHALL route to Shell UI submissions. + +No `AppMode::System` rename is accepted by this decision. + +`RenderSubmission` MUST be coherent with `AppMode`. The initial submission model SHOULD be a typed envelope rather than a generic universal command list: + +```text +RenderSubmission +- frame_id +- app_mode +- packet: + - Game2D(Game2DFramePacket) + - ShellUi(UiFramePacket) +``` + +The exact Rust layout may evolve during planning, but the contract MUST preserve typed per-pipeline command sets. + +## Rationale + +Typed command sets preserve domain meaning. Game 2D and Shell UI have different responsibilities and should not be forced into a weak universal command list. A future 3D or custom 2D pipeline should add its own packet rather than reinterpret a 2D/UI command model. + +`RenderManager` is required because mode transitions do not belong completely to either Shell UI or Game 2D. Shell can render an exit transition before launching a game, but once Game mode owns the frame, Shell UI is no longer available to render the entry transition. Therefore transition coordination, surface maintenance, active render capabilities, and frame publication need a manager above individual pipelines. + +Command buffers and submissions must be distinct. Domain buffers are mutable while the logical frame is being built. A `RenderSubmission` is a closed snapshot. This makes future VM/render parallelism possible without requiring a render thread in v1. + +The current fade model is rejected. Fade was a hardware-direction idea that no longer belongs in the Prometeu render contract after RGBA8888. Fade MUST NOT remain as a packet field, syscall, or implementation habit. Future visual transitions belong to `RenderManager`. + +## Invariantes / Contrato + +### Pipeline and Implementation Boundary + +- Pipelines MUST produce logical commands or state. +- Render implementations MUST consume submissions and write/publish to a surface. +- Pipeline code MUST NOT require direct mutable access to the framebuffer. +- Pipeline code MUST NOT depend on host-specific presentation details. + +### RenderManager + +- `RenderManager` MUST coordinate active `AppMode`, submission closure, mode transitions, capabilities, and publication policy. +- `RenderManager` MUST be a runtime abstraction, not a host renderer. +- Host/render-surface implementations MUST be separate adapters. +- `RenderManager` MUST own transition coordination between Game and Shell. +- `RenderManager` MUST own the policy for surface publication/present through the render surface. + +### Command Buffers and Submissions + +- Each render domain/pipeline MUST own its own mutable command/state buffer during a logical frame. +- `RenderManager` MUST close the active buffers into a `RenderSubmission` at frame boundary. +- Once closed, `RenderSubmission` MUST be treated as immutable by producers. +- `RenderSubmission` MUST include `frame_id` and `app_mode`. +- Future parallel render MUST be supported by the contract: consuming a submission MUST NOT require `&mut Hardware`, `&mut Gfx`, or live mutable VM state. +- Backpressure policy MUST be latest-complete-submission-wins. The system MUST NOT accumulate an unbounded frame queue. + +### AppMode Routing + +- `AppMode::Game` SHALL expose and route Game render domains. +- `AppMode::Shell` SHALL expose and route Shell UI render domains. +- Renderers/capabilities MAY differ by app mode. +- PBS stdlibs MAY expose similar high-level names, including `gfx`, but they MUST map to mode-appropriate ABI domains. + +### ABI Domains + +- `composer.*` MUST remain the high-level Game 2D composition domain. +- `composer.*` MUST own scene, camera, sprites, HUD, and Game 2D frame orchestration. +- `gfx2d.*` MUST contain Game 2D primitives only. +- `gfx2d.*` MUST NOT own scene, camera, sprites, HUD, or frame orchestration. +- `gfxui.*` MUST contain Shell UI primitives. +- `gfxui.*` MUST NOT contain widget/layout policy. Widget/layout belongs in Shell/UI code or stdlib, not the host implementation. +- Capabilities MUST be separated for `composer`, `gfx2d`, and `gfxui`. + +### Game 2D Composition + +- Game 2D scene and sprites MUST compose by integer `layer`. +- The v1 Game 2D model has four available layers. +- Scene and sprite composition MAY interleave by layer, normally as sprite/scene ordering across the four layers. +- HUD MUST render above scene/sprite composition. +- HUD belongs to `composer` in v1 and remains a minimal, evolvable contract. +- HUD in this decision means Game HUD only. Shell/system UI is always part of the Shell UI pipeline. +- Game 2D publish happens after scene/sprite/HUD composition. + +### Shell UI Composition + +- Shell UI MUST use its own `gfxui.*` primitive command set. +- Shell UI commands MAY reduce to the same local drawing directives as Game 2D primitives inside a host/render-surface implementation. +- That reduction MUST remain an implementation detail and MUST NOT collapse the ABI domains. + +### Fade and Transitions + +- Fade MUST be removed completely from canonical pipeline contracts. +- Fade MUST NOT appear as a `Game2DFramePacket`, `UiFramePacket`, `RenderSubmission`, `composer`, `gfx2d`, or `gfxui` field or syscall. +- Future visual transitions MUST be coordinated by `RenderManager`. + +### Debug Overlay + +- The current host-owned debug overlay is not part of the new render architecture. +- It MAY be removed during execution. +- A future console/debug UI MUST be discussed as a separate product/domain, not preserved as inherited host overlay behavior. + +## Impactos + +### Spec + +Specs must define the logical render pipeline model, `RenderManager`, `RenderSubmission`, app-mode routing, domain buffers, and publication boundary in English. + +The public syscall/ABI specs must replace the old primitive `gfx.*` surface with mode-appropriate `gfx2d.*` and `gfxui.*` primitive domains while preserving `composer.*` as the high-level Game 2D composition domain. + +### Runtime + +Runtime frame execution must stop treating `Gfx`/framebuffer as the direct target of logical render calls. It must accumulate domain state/commands and let `RenderManager` close submissions. + +`VirtualMachineRuntime` and firmware flow must route frame closure through `RenderManager`. + +### HAL + +HAL must expose distinct contracts for: + +- `composer`; +- `gfx2d`; +- `gfxui`; +- render submissions; +- render manager/surface boundary. + +Capability flags must be split accordingly. + +### Host + +The desktop host remains a concrete render-surface implementation. It may continue publishing RGBA8888 to `pixels`, but that behavior must sit below the render-surface adapter, not inside logical pipeline APIs. + +Host debug overlay may be removed. + +### Firmware / Shell + +Shell UI must migrate away from direct `gfx_mut()` drawing toward `gfxui.*`/Shell UI command buffers. + +Game mode must migrate toward `composer.*` plus `gfx2d.*` buffers closed by `RenderManager`. + +### PBS / Stdlibs + +PBS Game and Shell stdlibs may present similar high-level APIs to authors. They must map to different ABI domains according to `AppMode`. + +Game stdlib should map scene/camera/sprites/HUD to `composer.*` and primitive Game drawing to `gfx2d.*`. + +Shell stdlib should map UI primitives to `gfxui.*`. + +## Alternativas Descartadas + +### Universal RenderCommand + +A single `RenderCommand` display list for Game, Shell, and future pipelines is rejected. It collapses domain meaning and would likely force future 3D or custom pipelines into a 2D/UI-shaped contract. + +### Trait-Only RenderPipeline + +A trait that calls `render(&mut Surface)` without a closed packet is rejected as the primary boundary. It preserves immediate rendering and does not prepare VM/render parallelism. + +### Backend Registry Now + +A full backend registry, GPU/CPU backend abstraction, dynamic pipeline switching, render thread, or 3D implementation is out of scope. Those may come later after the command boundary is stable. + +### Moving Composer into Gfx2D + +Moving scene, camera, sprites, HUD, or frame orchestration into `gfx2d.*` is rejected. `gfx2d.*` is primitives only. + +## Referencias + +- Agenda: `AGD-0038` +- Related dependency: `DSC-0011` dirty regions must wait until this boundary exists. +- Related prior lessons: frame composition belongs above the render backend; public ABI must follow canonical service boundaries; RGBA8888 is the canonical framebuffer contract. + +## Propagacao Necessaria + +- Create a plan before any spec or code changes. +- Update canonical specs in English. +- Update HAL syscall registry, capability definitions, and resolver tests. +- Update PBS/stdlib syscall declarations for Game and Shell. +- Update runtime dispatch so render syscalls mutate domain buffers instead of drawing directly. +- Introduce `RenderManager`, domain buffers, `RenderSubmission`, and render-surface implementation boundary. +- Migrate Game 2D first, then Shell UI, unless the plan proves both can be safely migrated together. +- Remove fade surfaces from render contracts. +- Remove or explicitly retire the host debug overlay. +- Add packet/submission tests, app-mode capability tests, and pixel-equivalence tests for unchanged visible behavior. + +## Revision Log + +- 2026-05-25: Initial decision draft from `AGD-0038`. diff --git a/discussion/workflow/plans/PLN-0073-render-contract-specs.md b/discussion/workflow/plans/PLN-0073-render-contract-specs.md new file mode 100644 index 00000000..b7fdbe33 --- /dev/null +++ b/discussion/workflow/plans/PLN-0073-render-contract-specs.md @@ -0,0 +1,67 @@ +--- +id: PLN-0073 +ticket: render-frame-packet-boundary +title: Render Contract Specs +status: open +created: 2026-05-25 +ref_decisions: [DEC-0030] +tags: [gfx, renderer, runtime, frame-composer, architecture, ui, pipeline] +--- + +## Briefing + +Source decision: `DEC-0030`. + +Publish canonical English spec language for the logical render pipeline boundary before code migration. The specs must make `RenderManager`, domain buffers, typed `RenderSubmission`, app-mode routing, render-surface publication, latest-complete-submission policy, and fade removal explicit. + +## Target + +Canonical specs describe the DEC-0030 render contract well enough that HAL, runtime, host, firmware, and PBS work can proceed without reopening architecture. + +## Scope + +- Define the logical flow from mutable domain buffers to closed `RenderSubmission` to render-surface publication. +- Define `RenderManager` as runtime coordination, not a host renderer. +- Define `RenderSubmission` with `frame_id`, `app_mode`, and typed Game 2D or Shell UI packet. +- Define `composer.*`, `gfx2d.*`, and `gfxui.*` as separate ABI domains. +- Specify latest-complete-submission-wins backpressure. +- Remove fade from canonical render contracts. + +## Out of Scope + +- Rust implementation. +- PBS stdlib implementation. +- Pixel output changes. +- Backend registry, GPU backend, render thread, 3D pipeline, or debug console design. + +## Execution Sequence + +1. Inventory existing render, graphics, framebuffer, composer, and syscall specs. +2. Replace old primitive `gfx.*` ABI language with the DEC-0030 domain split. +3. Add sections for `RenderManager`, domain buffers, submission closure, immutability, and publication. +4. Add app-mode and capability routing language for Game and Shell. +5. Remove normative fade fields, syscalls, and packet references from render specs. +6. Cross-link impacted specs for HAL, runtime, host, firmware, and PBS propagation. + +## Acceptance Criteria + +- Specs are in English and reference `DEC-0030`. +- No canonical render spec presents direct framebuffer mutation as the logical render API. +- No canonical render spec keeps fade as a packet field, syscall, or ABI habit. +- Specs distinguish logical pipeline production from render-surface implementation. + +## Tests / Validation + +- Run repository documentation/spec validation if available. +- Inspect `rg -n "fade|gfx\\.\\*|RenderSubmission|RenderManager|present\\(" specs discussion/workflow/decisions/DEC-0030-logical-render-pipeline-command-boundary.md`. +- Run `discussion validate` if discussion references change. + +## Risks + +- Existing specs may use `gfx.*` as both author API and ABI name; preserve author clarity while changing ABI names. +- Removing fade text can accidentally delete transition requirements; move those requirements to `RenderManager` language. + +## Affected Artifacts + +- `specs/` +- `discussion/workflow/decisions/DEC-0030-logical-render-pipeline-command-boundary.md` diff --git a/discussion/workflow/plans/PLN-0074-hal-render-submission-types.md b/discussion/workflow/plans/PLN-0074-hal-render-submission-types.md new file mode 100644 index 00000000..9909f207 --- /dev/null +++ b/discussion/workflow/plans/PLN-0074-hal-render-submission-types.md @@ -0,0 +1,66 @@ +--- +id: PLN-0074 +ticket: render-frame-packet-boundary +title: HAL Render Submission Types +status: open +created: 2026-05-25 +ref_decisions: [DEC-0030] +tags: [gfx, renderer, runtime, frame-composer, architecture, ui, pipeline] +--- + +## Briefing + +Source decision: `DEC-0030`. + +Introduce HAL-level submission types that encode the logical render boundary without binding consumers to live `Hardware`, `Gfx`, framebuffer, or VM state. + +## Target + +HAL exposes typed contracts for `RenderSubmission`, `Game2DFramePacket`, `ShellUiFramePacket`, frame ids, app-mode routing, and immutable closed submissions. + +## Scope + +- Add typed packet structures for Game 2D and Shell UI. +- Add a `RenderSubmission` envelope with `frame_id`, `app_mode`, and typed packet variant. +- Add or reuse a monotonic frame id type. +- Encode closed-submission immutability through ownership and API shape. +- Keep packet types free of host presentation details and live mutable runtime references. + +## Out of Scope + +- `RenderManager` behavior beyond type integration. +- Renderer/rasterizer implementation. +- Backend registry, render thread, GPU path, or 3D packet. +- PBS stdlib updates. + +## Execution Sequence + +1. Locate current HAL graphics, composer, capability, and app-mode modules. +2. Add packet and submission types where ABI-facing render data belongs. +3. Represent packets as typed variants: `Game2D(Game2DFramePacket)` and `ShellUi(ShellUiFramePacket)`. +4. Ensure constructors or closure APIs consume or clone domain buffer contents. +5. Add tests for app-mode and packet coherence. +6. Update internal references to use the new types without changing runtime rendering yet. + +## Acceptance Criteria + +- HAL contains the DEC-0030 submission and packet vocabulary. +- A closed `RenderSubmission` can be handed to a consumer without borrowing live runtime rendering state. +- Game and Shell packets are distinguishable at the type level. +- The HAL API does not include fade fields. + +## Tests / Validation + +- Run HAL crate unit tests. +- Add tests for packet construction, app-mode coherence, and immutable ownership semantics. +- Inspect `rg -n "fade|UiFramePacket|ShellUiFramePacket|Game2DFramePacket|RenderSubmission" crates specs`. + +## Risks + +- New types must live at the ABI/contract level, not inside a host renderer. +- Borrowing shortcuts could leak mutability and violate the future parallel render contract. + +## Affected Artifacts + +- HAL crate/module under `crates/` +- HAL tests diff --git a/discussion/workflow/plans/PLN-0075-rendermanager-core.md b/discussion/workflow/plans/PLN-0075-rendermanager-core.md new file mode 100644 index 00000000..a2274b63 --- /dev/null +++ b/discussion/workflow/plans/PLN-0075-rendermanager-core.md @@ -0,0 +1,68 @@ +--- +id: PLN-0075 +ticket: render-frame-packet-boundary +title: RenderManager Core +status: open +created: 2026-05-25 +ref_decisions: [DEC-0030] +tags: [gfx, renderer, runtime, frame-composer, architecture, ui, pipeline] +--- + +## Briefing + +Source decision: `DEC-0030`. + +Add `RenderManager` as the runtime abstraction that closes domain buffers into typed submissions, tracks active app mode, owns transition coordination placeholders, and hands the latest complete submission to the render surface. + +## Target + +Runtime frame execution routes render closure through `RenderManager` without making it a host renderer or direct framebuffer writer. + +## Scope + +- Add the `RenderManager` module and public runtime API. +- Track active `AppMode` and frame id generation. +- Close the active domain buffer into a `RenderSubmission`. +- Enforce latest-complete-submission-wins rather than an unbounded queue. +- Add transition coordination placeholders owned by `RenderManager`. +- Provide a publication handoff to a render-surface abstraction. + +## Out of Scope + +- Full visual transition implementation. +- Host-specific presentation details. +- Domain buffer implementation beyond integration points. +- Render thread, GPU backend, or backend registry. + +## Execution Sequence + +1. Add a runtime render module that owns `RenderManager` and related state. +2. Wire `VirtualMachineRuntime` frame closure through `RenderManager`. +3. Add active app-mode routing and rejection for incoherent packet closure. +4. Add latest-complete-submission storage and replacement semantics. +5. Add a render-surface handoff interface without calling host-specific `present()` from producers. +6. Add explicit no-op transition hooks for future work. + +## Acceptance Criteria + +- Runtime has one frame closure authority for render submissions. +- Producers can mutate domain buffers before closure but cannot mutate the closed submission. +- `RenderManager` does not depend on desktop host types. +- Backpressure is latest-complete-submission-wins. +- App-mode routing is explicit and tested. + +## Tests / Validation + +- Add unit tests for frame id increment, latest submission replacement, app-mode routing, and no-op transition state. +- Add runtime integration coverage proving frame closure passes through `RenderManager`. +- Run affected crate tests. + +## Risks + +- Existing frame lifecycle code may assume immediate framebuffer mutation; isolate compatibility shims and remove them in later plans. +- Transition placeholders must not become hidden fade behavior. + +## Affected Artifacts + +- Runtime crate/modules under `crates/` +- Runtime tests diff --git a/discussion/workflow/plans/PLN-0076-capabilities-and-abi-domain-split.md b/discussion/workflow/plans/PLN-0076-capabilities-and-abi-domain-split.md new file mode 100644 index 00000000..6105c803 --- /dev/null +++ b/discussion/workflow/plans/PLN-0076-capabilities-and-abi-domain-split.md @@ -0,0 +1,67 @@ +--- +id: PLN-0076 +ticket: render-frame-packet-boundary +title: Capabilities and ABI Domain Split +status: open +created: 2026-05-25 +ref_decisions: [DEC-0030] +tags: [gfx, renderer, runtime, frame-composer, architecture, ui, pipeline] +--- + +## Briefing + +Source decision: `DEC-0030`. + +Split render capabilities and syscall metadata so `composer`, `gfx2d`, and `gfxui` are independently addressable and enforceable according to `AppMode`. + +## Target + +Capability gates reject wrong-domain render syscalls, and metadata no longer treats the old primitive `gfx.*` ABI as the single render surface. + +## Scope + +- Add or rename capability flags for `COMPOSER`, `GFX2D`, and `GFXUI`. +- Update syscall metadata for all render-domain calls. +- Enforce domain availability by `AppMode::Game` and `AppMode::Shell`. +- Update resolver and capability tests. +- Preserve `composer.*` as Game 2D high-level composition. + +## Out of Scope + +- Implementing command buffers. +- PBS stdlib author-facing wrappers. +- Host rendering. +- Backward compatibility for the old primitive `gfx.*` ABI. + +## Execution Sequence + +1. Locate capability definitions, syscall registry metadata, and resolver tests. +2. Introduce separate render capability identifiers for `composer`, `gfx2d`, and `gfxui`. +3. Update metadata for existing composer calls and new or renamed primitive domains. +4. Add app-mode checks so Game exposes `composer` and `gfx2d`, while Shell exposes `gfxui`. +5. Replace stale tests that assume one graphics capability. +6. Run resolver and runtime syscall tests. + +## Acceptance Criteria + +- Wrong-domain calls fail before mutating render state. +- Game mode cannot use `gfxui.*`. +- Shell mode cannot use `composer.*` or `gfx2d.*`. +- Capability metadata uses the split domain names. +- No compatibility promise remains for the old primitive `gfx.*` ABI. + +## Tests / Validation + +- Add resolver tests for all three capabilities. +- Add app-mode enforcement tests for allowed and rejected calls. +- Run affected unit and integration tests. + +## Risks + +- A large rename can hide semantic mistakes; verify every syscall maps to the correct domain responsibility. +- Author-facing stdlib names may still use `gfx`; keep this plan focused on ABI metadata. + +## Affected Artifacts + +- Syscall metadata and resolver modules under `crates/` +- Capability tests diff --git a/discussion/workflow/plans/PLN-0077-composer-buffer-and-game2d-packet.md b/discussion/workflow/plans/PLN-0077-composer-buffer-and-game2d-packet.md new file mode 100644 index 00000000..2adb510b --- /dev/null +++ b/discussion/workflow/plans/PLN-0077-composer-buffer-and-game2d-packet.md @@ -0,0 +1,66 @@ +--- +id: PLN-0077 +ticket: render-frame-packet-boundary +title: Composer Buffer and Game2D Packet +status: open +created: 2026-05-25 +ref_decisions: [DEC-0030] +tags: [gfx, renderer, runtime, frame-composer, architecture, ui, pipeline] +--- + +## Briefing + +Source decision: `DEC-0030`. + +Convert current `composer.*` frame state into a mutable `ComposerBuffer` that closes into `Game2DFramePacket` at frame boundary. + +## Target + +Game 2D scene, camera, sprites, HUD, and frame orchestration are represented as domain-owned state until `RenderManager` closes them into a typed packet. + +## Scope + +- Add `ComposerBuffer`. +- Move scene, camera, sprite, HUD, layer ordering, and Game 2D orchestration state into the buffer. +- Close the buffer into `Game2DFramePacket`. +- Preserve the v1 four-layer scene/sprite composition model and HUD-above-game rule. +- Ensure fade is absent from Game 2D packet state. + +## Out of Scope + +- Primitive `gfx2d.*` command buffering. +- Shell UI packet work. +- Renderer consumption refactor beyond packet shape. +- New Game 2D features. + +## Execution Sequence + +1. Locate current `FrameComposer`, composer syscalls, scene/camera/sprite/HUD state, and tests. +2. Introduce `ComposerBuffer` and migrate composer mutation paths into it. +3. Implement closure into `Game2DFramePacket` with immutable packet contents. +4. Preserve integer layer ordering across the four Game 2D layers and HUD final composition. +5. Route frame closure through `RenderManager`. +6. Update tests that currently inspect `FrameComposer` internals. + +## Acceptance Criteria + +- `composer.*` owns Game 2D high-level frame state. +- Closed `Game2DFramePacket` contains all data required by the Game 2D renderer without live VM or `Gfx` access. +- Scene/sprite layer behavior and HUD ordering are preserved. +- Fade is not represented. + +## Tests / Validation + +- Add unit tests for buffer mutation and packet closure. +- Add composition ordering tests for scene, sprites, and HUD. +- Run current frame composer/render tests and compare existing expected output. + +## Risks + +- Existing composer code may mix orchestration with drawing; split state capture from rendering before deeper migration. +- Layer behavior is user-visible and must not drift. + +## Affected Artifacts + +- Composer/frame-composer modules under `crates/` +- Game 2D tests diff --git a/discussion/workflow/plans/PLN-0078-classic2d-game-renderer-consumer.md b/discussion/workflow/plans/PLN-0078-classic2d-game-renderer-consumer.md new file mode 100644 index 00000000..9ed855f7 --- /dev/null +++ b/discussion/workflow/plans/PLN-0078-classic2d-game-renderer-consumer.md @@ -0,0 +1,64 @@ +--- +id: PLN-0078 +ticket: render-frame-packet-boundary +title: Classic2D Game Renderer Consumer +status: open +created: 2026-05-25 +ref_decisions: [DEC-0030] +tags: [gfx, renderer, runtime, frame-composer, architecture, ui, pipeline] +--- + +## Briefing + +Source decision: `DEC-0030`. + +Refactor the Classic2D renderer path so it consumes `Game2DFramePacket` instead of being called directly by `FrameComposer` or logical producers. + +## Target + +Classic2D remains the concrete Game 2D rasterizer, but its input is a closed packet and its visible pixel output remains equivalent. + +## Scope + +- Add a packet consumer entry point for the current Classic2D/Gfx renderer. +- Replace direct `FrameComposer` to `Gfx` calls with packet consumption. +- Keep RGBA8888 output unchanged for existing supported scenes. +- Keep renderer implementation below the logical pipeline boundary. + +## Out of Scope + +- Redesigning scene, sprite, HUD, or primitive semantics. +- Shell UI rendering. +- Backend registry or GPU work. +- Dirty region optimization. + +## Execution Sequence + +1. Locate the current Classic2D/Gfx rendering entry points and `FrameComposer` call graph. +2. Add a `Game2DFramePacket` consumer API. +3. Move rendering reads from live composer state to packet data. +4. Update frame execution to pass the closed packet into the renderer through the render surface path. +5. Preserve existing framebuffer dimensions, RGBA8888 format, and pixel behavior. +6. Remove direct producer-to-renderer calls that bypass the packet boundary. + +## Acceptance Criteria + +- Classic2D renders from `Game2DFramePacket`. +- Logical composer code no longer directly mutates `Gfx` during frame production. +- Existing Game 2D visual fixtures or tests remain pixel-equivalent except where explicitly updated for the new boundary. + +## Tests / Validation + +- Add packet-to-pixels tests for representative scene, sprite, primitive, and HUD cases. +- Run existing render tests. +- Add regression coverage comparing old expected pixel buffers where available. + +## Risks + +- Packet conversion can accidentally alter draw order; keep tests focused on ordering and final pixels. +- Some current code may depend on side effects from direct `Gfx` mutation; identify and replace those effects explicitly. + +## Affected Artifacts + +- Classic2D/Gfx renderer modules under `crates/` +- Render tests and fixtures diff --git a/discussion/workflow/plans/PLN-0079-gfx2d-primitive-domain.md b/discussion/workflow/plans/PLN-0079-gfx2d-primitive-domain.md new file mode 100644 index 00000000..58eaea61 --- /dev/null +++ b/discussion/workflow/plans/PLN-0079-gfx2d-primitive-domain.md @@ -0,0 +1,66 @@ +--- +id: PLN-0079 +ticket: render-frame-packet-boundary +title: Gfx2D Primitive Domain +status: open +created: 2026-05-25 +ref_decisions: [DEC-0030] +tags: [gfx, renderer, runtime, frame-composer, architecture, ui, pipeline] +--- + +## Briefing + +Source decision: `DEC-0030`. + +Replace primitive Game drawing paths with `gfx2d.*` command buffering while keeping `gfx2d` limited to primitives only. + +## Target + +Game primitive drawing becomes a Game-mode ABI domain that records commands into a buffer consumed as part of Game 2D rendering. + +## Scope + +- Add `gfx2d.*` syscall domain and command buffer. +- Migrate primitive Game drawing calls from old `gfx.*` behavior to `gfx2d.*`. +- Ensure `gfx2d` contains primitives only. +- Integrate `gfx2d` commands into the Game 2D packet/render path without taking ownership of scene, camera, sprites, HUD, or frame orchestration. + +## Out of Scope + +- Shell UI primitive domain. +- `composer.*` high-level Game state. +- Widget/layout policy. +- Compatibility with old primitive `gfx.*` ABI names. + +## Execution Sequence + +1. Inventory old primitive `gfx.*` syscalls and direct drawing callsites used by Game mode. +2. Define the `gfx2d.*` command enum and mutable command buffer. +3. Route Game primitive syscalls into the buffer. +4. Add app-mode and capability enforcement for Game-only access. +5. Integrate buffered primitives into Game 2D packet closure or renderer consumption at the DEC-0030-approved layer. +6. Remove or retire old primitive `gfx.*` ABI registrations. + +## Acceptance Criteria + +- Game primitive commands are buffered as `gfx2d.*`. +- `gfx2d` does not own scene, camera, sprites, HUD, or frame orchestration. +- Shell mode cannot call `gfx2d.*`. +- No logical primitive path directly mutates framebuffer during production. + +## Tests / Validation + +- Add syscall tests for each migrated primitive. +- Add command buffer ordering tests. +- Add capability rejection tests for Shell mode. +- Run pixel-equivalence tests for unchanged primitive output. + +## Risks + +- The old `gfx` naming may appear in PBS wrappers; distinguish author API names from ABI domain names. +- Primitive ordering relative to composer output must be explicit. + +## Affected Artifacts + +- Syscall registry and runtime render domain modules under `crates/` +- Game primitive tests diff --git a/discussion/workflow/plans/PLN-0080-shell-ui-packet-and-gfxui-domain.md b/discussion/workflow/plans/PLN-0080-shell-ui-packet-and-gfxui-domain.md new file mode 100644 index 00000000..bec557d6 --- /dev/null +++ b/discussion/workflow/plans/PLN-0080-shell-ui-packet-and-gfxui-domain.md @@ -0,0 +1,66 @@ +--- +id: PLN-0080 +ticket: render-frame-packet-boundary +title: Shell UI Packet and GfxUI Domain +status: open +created: 2026-05-25 +ref_decisions: [DEC-0030] +tags: [gfx, renderer, runtime, frame-composer, architecture, ui, pipeline] +--- + +## Briefing + +Source decision: `DEC-0030`. + +Add `gfxui.*` command buffering and `ShellUiFramePacket` for Shell UI primitives while keeping widget/layout policy outside the host/render-surface implementation. + +## Target + +Shell UI emits typed UI primitive commands into a Shell-only packet that render-surface implementations can consume without collapsing UI and Game ABI domains. + +## Scope + +- Define `gfxui.*` primitive commands. +- Add a mutable Shell UI command buffer. +- Close Shell UI commands into `ShellUiFramePacket`. +- Enforce Shell-only capability and app-mode access. +- Keep widget/layout policy in Shell/UI code or stdlib layers. + +## Out of Scope + +- Migrating all Shell callsites; that is handled by the Shell/Hub migration plan. +- Game primitive rendering. +- New widget framework. +- Host-owned debug overlay. + +## Execution Sequence + +1. Define the `gfxui.*` syscall and command vocabulary needed for current Shell UI primitives. +2. Add a Shell UI command buffer and closure into `ShellUiFramePacket`. +3. Add capability metadata and resolver enforcement for `GFXUI`. +4. Add a render-surface consumer path that can rasterize Shell UI commands as an implementation detail. +5. Keep layout/widget decisions above the packet boundary. +6. Add tests for closure, app-mode gating, and packet consumption. + +## Acceptance Criteria + +- Shell UI commands close into `ShellUiFramePacket`. +- `gfxui.*` does not contain widget/layout policy. +- Game mode cannot call `gfxui.*`. +- Host/render-surface code consumes commands without redefining Shell UI product policy. + +## Tests / Validation + +- Add Shell UI command buffer unit tests. +- Add app-mode rejection tests for Game mode. +- Add render-surface consumer tests for representative primitives. + +## Risks + +- It is easy to migrate widget policy into host rendering while adding UI primitives; keep commands low-level and policy-free. +- Shell UI and Game primitives may rasterize similarly, but ABI domains must remain distinct. + +## Affected Artifacts + +- Shell UI render domain modules under `crates/` +- Syscall metadata and tests diff --git a/discussion/workflow/plans/PLN-0081-shell-hub-migration.md b/discussion/workflow/plans/PLN-0081-shell-hub-migration.md new file mode 100644 index 00000000..dc39c7d7 --- /dev/null +++ b/discussion/workflow/plans/PLN-0081-shell-hub-migration.md @@ -0,0 +1,67 @@ +--- +id: PLN-0081 +ticket: render-frame-packet-boundary +title: Shell Hub Migration +status: open +created: 2026-05-25 +ref_decisions: [DEC-0030] +tags: [gfx, renderer, runtime, frame-composer, architecture, ui, pipeline] +--- + +## Briefing + +Source decision: `DEC-0030`. + +Move Prometeu Hub, shell windows, splash/crash UI, and Shell drawing away from `gfx_mut()` into `gfxui.*` and Shell UI command buffers. + +## Target + +Shell-facing UI no longer draws directly into `Gfx`; it produces Shell UI commands that close into `ShellUiFramePacket`. + +## Scope + +- Migrate Prometeu Hub UI drawing. +- Migrate shell windows and window-manager drawing. +- Migrate splash and crash UI drawing. +- Remove direct Shell access to `gfx_mut()` for render production. +- Preserve visible Shell output where behavior is not intentionally changed. + +## Out of Scope + +- Designing new Hub visuals. +- New widget/layout framework. +- Game mode migration. +- Debug console replacement. + +## Execution Sequence + +1. Inventory Shell, Hub, splash, crash, and firmware drawing callsites that use `gfx_mut()` or direct framebuffer access. +2. Replace direct primitive drawing with `gfxui.*` buffer writes. +3. Route Shell frame closure through `RenderManager`. +4. Ensure Shell UI packets are consumed by the render-surface implementation. +5. Remove now-unused direct Shell rendering hooks. +6. Update tests and snapshots for unchanged visible behavior. + +## Acceptance Criteria + +- Shell UI production no longer requires mutable `Gfx` access. +- Hub, shell windows, splash, and crash UI can render through `ShellUiFramePacket`. +- Shell mode does not use `composer.*` or `gfx2d.*`. +- Visible UI output is preserved except for approved fixture updates caused by boundary-only refactoring. + +## Tests / Validation + +- Add integration tests for Hub/shell frame production. +- Add tests for splash and crash UI packet output. +- Run host smoke tests where available. +- Use pixel or snapshot comparisons for representative Shell screens. + +## Risks + +- Firmware and Shell code may mix lifecycle side effects with drawing; split command production without changing lifecycle semantics. +- Some host tests may assume immediate framebuffer writes; update them to observe submissions or final pixels. + +## Affected Artifacts + +- Shell, Hub, firmware, and host integration modules under `crates/` +- Shell UI tests and fixtures diff --git a/discussion/workflow/plans/PLN-0082-frame-publication-and-present-boundary.md b/discussion/workflow/plans/PLN-0082-frame-publication-and-present-boundary.md new file mode 100644 index 00000000..3afae455 --- /dev/null +++ b/discussion/workflow/plans/PLN-0082-frame-publication-and-present-boundary.md @@ -0,0 +1,69 @@ +--- +id: PLN-0082 +ticket: render-frame-packet-boundary +title: Frame Publication and Present Boundary +status: open +created: 2026-05-25 +ref_decisions: [DEC-0030] +tags: [gfx, renderer, runtime, frame-composer, architecture, ui, pipeline] +--- + +## Briefing + +Source decision: `DEC-0030`. + +Move `present()` and surface publication behind the render-surface implementation boundary so runtime producers no longer publish buffers directly. + +## Target + +Only the render-surface implementation publishes RGBA8888 output; logical producers and `RenderManager` hand off closed submissions through a boundary. + +## Scope + +- Identify all direct `present()` and surface publication callsites. +- Define the render-surface adapter boundary. +- Route publication through the adapter from `RenderManager`. +- Keep desktop `pixels` publication as a host implementation detail. +- Preserve frame pacing and invalidation behavior. + +## Out of Scope + +- New backend registry. +- GPU implementation. +- Render thread. +- Dirty regions. +- Visual transition design. + +## Execution Sequence + +1. Inventory `present()`, framebuffer publication, and host invalidation callsites. +2. Add or refine a render-surface trait/adapter that consumes `RenderSubmission`. +3. Move host desktop publication below that adapter. +4. Update runtime frame loop to publish only through `RenderManager` and the adapter. +5. Remove direct publication from composer, `gfx2d`, `gfxui`, Shell, and Game producers. +6. Verify frame pacing and host invalidation still occur at the correct boundary. + +## Acceptance Criteria + +- Logical render domains cannot call `present()` or publish buffers directly. +- Host desktop publication remains functional below the render-surface boundary. +- `RenderManager` owns the policy for selecting the latest complete submission. +- Existing frame pacing behavior is not regressed. + +## Tests / Validation + +- Add unit tests for render-surface handoff. +- Add integration tests proving producers cannot publish directly. +- Run host desktop render/pacing tests. +- Inspect `rg -n "present\\(|publish|pixels" crates` for boundary violations. + +## Risks + +- Publication and invalidation may be coupled in current host code; preserve timing semantics while moving ownership. +- A too-broad adapter can become a backend registry prematurely. + +## Affected Artifacts + +- Runtime render manager modules +- Host desktop render surface modules +- Frame pacing tests diff --git a/discussion/workflow/plans/PLN-0083-fade-removal.md b/discussion/workflow/plans/PLN-0083-fade-removal.md new file mode 100644 index 00000000..0ebbd5bb --- /dev/null +++ b/discussion/workflow/plans/PLN-0083-fade-removal.md @@ -0,0 +1,63 @@ +--- +id: PLN-0083 +ticket: render-frame-packet-boundary +title: Fade Removal +status: open +created: 2026-05-25 +ref_decisions: [DEC-0030] +tags: [gfx, renderer, runtime, frame-composer, architecture, ui, pipeline] +--- + +## Briefing + +Source decision: `DEC-0030`. + +Remove fade fields, syscalls, packet members, renderer state, tests, and docs from canonical render contracts. + +## Target + +Fade is no longer a render pipeline feature. Future visual transitions remain the responsibility of `RenderManager` and require separate product/domain work. + +## Scope + +- Remove fade from specs, HAL packet types, syscall metadata, runtime state, renderer state, tests, and PBS declarations. +- Remove or update tests that assert fade behavior. +- Add guard tests or searches that prevent reintroducing fade in canonical render contracts. + +## Out of Scope + +- Implementing replacement visual transitions. +- Replacing fade with another transition API. +- Preserving backward compatibility for fade syscalls. + +## Execution Sequence + +1. Inventory all fade references in specs, crates, tests, examples, and PBS stdlibs. +2. Delete fade fields and syscalls from canonical ABI and packet definitions. +3. Remove renderer/runtime fade state and behavior. +4. Update callers and tests to stop setting or expecting fade. +5. Add documentation language that transitions belong to `RenderManager`. +6. Run targeted and full affected tests. + +## Acceptance Criteria + +- No canonical packet, syscall, or render contract contains fade. +- Runtime and renderer code do not maintain fade state. +- Tests no longer depend on fade behavior. +- Specs clearly state future transitions are `RenderManager` responsibility. + +## Tests / Validation + +- Run `rg -n "\\bfade\\b|Fade" specs crates discussion/workflow` and verify remaining references are only historical decision/agenda text or explicit removal notes. +- Run affected unit and integration tests. +- Add regression tests preventing fade fields in current packet types. + +## Risks + +- Removing tests can reduce coverage; replace fade-specific assertions with packet/transition boundary assertions where appropriate. +- Historical discussion files may keep fade references; do not rewrite history unless the framework requires it. + +## Affected Artifacts + +- Specs +- HAL, runtime, renderer, syscall, PBS, and tests under `crates/` diff --git a/discussion/workflow/plans/PLN-0084-host-debug-overlay-removal.md b/discussion/workflow/plans/PLN-0084-host-debug-overlay-removal.md new file mode 100644 index 00000000..0b30fe7c --- /dev/null +++ b/discussion/workflow/plans/PLN-0084-host-debug-overlay-removal.md @@ -0,0 +1,65 @@ +--- +id: PLN-0084 +ticket: render-frame-packet-boundary +title: Host Debug Overlay Removal +status: open +created: 2026-05-25 +ref_decisions: [DEC-0030] +tags: [gfx, renderer, runtime, frame-composer, architecture, ui, pipeline] +--- + +## Briefing + +Source decision: `DEC-0030`. + +Remove the current host-owned debug overlay from the render path. Any future console/debug UI is a separate product/domain discussion. + +## Target + +Host rendering no longer injects an inherited debug overlay into Game or Shell output. + +## Scope + +- Identify host-owned debug overlay code and render hooks. +- Remove overlay rendering from the host render path. +- Remove overlay toggles/tests that assume inherited host drawing. +- Preserve non-render telemetry and logging where they are not tied to overlay drawing. + +## Out of Scope + +- Designing a replacement debug console. +- Moving debug UI into `gfxui.*`. +- Changing telemetry collection. +- Removing unrelated developer diagnostics. + +## Execution Sequence + +1. Inventory debug overlay rendering callsites and tests. +2. Remove host overlay injection from Game and Shell render paths. +3. Delete overlay-specific drawing state, toggles, and fixture expectations. +4. Keep telemetry/logging APIs that do not render overlay pixels. +5. Update docs/specs to state that future debug UI requires a separate decision. +6. Run host and render tests. + +## Acceptance Criteria + +- Host render path does not draw debug overlay pixels. +- Game and Shell output do not depend on host overlay state. +- Remaining diagnostics do not violate the render pipeline boundary. +- Docs do not preserve host overlay as an architectural requirement. + +## Tests / Validation + +- Run host render tests. +- Add or update tests proving overlay state does not affect final rendered output. +- Run `rg -n "debug overlay|overlay|DebugOverlay" crates specs discussion/workflow` and inspect remaining references. + +## Risks + +- Removing overlay code can accidentally remove useful telemetry; keep non-render diagnostics intact. +- The word overlay may also refer to Game HUD/primitives; distinguish those from host debug overlay. + +## Affected Artifacts + +- Host desktop modules under `crates/` +- Host/render tests diff --git a/discussion/workflow/plans/PLN-0085-pbs-stdlib-and-syscall-declarations.md b/discussion/workflow/plans/PLN-0085-pbs-stdlib-and-syscall-declarations.md new file mode 100644 index 00000000..5b928399 --- /dev/null +++ b/discussion/workflow/plans/PLN-0085-pbs-stdlib-and-syscall-declarations.md @@ -0,0 +1,67 @@ +--- +id: PLN-0085 +ticket: render-frame-packet-boundary +title: PBS Stdlib and Syscall Declarations +status: open +created: 2026-05-25 +ref_decisions: [DEC-0030] +tags: [gfx, renderer, runtime, frame-composer, architecture, ui, pipeline] +--- + +## Briefing + +Source decision: `DEC-0030`. + +Update PBS Game and Shell stdlibs so high-level APIs map to app-mode-specific ABI domains: Game uses `composer.*` and `gfx2d.*`; Shell uses `gfxui.*`. + +## Target + +PBS authors can keep ergonomic high-level APIs where appropriate, but generated or declared syscalls use the correct DEC-0030 ABI domain for the active app mode. + +## Scope + +- Update Game stdlib declarations for `composer.*` and `gfx2d.*`. +- Update Shell stdlib declarations for `gfxui.*`. +- Remove old primitive `gfx.*` ABI declarations. +- Keep author-facing wrappers clear about mode-specific behavior. +- Update examples/tests that compile PBS code. + +## Out of Scope + +- Runtime implementation of the syscall handlers. +- New visual APIs beyond the domain split. +- Backward compatibility for old primitive `gfx.*` ABI declarations. +- Widget/layout redesign. + +## Execution Sequence + +1. Inventory PBS stdlib files and syscall declaration generation. +2. Map Game scene/camera/sprites/HUD APIs to `composer.*`. +3. Map Game primitive APIs to `gfx2d.*`. +4. Map Shell primitive APIs to `gfxui.*`. +5. Remove or fail old primitive `gfx.*` ABI declarations. +6. Update PBS compile tests, examples, and syscall metadata expectations. + +## Acceptance Criteria + +- PBS Game code emits only Game-allowed render ABI domains. +- PBS Shell code emits only Shell-allowed render ABI domains. +- Old primitive `gfx.*` ABI declarations are gone or explicitly rejected. +- Existing examples are updated to the new declarations. + +## Tests / Validation + +- Run PBS stdlib and compiler tests. +- Add Game and Shell declaration tests for emitted syscall names. +- Add negative tests for wrong-domain declarations. + +## Risks + +- User-facing API names may remain similar while ABI names change; tests must assert emitted syscall domains, not just wrapper names. +- Examples can mask stale declarations if they do not compile in both Game and Shell contexts. + +## Affected Artifacts + +- PBS stdlib files +- Syscall declaration generation +- PBS tests and examples diff --git a/discussion/workflow/plans/PLN-0086-end-to-end-render-boundary-validation.md b/discussion/workflow/plans/PLN-0086-end-to-end-render-boundary-validation.md new file mode 100644 index 00000000..e148e987 --- /dev/null +++ b/discussion/workflow/plans/PLN-0086-end-to-end-render-boundary-validation.md @@ -0,0 +1,71 @@ +--- +id: PLN-0086 +ticket: render-frame-packet-boundary +title: End-to-End Render Boundary Validation +status: open +created: 2026-05-25 +ref_decisions: [DEC-0030] +tags: [gfx, renderer, runtime, frame-composer, architecture, ui, pipeline] +--- + +## Briefing + +Source decision: `DEC-0030`. + +Add end-to-end validation proving the new boundary works across Game and Shell modes after the granular implementation plans land. + +## Target + +Integration coverage demonstrates typed submissions, app-mode capability gates, immutable closed submissions, render-surface publication, fade removal, and visible output preservation. + +## Scope + +- Add Game end-to-end tests from PBS/syscall production to `Game2DFramePacket` and final pixels. +- Add Shell end-to-end tests from UI production to `ShellUiFramePacket` and final pixels. +- Test wrong-domain capability failures. +- Test closed-submission immutability. +- Test latest-complete-submission-wins behavior. +- Test absence of fade and host debug overlay from canonical paths. + +## Out of Scope + +- Implementing missing production code. +- New rendering features. +- Performance tuning. +- Dirty regions. + +## Execution Sequence + +1. Define representative Game and Shell scenarios that cover composer, `gfx2d`, and `gfxui`. +2. Add integration harness access to inspect closed submissions where appropriate. +3. Assert Game produces `RenderSubmission::Game2D` and Shell produces `RenderSubmission::ShellUi`. +4. Assert wrong-domain syscalls fail before mutating buffers. +5. Assert closed submissions remain unchanged after producers continue mutating the next frame. +6. Assert final pixels match existing expected output for unchanged scenarios. +7. Add searches or tests proving fade and host debug overlay are absent from the active render path. + +## Acceptance Criteria + +- Game and Shell each have end-to-end typed submission tests. +- Capability gates reject `gfxui` in Game and `composer`/`gfx2d` in Shell. +- Closed submissions are immutable snapshots. +- Latest complete submission replaces older unpublished submissions without queue growth. +- Unchanged Game and Shell scenarios remain visually equivalent. + +## Tests / Validation + +- Run full affected Rust test suites. +- Run PBS compile/runtime integration tests. +- Run pixel-equivalence tests for representative Game and Shell output. +- Run `discussion validate` once execution discussion artifacts are updated. + +## Risks + +- End-to-end tests may become brittle if they assert host details; assert the logical contract and final pixels, not internal host implementation names. +- Pixel-equivalence fixtures must account for intentional removals such as host debug overlay. + +## Affected Artifacts + +- Integration tests under `crates/` +- PBS tests +- Render fixtures