---
id: PLN-0169
ticket: runtime-owned-variable-glyph-bank-palette-protocol
title: Asset Decode Validation for Variable Glyph Palettes
status: done
completed: 2026-07-14
created: 2026-07-14
ref_decisions: [DEC-0041]
tags: [runtime, assets, glyph-bank, decode, validation]
---

## Briefing

`DEC-0041` changes glyph-bank decode from a fixed 4096-byte palette block to a
variable `palette_count * 16 * 4` block. The asset manager is the runtime gate
that must reject malformed glyph payloads before residency.

## Decisions de Origem

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

## Alvo

Update glyph asset layout validation and decode to accept `palette_count` in
`1..=64` and materialize exactly that many palettes.

## Escopo

- Update `crates/console/prometeu-drivers/src/asset.rs`.
- Replace exact `palette_count == 64` validation.
- Replace fixed `GLYPH_BANK_PALETTE_BYTES_V1` usage in decode.
- Validate `size` and `decoded_size` using variable formulas.
- Read exactly `palette_count * 16 * 4` bytes.
- Preserve RGBA byte order.

## Fora de Escopo

- HAL storage changes except as required by `PLN-0168`.
- Composer invalid-reference behavior.
- Packer output changes.

## Plano de Execucao

### Step 1 - Change layout return data

**What:** Carry palette count through layout validation.

**How:** Update `decode_glyph_bank_layout` to return `palette_count` and
palette byte count along with tile size, dimensions, and serialized pixel byte
count.

**Files:** `crates/console/prometeu-drivers/src/asset.rs`

### Step 2 - Replace exact palette-count validation

**What:** Accept only the DEC-0041 range.

**How:** Reject `palette_count = 0` and `palette_count > 64`; accept all values
in `1..=64`.

**Files:** `crates/console/prometeu-drivers/src/asset.rs`

### Step 3 - Use variable size formulas

**What:** Align entry validation with the spec.

**How:** Compute `palette_bytes = palette_count * 16 * size_of::<u32>()`,
`serialized_size = packed_pixels + palette_bytes`, and
`decoded_size = logical_pixels + palette_bytes`.

**Files:** `crates/console/prometeu-drivers/src/asset.rs`

### Step 4 - Decode variable palette data

**What:** Read only materialized palettes.

**How:** In buffer and reader decode paths, slice/read exactly `palette_bytes`.
Populate the new variable `GlyphBank` palette representation in order.

**Files:** `crates/console/prometeu-drivers/src/asset.rs`

### Step 5 - Remove fixed-byte assumptions

**What:** Retire the fixed payload block from active decode.

**How:** Replace helper functions and tests that assume
`GLYPH_BANK_PALETTE_BYTES_V1` is always in the payload. Keep a maximum constant
only if it is named as a maximum, not a payload size.

**Files:** `crates/console/prometeu-drivers/src/asset.rs`

## Criterios de Aceite

- [ ] Decode accepts valid `palette_count` values from `1` through `64`.
- [ ] Decode rejects `palette_count = 0`.
- [ ] Decode rejects `palette_count > 64`.
- [ ] `size` and `decoded_size` validation use variable palette bytes.
- [ ] Buffer and reader decode paths behave consistently.
- [ ] RGBA channel order remains unchanged.

## Tests / Validacao

- Add unit tests for `palette_count = 1`, an intermediate count, and `64`.
- Add rejection tests for `0`, `65`, short palette data, oversized metadata
  size, and mismatched `decoded_size`.
- Run the crate tests that cover asset manager glyph decode.

## Riscos

- Existing tests may use generated glyph payload helpers with fixed 64-palette
  size.
- Reader and buffer paths can drift if only one path receives the variable-size
  change.