---
id: PLN-0171
ticket: runtime-owned-variable-glyph-bank-palette-protocol
title: Variable Glyph Palette Tests Fixtures and Residue Scan
status: open
created: 2026-07-14
ref_decisions: [DEC-0041]
tags: [runtime, tests, fixtures, glyph-bank, palette-serialization]
---

## Briefing

`DEC-0041` changes a cross-cutting asset contract. Tests and fixtures must be
updated as a dedicated pass so fixed 64-palette assumptions do not survive in
helpers, generated data, or residue.

## Decisions de Origem

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

## Alvo

Convert runtime tests and fixtures to exercise variable glyph palette counts
and prove fixed-padding assumptions are gone from active behavior.

## Escopo

- Update test helpers that build glyph payloads.
- Add minimum, maximum, and intermediate palette-count tests.
- Add invalid palette-count tests.
- Add invalid palette-reference tests once `PLN-0170` is implemented.
- Run residue scans for fixed palette payload assumptions.

## Fora de Escopo

- Production decode implementation.
- Production composer implementation.
- Packer/studio fixture generation.

## Plano de Execucao

### Step 1 - Inventory glyph payload helpers

**What:** Find all runtime test helpers with fixed glyph palette sizes.

**How:** Search for `GLYPH_BANK_PALETTE_COUNT_V1`,
`GLYPH_BANK_PALETTE_BYTES_V1`, `64 * 16 * 4`, `4096`, and helper names such as
`test_glyph_asset_data`.

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

### Step 2 - Create variable payload builders

**What:** Make tests express palette count deliberately.

**How:** Replace fixed helpers with helpers that accept `palette_count`, build
exactly `palette_count * 16 * 4` palette bytes, and compute matching `size` and
`decoded_size`.

**Files:** Runtime test modules that construct glyph assets.

### Step 3 - Add decode boundary coverage

**What:** Prove valid and invalid counts.

**How:** Add tests for `palette_count = 1`, an intermediate value, `64`, `0`,
and `65`.

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

### Step 4 - Add composition coverage

**What:** Prove invalid palette references fail.

**How:** After `PLN-0170`, add scene and sprite tests where
`palette_id == palette_count` and confirm explicit failure behavior.

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

### Step 5 - Run residue scan

**What:** Catch leftover active fixed-palette assumptions.

**How:** Scan code, tests, and specs for fixed palette byte formulas. Keep only
maximum-bound constants and historical documentation.

**Files:** `crates/`, `docs/specs/runtime/`, `discussion/`

## Criterios de Aceite

- [ ] Tests no longer need a fixed 4096-byte palette payload for every glyph
  bank.
- [ ] Decode tests cover `1`, intermediate counts, `64`, `0`, and `65`.
- [ ] Composition tests cover invalid palette references.
- [ ] Residue scan finds no active fixed serialized palette block assumption.
- [ ] Historical or maximum-bound uses of `64` are clearly named.

## Tests / Validacao

- Run targeted crate tests for asset decode, GFX, frame composer, and VM asset
  bank flows.
- Run `rg -n "4096|64 \\* 16|GLYPH_BANK_PALETTE_BYTES_V1|palette_count"`
  against `crates`, `docs/specs/runtime`, and active discussion artifacts.
- Run `discussion validate`.

## Riscos

- Residue scans can produce legitimate hits for the v1 maximum of `64`; those
  must be classified instead of mechanically removed.
- Test helper churn can obscure the behavioral assertions if not kept focused.