add real render worker implementation plans

discussion/workflow/decisions/DEC-0033-real-render-worker-contract.md

@@ -6,7 +6,7 @@ status: accepted
 created: 2026-06-15
 accepted:
 agenda: AGD-0043
-plans: []
+plans: [PLN-0110, PLN-0111, PLN-0112, PLN-0113, PLN-0114, PLN-0115, PLN-0116, PLN-0117, PLN-0118, PLN-0119, PLN-0120, PLN-0121]
 tags: [runtime, renderer, worker, concurrency, host, hal, architecture]
 ---
 

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

@@ -0,0 +1,79 @@
+---
+id: PLN-0110
+ticket: real-render-worker-establishment
+title: Define Owned RGBA8888 Frame Contract
+status: open
+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.

discussion/workflow/plans/PLN-0111-define-read-only-render-resource-access.md

@@ -0,0 +1,79 @@
+---
+id: PLN-0111
+ticket: real-render-worker-establishment
+title: Define Read-Only Render Resource Access
+status: open
+created: 2026-06-15
+completed:
+ref_decisions: [DEC-0033]
+tags: [runtime, renderer, worker, hal, resources]
+---
+
+## Briefing
+
+`DEC-0033` requires the worker backend to resolve render resources by stable ids through compact read-only access, without copying banks, snapshotting banks, requiring `Arc` in the public contract, or accessing mutable `Hardware`/`Gfx`/`FrameComposer`.
+
+## Decisions de Origem
+
+- `DEC-0033`: Real Render Worker Contract.
+
+## Alvo
+
+Define shared read-only render resource traits in HAL and implement them over existing local bank storage without changing bank ownership semantics.
+
+## Escopo
+
+- Define compact HAL traits for read-only glyph and scene bank access by id.
+- Keep the public contract id-based and read-only.
+- Implement the traits in the local driver/resource owner currently used by rendering.
+- Add tests proving banks are read through the new interface.
+
+## Fora de Escopo
+
+- No worker thread.
+- No bank copying or snapshotting.
+- No public `Arc` requirement.
+- No asset residency policy changes.
+
+## Plano de Execucao
+
+### Step 1 - Define HAL read-only traits
+
+**What:** Add worker-facing resource access contracts.
+**How:** Define traits for resolving glyph and scene banks by stable ids. Return borrowed read-only references or compact read-only views, not mutable handles.
+**File(s):** `crates/console/prometeu-hal/src/*`, likely a new render resource module.
+
+### Step 2 - Implement local resource access
+
+**What:** Expose current local bank storage through the new traits.
+**How:** Implement the read-only traits for the existing memory bank/resource owner used by `prometeu-drivers`.
+**File(s):** `crates/console/prometeu-drivers/src/memory_banks.rs`, `frame_composer.rs`, or adjacent resource modules.
+
+### Step 3 - Thread access through backend-facing APIs
+
+**What:** Make future backends able to receive resource access without `Hardware`.
+**How:** Add narrow parameters/types where needed so a backend can be given read-only resources independently from the full platform.
+**File(s):** HAL contracts and driver modules touched above.
+
+### Step 4 - Add resource access tests
+
+**What:** Prove id lookup and read-only behavior.
+**How:** Add tests for resident/missing glyph and scene banks through the new traits and verify no mutable API is exposed.
+**File(s):** HAL/driver tests.
+
+## Criterios de Aceite
+
+- [ ] Worker-facing render resource access is defined in `prometeu-hal`.
+- [ ] Resource access is by stable id and read-only.
+- [ ] The public contract does not require `Arc`, bank copies, bank snapshots, `Hardware`, `Gfx`, or `FrameComposer`.
+- [ ] Local driver storage implements the traits.
+
+## Tests / Validacao
+
+- `cargo test -p prometeu-hal -p prometeu-drivers`
+- `rg "Arc<.*RenderResource|snapshot.*bank|&mut Hardware|&mut Gfx|FrameComposer" crates/console/prometeu-hal crates/console/prometeu-drivers -n`
+
+## Riscos
+
+- Returning concrete bank internals may overexpose driver implementation.
+- Accidentally requiring `Arc` in the trait would make a storage strategy part of the public contract.

discussion/workflow/plans/PLN-0112-define-render-worker-errors-and-telemetry.md

@@ -0,0 +1,78 @@
+---
+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.

