prometeu-runtime/discussion/workflow/agendas/AGD-0042-host-hardware-render-boundary-preparation.md

id	ticket	title	status	created	resolved	decision	tags
AGD-0042	real-render-worker-establishment	Host Hardware and Render Boundary Preparation	accepted	2026-06-06		DEC-0032	runtime renderer hardware host hal boundary architecture

Contexto

DSC-0040 fechou a arquitetura base para separar VM/logical execution de render consumption. A implementacao atual ainda usa HardwareBridge como uma trait agregadora grande: render, composer, Gfx, audio, input, touch e assets ficam expostos juntos para runtime, firmware e syscalls.

Para estabelecer um worker real, precisamos antes preparar essa fronteira. A direcao agora nao e mais transformar HardwareBridge em uma interface host-implemented permanente. A direcao e reformular o runtime em uma platform layer com servicos explicitos e eliminar completamente o HardwareBridge monolitico como contrato final.

O worker real deve depender apenas de uma sub-abstracao minima de render, nunca de &mut Hardware inteiro.

Esta agenda (AGD-0042) discute a preparacao/refatoracao de fronteiras. A agenda seguinte (AGD-0043) dentro da mesma DSC-0042 discutira o estabelecimento do worker real propriamente dito.

Problema

Hoje o sistema ja tem uma trait (HardwareBridge), mas ela ainda permite acoplamentos que impedem um worker real limpo:

• HostContext entrega &mut dyn HardwareBridge para syscalls;
• syscalls gfx2d.* e gfxui.* ainda fazem buffering de comandos e tambem desenham imediatamente via hw.gfx_mut();
• composer state (bind_scene, set_camera, emit_sprite, close_game2d_packet) vive dentro da mesma abstracao que render/present;
• firmware e Hub publicam diretamente via hw.publish_render_submission;
• host desktop instancia prometeu_drivers::Hardware diretamente e usa constantes concretas como Hardware::W/H;
• testes dependem fortemente do Hardware concreto.

Se introduzirmos o worker real agora, a implementacao provavelmente acabara passando &mut Hardware, &mut Gfx ou FrameComposer vivo para a fronteira do worker por conveniencia. Isso quebraria o contrato definido em DEC-0031.

Pontos Criticos

0. Escopo da migracao completa

Podemos migrar render primeiro para reduzir risco e desbloquear o worker real, mas a mudanca nao deve parar no render. Audio, input, touch, assets/storage, clock/pacing e telemetry tambem devem sair do HardwareBridge monolitico para servicos/facades explicitos.

HardwareBridge deve morrer ao final desta mudanca. Qualquer uso intermediario e scaffold de migracao, nao contrato final.

1. Eliminacao do HardwareBridge

HardwareBridge pode existir apenas como detalhe transitorio durante a migracao, se isso reduzir risco de implementacao. Ele nao deve sobreviver como compat layer permanente nem como contrato publico do runtime.

O estado final deve remover HardwareBridge e substituir o acesso monolitico por servicos explicitos de plataforma.

2. Render submission sink

O primeiro corte provavelmente deve extrair algo como RenderSubmissionSink, separando submit/publish de HardwareBridge.

3. Remocao de render imediato das syscalls

As syscalls de gfx2d/gfxui devem apenas gravar comandos nos buffers que fecham o packet. O desenho imediato via hw.gfx_mut() deve sair antes do worker real.

4. Composer como dominio logico

bind_scene, set_camera, emit_sprite e close_game2d_packet pertencem ao fechamento logico do frame. Precisamos separar essa capacidade do backend que rasteriza/presenta.

5. Host-owned concrete hardware

prometeu_drivers::Hardware deve continuar existindo como implementacao local/default, mas nao como a arquitetura. O host desktop pode owns essa implementacao ou uma composicao de facades.

6. Test migration

Muitos testes instanciam Hardware::new(). A migracao deve preservar fixtures simples, talvez com um TestHardware ou LocalHardware que implemente as novas facades.

Opcoes

Opcao A - Quebrar HardwareBridge em uma unica grande refatoracao

Abordagem: substituir HardwareBridge por facades menores em runtime, firmware, host e testes de uma vez.

Pros:

• resultado final mais limpo imediatamente;
• remove rapidamente o risco de acoplamento.

Contras:

• alto blast radius;
• muitos testes mudam ao mesmo tempo;
• dificil isolar regressao funcional de regressao arquitetural.

Manutenibilidade: boa no destino, arriscada durante a transicao.

Opcao B - Extrair facades incrementalmente e eliminar HardwareBridge no final

Abordagem: criar facades menores (RenderSubmissionSink, composer/logical frame facade, audio/input/assets), usar HardwareBridge apenas como scaffold temporario se necessario, migrar callers por etapas e remover HardwareBridge ao final.

