120 lines
3.9 KiB
Markdown
120 lines
3.9 KiB
Markdown
---
|
|
id: PLN-0168
|
|
ticket: runtime-owned-variable-glyph-bank-palette-protocol
|
|
title: GlyphBank Variable Palette Resident Model
|
|
status: done
|
|
completed: 2026-07-14
|
|
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`.
|