discussion/workflow/plans/PLN-0113-implement-thread-safe-latest-wins-handoff.md

@@ -0,0 +1,80 @@
+---
+id: PLN-0113
+ticket: real-render-worker-establishment
+title: Implement Thread-Safe Latest-Wins Handoff
+status: open
+created: 2026-06-15
+completed:
+ref_decisions: [DEC-0033]
+tags: [runtime, renderer, worker, concurrency, handoff]
+---
+
+## Briefing
+
+`DEC-0033` requires a thread-safe single-slot latest-wins handoff. The producer must replace pending work without waiting for rasterization or present, and the consumer must take ownership of the latest pending submission.
+
+## Decisions de Origem
+
+- `DEC-0033`: Real Render Worker Contract.
+
+## Alvo
+
+Add the real worker handoff primitive in `prometeu-system`, using explicit synchronization and deterministic tests.
+
+## Escopo
+
+- Implement a single-slot pending submission structure.
+- Use `Mutex<Option<RenderSubmission>> + Condvar` or an equivalent explicit structure.
+- Add producer publish/replace behavior and consumer wait/take behavior.
+- Track replacement/drop telemetry.
+
+## Fora de Escopo
+
+- No worker thread controller lifecycle.
+- No backend rendering.
+- No host integration.
+- No stale epoch publish behavior beyond storing ownership data already present in submissions.
+
+## Plano de Execucao
+
+### Step 1 - Add handoff module
+
+**What:** Create the worker handoff primitive.
+**How:** Add a module under `crates/console/prometeu-system/src/services/vm_runtime/`, for example `render_worker_handoff.rs`.
+**File(s):** new system module, `mod.rs` exports.
+
+### Step 2 - Implement publish replacement
+
+**What:** Producer publishes owned `RenderSubmission`.
+**How:** Lock the slot, replace any pending submission, increment replacement/drop counters when applicable, notify the condvar, and return immediately.
+**File(s):** handoff module.
+
+### Step 3 - Implement consumer wait/take
+
+**What:** Consumer waits for work or shutdown signal.
+**How:** Add wait/take APIs that block only the consumer side and return owned submissions.
+**File(s):** handoff module.
+
+### Step 4 - Add deterministic tests
+
+**What:** Prove latest-wins and blocking boundaries.
+**How:** Use threads, barriers, and condvars to prove producer replacement and consumer wake behavior without sleeps.
+**File(s):** handoff module tests or `async_render_contract_tests.rs`.
+
+## Criterios de Aceite
+
+- [ ] Producer publish does not wait for consumer rasterization.
+- [ ] Multiple pending publishes leave only the newest submission available.
+- [ ] Replacements increment telemetry.
+- [ ] Consumer can wait for work and is woken by publish.
+- [ ] Tests do not use sleep as their primary synchronization proof.
+
+## Tests / Validacao
+
+- `cargo test -p prometeu-system render_worker_handoff`
+- `cargo test -p prometeu-system`
+
+## Riscos
+
+- Holding the mutex while doing heavy work would violate non-blocking producer behavior.
+- Condvar wait loops must handle spurious wakeups.

discussion/workflow/plans/PLN-0114-add-deterministic-render-worker-test-harness.md

