prometeu-runtime/discussion/workflow/plans/PLN-0168-glyphbank-variable-palette-resident-model.md

id	ticket	title	status	completed	created	ref_decisions	tags
PLN-0168	runtime-owned-variable-glyph-bank-palette-protocol	GlyphBank Variable Palette Resident Model	done	2026-07-14	2026-07-14	DEC-0041	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.