prometeu-runtime/discussion/workflow/plans/PLN-0067-rgba8888-published-contracts-and-specs.md

id	ticket	title	status	created	ref_decisions	tags
PLN-0067	rgba8888-framebuffer-and-pixel-format-direction	RGBA8888 Published Contracts and Specs	open	2026-05-23	DEC-0029	gfx framebuffer rgb565 rgba8888 renderer assets host backend

Briefing

Publish the RGBA8888 contract before touching runtime code. This plan updates the canonical specs, ABI documentation, and public docs so the repository has a single written source of truth for the migration required by DEC-0029.

Source Decisions

• DEC-0029 - RGBA8888 Runtime Pixel Format Contract.

Target

Document RGBA8888 as the only supported runtime color and framebuffer contract, remove RGB565 compatibility language from published contracts, and define format-neutral GFX API naming rules.

Scope

Included:

• Update docs/specs/runtime/04-gfx-peripheral.md to define logical color, framebuffer output, alpha behavior, and format-neutral GFX command naming.
• Update docs/specs/runtime/15-asset-management.md to define RGBA8888 palette entries in assets.pa and remove RGB565 palette compatibility.
• Update docs/specs/runtime/16-host-abi-and-syscalls.md to remove Gfx*565 as public ABI and define format-neutral syscall names such as GfxClear.
• Update docs/specs/runtime/02a-vm-values-and-calling-convention.md only if it describes raw color value width/range.
• Update docs/specs/runtime/11-portability-and-cross-platform-execution.md only if it describes host framebuffer format or RGB565 presentation.
• Update docs/specs/runtime/README.md if the index or spec summaries mention RGB565 as current contract.

Out of Scope

• Code changes under crates/.
• Asset fixture regeneration.
• Host presentation implementation.
• Lessons; they are written after execution, not before.
• New backend abstractions, render thread, GPU backend, RGB565 fallback.

Execution Plan

1. Audit published contract text.

   • Search docs/ for RGB565, rgb565, 565, u16, GfxClear565, Gfx*565, front_buffer, palette, assets.pa, and RGBA.
   • Classify each hit as historical, obsolete contract, or still-valid implementation detail.

2. Update the GFX peripheral spec.

   • State that runtime color values are RGBA8888 in RGBA channel order.
   • State that front-buffer alpha may be meaningful.
   • State that GFX APIs must be format-neutral and must not expose Gfx*565.
   • State that palette indices are ordinary indices and transparency comes from resolved RGBA alpha.

3. Update asset-management specs.

   • Define palette entries as RGBA8888.
   • Keep indexed tile/sprite payloads and palette limits if already specified.
   • Remove compatibility promises for RGB565 palette payloads.
   • Call out that existing RGB565 assets must be regenerated or converted by tooling, not accepted as runtime compatibility input.

4. Update host and ABI specs.

   • Replace RGB565 and u16 color/framebuffer ABI language with RGBA8888.
   • Replace GfxClear565 and any Gfx*565 surface with format-neutral names.
   • Document expected syscall color range/shape for RGBA8888 values.

5. Add a short migration note to each touched spec.

   • Reference DEC-0029.
   • Make clear that RGB565 text is superseded for the active runtime contract.

Acceptance Criteria

• docs/ no longer describes RGB565 as the current runtime color, framebuffer, palette, or host presentation contract.
• docs/ no longer describes Gfx*565 as public canonical ABI.
• Specs state RGBA8888 raw channel order as RGBA.
• Specs state that front-buffer alpha may be meaningful.
• Specs state that palette transparency comes from alpha, not reserved index 0.
• Specs state that RGB565 asset palettes are not compatible runtime input.

Tests / Validation

• Run a repository text audit with rg -n "RGB565|rgb565|Gfx.*565|u16|565" docs and verify every remaining hit is explicitly historical or unrelated.
• Run discussion validate.
• No Rust build is required for this docs-only plan.

Risks

• Specs may contain old historical sections that should remain for context. If retained, they must be marked historical and must not read as active contract.
• Some ABI names may be generated from Rust enums; this plan documents the target but does not update generated code.