126 lines
4.5 KiB
Markdown
126 lines
4.5 KiB
Markdown
---
|
|
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.
|