Pros:

• menor risco;
• permite commits pequenos;
• preserva testes e host desktop enquanto a fronteira e endurecida;
• facilita medir quando o worker real ja pode nascer.

Contras:

• periodo intermediario com duas camadas;
• exige disciplina para nao continuar usando gfx_mut() no caminho errado.
• requer criterio explicito de remocao para evitar que o scaffold vire legado.

Manutenibilidade: melhor equilibrio para o estado atual do repo.

Opcao C - Criar apenas RenderSubmissionSink agora e adiar o resto

Abordagem: extrair somente a publicacao de submissions e manter composer/gfx/audio/input/assets no HardwareBridge por enquanto.

Pros:

• menor mudanca inicial;
• desbloqueia parte do worker path.

Contras:

• ainda deixa syscalls e composer acoplados ao hardware grande;
• worker real ainda pode esbarrar no viewport cache/composer vivo;
• risco de adiar o problema central.

Manutenibilidade: aceitavel como primeiro PR, insuficiente como preparacao completa.

Sugestao / Recomendacao

Recomendo a Opcao B, em fases, com uma restricao forte: HardwareBridge deve ser eliminado no estado final.

1. Criar RenderSubmissionSink com erro tipado minimo, mantendo implementacao local em prometeu_drivers::Hardware.
2. Trocar publication local para depender de RenderSubmissionSink, nao do HardwareBridge inteiro.
3. Remover writes imediatos de gfx_mut() nas syscalls gfx2d/gfxui; syscalls devem apenas bufferizar comandos.
4. Extrair uma facade de composer/logical frame closure para bind_scene, set_camera, emit_sprite, close_game2d_packet.
5. Migrar firmware, Hub, runtime, host desktop e testes para as facades novas.
6. Remover HardwareBridge e qualquer dependencia nova dele.
7. Atualizar fixtures/testes para dependerem das facades certas.

O criterio tecnico: antes da agenda do worker real virar plano, nenhum caminho de render worker deve precisar de &mut Hardware, &mut Gfx, FrameComposer vivo ou estado mutavel da VM.

O criterio arquitetural: antes desta agenda fechar, HardwareBridge deve estar definido como artefato a ser removido, nao como compatibilidade preservada.

Perguntas em Aberto

• HardwareBridge deve sobreviver como compatibilidade final?
  • Resposta: nao. Ele deve ser completamente eliminado no destino.
• Se houver transicao incremental, HardwareBridge deve herdar facades menores ou apenas expor accessors temporarios?
  • Resposta: se existir durante a migracao, deve usar accessors/adapters temporarios explicitos. Nao deve herdar facades menores, para nao parecer o novo contrato arquitetural.
• RenderSubmissionSink deve receber &RenderSubmission ou owned RenderSubmission?
  • Resposta: owned RenderSubmission. O contrato deve nascer pronto para handoff/worker; o caminho local pode adaptar internamente quando necessario.
• O erro tipado minimo entra ja nesta preparacao ou fica para a agenda do worker real?
  • Resposta: entra ja nesta preparacao, em forma minima. A API nao deve nascer infalivel para ser quebrada logo na agenda do worker real.
• Qual e a primeira syscall/teste que prova que gfx2d nao desenha mais imediatamente?
  • Resposta: comecar por gfx2d.clear e gfx2d.draw_text. Os testes devem provar que a syscall apenas bufferiza comando e que pixels mudam somente apos fechamento/publicacao da submission.
• Composer deve ficar no runtime/logical side ou continuar em prometeu_drivers::Hardware enquanto nao houver worker?
  • Resposta: deve ficar no logical side/runtime service. A migracao pode ser faseada, mas bind_scene, set_camera, emit_sprite e close_game2d_packet sao preparacao de frame logico, nao backend fisico.
• Como preservar testes simples que hoje usam Hardware::new()?
  • Resposta: criar TestPlatform como fixture explicita para testes. Nao preservar HardwareBridge como compatibilidade.
• Que nomes vamos usar: Hardware, HostHardware, LocalHardware, RuntimeHardware, RenderDevice, RenderSubmissionSink?
  • Resposta: usar Platform/RuntimePlatform para o agregado de servicos, TestPlatform para fixtures de teste, RenderSubmissionSink para submissao, RenderBackend para raster/present, e Game2DFrameComposer para o composer logico de Game2D. Evitar Hardware como nome arquitetural central.
• Onde os contratos da platform layer devem viver?
  • Resposta: contratos/facades em prometeu-hal; implementacoes locais/test em prometeu-drivers; integracao e ownership operacional no prometeu-system e nos hosts.