@@ -0,0 +1,78 @@
+---
+id: PLN-0114
+ticket: real-render-worker-establishment
+title: Add Deterministic Render Worker Test Harness
+status: open
+created: 2026-06-15
+completed:
+ref_decisions: [DEC-0033]
+tags: [runtime, renderer, worker, tests, concurrency]
+---
+
+## Briefing
+
+`DEC-0033` requires worker behavior to be proven without a native window and without fragile sleeps. This plan creates reusable deterministic test fixtures for the remaining worker plans.
+
+## Decisions de Origem
+
+- `DEC-0033`: Real Render Worker Contract.
+
+## Alvo
+
+Add a fake backend and synchronization harness capable of blocking render at controlled points, observing publication, and proving non-blocking VM/producer behavior.
+
+## Escopo
+
+- Create test-only synchronization helpers using barriers/condvars.
+- Create a fake render backend shape that can block/fail/publish deterministically.
+- Add helper functions for constructing owned render submissions and frames.
+- Reuse the harness in later worker tests.
+
+## Fora de Escopo
+
+- No production worker lifecycle.
+- No desktop host integration.
+- No real GFX rasterization.
+
+## Plano de Execucao
+
+### Step 1 - Add test support module
+
+**What:** Introduce deterministic worker test fixtures.
+**How:** Add test-only helpers under `prometeu-system` worker tests or a local test module.
+**File(s):** `crates/console/prometeu-system/src/services/vm_runtime/*`.
+
+### Step 2 - Add controllable fake backend
+
+**What:** Provide backend behavior for tests.
+**How:** Fake backend can block at render start, unblock by test signal, return errors, and record published frames.
+**File(s):** worker test module.
+
+### Step 3 - Add submission/frame builders
+
+**What:** Make tests concise and consistent.
+**How:** Build Game/Shell submissions with explicit frame ids and ownership metadata; build `OwnedRgba8888Frame` fixtures.
+**File(s):** worker test module.
+
+### Step 4 - Add initial harness self-tests
+
+**What:** Prove harness itself is deterministic.
+**How:** Verify a test can block and release backend render without timing sleeps.
+**File(s):** worker test module.
+
+## Criterios de Aceite
+
+- [ ] Tests can block worker backend render using deterministic synchronization.
+- [ ] Tests can observe published `OwnedRgba8888Frame` values.
+- [ ] Harness can inject backend errors.
+- [ ] Harness helpers are scoped to tests or clearly internal.
+
+## Tests / Validacao
+
+- `cargo test -p prometeu-system render_worker`
+- `rg "sleep\\(|thread::sleep" crates/console/prometeu-system/src/services/vm_runtime -n`
+
+## Riscos
+
+- Test harness code can become too coupled to implementation internals.
+- Overly broad helpers can hide important assertions in later plans.

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

@@ -0,0 +1,87 @@
+---
+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.

discussion/workflow/plans/PLN-0116-implement-fake-local-render-backend.md

@@ -0,0 +1,78 @@
+---
+id: PLN-0116
+ticket: real-render-worker-establishment
+title: Implement Fake Local Render Backend
+status: open
+created: 2026-06-15
+completed:
+ref_decisions: [DEC-0033]
+tags: [runtime, renderer, worker, backend, drivers]
+---
+
+## Briefing
+
+`DEC-0033` requires fake/local backend behavior before desktop integration so worker semantics can be proven without a window.
+
+## Decisions de Origem
+
+- `DEC-0033`: Real Render Worker Contract.
+
+## Alvo
+
+Implement backend contracts that consume `RenderSubmission` plus read-only resources and produce `OwnedRgba8888Frame`.
+
+## Escopo
+
+- Define or finalize a backend trait for worker rendering.
+- Add a fake backend for deterministic tests.
+- Add a local framebuffer backend that can rasterize through existing driver/GFX logic without exposing mutable `Hardware` as the worker contract.
+- Verify output frame ownership and pixels.
+
+## Fora de Escopo
+
+- No desktop upload/present.
+- No runtime tick integration.
+- No resource mutation policy changes.
+
+## Plano de Execucao
+
+### Step 1 - Define backend trait
+
+**What:** Encode backend consumption contract.
+**How:** Trait consumes `RenderSubmission` and read-only resource access and returns `OwnedRgba8888Frame` or `RenderWorkerError`.
+**File(s):** HAL if shared, or system if internal; prefer HAL if host/drivers implement it.
+
+### Step 2 - Implement fake backend
+
+**What:** Provide test backend.
+**How:** Fake backend returns deterministic frames, can block through harness, and can return typed errors.
+**File(s):** system test module or driver test utility.
+
+### Step 3 - Implement local framebuffer backend
+
+**What:** Provide non-window raster backend.
+**How:** Use existing GFX rendering internally to turn submissions into `OwnedRgba8888Frame`, but expose only the backend trait and read-only resources.
+**File(s):** `prometeu-drivers` rendering modules, possibly a new backend module.
+
+### Step 4 - Add output tests
+
+**What:** Prove frame content and metadata.
+**How:** Render simple Game2D and ShellUi submissions and compare `OwnedRgba8888Frame` pixels/metadata.
+**File(s):** driver/system tests.
+
+## Criterios de Aceite
+
+- [ ] Backend trait does not expose mutable `Hardware`, `Gfx`, `FrameComposer`, or VM state.
+- [ ] Fake backend supports deterministic blocking/error behavior.
+- [ ] Local backend produces `OwnedRgba8888Frame`.
+- [ ] Game2D and ShellUi submissions can produce frame output without a native window.
+
+## Tests / Validacao
+
+- `cargo test -p prometeu-drivers -p prometeu-system`
+- `rg "&mut Hardware|&mut Gfx|FrameComposer" crates/console/prometeu-hal crates/console/prometeu-system/src/services/vm_runtime -n`
+
+## Riscos
+
+- Local backend may be tempted to reuse `Hardware` directly as the public worker contract.
+- Resource access gaps may surface when moving from fake to local rasterization.

