---
id: PLN-0168
ticket: runtime-owned-variable-glyph-bank-palette-protocol
title: GlyphBank Variable Palette Resident Model
status: open
created: 2026-07-14
ref_decisions: [DEC-0041]
tags: [runtime, gfx, assets, glyph-bank, hal]
---

## Briefing

`DEC-0041` requires resident `GlyphBank` memory to materialize exactly
`palette_count` palettes. The current HAL model exposes a fixed
`[[Color; 16]; 64]` table and must be changed before decode and composition can
enforce bank-dependent palette validity cleanly.

## Decisions de Origem

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

## Alvo

Replace the fixed resident palette table with a variable resident palette model
that preserves direct `palette_id` identity.

## Escopo

- Update `crates/console/prometeu-hal/src/glyph_bank.rs`.
- Keep `GLYPH_BANK_COLORS_PER_PALETTE = 16`.
- Replace the fixed palette table with a variable representation.
- Expose palette count and palette validation helpers.
- Ensure `resolve_color` no longer hides invalid palette references in
  canonical paths.
- Update local HAL tests and call sites that construct `GlyphBank` directly.

## Fora de Escopo

- Asset payload decode changes.
- Composer status/fault policy.
- Packer/studio changes.
- Sparse palette remapping.

## Plano de Execucao

### Step 1 - Introduce variable palette storage

**What:** Replace fixed palette storage.

**How:** Change `GlyphBank::palettes` from
`[[Color; GLYPH_BANK_COLORS_PER_PALETTE]; GLYPH_BANK_PALETTE_COUNT_V1]` to a
variable collection such as `Vec<[Color; GLYPH_BANK_COLORS_PER_PALETTE]>`.
Keep a separate maximum constant for v1 if useful.

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

### Step 2 - Update constructors

**What:** Make constructors explicit about palette count.

**How:** Add or update constructors so tests and loaders can create a bank with
a chosen palette count. Default constructors used only for empty test banks
must choose a valid count and not imply fixed 64 capacity.

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

### Step 3 - Add validation helpers

**What:** Provide canonical palette validity APIs.

**How:** Add methods such as `palette_count()`, `contains_palette(palette_id)`,
and a fallible color lookup that distinguishes invalid palette references from
transparent colors.

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

### Step 4 - Update direct palette mutations in tests

**What:** Fix tests that write directly into fixed array slots.

**How:** Replace direct `bank.palettes[id][color] = value` call sites with
helpers or ensure the test bank was created with enough palettes first.

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

### Step 5 - Keep direct identity

**What:** Preserve `palette_id` identity.

**How:** Do not introduce maps, compaction tables, or translated palette ids.
Index `N` in the vector is palette identity `N`.

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

## Criterios de Aceite

- [ ] Resident `GlyphBank` stores exactly the loaded palette count.
- [ ] `GlyphBank` exposes bank-dependent palette validity.
- [ ] Invalid palette lookup can be detected separately from a transparent
  color.
- [ ] No sparse-to-dense remapping structure is added.
- [ ] Direct test constructors no longer rely on implicit 64 palette capacity.

## Tests / Validacao

- Run HAL and driver unit tests that cover glyph bank construction and color
  lookup.
- Add focused tests for `palette_count = 1` and `palette_count = 64`.
- Add a test proving invalid palette lookup is not silently equivalent to
  transparent color.

## Riscos

- Many tests directly mutate `palettes[id]`; the migration can be noisy.
- Existing renderer paths may rely on `resolve_color` returning transparent for
  invalid ids, which conflicts with `DEC-0041`.