prometeu-runtime/discussion/workflow/plans/PLN-0072-rgba8888-residue-removal-and-end-to-end-validation.md

id	ticket	title	status	created	ref_decisions	tags
PLN-0072	rgba8888-framebuffer-and-pixel-format-direction	RGBA8888 Residue Removal and End to End Validation	done	2026-05-23	DEC-0029	gfx framebuffer rgb565 rgba8888 renderer assets host backend

Briefing

Close the RGBA8888 migration by removing residual RGB565 contract text and code paths, running end-to-end validation, and preparing the discussion thread for post-execution lessons.

Source Decisions

• DEC-0029 - RGBA8888 Runtime Pixel Format Contract.

Dependencies

• PLN-0067 through PLN-0071 must be complete or merged into the execution branch.

Target

The repository must no longer expose RGB565, Gfx*565, u16 framebuffer/color contracts, RGB565 palette payloads, or RGB565 host conversion as active runtime contract.

Scope

Included:

• Whole-repository residue audit.
• End-to-end build and test validation.
• Documentation consistency checks.
• Final migration notes needed for housekeeping and lessons.
• Any small missed cleanup in code, docs, tests, or fixtures that directly violates DEC-0029.

Out of Scope

• New alpha-only commands.
• Performance optimization after broad alpha support.
• GPU backend, render thread, RGB565 backend, multi-format backend abstraction.
• New visual design work for the Hub.

Execution Plan

1. Run repository-wide residue scans.

   • Search for RGB565, rgb565, Gfx.*565, clear_565, u16 near color or framebuffer APIs, GLYPH_BANK_PALETTE.*u16, size_of::<u16>() near palette code, draw_rgb565, and 0xFFFF near color validation.
   • Classify every remaining hit as removed, historical-only, unrelated, or a bug.

2. Remove active-contract residues.

   • Delete or rename any remaining active Gfx*565 surface.
   • Remove RGB565 helpers from runtime and host normal paths.
   • Remove comments that still describe RGB565 as current behavior.
   • Remove tests that assert RGB565 output.

3. Verify docs and ABI consistency.

   • Ensure docs/specs/runtime/04-gfx-peripheral.md, docs/specs/runtime/15-asset-management.md, and docs/specs/runtime/16-host-abi-and-syscalls.md agree on RGBA8888.
   • Ensure public syscall declarations and docs use format-neutral names.
   • Ensure any historical RGB565 mention is clearly historical and not normative.

4. Run full test/build validation.

   • Run the repo's standard build command.
   • Run the relevant Rust test suites across HAL, drivers, system, VM, tools, and host.
   • Run any visual/snapshot validation available in the repository.

5. Record final evidence.

   • Capture the exact commands and outcomes in the plan or final PR notes.
   • List remaining historical RGB565 mentions and why they are acceptable.
   • Identify lesson candidates for discussion-housekeep after execution.

Acceptance Criteria

• Repository scan finds no active RGB565 runtime contract.
• No public Gfx*565 API, syscall, metadata, or ABI declaration remains.
• No normal renderer or host path performs RGB565 conversion.
• No asset decode path accepts RGB565 palettes as compatible runtime input.
• Specs, docs, ABI contracts, code, fixtures, and tests agree on RGBA8888.
• Full validation commands pass or any failure is documented as unrelated.
• The discussion thread has enough evidence for housekeeping and lessons.

Tests / Validation

• Run the standard repository build command.
• Run affected crate tests: prometeu-hal, prometeu-drivers, prometeu-system, prometeu-vm, prometeu-bytecode, prometeu-host-desktop-winit, and pbxgen-stress where applicable.
• Run all available visual/snapshot tests.
• Run repository-wide rg residue scans described above.
• Run discussion validate.

Risks

• Some remaining RGB565 references may be legitimate historical notes. They must be marked clearly enough that readers cannot mistake them for active contract.
• End-to-end visual validation may not exist yet. If so, record the gap and add minimal deterministic checks around RGBA channel order and alpha behavior.

Validation Evidence

• cargo check --workspace passed.
• cargo test --workspace passed.
• discussion validate passed.
• Residue scan command: rg -n "RGB565|rgb565|Gfx.*565|clear_565|_565|draw_rgb565|0x1010|front_buffer\\(\\).*u16|Vec<u16>|\\[u16\\]|GLYPH_BANK_PALETTE.*u16|size_of::<u16>|from_rgb565|to_rgb565" crates docs -S
• Remaining scan hits are either negative normative documentation or unrelated u16 uses such as VM verifier instruction offsets / glyph ids.