prometeu-runtime/discussion/workflow/plans/PLN-0171-variable-glyph-palette-tests-fixtures-and-residue-scan.md

id	ticket	title	status	completed	created	ref_decisions	tags
PLN-0171	runtime-owned-variable-glyph-bank-palette-protocol	Variable Glyph Palette Tests Fixtures and Residue Scan	done	2026-07-14	2026-07-14	DEC-0041	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.