• Game2DFrameComposer pertence ao runtime/logical side ou ao backend de render?
  • Resposta: pertence ao logical side. O contrato deve ficar separado do backend renderizavel. A implementacao inicial pode migrar em fases, mas nao deve continuar sendo tratada como parte do hardware fisico.
• Qual e o criterio para remover HardwareBridge?
  • Resposta: remover quando runtime, firmware, Hub, host desktop e testes tiverem migrado para facades explicitas. A remocao deve ser plano proprio ou criterio final de um plano de migracao, nao compatibilidade opcional.
• Aceitamos a quebra intencional de render imediato em gfx2d/gfxui?
  • Resposta: sim. Syscalls devem bufferizar comandos; pixels devem mudar somente no fechamento/publicacao da submission. Testes que dependem de desenho imediato devem ser atualizados para o novo contrato.

Criterio para Encerrar

Esta agenda pode virar decision quando tivermos:

• sequencia clara de refatoracao para preparar a fronteira;
• definicao das facades minimas;
• estrategia para remover render imediato das syscalls;
• decisao de remocao do HardwareBridge e estrategia de transicao, se houver;
• estrategia de testes/fixtures;
• criterio objetivo de pronto para iniciar AGD-0043.

Discussion

• 2026-06-06: Agenda reescopada. A DSC-0042 passa a ter duas agendas: esta para preparacao da fronteira host/hardware/render, e AGD-0043 para o worker real.
• 2026-06-06: Direcao levantada: Hardware deve ser uma abstracao/contrato implementado pelo host, nao um objeto concreto owned pelo runtime que cruza a fronteira do worker.
• 2026-06-06: Avaliacao inicial de impacto: mudanca media/alta, mas fatiavel. O acoplamento principal esta em HardwareBridge, HostContext, syscalls de dispatch, firmware, Hub, host desktop e testes.
• 2026-06-06: Reformulacao de objetivo: a intencao inicial era expor Hardware como interface consumida pelo runtime e implementada pelo host. Com a evolucao do sistema, isso pode estar limitado demais. O novo objetivo e reformular o runtime para um padrao mais proximo de uma plataforma handheld: runtime/OS como dono de lifecycle, scheduling, recursos e contratos; host/board support package como implementacao de dispositivos; render/audio/input/assets expostos por facades separadas e testaveis, nao por uma unica abstracao monolitica de hardware.
• 2026-06-06: Direcao cravada: HardwareBridge nao deve ser preservado como compatibilidade. No estado final da reformulacao ele deve ser completamente eliminado, substituido por servicos/facades explicitos de platform layer.
• 2026-06-06: Perguntas abertas respondidas: transicao por adapters/accessors temporarios, RenderSubmissionSink owned, erro tipado minimo ja na preparacao, primeiros testes em gfx2d.clear/gfx2d.draw_text, composer no logical side, fixtures via TestPlatform, e nomes preferidos Platform/RuntimePlatform, RenderSubmissionSink, RenderBackend, Game2DFrameComposer.
• 2026-06-06: Escopo confirmado: render pode migrar primeiro, mas a migracao deve cobrir todos os dominios atualmente presos ao HardwareBridge. O objetivo final inclui a remocao completa do HardwareBridge, nao apenas reduzir seu uso no render.
• 2026-06-06: Pontos adicionais aceitos: facades em prometeu-hal, implementacoes local/test em prometeu-drivers, integracao em prometeu-system/hosts; Game2DFrameComposer no logical side; HardwareBridge removido apos migracao completa dos callers; e quebra intencional do desenho imediato das syscalls gfx2d/gfxui.

Resolution

AGD-0042 resolve que o destino arquitetural nao e uma interface monolitica HardwareBridge implementada pelo host. O destino e uma platform layer composta por servicos/facades explicitos, com contratos em prometeu-hal, implementacoes local/test em prometeu-drivers, e integracao operacional em prometeu-system e nos hosts.

HardwareBridge pode existir apenas como scaffold temporario de migracao. Ele deve ser completamente eliminado ao final, sem compatibilidade permanente. A migracao pode comecar por render, mas deve cobrir todos os dominios atualmente presos ao bridge: render, composer/frame, audio, input/touch, assets/storage, clock/pacing e telemetry quando aplicavel.

O primeiro corte deve preparar o caminho do render worker sem implementa-lo ainda: introduzir RenderSubmissionSink owned com erro tipado minimo, remover desenho imediato das syscalls gfx2d/gfxui, mover Game2DFrameComposer para o logical side/runtime service, e substituir fixtures baseadas em Hardware::new() por TestPlatform.

Esta agenda estara pronta para decision quando a decision puder definir a sequencia de migracao e os criterios de remocao final do HardwareBridge sem reabrir o contrato de render worker da DSC-0040.