---
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