implements PLN-0120

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

@@ -2,7 +2,7 @@
 id: PLN-0120
 ticket: real-render-worker-establishment
 title: Update Real Render Worker Specs
-status: open
+status: done
 created: 2026-06-15
 completed:
 ref_decisions: [DEC-0033]

docs/specs/runtime/04-gfx-peripheral.md

@@ -73,6 +73,24 @@ Color values in the runtime, HAL, host-facing framebuffer, and GFX ABI are
 logical RGBA8888 values. RGB565 is not a supported runtime framebuffer,
 palette, host presentation, or compatibility contract.
 
+### Published owned frame
+
+The canonical worker-published frame value is `OwnedRgba8888Frame`.
+
+`OwnedRgba8888Frame` contains:
+
+- the logical `FrameId`;
+- render ownership metadata;
+- width and height in pixels;
+- stride in pixels;
+- an owned `Vec<u32>` containing packed RGBA8888 pixels in canonical RGBA
+  channel order.
+
+The pixel vector is owned by the published frame. Consumers may copy it into a
+host upload buffer, retain it as the latest published frame, or repeat it for a
+host redraw. Consumers MUST NOT interpret the frame as a native texture,
+swapchain image, window handle, or host GPU resource.
+
 ---
 
 ## 3. Double Buffering
@@ -134,6 +152,11 @@ to the logical/runtime side before handoff, or to an owning service. They MUST
 NOT require the render consumer to hold mutable VM, `Hardware`, `Gfx`, or
 `FrameComposer` references.
 
+Read-only resource APIs expose compact lookup by ID. They do not expose mutable
+bank state, `Arc` ownership as part of the contract, copies of whole banks, or
+snapshot payloads. The implementation may choose its internal sharing mechanism,
+but the render boundary contract is ID-based read-only access.
+
 Local host implementations may keep a concrete hardware object internally as a
 platform implementation detail. That object is not part of the runtime-facing
 render boundary; the boundary is the typed platform service set.
@@ -155,6 +178,12 @@ latest-wins semantics:
 
 The consumer status is telemetry. It is not a semantic ACK to the VM.
 
+The real render worker consumes owned `RenderSubmission` values from this
+single-slot handoff and publishes owned `OwnedRgba8888Frame` values. The
+producer path MUST remain non-blocking with respect to worker rasterization and
+host present. A slow worker can cause replacement/drop telemetry, but it MUST
+NOT create an unbounded queue or stall VM logical frame production.
+
 ### 4.4 Frame pacing
 
 Game logical frames are paced by the runtime frame scheduler, not by render
@@ -170,6 +199,10 @@ sequential. The render consumer may repeat the last valid frame, and telemetry
 records the overrun/repeat. The VM MUST NOT produce catch-up frames to skip
 from frame `N` to frame `N+k`.
 
+Repeating a frame means reusing the latest published `OwnedRgba8888Frame`
+without recomposing, rerunning VM code, or consuming a new submission. Repeat
+behavior is presentation cadence behavior, not guest-visible execution.
+
 ### 4.5 AppMode policy
 
 Render execution policy is explicit by pipeline/AppMode:
@@ -231,6 +264,17 @@ Minimum render telemetry includes:
 - last produced, consumed, presented, dropped, and error frame IDs;
 - active render epoch.
 
+### 4.8 Shutdown and typed failures
+
+Render worker shutdown is bounded and observable. A shutdown request MUST
+wake a waiting worker, discard pending submissions that will not be consumed,
+and either join within the configured timeout or report a typed shutdown
+failure.
+
+Worker backend failures, sink publication failures, stale ownership discards,
+panic capture, and shutdown timeout are typed render worker outcomes. They are
+recorded through telemetry and diagnostics; they do not become VM-visible ACKs.
+
 ---
 
 ## 5. PROMETEU Graphical Structure

docs/specs/runtime/09-events-and-concurrency.md

@@ -100,7 +100,34 @@ Important properties:
 - no execution occurs outside the frame loop;
 - frame structure remains observable for host tooling and host-owned certification.
 
