79 lines
2.8 KiB
Markdown
79 lines
2.8 KiB
Markdown
---
|
|
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.
|