---
id: PLN-0110
ticket: real-render-worker-establishment
title: Define Owned RGBA8888 Frame Contract
status: done
created: 2026-06-15
completed:
ref_decisions: [DEC-0033]
tags: [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.