-## 7 Determinism and Best Practices
+## 7 Render Worker Concurrency
+
+The render worker is not a machine-visible event source and does not introduce
+guest callbacks. It is an implementation-side consumer of closed render
+submissions.
+
+The render worker handoff uses single-slot latest-wins semantics:
+
+- a producer publishes at most one pending owned `RenderSubmission`;
+- a newer submission replaces an older unconsumed pending submission;
+- replacement is counted as telemetry;
+- the producer does not wait for worker rasterization or host present;
+- the worker takes ownership of the submission it consumes.
+
+The worker publishes `OwnedRgba8888Frame` values. Each published frame owns its
+RGBA8888 pixel vector and carries frame and ownership metadata. Repeating a
+frame reuses the latest published owned frame and does not execute guest code
+or recompose the frame.
+
+Render resources reachable from a submission are resolved through read-only
+ID-based access. The worker MUST NOT hold mutable VM state, mutable `Hardware`,
+mutable `Gfx`, or a live mutable `FrameComposer` as its cross-thread contract.
+
+Shutdown is explicit and bounded. A shutdown request wakes a waiting worker,
+causes pending work that will not be consumed to be discarded, and reports a
+typed failure if the worker cannot join within the configured timeout.
+
+## 8 Determinism and Best Practices
 
 PROMETEU encourages:
 
@@ -115,7 +142,7 @@ PROMETEU discourages:
 - hidden timing channels;
 - ambiguous out-of-band execution.
 
-## 8 Relationship to Other Specs
+## 9 Relationship to Other Specs
 
 - [`09a-coroutines-and-cooperative-scheduling.md`](09a-coroutines-and-cooperative-scheduling.md) defines coroutine lifecycle and scheduling behavior.
 - [`10-debug-inspection-and-profiling.md`](10-debug-inspection-and-profiling.md) defines observability and diagnostics surfaces.

docs/specs/runtime/11-portability-and-cross-platform-execution.md

@@ -118,6 +118,8 @@ Hardware differences:
 The graphics system:
 
 - produces typed logical render submissions that render to RGBA8888 output
+- may consume Game submissions through a render worker that publishes owned
+  `OwnedRgba8888Frame` values
 - uses an indexed palette
 - does not depend on a specific GPU
 
@@ -126,7 +128,8 @@ The platform layer:
 - exposes typed service facades for render submission, render backend
   execution, Game 2D composition, input, audio, assets, and telemetry
 - consumes closed render submissions through a render-surface implementation
-- transports published RGBA8888 output into a host presentation surface without
+- transports published RGBA8888 output or worker-published
+  `OwnedRgba8888Frame` pixels into a host presentation surface without
   injecting host-owned debug overlay pixels
 - is the runtime-facing portability boundary; runtime and firmware code must not
   depend on a monolithic hardware bridge or on a concrete hardware aggregate
@@ -135,6 +138,12 @@ The host presentation layer MUST treat RGBA8888 as the canonical logical
 framebuffer format. RGB565 conversion is not part of the normal host
 presentation contract.
 
+Native upload and present belong to the host event loop. The render worker MUST
+NOT own or require a native window, swapchain, `pixels` surface, SDL texture, or
+host GPU texture as part of its contract. The worker output is an owned
+RGBA8888 frame; the host decides how to upload that frame to the native
+presentation API for the current platform.
+
 Host presentation SHOULD be driven by published render submissions and explicit
 host-owned invalidation, not by perpetual redraw polling.
 

docs/specs/runtime/README.md

@@ -56,6 +56,13 @@ input, audio, assets, and telemetry. A concrete local hardware aggregate may
 exist inside a host or test platform, but it is not the normative runtime-facing
 contract.
 
+The real render worker contract is documented across the GFX, events, and
+portability chapters. `04-gfx-peripheral.md` defines the render submission and
+`OwnedRgba8888Frame` publication contract, `09-events-and-concurrency.md`
+defines latest-wins handoff and bounded shutdown behavior, and
+`11-portability-and-cross-platform-execution.md` defines the split between
+worker-owned RGBA8888 frame production and host-owned native upload/present.
+
 ## Document Functions
 
 - `normative`: defines the technical contract, expected behavior, or implementation-facing surface.