prometeu-runtime/discussion/workflow/plans/PLN-0027-deferred-gfx-overlay-subsystem.md

id	ticket	title	status	created	completed	tags
PLN-0027	deferred-overlay-and-primitive-composition	Plan - Deferred GFX Overlay Subsystem	accepted	2026-04-18		gfx runtime overlay primitives text drivers

Objective

Introduce a dedicated deferred overlay/debug subsystem for gfx.* primitives outside FrameComposer, with command capture for draw_text(...) and the primitive family selected for the first migration.

Background

DEC-0016 requires primitive/text overlay ownership to remain outside FrameComposer while still allowing shared raster helpers and low-level optimizations internally. The new subsystem must preserve semantic separation from scene/sprite/HUD composition.

Scope

Included

• introduce an overlay/debug command queue or equivalent subsystem outside FrameComposer
• route gfx.draw_text(...) into deferred command capture instead of stable direct framebuffer writes
• route the chosen V1 primitive family into the same deferred overlay/debug path
• keep raster helper reuse allowed without merging semantic ownership

Excluded

• runtime frame-end sequencing
• no-scene/scene parity tests at the runtime level
• final repository-wide CI

Execution Steps

Step 1 - Define overlay/debug state ownership in drivers

What: Create the subsystem that owns deferred gfx.* overlay/debug commands.

How:

• Add a dedicated owner adjacent to Gfx/Hardware, but not inside FrameComposer.
• Define the minimal command model required for V1 operations.
• Keep the subsystem screen-space and explicitly pipeline-agnostic relative to composer.*.

File(s):

• crates/console/prometeu-drivers/src/*
• crates/console/prometeu-hal/src/* if bridge traits need extension

Step 2 - Route text and selected primitives into deferred capture

What: Stop treating text/primitives as stable direct writes.

How:

• Change gfx.draw_text(...) to enqueue deferred overlay/debug work.
• Migrate the selected V1 primitive set into the same deferred path.
• Keep any remaining unmigrated primitives either explicitly out of scope or routed consistently if they are already part of the accepted V1 set.
• Preserve internal raster helper reuse where useful.

File(s):

• crates/console/prometeu-drivers/src/gfx.rs
• runtime dispatch call sites that submit gfx.* primitives

Step 3 - Add local driver-level tests for deferred capture semantics

What: Prove that overlay/debug commands are captured separately from game composition state.

How:

• Add tests that assert text/primitives do not need direct stable writes to back to survive until overlay drain.
• Add tests that assert the overlay owner is independent from FrameComposer state.

File(s):

• crates/console/prometeu-drivers/src/gfx.rs
• new or existing driver test modules

Test Requirements

Unit Tests

• command capture tests for draw_text(...)
• tests for each migrated V1 primitive class
• tests proving overlay/debug state is owned outside FrameComposer

Integration Tests

• none in this plan; runtime-level ordering is covered by the next plan

Manual Verification

• inspect driver ownership boundaries to confirm FrameComposer does not gain overlay/debug state

Acceptance Criteria

• A dedicated deferred overlay/debug subsystem exists outside FrameComposer.
• gfx.draw_text(...) is captured as deferred overlay/debug work.
• The selected V1 primitive family is captured through the same subsystem.
• Driver-level tests prove overlay/debug state is operationally separate from canonical game composition state.

Dependencies

• Source decision: DEC-0016
• Prefer to execute after PLN-0026

Risks

• Accidentally reusing FrameComposer storage or state would violate the accepted ownership boundary.
• Migrating only part of the primitive family without explicit scoping could create inconsistent semantics across gfx.*.