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

---
id: AGD-0042
ticket: real-render-worker-establishment
title: Host Hardware and Render Boundary Preparation
status: accepted
created: 2026-06-06
resolved:
decision: DEC-0032
tags: [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

- [x] `HardwareBridge` deve sobreviver como compatibilidade final?
  - Resposta: nao. Ele deve ser completamente eliminado no destino.
- [x] 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.
- [x] `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.
- [x] 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.
- [x] 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.
- [x] 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.
- [x] Como preservar testes simples que hoje usam `Hardware::new()`?
  - Resposta: criar `TestPlatform` como fixture explicita para testes. Nao preservar `HardwareBridge` como compatibilidade.
- [x] 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.
- [x] 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.
- [x] `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.
- [x] 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.
- [x] 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`.