primitives pipeline adjustments

This commit is contained in:
2026-04-18 09:50:13 +01:00
parent 4a5210f347
commit b0b8bb9028
13 changed files with 1002 additions and 101 deletions
@@ -0,0 +1,93 @@
---
id: PLN-0026
ticket: deferred-overlay-and-primitive-composition
title: Plan - GFX Overlay Contract and Spec Propagation
status: accepted
created: 2026-04-18
completed:
tags: [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`.
@@ -0,0 +1,104 @@
---
id: PLN-0027
ticket: deferred-overlay-and-primitive-composition
title: Plan - Deferred GFX Overlay Subsystem
status: accepted
created: 2026-04-18
completed:
tags: [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.*`.
@@ -0,0 +1,106 @@
---
id: PLN-0028
ticket: deferred-overlay-and-primitive-composition
title: Plan - Runtime Frame-End Overlay Integration and Parity
status: accepted
created: 2026-04-18
completed:
tags: [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.
@@ -0,0 +1,82 @@
---
id: PLN-0029
ticket: deferred-overlay-and-primitive-composition
title: Plan - Final Overlay CI Validation and Polish
status: accepted
created: 2026-04-18
completed:
tags: [ci, overlay, runtime, gfx, validation]
---
## Objective
Run the final repository validation path for the deferred overlay/debug migration and perform the last compatibility, formatting, lint, and regression fixes required to close the thread cleanly.
## Background
`DEC-0016` changes visible runtime semantics and touches both specs and code paths around frame composition. A dedicated final-validation plan is needed so the implementation family can close on a clean CI signal rather than leaving integration fallout for later.
## Scope
### Included
- full-tree formatting, lint, and test validation
- stress-path smoke validation after overlay integration
- final cleanup fixes required to satisfy CI
### Excluded
- new feature work outside the accepted overlay/debug migration
## Execution Steps
### Step 1 - Run focused validation before full CI
**What:**
Catch local fallout in the touched areas before the full repository pass.
**How:**
- Run targeted tests for drivers, runtime, and `pbxgen-stress`.
- Inspect touched files for stale immediate-write assumptions or missed contract updates.
**File(s):**
- touched files from `PLN-0026` through `PLN-0028`
### Step 2 - Run final repository CI
**What:**
Validate the migration end to end.
**How:**
- Run the repository validation path, including `make ci`.
- Fix any final formatting, lint, test, or generated-fixture fallout caused by the overlay/debug migration.
- Do not widen scope beyond the accepted thread.
**File(s):**
- repository-wide
## Test Requirements
### Unit Tests
- all relevant crate unit tests pass after the migration
### Integration Tests
- runtime and stress/integration tests pass after the migration
- `make ci` passes
### Manual Verification
- inspect the tree for residual direct-write assumptions or incomplete overlay propagation
## Acceptance Criteria
- [ ] Targeted validation passes for the touched drivers/runtime/stress areas.
- [ ] `make ci` passes after the deferred overlay/debug migration family lands.
- [ ] No residual contract mismatch remains between spec text and code behavior in the touched thread.
## Dependencies
- Source decision: `DEC-0016`
- Depends on `PLN-0026`, `PLN-0027`, and `PLN-0028`
## Risks
- Final CI may surface unrelated renderer assumptions that still expect immediate-write semantics.
- Generated cartridge fixtures may drift if regeneration is forgotten during earlier plans.