---
id: PLN-0067
ticket: rgba8888-framebuffer-and-pixel-format-direction
title: RGBA8888 Published Contracts and Specs
status: done
created: 2026-05-23
ref_decisions: [DEC-0029]
tags: [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.