---
id: PLN-0088
ticket: variable-tile-bank-palette-serialization
title: Variable Glyph Palette Metadata and Count Model
status: done
created: 2026-07-14
completed: 2026-07-14
ref_decisions:
  - DEC-0038
tags:
  - 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

- [x] Packer computes runtime-effective `palette_count` from declared palettes.
- [x] `palette_count` is validated as `1..=64`.
- [x] Sparse palette ids are not remapped.
- [x] `palette_authored` is not treated as runtime-effective metadata.
- [x] 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`.