discussion/workflow/plans/PLN-0117-integrate-runtime-submission-with-worker.md

@@ -0,0 +1,80 @@
+---
+id: PLN-0117
+ticket: real-render-worker-establishment
+title: Integrate Runtime Submission With Worker
+status: open
+created: 2026-06-15
+completed:
+ref_decisions: [DEC-0033]
+tags: [runtime, renderer, worker, integration]
+---
+
+## Briefing
+
+`DEC-0033` requires VM/render production to submit work without blocking on worker consumption. This plan connects runtime frame closure to the worker handoff while preserving local synchronous fallback.
+
+## Decisions de Origem
+
+- `DEC-0033`: Real Render Worker Contract.
+
+## Alvo
+
+Route eligible Game render submissions from `RenderManager` into the real worker handoff and keep Shell/local paths correct.
+
+## Escopo
+
+- Add worker-capable runtime path.
+- Submit owned `RenderSubmission` to the handoff.
+- Preserve AppMode policy: Game may use worker; Shell remains local unless a future decision changes it.
+- Keep local synchronous fallback.
+- Prove VM tick returns without waiting for worker backend completion.
+
+## Fora de Escopo
+
+- No desktop host presentation.
+- No final stale/repeat behavior beyond integration needed for basic worker use.
+- No spec edits.
+
+## Plano de Execucao
+
+### Step 1 - Add worker ownership to runtime state
+
+**What:** Store worker controller/handoff in runtime-owned state.
+**How:** Extend `VirtualMachineRuntime` or `RenderManager` integration points without moving policy to host.
+**File(s):** `crates/console/prometeu-system/src/services/vm_runtime/tick.rs`, `render_manager.rs`, worker modules.
+
+### Step 2 - Submit Game frames to worker handoff
+
+**What:** Replace local worker prototype path with real worker submission.
+**How:** On eligible Game frame closure, publish owned `RenderSubmission` into the handoff and return to VM tick without waiting for consumption.
+**File(s):** runtime tick/render manager integration.
+
+### Step 3 - Preserve local fallback
+
+**What:** Keep current local synchronous behavior available.
+**How:** Use existing `RenderConsumerPath`/policy or update it to select local fallback when worker is disabled/unavailable.
+**File(s):** `render_manager.rs`, `tick.rs`.
+
+### Step 4 - Add non-blocking tests
+
+**What:** Prove VM producer does not block.
+**How:** Use harness to hold backend render, run tick/publish additional frames, assert return and replacement telemetry.
+**File(s):** runtime worker tests.
+
+## Criterios de Aceite
+
+- [ ] Game render submissions can be sent to the real worker handoff.
+- [ ] VM tick does not wait for worker rasterization.
+- [ ] Shell/local policy remains unchanged.
+- [ ] Local synchronous fallback still passes existing tests.
+- [ ] Replacement telemetry increments when producer outruns worker.
+
+## Tests / Validacao
+
+- `cargo test -p prometeu-system`
+- `cargo test -p prometeu-firmware`
+
+## Riscos
+
+- Accidentally making frame closure wait for worker consumption would violate DEC-0033.
+- Mixing Shell lifecycle rendering into the worker path too early would broaden scope.

discussion/workflow/plans/PLN-0118-add-stale-epoch-and-repeat-frame-behavior.md

