---
id: PLN-0112
ticket: real-render-worker-establishment
title: Define Render Worker Errors and Telemetry
status: open
created: 2026-06-15
completed:
ref_decisions: [DEC-0033]
tags: [runtime, renderer, worker, hal, telemetry]
---

## Briefing

`DEC-0033` requires typed worker/backend errors and telemetry that observes worker behavior without changing VM semantics.

## Decisions de Origem

- `DEC-0033`: Real Render Worker Contract.

## Alvo

Introduce the shared error and telemetry vocabulary required by the real worker.

## Escopo

- Define `RenderWorkerError` or equivalent shared error type.
- Define worker telemetry counters/snapshot shape.
- Integrate the new telemetry shape with existing render telemetry types where appropriate.
- Add tests for error/debug/copy/equality behavior and telemetry defaults.

## Fora de Escopo

- No worker lifecycle implementation.
- No thread-safe handoff.
- No host integration.

## Plano de Execucao

### Step 1 - Add worker error type

**What:** Define typed worker errors.
**How:** Add variants for backend unavailable, render failed, publish/present handoff failed, shutdown timeout, stale submission discarded, and worker panic/internal failure.
**File(s):** `crates/console/prometeu-hal/src/*` or `prometeu-system` if the type is not shared; prefer HAL if host/tests need it.

### Step 2 - Add telemetry snapshot

**What:** Define counters required by DEC-0033.
**How:** Include produced, replaced/dropped, consumed, published/presented, stale discarded, render failures, repeated frames, and shutdown timeouts.
**File(s):** existing telemetry/render manager modules or new worker telemetry module.

### Step 3 - Preserve existing telemetry compatibility

**What:** Avoid breaking existing render telemetry tests.
**How:** Map or extend current render telemetry without changing VM semantics or current counters unexpectedly.
**File(s):** `crates/console/prometeu-system/src/services/vm_runtime/render_manager.rs`, HAL telemetry modules as needed.

### Step 4 - Add tests

**What:** Pin type behavior.
**How:** Test default zero telemetry, counter increments through helper methods if added, and error formatting/debug behavior.
**File(s):** HAL/system tests.

## Criterios de Aceite

- [ ] Worker/backend failure has a typed error surface.
- [ ] Telemetry includes all DEC-0033 minimum counters.
- [ ] Existing render telemetry tests still pass.
- [ ] No worker/backend failure path relies on panic as the normal reporting model.

## Tests / Validacao

- `cargo test -p prometeu-hal -p prometeu-system`
- `rg "RenderWorkerError|shutdown_timeout|stale.*discard|repeat" crates/console -n`

## Riscos

- Splitting telemetry between too many structs may make final worker accounting inconsistent.
- Adding errors before call sites exist may create unused-code warnings if not scoped carefully.