prometeu-runtime/discussion/workflow/plans/PLN-0167-spec-contract-update-for-variable-glyph-palettes.md

id	ticket	title	status	created	ref_decisions	tags
PLN-0167	runtime-owned-variable-glyph-bank-palette-protocol	Spec Contract Update for Variable Glyph Palettes	open	2026-07-14	DEC-0041	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.