@@ -0,0 +1,85 @@
+---
+id: PLN-0118
+ticket: real-render-worker-establishment
+title: Add Stale Epoch and Repeat Frame Behavior
+status: open
+created: 2026-06-15
+completed:
+ref_decisions: [DEC-0033]
+tags: [runtime, renderer, worker, ownership, telemetry]
+---
+
+## Briefing
+
+`DEC-0033` requires the worker to discard stale in-flight frames before publication and repeat the last published `OwnedRgba8888Frame` rather than recomposing.
+
+## Decisions de Origem
+
+- `DEC-0033`: Real Render Worker Contract.
+
+## Alvo
+
+Complete ownership/epoch checks and repeat-last-published-frame behavior for the worker path.
+
+## Escopo
+
+- Add shared active ownership/epoch observation for worker publication checks.
+- Discard stale in-flight frames before publication.
+- Store and expose the latest published `OwnedRgba8888Frame`.
+- Implement repeat-last-frame behavior and telemetry.
+
+## Fora de Escopo
+
+- No desktop upload/present.
+- No new AppMode policy.
+- No native window invalidation changes.
+
+## Plano de Execucao
+
+### Step 1 - Expose ownership/epoch to worker
+
+**What:** Let worker validate in-flight submissions before publishing.
+**How:** Add a thread-safe snapshot or handle that the worker can read without mutating runtime state.
+**File(s):** `render_manager.rs`, worker modules.
+
+### Step 2 - Implement stale discard
+
+**What:** Prevent stale pixels from publication.
+**How:** Before publishing frame output, compare submission ownership/epoch with active ownership/epoch; discard on mismatch and increment telemetry.
+**File(s):** worker controller module.
+
+### Step 3 - Store latest published frame
+
+**What:** Make the latest valid frame available to host/fallback tests.
+**How:** Add a published-frame slot distinct from pending submission and in-flight work.
+**File(s):** worker controller or published frame module.
+
+### Step 4 - Implement repeat behavior
+
+**What:** Repeat last valid frame without recomposition.
+**How:** Add API to fetch/reuse the latest published `OwnedRgba8888Frame`; increment repeat telemetry when cadence requests reuse.
+**File(s):** worker modules, tests.
+
+### Step 5 - Add tests
+
+**What:** Prove stale discard and repeat.
+**How:** Use harness to hold in-flight work, change owner/epoch, release backend, and assert no publication; separately assert repeat returns last frame.
+**File(s):** worker tests.
+
+## Criterios de Aceite
+
+- [ ] Worker checks active owner/epoch before publishing.
+- [ ] Stale in-flight frames are discarded and counted.
+- [ ] Latest published frame is an `OwnedRgba8888Frame`.
+- [ ] Repeat uses the last published frame and does not recompose.
+- [ ] Tests cover stale discard and repeat deterministically.
+
+## Tests / Validacao
+
+- `cargo test -p prometeu-system render_worker`
+- `cargo test -p prometeu-system`
+
+## Riscos
+
+- Reading active ownership from the wrong layer may reintroduce mutable runtime coupling.
+- Repeat behavior must not hide render failures unless telemetry records them.

discussion/workflow/plans/PLN-0119-integrate-desktop-host-worker-presentation.md

