prometeu-runtime/discussion/workflow/plans/PLN-0110-define-owned-rgba8888-frame-contract.md

id	ticket	title	status	created	completed	ref_decisions	tags
PLN-0110	real-render-worker-establishment	Define Owned RGBA8888 Frame Contract	done	2026-06-15		DEC-0033	runtime renderer worker hal frame-contract

Briefing

DEC-0033 requires the worker to publish an owned RGBA8888 frame that is independent of native window APIs. This plan defines that shared HAL contract before any worker implementation depends on it.

Decisions de Origem

• DEC-0033: Real Render Worker Contract.

Alvo

Introduce OwnedRgba8888Frame in prometeu-hal as the canonical worker-to-host published frame type.

Escopo

• Add the shared frame type to HAL.
• Include frame id, ownership/epoch metadata, dimensions, stride, and owned Vec<u32> RGBA8888 pixels.
• Add constructors and validation helpers that keep dimensions, stride, and pixel length coherent.
• Add unit tests for layout and validation.

Fora de Escopo

• No worker thread.
• No host upload/present integration.
• No resource bank access.
• No spec updates beyond code-facing rustdoc if useful.

Plano de Execucao

Step 1 - Add HAL frame module

What: Add OwnedRgba8888Frame. How: Create a HAL module, likely crates/console/prometeu-hal/src/owned_frame.rs or equivalent, and export it from lib.rs. File(s): crates/console/prometeu-hal/src/lib.rs, new HAL frame module.

Step 2 - Define required fields

What: Encode the DEC-0033 frame contract. How: Include FrameId, render ownership/epoch metadata compatible with RenderSubmission, width, height, stride_pixels, and pixels: Vec<u32>. File(s): HAL frame module, existing render ownership types if reuse is needed.

Step 3 - Add constructors and validation

What: Prevent malformed frame buffers from entering the worker-host boundary. How: Add checked constructor(s) that reject zero dimensions, too-small stride, and pixel buffers shorter than stride_pixels * height. File(s): HAL frame module.

Step 4 - Add tests

What: Pin layout semantics. How: Test valid construction, invalid stride, invalid pixel length, and that raw pixel values are preserved as RGBA8888 u32. File(s): HAL frame module tests.

Criterios de Aceite

• OwnedRgba8888Frame is exported by prometeu-hal.
• The type contains FrameId, ownership/epoch, width, height, stride_pixels, and Vec<u32> pixels.
• Invalid dimensions/stride/pixel length cannot be silently accepted by checked constructors.
• No native host/window/pixels/winit/SDL type appears in the HAL frame contract.

Tests / Validacao

• cargo test -p prometeu-hal
• rg "OwnedRgba8888Frame" crates/console/prometeu-hal -n

Riscos

• Reusing native pixel terminology could blur the logical RGBA8888 contract.
• Overfitting the frame type to current desktop upload code would leak host details into HAL.