prometeu-runtime/discussion/workflow/agendas/AGD-0042-real-render-worker-establishment.md

id	ticket	title	status	created	resolved	decision	tags
AGD-0042	real-render-worker-establishment	Real Render Worker Establishment	open	2026-06-06			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