---
id: PLN-0167
ticket: runtime-owned-variable-glyph-bank-palette-protocol
title: Spec Contract Update for Variable Glyph Palettes
status: open
created: 2026-07-14
ref_decisions: [DEC-0041]
tags: [runtime, gfx, assets, glyph-bank, palette-serialization, protocol, specs]
---

## Briefing

`DEC-0041` accepts variable glyph-bank palette serialization for
`GLYPH/indexed_v1`. The runtime specs must become the canonical source before
code and tooling are changed.

## Decisions de Origem

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

## Alvo

Publish the runtime contract for variable glyph-bank palettes in the canonical
runtime specs.

## Escopo

- Update `docs/specs/runtime/15-asset-management.md`.
- Update `docs/specs/runtime/04-gfx-peripheral.md`.
- Remove or reword active spec text that requires exactly 64 serialized or
  resident palettes per glyph bank.
- Define `palette_count` as serialized and resident palette count.
- Define `palette_count` as `1..=64`.
- Define `palette_id` validity as `palette_id < palette_count` for the loaded
  glyph bank.
- Preserve RGBA8888, alpha-as-data, and ordinary index `0` semantics.

## Fora de Escopo

- Runtime code changes.
- Packer or studio code changes.
- New `GLYPH/indexed_v2` format text.
- Sparse-to-dense palette remapping.

## Plano de Execucao

### Step 1 - Update asset metadata contract

**What:** Change the `GLYPH` v1 metadata contract.

**How:** In `docs/specs/runtime/15-asset-management.md`, replace the exact
`palette_count = 64` requirement with `palette_count` in `1..=64`. State that
the field is both serialized palette count and resident palette count.

**Files:** `docs/specs/runtime/15-asset-management.md`

### Step 2 - Update payload and decoded-size formulas

**What:** Make payload size formulas variable.

**How:** Define `palette_bytes = palette_count * 16 * 4`, then define
`size = ceil(width * height / 2) + palette_bytes` and
`decoded_size = width * height + palette_bytes`.

**Files:** `docs/specs/runtime/15-asset-management.md`

### Step 3 - Update GFX palette reference semantics

**What:** Document bank-dependent `palette_id` validity.

**How:** In `docs/specs/runtime/04-gfx-peripheral.md`, make scene and sprite
composition text state that `palette_id` is valid only when it is lower than
the referenced glyph bank's `palette_count`.

**Files:** `docs/specs/runtime/04-gfx-peripheral.md`

### Step 4 - Document explicit failure

**What:** Remove fallback ambiguity for missing palettes.

**How:** State that canonical composition must not substitute transparent,
black, or default colors for `palette_id >= palette_count`.

**Files:** `docs/specs/runtime/04-gfx-peripheral.md`,
`docs/specs/runtime/15-asset-management.md`

### Step 5 - Run spec residue scan

**What:** Verify no active spec contradicts `DEC-0041`.

**How:** Search specs for fixed palette phrases and validate remaining hits are
historical or explicitly bounded maximums.

**Files:** `docs/specs/runtime/*.md`

## Criterios de Aceite

- [ ] `15-asset-management.md` defines `palette_count` as `1..=64`.
- [ ] `15-asset-management.md` uses variable size formulas.
- [ ] `04-gfx-peripheral.md` defines bank-dependent `palette_id` validity.
- [ ] Specs do not describe fixed 64 serialized palettes as the active
  contract.
- [ ] No v2 format is introduced.

## Tests / Validacao

- Run `rg -n "palette_count|64 \\* 16|4096|palette_id" docs/specs/runtime`.
- Run `discussion validate`.

## Riscos

- The specs already contain mixed fixed and variable wording; partial edits may
  preserve contradiction.
- `palette_id` failure semantics may overlap with existing scene dependency
  fatal-failure text and must be worded consistently.