prometeu-studio/discussion/workflow/plans/PLN-0088-variable-glyph-palette-metadata-and-count-model.md

id	ticket	title	status	created	completed	ref_decisions	tags
PLN-0088	variable-tile-bank-palette-serialization	Variable Glyph Palette Metadata and Count Model	done	2026-07-14	2026-07-14	DEC-0038	packer metadata glyph-bank palette-count

Objective

Make packer metadata compute and expose runtime-effective glyph-bank palette_count from declared palette data instead of hard-coding 64.

Background

DEC-0038 requires palette_count to describe the number of serialized and resident palettes expected by runtime. Current packer code emits palette_count = 64 and uses palette_authored for the actual authored count. That makes the informative count and effective runtime count diverge.

Scope

Included

• Compute effective glyph palette count from declared output.pipeline.palettes.
• Validate palette_count in 1..=64.
• Keep palette identity direct; do not remap sparse authored indices.
• Stop using palette_authored as a runtime-effective field.

Excluded

• Binary payload byte emission.
• Size formula changes.
• Studio UI changes except compile-safe DTO/projection adjustments.

Execution Steps

Step 1 - Add a runtime-effective palette count helper

What: Centralize effective glyph palette count calculation.

How: Add or update helper logic so packer derives palette_count from declared palette indices. Because v1 has no remapping, the effective count must cover the highest direct palette id: max(index) + 1. Reject no palettes, negative indices, duplicate indices, and any effective count above 64.

File(s):

• prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/FileSystemPackerWorkspaceService.java
• prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerAssetWalker.java
• prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/PackerAssetDeclarationParser.java

Step 2 - Replace fixed runtime metadata

What: Stop writing palette_count = 64 unconditionally.

How: Replace runtime metadata emission so glyph-bank entries publish the computed runtime-effective palette_count. Keep palette_authored only if it is useful as pipeline/tooling information and never as runtime-effective root metadata.

File(s):

• prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/FileSystemPackerWorkspaceService.java
• prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerRuntimeAssetMaterializer.java

Step 3 - Validate direct palette identity

What: Preserve runtime direct palette_id semantics.

How: Ensure packer does not compact or renumber palette indices. If palette indices are sparse, emitted palette slots up to palette_count - 1 must keep their direct identity, with missing slots represented by deterministic default RGBA8888 palette data only when required to preserve direct ids.

File(s):

• prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/FileSystemPackerWorkspaceService.java
• prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerGlyphBankWalker.java

Step 4 - Update projections that expose metadata

What: Align details/read projections with the effective count.

How: Ensure packer read/details APIs expose palette_count consistently where runtime metadata is projected, and do not present palette_authored as the field that runtime consumes.

File(s):

• prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/PackerAssetDetailsService.java
• prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/PackerReadMessageMapper.java

Test Requirements

Unit Tests

• Parser/metadata tests for palette_count = 1, intermediate count, and 64.
• Rejection tests for zero effective palettes, duplicate indices, negative indices, and count above 64.
• Sparse direct identity tests where palette index 3 implies palette_count = 4, without remapping palette 3 to 0.

Integration Tests

• Workspace read/build test proving asset table metadata reports variable palette_count.

Manual Verification

• Search packer code for palette_count = 64 and GLYPH_BANK_PALETTE_COUNT assumptions after the change.

Acceptance Criteria

• Packer computes runtime-effective palette_count from declared palettes.
• palette_count is validated as 1..=64.
• Sparse palette ids are not remapped.
• palette_authored is not treated as runtime-effective metadata.
• Read/details projections do not expose stale fixed-count assumptions.

Dependencies

• Depends on PLN-0087.
• Must complete before payload emission changes in PLN-0089.

Risks

• Sparse palette handling can accidentally become remapping if implemented by sorting and compacting declarations.
• Keeping palette_authored in tooling may confuse readers unless tests prove runtime-effective metadata uses palette_count.