Real Render Worker Establishment

This commit is contained in:
2026-06-06 17:52:25 +01:00
parent 26e038e195
commit 80a36a3e7a
17 changed files with 1533 additions and 174 deletions
@@ -0,0 +1,191 @@
---
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`.
@@ -1,172 +0,0 @@
---
id: AGD-0042
ticket: real-render-worker-establishment
title: Real Render Worker Establishment
status: open
created: 2026-06-06
resolved:
decision:
tags: [runtime, renderer, worker, concurrency, host, hal, architecture]
---
## Contexto
`DEC-0031` fechou a arquitetura base da fronteira VM/render: submissions fechadas, handoff single-slot latest-wins, pacing por `FrameScheduler`, politica explicita por `AppMode`, ownership/epoch e telemetria.
A implementacao atual ja tem a base local/sincrona e um `LocalRenderWorker` cooperativo por capability flag. Isso valida o roteamento e a politica, mas ainda nao estabelece um worker real em outra thread/core. O proximo passo arquitetural e transformar esse prototipo em uma unidade de execucao real sem reabrir a decisao base.
Esta agenda existe para discutir somente o estabelecimento do worker real. Ela nao deve redecidir `gfx2d` como overlay, o packet boundary, AppMode policy, ou latest-wins; esses pontos pertencem a `DEC-0031`.
## Problema
Um worker real precisa cruzar fronteiras que o prototipo local ainda evita:
- ownership e lifetime de recursos compartilhados entre VM/logical core e render worker;
- como o worker recebe, consome, rasteriza e apresenta submissions sem `&mut Hardware`, `&mut Gfx`, `FrameComposer` vivo ou estado mutavel da VM;
- como o viewport cache/read model fica seguro e barato;
- como shutdown, stop token, current work e stale owner funcionam quando ha trabalho realmente em voo;
- onde fica o present loop e se ele roda a 60Hz independentemente da VM;
- como erros de render/present deixam de ser apenas panic containment e viram resultado tipado;
- como host desktop, hardware proprio, outro core, DMA ou coprocessador mapeiam para o mesmo contrato.
## Pontos Criticos
### 1. Ownership do worker
Precisamos decidir se o worker real pertence ao runtime, ao host, a HAL, ou a uma camada hibrida. `DEC-0031` diz que host/HAL fornece capability concreta, mas `RenderManager` coordena contrato. Falta definir o boundary operacional.
### 2. Surface e backend renderizavel
O worker nao pode receber `&mut Hardware` ou `&mut Gfx` da VM thread. Precisamos de um objeto/capability renderizavel que seja owned pelo worker ou mediado por host.
### 3. Recursos read-only e viewport cache
Glyph/scene banks ja tem boundary read-only inicial. O viewport cache ainda precisa de um modelo concreto: snapshot, `Arc` read-only, double-buffer cache, cache materializado por frame, ou service proprietario.
### 4. Current work e cancelamento
O `RenderManager` ja descarta pending e rejeita stale epoch antes de present. Com worker real, uma submission pode estar em rasterizacao. Precisamos definir stop token, epoch check antes de present, bounded join e descarte de current work.
### 5. Present loop e frame repeat
Hoje repeated present e telemetria/hook. Um worker real provavelmente precisa de loop de present/display cadence. Falta decidir se o worker apresenta a 60Hz, se o host faz scanout/repeat, e como isso conversa com `FrameScheduler`.
### 6. Erros tipados
`RenderSurface` hoje e infalivel e panic containment vira `PresentFailed`. Para worker real, render/present deveria retornar erro tipado, distinguindo falha recuperavel, backend lost, surface lost, panic, shutdown e stale discard.
### 7. Testabilidade
Precisamos de testes que provem thread boundary, latest-wins sob atraso real, shutdown com current work em voo, stale epoch durante rasterizacao, repeat do ultimo frame e ausencia de bloqueio da VM.
## Opcoes
### Opcao A - Worker real dentro do runtime
**Abordagem:** `RenderManager` ou um novo `RenderWorkerRuntime` cria e gerencia uma thread de render, canais/slots, stop token e lifecycle.
**Pros:**
- contrato fica perto de `RenderManager`;
- facil testar com runtime puro;
- menos dependencia de host desktop.
**Contras:**
- risco de runtime assumir detalhes de surface/window que pertencem ao host;
- pode ficar ruim para hardware proprio, DMA ou coprocessador;
- exige abstrair muito bem o backend renderizavel.
**Manutenibilidade:** boa se o backend for uma trait pequena e owned pelo worker; ruim se vazar `Hardware`/`Gfx` vivo.
### Opcao B - Worker real como responsabilidade do host
**Abordagem:** runtime fecha submissions e handoff; host implementa thread/core/present loop usando uma capability HAL/host.
**Pros:**
- encaixa melhor desktop windowing, swapchain, surface lost e display cadence;
- facilita mapeamento para plataformas diferentes;
- runtime continua sem detalhe de thread/window.
**Contras:**
- testes de contrato podem ficar mais integrados e menos unitarios;
- risco de cada host reinterpretar o contrato;
- `RenderManager` precisa expor hooks suficientes sem virar passivo demais.
**Manutenibilidade:** boa para plataformas diversas, desde que exista uma suite de contrato obrigatoria.
### Opcao C - Worker como HAL/backend owned, coordenado pelo runtime
**Abordagem:** runtime possui `RenderManager` e policy; HAL/host fornece um `RenderBackend`/`RenderWorkerBackend` owned e thread-safe. Um `RenderWorkerController` conecta handoff, stop token, epoch e telemetry.
**Pros:**
- separa contrato runtime de implementacao de host;
- permite worker thread no desktop e outro core/DMA em hardware;
- cria ponto unico para testes de contrato;
- evita passar `&mut Hardware` ou `&mut Gfx` pela fronteira.
**Contras:**
- mais desenho inicial;
- exige definir traits novas com cuidado;
- pode ser excessivo se o primeiro worker real for apenas desktop.
**Manutenibilidade:** melhor direcao se quisermos preservar portabilidade e nao acoplar runtime a winit/surface.
### Opcao D - Adiar worker real e manter prototipo local
**Abordagem:** nao implementar worker real agora; apenas fortalecer testes/spec e manter `LocalRenderWorker`.
**Pros:**
- menor risco imediato;
- evita mexer em host/surface antes da necessidade real.
**Contras:**
- nao valida thread/core real;
- deixa lacunas de Send/Sync, shutdown current work e present cadence;
- pode mascarar problemas de ownership ate tarde.
**Manutenibilidade:** aceitavel por curto prazo, fraca se a demanda agora e paralelismo real.
## Sugestao / Recomendacao
Recomendo seguir pela **Opcao C - Worker como HAL/backend owned, coordenado pelo runtime**.
O desenho deve manter `RenderManager` como dono de policy, epoch, handoff e telemetry, mas introduzir uma camada operacional para worker real com:
- backend/render surface owned pelo worker ou pelo host;
- handoff single-slot sem bloquear VM;
- stop token e bounded shutdown;
- check de epoch/owner antes de present;
- erro tipado para render/present;
- present cadence explicita, com repeat do ultimo frame quando nao houver submission nova;
- testes de contrato que rodem sem janela nativa sempre que possivel.
Essa recomendacao preserva `DEC-0031` e evita transformar o runtime puro em dono de detalhes de window/swapchain.
## Perguntas em Aberto
- [ ] O primeiro worker real deve nascer no host desktop/winit ou em uma abstracao runtime/HAL testavel sem janela?
- [ ] Qual trait substitui `RenderSurface::consume_submission(&RenderSubmission) -> ()` para erro tipado?
- [ ] O worker owns `Gfx`/framebuffer, ou `Gfx` continua em `Hardware` e precisa ser dividido?
- [ ] Como o viewport cache sera exposto ao worker: snapshot por frame, `Arc` read-only, double-buffer, ou service proprietario?
- [ ] Quem roda o present loop de 60Hz: worker, host event loop, ou uma autoridade de display separada?
- [ ] Como testar current work em voo sem depender de sleeps/flakiness?
- [ ] Como mapear shutdown: stop accepting, discard pending, cancel current, join bounded, preserve last surface?
- [ ] Quais tipos precisam de prova `Send + Sync` antes do primeiro worker real?
- [ ] Shell continua fora do worker no primeiro passo, ou devemos provar explicitamente que capability Game nao afeta Shell?
## Criterio para Encerrar
Esta agenda pode virar decision quando tivermos uma resposta clara para:
- ownership/layer responsavel pelo worker real;
- trait/backend de render/present e modelo de erro;
- modelo de recurso read-only, especialmente viewport cache;
- protocolo de shutdown/current work;
- present cadence/repeat;
- plano de testes para thread/core real;
- escopo do primeiro worker real, incluindo o que fica explicitamente fora.
## Discussion
- 2026-06-06: Agenda criada apos a execucao de `DSC-0040`, que fechou a arquitetura base mas deixou o worker real como etapa futura deliberada.
## Resolution
@@ -0,0 +1,153 @@
---
id: AGD-0043
ticket: real-render-worker-establishment
title: Real Render Worker Establishment
status: open
created: 2026-06-06
resolved:
decision:
tags: [runtime, renderer, worker, concurrency, host, hal, architecture]
---
## Contexto
`DEC-0031` definiu o contrato arquitetural da fronteira VM/render. `AGD-0042` prepara a fronteira host/hardware/render para que `Hardware` deixe de ser um objeto concreto atravessando o worker e passe a ser contrato/facades implementadas pelo host.
Esta agenda discute a implementacao do worker real propriamente dito, assumindo que a preparacao da fronteira foi ou sera resolvida antes da execucao.
## Problema
O `LocalRenderWorker` atual e cooperativo/local. Ele prova o roteamento de policy, mas nao prova:
- thread/core real;
- ownership do backend renderizavel;
- present loop;
- stop token para current work;
- bounded shutdown/join;
- stale epoch durante rasterizacao;
- erro tipado de render/present;
- repeat real do ultimo frame valido;
- ausencia de bloqueio da VM sob atraso do render.
## Pontos Criticos
### 1. Ownership e lifecycle do worker
Precisamos decidir quem cria, inicia, para e reinicia o worker: runtime controller, host/HAL, ou ambos em contrato dividido.
### 2. Handoff real
O single-slot latest-wins ja existe como abstracao local. O worker real precisa de uma implementacao thread-safe, sem fila crescente e sem bloquear a VM.
### 3. Backend renderizavel
O worker deve owns um backend minimo ou receber capability host-owned. Esse backend deve consumir `RenderSubmission`, resolver recursos read-only e produzir/presentar frame sem `&mut Hardware`.
### 4. Present cadence
Precisamos decidir se o worker roda a 60Hz, se o host event loop dirige present, ou se ha uma autoridade separada de display cadence. Repeated present deve virar comportamento real, nao apenas hook.
### 5. Shutdown/current work
Quando houver uma submission em rasterizacao, shutdown e owner transition precisam impedir present obsoleto e terminar em tempo bounded.
### 6. Error model
Precisamos trocar o modelo infalivel/panic containment por erro tipado para render/present/worker failure.
### 7. Testes de concorrencia
Precisamos provar o contrato sem depender de janela nativa nem sleeps frageis.
## Opcoes
### Opcao A - Worker thread no runtime com backend mockavel
**Abordagem:** runtime cria um worker thread generico que recebe um backend implementando trait testavel.
**Pros:**
- testes de contrato mais diretos;
- menor dependencia do host desktop.
**Contras:**
- runtime passa a owns detalhes de thread;
- precisa cuidado para nao absorver politica de host/window.
**Manutenibilidade:** boa se o backend for limpo; ruim se virar acoplamento de host dentro do runtime.
### Opcao B - Worker thread no host desktop primeiro
**Abordagem:** implementar o primeiro worker no host winit/pixels e adaptar o runtime a submit/policy.
**Pros:**
- valida o caso real visual;
- encaixa com surface/present/winit.
**Contras:**
- mais dificil testar sem janela;
- risco de contrato ficar host-specific;
- portabilidade fica menos comprovada.
**Manutenibilidade:** boa para desktop, menos boa para hardware proprio.
### Opcao C - Worker controller runtime + backend host/HAL
**Abordagem:** criar um controller de worker que implementa handoff, stop token, epoch check e telemetry; o backend concreto vem de host/HAL e pode ser mockado em testes.
**Pros:**
- separa contrato de backend;
- testavel sem janela;
- mapeia para thread desktop, outro core ou fallback;
- preserva `RenderManager` como coordenador.
**Contras:**
- desenho inicial mais exigente;
- depende da preparacao da `AGD-0042`.
**Manutenibilidade:** melhor opcao se queremos worker real sem amarrar a winit.
## Sugestao / Recomendacao
Recomendo a **Opcao C - Worker controller runtime + backend host/HAL**.
O primeiro worker real deveria:
- consumir um handoff thread-safe single-slot;
- ter stop token e shutdown bounded;
- checar ownership/epoch antes de present;
- expor erros tipados;
- repetir o ultimo frame valido em cadence definida;
- sincronizar telemetry sem alterar semantica da VM;
- ter backend fake/mocked para testes de concorrencia.
O host desktop pode ser a primeira integracao concreta, mas nao deve ser o unico lugar onde o contrato e testado.
## Perguntas em Aberto
- [ ] O worker controller vive em `prometeu-system`, `prometeu-hal`, `prometeu-drivers`, ou host?
- [ ] O handoff thread-safe sera `Mutex<Option<...>>`, canal bounded, atomic slot, ou estrutura propria?
- [ ] Como modelar current work para shutdown e stale owner?
- [ ] Quem chama present: worker, host event loop, ou display cadence service?
- [ ] Como o worker recebe recursos read-only preparados na `AGD-0042`?
- [ ] Qual erro tipado minimo precisamos no primeiro worker?
- [ ] Como provar que a VM nao bloqueia quando o worker atrasa?
- [ ] Qual sera o primeiro backend real: desktop `Gfx`/pixels, framebuffer local, ou fake backend?
## Criterio para Encerrar
Esta agenda pode virar decision quando tivermos:
- local/camada do worker controller;
- estrutura thread-safe de handoff;
- trait/backend de render/present;
- present cadence/repeat;
- shutdown/current work;
- error model;
- test matrix de concorrencia;
- escopo do primeiro worker real.
## Discussion
- 2026-06-06: Agenda criada dentro da `DSC-0042` para separar worker real da preparacao de fronteira discutida em `AGD-0042`.
## Resolution