prometeu-runtime/discussion/workflow/plans/PLN-0026-gfx-overlay-contract-and-spec-propagation.md

id	ticket	title	status	created	completed	tags
PLN-0026	deferred-overlay-and-primitive-composition	Plan - GFX Overlay Contract and Spec Propagation	accepted	2026-04-18		gfx runtime spec overlay primitives hud

Objective

Propagate DEC-0016 into the canonical specs and internal contracts so gfx.* primitives are defined as deferred final overlay/debug operations outside FrameComposer.

Background

DEC-0016 locks a new semantic boundary:

• FrameComposer remains the owner of canonical game-frame composition;
• gfx.* primitives and draw_text(...) become deferred final overlay/debug operations;
• that overlay lives outside FrameComposer and is drained after hud_fade.

Execution must start by updating the normative contract before implementation changes spread through runtime and drivers.

Scope

Included

• update canonical runtime/gfx spec text to describe deferred overlay semantics
• update any ABI-facing or developer-facing docs that still imply direct stable writes to back
• align local contract comments and module docs where they currently imply immediate-write semantics as the stable model

Excluded

• implementation of the overlay subsystem
• runtime frame-end integration
• final repository-wide CI

Execution Steps

Step 1 - Update canonical graphics/runtime documentation

What: Publish the new semantic contract for gfx.* primitives.

How:

• Update the canonical runtime/gfx spec so gfx.draw_text(...) and peer primitives are described as deferred final overlay/debug operations.
• State explicitly that primitives are not part of canonical scene/sprite/HUD composition.
• State the ordering rule that overlay/debug is drained after hud_fade.
• Ensure the no-scene and scene-bound paths are described consistently.

File(s):

• canonical runtime/gfx spec files under docs/specs/runtime/

Step 2 - Align implementation-facing contract text

What: Remove stale implementation comments that imply immediate stable writes to the framebuffer.

How:

• Inspect module-level comments and trait docs in hal, drivers, and runtime code for language that now contradicts DEC-0016.
• Update only the contract-bearing comments and docs that materially affect maintenance and implementation clarity.

File(s):

• crates/console/prometeu-hal/src/gfx_bridge.rs
• crates/console/prometeu-drivers/src/gfx.rs
• crates/console/prometeu-drivers/src/frame_composer.rs
• runtime-adjacent modules where frame ordering is described

Test Requirements

Unit Tests

• none required for pure doc propagation

Integration Tests

• none required for pure doc propagation

Manual Verification

• inspect the updated spec and local contract comments to confirm they no longer describe primitives as stable direct writes to back

Acceptance Criteria

• Canonical spec text describes gfx.* primitives as deferred final overlay/debug operations.
• The spec states that overlay/debug is outside FrameComposer.
• The spec states that overlay/debug is drained after hud_fade.
• Local implementation-facing contract comments no longer imply immediate-write semantics as the stable model.

Dependencies

• Source decision: DEC-0016

Risks

• Missing a normative doc location would leave code and published contract divergent.
• Over-editing local comments could unintentionally restate design choices outside the scope of DEC-0016.