prometeu-runtime/discussion/workflow/plans/PLN-0170-composer-palette-reference-failure-semantics.md

id	ticket	title	status	completed	created	ref_decisions	tags
PLN-0170	runtime-owned-variable-glyph-bank-palette-protocol	Composer Palette Reference Failure Semantics	done	2026-07-14	2026-07-14	DEC-0041	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.