prometeu-runtime/discussion/workflow/plans/PLN-0028-runtime-frame-end-overlay-integration-and-parity.md

id	ticket	title	status	created	completed	tags
PLN-0028	deferred-overlay-and-primitive-composition	Plan - Runtime Frame-End Overlay Integration and Parity	accepted	2026-04-18		runtime overlay frame-composer no-scene regression stress

Objective

Integrate deferred overlay/debug draining into the runtime frame-end sequence so scene-bound and no-scene frames both present the same final gfx.* primitive behavior after hud_fade.

Background

After PLN-0027, the overlay/debug subsystem will exist but still needs to be drained in the correct place relative to FrameComposer.render_frame(), fades, and present/present-adjacent behavior. This plan closes the observable runtime semantics required by DEC-0016.

Scope

Included

• runtime frame-end ordering changes
• scene-bound and no-scene parity
• regression coverage for overlay visibility above the canonical game frame
• stress-cartridge adjustments if needed to prove text/primitives now survive frame composition

Excluded

• broad renderer optimization work
• final repository-wide CI

Execution Steps

Step 1 - Insert overlay/debug drain into the frame-end path

What: Drain deferred overlay/debug after canonical game composition is complete.

How:

• Update the runtime frame-end path so overlay/debug drain occurs after:
  • FrameComposer.render_frame()
  • scene_fade
  • hud_fade
• Ensure the same ordering is respected in the no-scene path.

File(s):

• crates/console/prometeu-system/src/virtual_machine_runtime/tick.rs
• crates/console/prometeu-drivers/src/hardware.rs
• crates/console/prometeu-drivers/src/gfx.rs
• any bridge traits needed by the runtime/hardware path

Step 2 - Add runtime and driver regressions for final visual ordering

What: Lock the new visible behavior.

How:

• Add tests proving gfx.draw_text(...) remains visible after scene-backed frame composition.
• Add tests proving the same behavior with no scene bound.
• Add tests proving overlay/debug sits above the canonical game frame rather than being erased by it.

File(s):

• crates/console/prometeu-system/src/virtual_machine_runtime/tests.rs
• driver-level render tests where helpful

Step 3 - Update stress/integration fixtures if needed

What: Restore or improve stress scenarios that rely on visible text/primitives.

How:

• Update pbxgen-stress or related stress fixtures so text/primitives are once again a valid visible overlay signal.
• Keep the stress focused on the new model rather than reintroducing obsolete immediate-write assumptions.

File(s):

• crates/tools/pbxgen-stress/src/lib.rs
• test-cartridges/stress-console/*

Test Requirements

Unit Tests

• local ordering tests where runtime integration depends on helper sequencing

Integration Tests

• runtime tests for scene-bound overlay/debug visibility
• runtime tests for no-scene parity
• stress/tooling validation that text or primitives are visible again as final overlay/debug

Manual Verification

• run the stress path and visually confirm overlay/debug survives on top of scene/sprites after frame composition

Acceptance Criteria

• The runtime drains deferred overlay/debug after canonical game composition and after hud_fade.
• Scene-bound and no-scene paths expose the same overlay/debug semantics.
• Regression tests prove draw_text(...) is no longer erased by scene-backed frame composition.
• Stress/integration fixtures reflect the new final-overlay semantics where applicable.

Dependencies

• Source decision: DEC-0016
• Depends on PLN-0027

Risks

• If fades are still applied after overlay/debug drain, the visible contract will contradict DEC-0016.
• Incomplete parity between scene-bound and no-scene paths would leave runtime behavior mode-dependent.