@@ -0,0 +1,81 @@
+---
+id: PLN-0119
+ticket: real-render-worker-establishment
+title: Integrate Desktop Host Worker Presentation
+status: open
+created: 2026-06-15
+completed:
+ref_decisions: [DEC-0033]
+tags: [runtime, renderer, worker, host, desktop]
+---
+
+## Briefing
+
+`DEC-0033` is not complete until the real host path uses the worker. This plan integrates desktop presentation with the latest published `OwnedRgba8888Frame` while keeping native upload/present in the host event loop.
+
+## Decisions de Origem
+
+- `DEC-0033`: Real Render Worker Contract.
+
+## Alvo
+
+Make `prometeu-host-desktop-winit` present frames produced by the worker path.
+
+## Escopo
+
+- Wire the host to enable/use the worker path.
+- Read the latest published `OwnedRgba8888Frame`.
+- Upload/copy RGBA8888 pixels to the existing pixels/winit presentation surface in the event loop.
+- Preserve host invalidation and redraw behavior.
+- Keep worker free of native window dependencies.
+
+## Fora de Escopo
+
+- No SDL migration.
+- No change to logical pixel format.
+- No change to input/audio/filesystem host behavior.
+
+## Plano de Execucao
+
+### Step 1 - Add host access to published frame
+
+**What:** Expose latest worker-published frame to desktop host.
+**How:** Add an API through runtime/platform integration that returns or copies the latest `OwnedRgba8888Frame` for host upload.
+**File(s):** system worker modules, host runner integration.
+
+### Step 2 - Upload RGBA8888 in event loop
+
+**What:** Present worker output through existing host surface.
+**How:** Convert/copy `Vec<u32>` RGBA8888 into the existing pixels frame buffer using existing RGBA8888 utility conventions.
+**File(s):** `crates/host/prometeu-host-desktop-winit/src/runner.rs`, `utilities.rs` if needed.
+
+### Step 3 - Preserve invalidation model
+
+**What:** Keep host redraw policy coherent.
+**How:** Trigger redraw when a new frame is published or host invalidation occurs; repeat uses the last published frame.
+**File(s):** host runner/presentation state.
+
+### Step 4 - Add host tests
+
+**What:** Prove host consumes worker-published frame.
+**How:** Add unit tests for RGBA8888 copy/upload helper and presentation state transitions without opening a native window.
+**File(s):** host tests.
+
+## Criterios de Aceite
+
+- [ ] Desktop host presents the latest worker-published `OwnedRgba8888Frame`.
+- [ ] Worker code does not import winit, pixels, SDL, swapchain, native texture, or window APIs.
+- [ ] Host event loop remains responsible for native present.
+- [ ] Existing host invalidation tests still pass.
+- [ ] Real host path can run with worker enabled.
+
+## Tests / Validacao
+
+- `cargo test -p prometeu-host-desktop-winit`
+- `cargo test -p prometeu-system -p prometeu-firmware`
+- Manual run of a simple cartridge through desktop host with worker path enabled.
+
+## Riscos
+
+- Upload/copy can accidentally reinterpret RGBA8888 as native endian bytes.
+- Host redraw policy can regress into perpetual polling if publication/invalidation are not kept separate.

discussion/workflow/plans/PLN-0120-update-real-render-worker-specs.md

@@ -0,0 +1,79 @@
+---
+id: PLN-0120
+ticket: real-render-worker-establishment
+title: Update Real Render Worker Specs
+status: open
+created: 2026-06-15
+completed:
+ref_decisions: [DEC-0033]
+tags: [runtime, renderer, worker, specs]
+---
+
+## Briefing
+
+`DEC-0033` requires canonical runtime specs to document the real worker contract after implementation publishes the behavior.
+
+## Decisions de Origem
+
+- `DEC-0033`: Real Render Worker Contract.
+
+## Alvo
+
+Update English canonical specs to describe `OwnedRgba8888Frame`, worker handoff, host presentation split, read-only bank access, shutdown, errors, and telemetry.
+
+## Escopo
+
+- Update GFX/render specs.
+- Update portability/host presentation specs.
+- Update host ABI/syscall specs if worker behavior affects published runtime surfaces.
+- Ensure no spec says the worker owns native window present.
+
+## Fora de Escopo
+
+- No new architecture beyond `DEC-0033`.
+- No lesson writing.
+- No implementation changes except documentation.
+
+## Plano de Execucao
+
+### Step 1 - Update GFX spec
+
+**What:** Document worker frame publication.
+**How:** Add `OwnedRgba8888Frame`, RGBA8888 `Vec<u32>` semantics, latest published frame, and repeat behavior.
+**File(s):** `docs/specs/runtime/04-gfx-peripheral.md`.
+
+### Step 2 - Update portability spec
+
+**What:** Document worker/host split.
+**How:** State that worker produces owned RGBA8888 frames and host event loop performs native upload/present.
+**File(s):** `docs/specs/runtime/11-portability-and-cross-platform-execution.md`.
+
+### Step 3 - Update concurrency/events spec if needed
+
+**What:** Document handoff and shutdown behavior.
+**How:** Add single-slot latest-wins, bounded shutdown, and non-blocking producer semantics where concurrency is specified.
+**File(s):** `docs/specs/runtime/09-events-and-concurrency.md` or adjacent runtime spec.
+
+### Step 4 - Update README/index references
+
+**What:** Keep spec map discoverable.
+**How:** Add any needed cross-reference to worker/render sections.
+**File(s):** `docs/specs/runtime/README.md`.
+
+## Criterios de Aceite
+
+- [ ] Specs define `OwnedRgba8888Frame`.
+- [ ] Specs state worker does not own native window present.
+- [ ] Specs state producer does not block on worker rasterization/present.
+- [ ] Specs document read-only bank access by id.
+- [ ] Specs document bounded shutdown and typed error expectations.
+
+## Tests / Validacao
+
+- `rg "OwnedRgba8888Frame|latest-wins|shutdown|read-only" docs/specs/runtime -n`
+- `discussion validate`
+
+## Riscos
+
+- Updating specs before implementation may accidentally publish intent as completed behavior; execute after code plans that establish the behavior.
+- Spec wording must remain English and normative.

