Real Render Worker Establishment
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
This commit is contained in:
@@ -1,191 +0,0 @@
|
||||
---
|
||||
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,241 +0,0 @@
|
||||
---
|
||||
id: AGD-0043
|
||||
ticket: real-render-worker-establishment
|
||||
title: Real Render Worker Establishment
|
||||
status: accepted
|
||||
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` preparou 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 ja foi resolvida antes da execucao.
|
||||
|
||||
### Estado Atual Depois da `AGD-0042`
|
||||
|
||||
A preparacao de fronteira foi executada pelos planos `PLN-0098` a `PLN-0109`:
|
||||
|
||||
- `HardwareBridge` foi removido do codigo e deixou de ser contrato publico;
|
||||
- `RuntimePlatform` passou a ser a fronteira runtime-facing para render, input, audio, assets e telemetry;
|
||||
- `RenderSubmissionSink` aceita submissao owned;
|
||||
- `Game2DFrameComposer` separa fechamento logico de frame do backend de render;
|
||||
- syscalls `gfx2d.*` e `gfxui.*` bufferizam comandos e nao desenham imediatamente via `Gfx`;
|
||||
- firmware, Hub, runtime e host desktop passam por servicos de plataforma;
|
||||
- testes de runtime/firmware usam `TestPlatform` como fixture local;
|
||||
- specs de GFX/portabilidade documentam que o worker/render consumer nao deve depender de `&mut Hardware`, `&mut Gfx`, `FrameComposer` vivo ou estado mutavel da VM.
|
||||
|
||||
O estado atual ainda nao tem worker real. O `LocalRenderWorker` continua sendo o caminho local/cooperativo que consome `RenderSubmission` no mesmo processo. O proximo passo desta agenda e decidir onde vive o controller do worker real, qual handoff thread-safe ele usa, e qual backend renderizavel ele owns ou recebe.
|
||||
|
||||
## 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
|
||||
|
||||
### 1. Onde vive o worker controller?
|
||||
|
||||
**Pergunta:** O worker controller vive em `prometeu-system`, `prometeu-hal`, `prometeu-drivers`, ou host?
|
||||
|
||||
**Sugestao:** colocar o controller contratual em `prometeu-system`, proximo de `RenderManager`, e manter traits pequenas em `prometeu-hal` quando forem superficie compartilhada. `prometeu-drivers` deve continuar oferecendo implementacoes locais/testaveis; host desktop deve integrar o controller, nao definir o contrato.
|
||||
|
||||
**Motivo:** o `RenderManager` ja owns policy de AppMode, ownership/epoch, latest-wins e telemetry. Se o controller nascer apenas no host, a semantica de worker vira desktop-specific e fica mais dificil provar o contrato sem janela nativa.
|
||||
|
||||
### 2. Qual handoff thread-safe usar?
|
||||
|
||||
**Pergunta:** O handoff thread-safe sera `Mutex<Option<...>>`, canal bounded, atomic slot, ou estrutura propria?
|
||||
|
||||
**Sugestao:** comecar com uma estrutura propria simples baseada em `Mutex<Option<RenderSubmission>> + Condvar`, encapsulada como single-slot latest-wins. O produtor substitui a pending submission sem bloquear em rasterizacao; o consumidor espera por nova submission ou shutdown.
|
||||
|
||||
**Motivo:** canal bounded tende a preservar historico ou bloquear produtor se nao for usado com cuidado. Um slot explicito modela diretamente a regra ja aceita: nao existe fila crescente, a ultima submissao completa vence.
|
||||
|
||||
### 3. Como modelar current work, shutdown e stale owner?
|
||||
|
||||
**Pergunta:** Como modelar current work para shutdown e stale owner?
|
||||
|
||||
**Sugestao:** separar `pending` de `in_flight`. Ao tomar uma submission, o worker carimba `in_flight` localmente, renderiza, e checa ownership/epoch contra um snapshot atomico ou handle compartilhado antes de present. Shutdown sinaliza stop, acorda o worker e faz join bounded; se houver trabalho em andamento, ele pode terminar rasterizacao, mas nao pode apresentar se o owner/epoch estiver obsoleto ou o stop ja exigir descarte. O timeout deve ser configuravel; como default inicial, usar `250ms`, que e longo o bastante para evitar falso positivo em desktop comum e curto o bastante para detectar worker preso sem travar encerramento.
|
||||
|
||||
**Motivo:** isso evita que shutdown dependa de cancelar mid-raster em codigo que talvez nao seja cancelavel, mas ainda impede present obsoleto.
|
||||
|
||||
### 4. Quem chama present?
|
||||
|
||||
**Pergunta:** Quem chama present: worker, host event loop, ou display cadence service?
|
||||
|
||||
**Sugestao:** no primeiro corte, o worker deve produzir/publish uma superficie pronta como buffer RGBA8888 owned, por exemplo `OwnedRgba8888Frame`, definido em `prometeu-hal`. O host event loop continua sendo autoridade de apresentacao da janela nativa. O "repeat ultimo frame valido" deve repetir o ultimo buffer publicado, nao recompor nem exigir que o worker conheca a API nativa de janela/swap.
|
||||
|
||||
**Motivo:** RGBA8888 ja e o formato logico canonico nas specs. Um frame owned com `FrameId`, ownership/epoch, largura, altura, `stride_pixels` e pixels RGBA8888 em `Vec<u32>` deixa o contrato testavel sem janela e evita acoplamento a winit/pixels, SDL, swapchain ou textura nativa. Colocar o swap real dentro do worker pode funcionar em alguns hosts e quebrar portabilidade. O contrato importante e que a VM nao bloqueie e que o host tenha uma superficie publicada coerente.
|
||||
|
||||
### 5. Como o worker recebe recursos read-only?
|
||||
|
||||
**Pergunta:** Como o worker recebe recursos read-only preparados na `AGD-0042`?
|
||||
|
||||
**Sugestao:** o primeiro backend deve receber `RenderSubmission` owned e uma interface compacta de acesso read-only aos banks por id. Banks sao read-only por definicao durante o consumo de render; o worker resolve recursos por ids estaveis, sem copiar bank, sem snapshot de bank e sem depender de `Arc` como requisito do contrato.
|
||||
|
||||
**Motivo:** `AGD-0042` eliminou o bridge monolitico exatamente para impedir que o worker dependa do hardware inteiro. A proxima decisao precisa declarar quais recursos sao lidos pelo render backend e como sua estabilidade e garantida durante uma submissao em voo. A estabilidade vem da regra de leitura: o worker ve banks por id via interface read-only, enquanto instalacao/mutacao de bank permanece fora do consumo renderizavel em voo.
|
||||
|
||||
### 6. Qual erro tipado minimo?
|
||||
|
||||
**Pergunta:** Qual erro tipado minimo precisamos no primeiro worker?
|
||||
|
||||
**Sugestao:** introduzir um erro pequeno, por exemplo `RenderWorkerError`, cobrindo pelo menos: backend unavailable, render failed, present/publish failed, shutdown timeout, stale submission discarded. Panics continuam sendo capturados como falha interna, mas nao devem ser o modelo operacional normal.
|
||||
|
||||
**Motivo:** `LocalRenderWorker` hoje prova policy, mas nao diferencia falhas reais de render/present. O worker real precisa reportar falhas sem contaminar a VM com detalhes de host.
|
||||
|
||||
### 7. Como provar que a VM nao bloqueia?
|
||||
|
||||
**Pergunta:** Como provar que a VM nao bloqueia quando o worker atrasa?
|
||||
|
||||
**Sugestao:** criar testes deterministas com backend fake controlado por barreiras/condvars, nao sleeps. O teste deve segurar o worker em rasterizacao, produzir frames adicionais no runtime, verificar substituicao latest-wins/drop telemetry, e provar que o tick da VM retorna sem esperar o consumo terminar.
|
||||
|
||||
**Motivo:** sleeps tornam teste de concorrencia fragil. Barreiras permitem provar especificamente a propriedade desejada: produtor nao bloqueia em raster/present lento.
|
||||
|
||||
### 8. Qual primeiro backend real?
|
||||
|
||||
**Pergunta:** Qual sera o primeiro backend real: desktop `Gfx`/pixels, framebuffer local, ou fake backend?
|
||||
|
||||
**Sugestao:** implementar primeiro um backend fake/mocked para contrato e um backend local framebuffer para integracao sem janela. A integracao desktop vem em seguida como consumidor concreto, usando a mesma trait. Ao final desta agenda, o worker deve estar funcionando completamente no caminho host real; a divisao em planos serve para controlar risco, nao para reduzir o alvo final.
|
||||
|
||||
**Motivo:** se o primeiro backend for desktop/winit, o contrato corre risco de nascer acoplado a detalhes de janela. Se o primeiro for fake/local, a semantica do worker fica testavel antes da integracao visual. Ainda assim, a agenda so deve ser considerada concluida quando a integracao host real tambem estiver operando sobre o worker.
|
||||
|
||||
## 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`.
|
||||
- 2026-06-15: Apos a conclusao dos planos `PLN-0098` a `PLN-0109`, a direcao da agenda foi alinhada em torno da Opcao C: controller em `prometeu-system`, handoff single-slot thread-safe, backend fake/local primeiro, e publicacao de frame owned RGBA8888 antes da integracao desktop concreta.
|
||||
- 2026-06-15: Perguntas restantes alinhadas: `OwnedRgba8888Frame` deve viver em `prometeu-hal` com pixels `Vec<u32>` RGBA8888; banks sao acessados por interface compacta read-only via ids, sem copia/snapshot/`Arc` como contrato; shutdown deve ter timeout configuravel com default inicial sugerido de `250ms`; a agenda pode virar varios plans, mas so fecha quando o worker funcionar no host real.
|
||||
|
||||
## Resolution
|
||||
|
||||
Direcao proposta para decisao:
|
||||
|
||||
- `RenderManager` continua como autoridade de policy, ownership/epoch, latest-wins e telemetry;
|
||||
- o worker controller contratual deve viver em `prometeu-system`;
|
||||
- traits compartilhadas minimas podem viver em `prometeu-hal`;
|
||||
- o handoff real deve ser single-slot latest-wins com sincronizacao explicita, inicialmente `Mutex<Option<RenderSubmission>> + Condvar`;
|
||||
- o worker separa `pending` de `in_flight` e checa stop/ownership/epoch antes de publicar;
|
||||
- shutdown deve ser bounded e configuravel; default inicial sugerido: `250ms`;
|
||||
- o worker publica um `OwnedRgba8888Frame` em `prometeu-hal`, contendo frame id, owner/epoch, dimensoes, `stride_pixels` e pixels RGBA8888 owned em `Vec<u32>`;
|
||||
- o worker acessa banks por ids estaveis atraves de uma interface compacta read-only; nao copia banks, nao depende de snapshots de bank e nao usa `Arc` como parte obrigatoria do contrato;
|
||||
- o host event loop faz o upload/present nativo a partir do ultimo frame publicado;
|
||||
- o primeiro backend deve ser fake/local para provar contrato e concorrencia sem janela;
|
||||
- a integracao desktop concreta vem depois, usando a mesma trait/backend contract;
|
||||
- a agenda pode ser executada em varios plans, mas o criterio final e ter o worker funcionando completamente no host real;
|
||||
- testes devem usar barreiras/condvars para provar ausencia de bloqueio da VM, latest-wins, stale discard, shutdown bounded e telemetry.
|
||||
Reference in New Issue
Block a user