prometeu-runtime/discussion/workflow/plans/PLN-0008-host-overlay-native-composition-alignment.md

id	ticket	title	status	created	completed	tags
PLN-0008	perf-host-debug-overlay-isolation	PR/Plan - Host Overlay Native Composition Alignment	in_progress	2026-04-10		performance host gfx telemetry

Objective

Bring the desktop debug overlay implementation back into compliance with DEC-0007, DEC-0009, and DEC-0010 by keeping the overlay in the host layer while rendering it in a dedicated host module and separate host layer, outside the emulated hardware framebuffer and outside hardware.gfx.

Background

DEC-0007 requires the debug overlay to be a host-only layer composed after the emulated frame is complete. DEC-0009 further clarifies that fill_rect and draw_text remain part of the emulated machine contract, but the host overlay must not depend on them and must live in a dedicated host module and separate host layer. DEC-0010 fixes the semantics of the visible LOGS metric so the Host overlay reads the last completed frame value instead of a transient intra-frame counter.

The current HostRunner still calls hardware.gfx.fill_rect() and hardware.gfx.draw_text() for the overlay, which means the HUD is still being injected into the emulated graphics path even though its data source already comes from AtomicTelemetry.

PLN-0007 completed the telemetry migration, so the remaining gap is no longer data access. The remaining gap is presentation architecture in the desktop host.

Scope

Included

• Remove all overlay rendering calls that write through hardware.gfx.
• Introduce a desktop-host-native overlay composition path in prometeu-host-desktop-winit.
• Implement the overlay in a dedicated host module instead of ad hoc logic inside runner.rs.
• Keep overlay visibility and lifecycle fully controlled by the desktop host.
• Continue reading inspection data through AtomicTelemetry::snapshot() and host-side log access.
• Expose LOGS to the overlay as the last completed logical frame value.
• Update runtime specifications so they explicitly state that the overlay is host-native and not part of the emulated machine framebuffer.
• Add verification that enabling the overlay does not mutate emulated pixels.

Excluded

• Adding overlays to non-desktop hosts.
• Reopening the telemetry model or changing TelemetryFrame semantics.
• Reworking unrelated presentation, frame pacing, debugger transport, or certification behavior.

Execution Steps

Step 1 - Extract overlay responsibilities into a dedicated host module

What: Move overlay formatting, layout, and drawing responsibilities out of runner.rs and into a dedicated host module.

How: Create a dedicated module such as overlay.rs that owns host overlay data preparation, panel layout, simple bars, and text rendering. runner.rs should orchestrate visibility and presentation only. The new module must never call emulated graphics primitives.

File(s):

• crates/host/prometeu-host-desktop-winit/src/runner.rs
• crates/host/prometeu-host-desktop-winit/src/stats.rs
• crates/host/prometeu-host-desktop-winit/src/overlay.rs

Step 2 - Compose the overlay in a separate host layer

What: Ensure the overlay is rendered in a separate host layer/surface and never blitted into the emulated framebuffer.

How: Preserve the F1 toggle in HostRunner, keep telemetry reads on the host side, and present the overlay after the emulated frame is already ready for display. The implementation may transport the emulated framebuffer into the host presentation surface, but the overlay must remain a separate host composition step and must not write back into hardware.gfx.

File(s):

• crates/host/prometeu-host-desktop-winit/src/runner.rs
• crates/host/prometeu-host-desktop-winit/src/overlay.rs

Step 3 - Add regression coverage for framebuffer purity

What: Add tests or deterministic checks that prove the overlay no longer modifies emulated graphics output.

How: Cover the overlay toggle and composition boundary with focused host tests where practical. At minimum, add a test seam or helper that lets the host render path be exercised without requiring overlay drawing through hardware.gfx. If a full automated framebuffer assertion is not practical yet, add a narrow unit test around the new composition entry point plus manual verification instructions that compare raw emulated output with overlay enabled and disabled.

File(s):

• crates/host/prometeu-host-desktop-winit/src/runner.rs
• crates/host/prometeu-host-desktop-winit/src/overlay.rs
• crates/host/prometeu-host-desktop-winit/src/tests.rs or existing test module location

Step 4 - Align log metric semantics with frame-end snapshots

What: Ensure the visible LOGS metric represents the last completed frame instead of a transient in-flight counter.

How: Persist the completed-frame log count into AtomicTelemetry before resetting the transient LogService counter. Keep certification evaluation and host overlay consumption aligned on that persisted frame-end value.

File(s):

• crates/console/prometeu-hal/src/log/log_service.rs
• crates/console/prometeu-hal/src/telemetry.rs
• crates/console/prometeu-system/src/virtual_machine_runtime/tick.rs
• crates/host/prometeu-host-desktop-winit/src/overlay.rs

Step 5 - Update normative documentation

What: Align specs and workflow artifacts with the corrected execution path.

How: Update the runtime debug and portability specifications to explicitly say the overlay is desktop-host-native, post-upscaling, and outside the emulated framebuffer. Keep the discussion workflow aligned by referencing this corrective plan during execution and closure.

File(s):

• docs/specs/runtime/10-debug-inspection-and-profiling.md
• docs/specs/runtime/11-portability-and-cross-platform-execution.md

Test Requirements

Unit Tests

• Host overlay toggle logic remains host-owned and does not require hardware.gfx text drawing.
• New host-native overlay composition entry point can format and present telemetry without mutating the emulated framebuffer abstraction.
• Simple bars and text layout are owned by the dedicated host overlay module.

Integration Tests

• cargo check for prometeu-host-desktop-winit, prometeu-system, and any touched supporting crate.
• If automated host rendering tests are feasible, verify an emulated frame buffer dump is identical with overlay off and overlay on before the host-only composition stage.

Manual Verification

• Run the desktop host, toggle F1, and confirm the overlay appears and disappears correctly.
• Capture or inspect the emulated framebuffer path and confirm no HUD pixels are written into machine output.
• Confirm telemetry values still update through AtomicTelemetry.

Acceptance Criteria

• No desktop overlay code writes through hardware.gfx.fill_rect, hardware.gfx.draw_text, or equivalent emulated-machine drawing APIs.
• fill_rect and draw_text remain intact as part of the emulated graphics contract and are not repurposed for host overlay rendering.
• The desktop overlay remains controlled by HostRunner and uses host-side telemetry snapshots.
• The visible overlay is composed in a separate host layer after the emulated frame and is not burned into the emulated framebuffer.
• Runtime telemetry remains gated by inspection state and continues to function for overlay consumption.
• The visible LOGS metric represents the last completed logical frame.
• Specs describe the overlay as host-native and outside the emulated hardware contract.

Dependencies

• DEC-0007 accepted and unchanged.
• DEC-0008 accepted and unchanged.
• DEC-0009 accepted and unchanged.
• DEC-0010 accepted and unchanged.
• Existing AtomicTelemetry host snapshot path remains available.

Risks

• Desktop-native text and alpha composition may require extra host rendering plumbing that is more complex than the previous hardware.gfx path.
• Without an explicit test seam, it is easy to accidentally reintroduce overlay writes into the emulated graphics path during future host refactors.
• Host composition cost may rise slightly, but that cost is acceptable as long as it remains outside runtime cycle accounting.