discussion/workflow/plans/PLN-0121-final-worker-path-validation-and-hardening.md

@@ -0,0 +1,93 @@
+---
+id: PLN-0121
+ticket: real-render-worker-establishment
+title: Final Worker Path Validation and Hardening
+status: open
+created: 2026-06-15
+completed:
+ref_decisions: [DEC-0033]
+tags: [runtime, renderer, worker, validation, hardening]
+---
+
+## Briefing
+
+`DEC-0033` is complete only when the worker functions on the real host path and the contract is proven end to end. This plan performs final validation, residue scans, and hardening before housekeeping.
+
+## Decisions de Origem
+
+- `DEC-0033`: Real Render Worker Contract.
+
+## Alvo
+
+Prove the real render worker path satisfies DEC-0033 across HAL, system, drivers, firmware, host, specs, and tests.
+
+## Escopo
+
+- Run broad test suites.
+- Add missing edge tests found during validation.
+- Scan for forbidden coupling.
+- Verify host real path uses worker.
+- Verify local fallback still works.
+- Prepare evidence for discussion housekeeping.
+
+## Fora de Escopo
+
+- No new worker architecture.
+- No SDL migration.
+- No unrelated performance tuning.
+
+## Plano de Execucao
+
+### Step 1 - Run full affected test suite
+
+**What:** Validate all touched crates.
+**How:** Run workspace tests and focused worker/host tests.
+**File(s):** repository root.
+
+### Step 2 - Run coupling residue scans
+
+**What:** Enforce DEC-0033 boundaries.
+**How:** Search worker/system/HAL code for native window dependencies, mutable hardware/GFX/composer leaks, bank copying/snapshot terminology, and sleeps in concurrency tests.
+**File(s):** repository root.
+
+### Step 3 - Add missing hardening tests
+
+**What:** Close any discovered gaps.
+**How:** Add focused tests for missing telemetry/error/shutdown/host-path cases.
+**File(s):** affected test modules.
+
+### Step 4 - Verify host path
+
+**What:** Prove desktop host uses worker output.
+**How:** Run host tests and a manual/simple cartridge path with worker enabled; record evidence in final summary.
+**File(s):** host runner and runtime integration.
+
+### Step 5 - Prepare housekeeping evidence
+
+**What:** Make `DSC-0042` ready for final lesson/housekeeping.
+**How:** Record completed plan state and validation evidence for later `discussion-housekeep`.
+**File(s):** discussion artifacts if needed.
+
+## Criterios de Aceite
+
+- [ ] `cargo test --workspace` passes.
+- [ ] Focused worker, system, drivers, firmware, and host tests pass.
+- [ ] Residue scans show worker code does not depend on native window APIs.
+- [ ] Residue scans show worker boundary does not expose `&mut Hardware`, `&mut Gfx`, live `FrameComposer`, or mutable VM state.
+- [ ] Desktop host path uses the real worker output.
+- [ ] Local fallback still works.
+- [ ] `discussion validate` passes.
+
+## Tests / Validacao
+
+- `cargo test --workspace`
+- `cargo test -p prometeu-system -p prometeu-drivers -p prometeu-hal -p prometeu-firmware -p prometeu-host-desktop-winit`
+- `discussion validate`
+- `rg "winit|pixels|SDL|swapchain|native texture" crates/console/prometeu-system crates/console/prometeu-hal -n`
+- `rg "&mut Hardware|&mut Gfx|FrameComposer" crates/console/prometeu-system/src/services/vm_runtime crates/console/prometeu-hal -n`
+- `rg "thread::sleep|sleep\\(" crates/console/prometeu-system/src/services/vm_runtime -n`
+
+## Riscos
+
+- Final validation may expose earlier plan gaps; fix them in the narrowest affected plan/module.
+- Manual host evidence can be flaky if tied to native window availability; keep automated host-unit evidence as the primary gate.