---
id: PLN-0115
ticket: real-render-worker-establishment
title: Implement Render Worker Controller Lifecycle
status: open
created: 2026-06-15
completed:
ref_decisions: [DEC-0033]
tags: [runtime, renderer, worker, lifecycle, concurrency]
---

## Briefing

`DEC-0033` requires a runtime-owned worker controller in `prometeu-system`, with stop signaling, bounded shutdown, pending/in-flight separation, typed errors, and telemetry.

## Decisions de Origem

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

## Alvo

Implement the production worker controller lifecycle around the handoff primitive and backend trait shape.

## Escopo

- Add worker controller type in `prometeu-system`.
- Spawn and join a worker thread.
- Add configurable shutdown timeout with initial default `250ms`.
- Add stop token/wakeup behavior.
- Preserve pending/in-flight separation.
- Capture panic as typed internal failure.

## Fora de Escopo

- No desktop host presentation.
- No full runtime tick integration.
- No stale epoch/repeat behavior beyond lifecycle foundations.

## Plano de Execucao

### Step 1 - Define controller and config

**What:** Add worker controller and configuration.
**How:** Include shutdown timeout, default `250ms`, and hooks for backend and handoff dependencies.
**File(s):** new `render_worker.rs` or similar in `prometeu-system`.

### Step 2 - Implement start and run loop

**What:** Start worker execution.
**How:** Spawn a thread that waits on the handoff, takes submissions, marks in-flight locally, calls backend, and publishes results through a frame sink abstraction.
**File(s):** worker controller module.

### Step 3 - Implement stop and bounded join

**What:** Make shutdown observable and bounded.
**How:** Signal stop, wake the condvar, join with timeout strategy available in Rust implementation, and return/report `ShutdownTimeout` when exceeded.
**File(s):** worker controller module.

### Step 4 - Add panic containment

**What:** Convert worker panic into typed failure.
**How:** Use panic containment around backend calls or worker thread join result and update telemetry/errors.
**File(s):** worker controller module.

### Step 5 - Add lifecycle tests

**What:** Prove start/stop/join behavior.
**How:** Use deterministic harness from `PLN-0114`.
**File(s):** worker tests.

## Criterios de Aceite

- [ ] Worker controller lives in `prometeu-system`.
- [ ] Controller can start and stop a real worker thread.
- [ ] Shutdown wakes waiting worker and completes within configured bound in tests.
- [ ] Shutdown timeout is typed and observable.
- [ ] Worker panic is captured as typed internal failure.

## Tests / Validacao

- `cargo test -p prometeu-system render_worker`
- `cargo test -p prometeu-system`

## Riscos

- Rust thread join timeout requires careful design because standard `JoinHandle::join` has no timeout.
- Backend ownership must be `'static + Send` without leaking host-specific types into system contracts.