---
id: PLN-0170
ticket: runtime-owned-variable-glyph-bank-palette-protocol
title: Composer Palette Reference Failure Semantics
status: open
created: 2026-07-14
ref_decisions: [DEC-0041]
tags: [runtime, gfx, composer, scene, sprite, validation]
---

## Briefing

`DEC-0041` requires invalid palette references to fail explicitly when
scene/sprite/composer logic uses `palette_id >= palette_count` against a loaded
glyph bank. Current color resolution can silently return transparent for
missing palettes, which is no longer canonical behavior.

## Decisions de Origem

- `DEC-0041` - Variable Glyph Bank Palette Protocol

## Alvo

Define and implement explicit runtime failure behavior for invalid palette
references in canonical composition paths.

## Escopo

- Inspect scene binding, scene composition, sprite emission, and render
  resolution paths.
- Choose existing status/fault behavior where it fits the current ABI.
- Prevent canonical composition from substituting transparent/default color for
  invalid palette references.
- Update tests for scene and sprite invalid palette references.

## Fora de Escopo

- Adding new public ABI status values unless existing statuses cannot represent
  the error.
- Packer or scene authoring validation.
- Sparse palette remapping.

## Plano de Execucao

### Step 1 - Map current composition paths

**What:** Identify where palette ids are consumed.

**How:** Trace `composer.emit_sprite`, scene binding/composition, frame
composer packet creation, and software GFX resolution from `Glyph` to
`GlyphBank::resolve_color`.

**Files:** `crates/console/prometeu-system/src/services/vm_runtime/dispatch.rs`,
`crates/console/prometeu-drivers/src/frame_composer.rs`,
`crates/console/prometeu-drivers/src/gfx.rs`,
`crates/console/prometeu-hal/src/glyph_bank.rs`

### Step 2 - Select explicit failure behavior

**What:** Choose the runtime-visible failure route.

**How:** Use existing semantics where possible: status-returning sprite calls
should use an existing invalid status if it accurately describes the failure;
scene dependency failures that occur during binding/composition should follow
the existing fatal dependency-failure model documented in the GFX spec.

**Files:** `docs/specs/runtime/04-gfx-peripheral.md`,
`crates/console/prometeu-system/src/services/vm_runtime/dispatch.rs`,
`crates/console/prometeu-drivers/src/frame_composer.rs`

### Step 3 - Validate sprite references

**What:** Prevent invalid sprite palette references.

**How:** When `emit_sprite` has access to the target glyph bank, reject
`palette_id >= palette_count` before the sprite is accepted for canonical
composition.

**Files:** `crates/console/prometeu-system/src/services/vm_runtime/dispatch.rs`,
`crates/console/prometeu-drivers/src/frame_composer.rs`,
`crates/console/prometeu-drivers/src/hardware.rs`

### Step 4 - Validate scene references

**What:** Prevent invalid scene palette references.

**How:** During scene bind or scene composition, validate tile palette ids
against each referenced loaded glyph bank. Fail explicitly if a scene layer
references a palette not present in its glyph dependency.

**Files:** `crates/console/prometeu-drivers/src/gfx.rs`,
`crates/console/prometeu-hal/src/scene_viewport_cache.rs`,
`crates/console/prometeu-hal/src/scene_viewport_resolver.rs`

### Step 5 - Remove silent fallback from canonical paths

**What:** Stop hiding invalid palette ids as transparent.

**How:** Use fallible palette lookup in canonical render paths. Transparent is
valid only when produced by an actual RGBA palette entry with alpha `0`.

**Files:** `crates/console/prometeu-drivers/src/gfx.rs`,
`crates/console/prometeu-hal/src/glyph_bank.rs`

## Criterios de Aceite

- [ ] Invalid sprite `palette_id` is rejected before canonical composition.
- [ ] Invalid scene tile `palette_id` fails explicitly against the loaded bank.
- [ ] Canonical render paths do not use invalid palette lookup as transparent.
- [ ] Valid transparent RGBA palette entries still render as transparent.
- [ ] The selected status/fault behavior is documented in the spec.

## Tests / Validacao

- Add sprite test for `palette_id == palette_count`.
- Add scene test for a tile palette id above the referenced bank's count.
- Add regression test proving alpha `0` in a valid palette still works.
- Run VM runtime and GFX driver tests.

## Riscos

- Some paths may not have easy access to the loaded glyph bank when accepting a
  sprite packet.
- Existing ABI statuses may be less precise than a new status, but adding a new
  status has wider compatibility cost.