prometeu-runtime/discussion/workflow/plans/PLN-0115-implement-render-worker-controller-lifecycle.md

id	ticket	title	status	created	completed	ref_decisions	tags
PLN-0115	real-render-worker-establishment	Implement Render Worker Controller Lifecycle	done	2026-06-15		DEC-0033	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.