prometeu-studio/discussion/workflow/plans/PLN-0089-variable-glyph-palette-payload-emission-and-size-accounting.md

id	ticket	title	status	created	completed	ref_decisions	tags
PLN-0089	variable-tile-bank-palette-serialization	Variable Glyph Palette Payload Emission and Size Accounting	done	2026-07-14	2026-07-14	DEC-0038	packer assets-pa glyph-bank payload

Objective

Change packer GLYPH/indexed_v1 payload emission from a fixed 64-palette block to exactly palette_count * 16 * 4 RGBA8888 bytes, with matching size and decoded-size accounting.

Background

FileSystemPackerWorkspaceService currently defines fixed palette constants and emits a fixed GLYPH_BANK_PALETTE_BYTES block. DEC-0038 requires packer to emit only the runtime-effective palette count and compute asset table sizes from that count.

Scope

Included

• Replace fixed palette byte constants with count-dependent formulas.
• Emit exactly palette_count palettes in RGBA byte order.
• Update asset table size and decoded_size.
• Reject metadata/payload mismatches.

Excluded

• Palette model extraction changes covered by PLN-0088.
• Studio UI changes.
• Runtime code changes.

Execution Steps

Step 1 - Replace fixed palette byte constants

What: Remove normal-path fixed 64 * 16 * 4 size assumptions.

How: Keep maximum constants such as MAX_PALETTE_COUNT = 64, but compute payload palette bytes as palette_count * 16 * 4 at each glyph-bank packing boundary.

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/repositories/PackerRuntimeAssetMaterializer.java

Step 2 - Emit variable palette bytes

What: Write only runtime-effective palettes.

How: Update palette byte generation to allocate palette_count * 16 * 4 bytes and fill direct palette ids from 0 through palette_count - 1. Each color remains RGBA8888 in R, G, B, A order.

File(s):

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

Step 3 - Update size and decoded-size formulas

What: Align asset table sizes with runtime DEC-0041.

How: Compute:

size = ceil(width * height / 2) + palette_count * 16 * 4
decoded_size = width * height + palette_count * 16 * 4

Use these formulas for asset table entries, materializer expectations, and workspace build outputs.

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 4 - Reject metadata/payload mismatches

What: Prevent stale fixed-padding artifacts.

How: Add validation that emitted palette byte length, root metadata palette_count, size, and decoded_size agree. Do not allow a fixed 64-palette block when palette_count < 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/PackerRuntimeAssetMaterializer.java

Test Requirements

Unit Tests

• Assert emitted palette bytes for palette_count = 1, an intermediate count, and 64.
• Assert size and decoded_size formulas for variable counts.
• Assert RGBA byte order is unchanged.

Integration Tests

• Build a workspace and inspect assets.pa asset table and payload length for variable palette counts.

Manual Verification

• Search for fixed normal-path 4096, 64 * 16 * 4, and GLYPH_BANK_PALETTE_BYTES residue.

Acceptance Criteria

• Glyph payloads emit exactly palette_count * 16 * 4 palette bytes.
• Asset table size and decoded_size use variable formulas.
• RGBA byte order is unchanged.
• Fixed 64-palette padding is emitted only when palette_count = 64.
• Metadata/payload mismatch is rejected or impossible by construction.

Dependencies

• Depends on PLN-0088.

Risks

• Updating metadata without payload length will corrupt runtime slicing.
• Updating payload length without decoded-size metadata will fail runtime asset validation.