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

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