141 lines
4.9 KiB
Markdown
141 lines
4.9 KiB
Markdown
---
|
|
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`.
|