Variable Glyph Bank Palette Serialization
JaCoCo Coverage #### Project Overview No changes detected, that affect the code coverage. * Line Coverage: 61.08% (17147/28073) * Branch Coverage: 51.93% (6599/12707) * Lines of Code: 28073 * Cyclomatic Complexity: 11234 #### Quality Gates Summary Output truncated.
Test / Build skipped: 15, passed: 583
Intrepid/Prometeu/Studio/pipeline/head This commit looks good

This commit is contained in:
2026-07-14 16:53:20 +01:00
parent fa089c5cd0
commit ad2ae00f39
9 changed files with 128 additions and 1121 deletions
@@ -1,132 +0,0 @@
---
id: PLN-0087
ticket: variable-tile-bank-palette-serialization
title: Variable Glyph Palette Spec Propagation
status: done
created: 2026-07-14
completed: 2026-07-14
ref_decisions:
- DEC-0038
tags:
- specs
- packer
- studio
- glyph-bank
- palette-serialization
---
## Objective
Propagate `DEC-0038` into the canonical Studio and packer specifications before
code changes start.
## Background
Runtime `DEC-0041` makes `palette_count` the serialized and resident palette
count for `GLYPH/indexed_v1`. Studio/packer `DEC-0038` adopts that runtime
contract downstream. Current packer specs still describe a fixed
`64 * 16 * 4 = 4096` palette block and `palette_count = 64`.
## Scope
### Included
- Update packer specs for glyph-bank metadata, payload layout, and size formulas.
- Update Studio specs only where Studio-facing palette count projection or asset
details are documented.
- Preserve RGBA8888 channel order, packed `u4` pixels, and `GLYPH/indexed_v1`.
### Excluded
- Code changes.
- Fixture regeneration.
- Runtime spec changes.
- Any `GLYPH/indexed_v2` design.
## Execution Steps
### Step 1 - Update asset declaration metadata rules
**What:** Define `palette_count` as the effective runtime metadata field.
**How:** Update glyph-bank declaration language so `palette_count` means the
number of serialized and resident RGBA8888 palettes, constrained to `1..=64`.
State that `palette_authored`, if present, is informative and not runtime
effective.
**File(s):**
- `docs/specs/packer/3. Asset Declaration and Virtual Asset Contract Specification.md`
### Step 2 - Update glyph payload layout
**What:** Replace fixed 4096-byte palette block text.
**How:** Change the layout to `palette_count * 16 * 4` palette bytes and update
formulas to:
```text
size = ceil(width * height / 2) + palette_count * 16 * 4
decoded_size = width * height + palette_count * 16 * 4
```
**File(s):**
- `docs/specs/packer/4. Build Artifacts and Deterministic Packing Specification.md`
### Step 3 - Preserve v1 boundaries
**What:** Explicitly prohibit v2, compatibility padding, and remapping.
**How:** Add rules that this remains `GLYPH/indexed_v1`, old fixed-padding is
not a compatibility mode, and v1 has no sparse-to-dense palette remapping.
**File(s):**
- `docs/specs/packer/4. Build Artifacts and Deterministic Packing Specification.md`
### Step 4 - Update Studio-facing spec text
**What:** Align Studio projections if they mention palette count or fixed bank
shape.
**How:** Search the Studio asset workspace spec for palette projection, details,
or pack wizard language and update only stale fixed-count wording.
**File(s):**
- `docs/specs/studio/4. Assets Workspace Specification.md`
## Test Requirements
### Unit Tests
- Not applicable for this spec-only plan.
### Integration Tests
- Not applicable for this spec-only plan.
### Manual Verification
- Search specs for stale normal-path `palette_count = 64`, `4096`, fixed
64-palette block, `GLYPH/indexed_v2`, and remapping language.
## Acceptance Criteria
- [x] Packer specs define `palette_count` as runtime-effective `1..=64`.
- [x] Packer specs use variable palette byte and size formulas.
- [x] Specs keep `GLYPH/indexed_v1` and reject v2 for this change.
- [x] Specs reject fixed-padding compatibility and sparse-to-dense remapping.
- [x] Studio specs contain no stale fixed 64-palette projection wording.
## Dependencies
- Depends on accepted `DEC-0038`.
- Should complete before code plans.
## Risks
- Leaving stale fixed 4096-byte examples will make implementation review
ambiguous.
- Over-editing Studio specs could imply UI behavior not required by `DEC-0038`.
@@ -1,140 +0,0 @@
---
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`.
@@ -1,140 +0,0 @@
---
id: PLN-0089
ticket: variable-tile-bank-palette-serialization
title: Variable Glyph Palette Payload Emission and Size Accounting
status: done
created: 2026-07-14
completed: 2026-07-14
ref_decisions:
- DEC-0038
tags:
- 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:
```text
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
- [x] Glyph payloads emit exactly `palette_count * 16 * 4` palette bytes.
- [x] Asset table `size` and `decoded_size` use variable formulas.
- [x] RGBA byte order is unchanged.
- [x] Fixed 64-palette padding is emitted only when `palette_count = 64`.
- [x] 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.
@@ -1,147 +0,0 @@
---
id: PLN-0090
ticket: variable-tile-bank-palette-serialization
title: Studio and Packer Projections for Variable Glyph Palettes
status: done
created: 2026-07-14
completed: 2026-07-14
ref_decisions:
- DEC-0038
tags:
- studio
- packer
- api
- projections
- glyph-bank
---
## Objective
Align Studio-facing and packer-facing projections so variable glyph
`palette_count` is visible and not confused with `palette_authored`.
## Background
`DEC-0038` says packer metadata projection and Studio-facing read/detail APIs
must expose the runtime-effective `palette_count` correctly. Studio code must
not treat `palette_authored` as the runtime-effective count.
## Scope
### Included
- Update packer read/detail DTO projections where runtime metadata is surfaced.
- Update Studio asset details, palette overhauling, schema, or pack wizard code
if it reads fixed counts or authored counts as runtime-effective.
- Keep `rgba8888` color projection unchanged.
### Excluded
- Binary payload emission.
- General palette UI redesign.
- `originalArgb8888` UI fallback cleanup unrelated to variable `palette_count`.
## Execution Steps
### Step 1 - Audit projection boundaries
**What:** Find all Studio/packer paths that expose glyph palette metadata.
**How:** Search for `palette_count`, `palette_authored`,
`GLYPH_BANK_PALETTE_COUNT`, fixed `64`, and related asset details projections.
Classify each match as runtime-effective metadata, tooling-only metadata, UI
fallback, or unrelated.
**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`
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/**`
### Step 2 - Update packer details/read surfaces
**What:** Expose runtime-effective `palette_count`.
**How:** Ensure details/read projections show the `palette_count` that will be
written to the runtime asset table. Preserve `palette_authored` only as
explicitly tooling-only information if it remains useful.
**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`
### Step 3 - Update Studio consumers
**What:** Prevent Studio from using authored count as runtime count.
**How:** Adjust Studio asset details and pack wizard code so any displayed or
validated runtime count comes from effective `palette_count`. Keep palette
color rendering based on `rgba8888`.
**File(s):**
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/**`
- `prometeu-studio/src/test/java/p/studio/workspaces/assets/details/**`
### Step 4 - Preserve scene palette id shape
**What:** Avoid accidental scene payload changes.
**How:** Confirm scene projections still carry `palette_id` unchanged and only
runtime/packer validation changes count semantics.
**File(s):**
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/**`
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/FileSystemPackerWorkspaceService.java`
## Test Requirements
### Unit Tests
- Packer details/read tests for variable `palette_count`.
- Studio asset details tests proving runtime count and authored/tooling count
are not conflated.
### Integration Tests
- Workspace read/build flow where a glyph bank with an intermediate
`palette_count` is projected through packer/Studio surfaces.
### Manual Verification
- Search Studio and packer projection code for stale assumptions that
`palette_authored` is runtime-effective.
## Acceptance Criteria
- [x] Packer read/details projections expose effective `palette_count`.
- [x] Studio consumers do not use `palette_authored` as runtime-effective count.
- [x] `rgba8888` color projection remains unchanged.
- [x] Scene `palette_id` payload shape is unchanged.
- [x] Tests cover variable count projection.
## Execution Notes
- Packer runtime output projection is the `assets.pa` asset table generated by
`FileSystemPackerWorkspaceService`; `PLN-0088` and `PLN-0089` now project the
runtime-effective `palette_count` there.
- `PackerAssetDetailsService` and `PackerReadMessageMapper` project palette
color data through `pipelinePalettes` and do not expose
`palette_authored` as runtime-effective metadata.
- Studio asset details mapping forwards packer details without deriving a
runtime count from `palette_authored`.
- No DTO field was added because doing so would create a new Studio/packer API
surface not required by `DEC-0038`.
## Dependencies
- Depends on `PLN-0088`.
- Can run in parallel with `PLN-0089` after metadata semantics are stable.
## Risks
- UI code may still need ARGB helper fields for presentation. This plan must not
turn that into a runtime metadata decision.
- Overbroad projection edits could accidentally change scene contracts.
@@ -1,167 +0,0 @@
---
id: PLN-0091
ticket: variable-tile-bank-palette-serialization
title: Variable Glyph Palette Tests, Fixtures, and Final Validation
status: done
created: 2026-07-14
completed: 2026-07-14
ref_decisions:
- DEC-0038
tags:
- tests
- fixtures
- validation
- glyph-bank
- palette-serialization
---
## Objective
Update tests and fixtures to prove Studio/packer emit runtime-conforming
variable glyph palette payloads and contain no stale fixed-padding assumptions.
## Background
`DEC-0038` requires downstream fixture coverage for `palette_count = 1`, an
intermediate count, and `palette_count = 64`, plus producer validation for
metadata/payload mismatch. Earlier tests still assert `palette_count = 64`,
4096-byte palette blocks, and fixed glyph payload sizes.
## Scope
### Included
- Update packer unit tests and integration-style workspace tests.
- Update packer fixture `asset.json` files and expected runtime payload checks.
- Update Studio tests only where Studio projections or UI logic expose
effective palette count.
- Run focused and broad validation.
### Excluded
- Runtime repository tests.
- New feature design.
- Palette remapping behavior.
## Execution Steps
### Step 1 - Update packer parser and metadata tests
**What:** Prove effective `palette_count` validation.
**How:** Add tests for `palette_count = 1`, intermediate counts, `64`,
duplicate/sparse direct identity behavior, and rejection above `64`.
**File(s):**
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/PackerAssetDeclarationParserTest.java`
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/repositories/PackerGlyphBankWalkerTest.java`
### Step 2 - Update payload and asset table tests
**What:** Prove variable payload lengths and size formulas.
**How:** Replace fixed 4096-byte expectations with
`palette_count * 16 * 4`. Assert `size`, `decoded_size`, payload offsets, and
RGBA bytes for several counts.
**File(s):**
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/FileSystemPackerWorkspaceServiceTest.java`
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/repositories/PackerRuntimeAssetMaterializerTest.java`
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/PackerRuntimePatchServiceTest.java`
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/PackerRuntimeRegistryTest.java`
### Step 3 - Update fixtures
**What:** Replace stale fixed-padding fixtures.
**How:** Regenerate or edit packer test fixtures so at least one glyph bank uses
`palette_count = 1`, one uses an intermediate count, and one uses `64`.
Fixtures with fixed 64 padding are valid only when metadata says
`palette_count = 64`.
**File(s):**
- `prometeu-packer/prometeu-packer-v1/src/test/resources/fixtures/**/asset.json`
- Related binary or generated expected payload fixtures under packer test
resources.
### Step 4 - Update Studio tests
**What:** Cover Studio-facing projection changes.
**How:** Adjust tests only where Studio surfaces effective palette counts or
metadata. Keep color rendering assertions focused on `rgba8888`.
**File(s):**
- `prometeu-studio/src/test/java/p/studio/workspaces/assets/details/**`
### Step 5 - Run validation and residue scans
**What:** Prove no normal-path fixed-padding residue remains.
**How:** Run relevant Gradle tests and search normal specs/code/tests/fixtures
for stale `palette_count = 64`, `4096`, fixed `64 * 16 * 4`, `GLYPH/indexed_v2`,
and sparse remapping language. Classify any remaining match as historical,
max-bound, or a bug.
**File(s):**
- `docs/specs/packer/**`
- `docs/specs/studio/**`
- `prometeu-packer/**`
- `prometeu-studio/**`
## Test Requirements
### Unit Tests
- Packer parser, walker, materializer, details/read, and workspace service tests
pass.
- Studio asset details tests pass where touched.
### Integration Tests
- Packer workspace build/materialization tests pass.
- Repository build or narrow Studio/packer build validation passes.
### Manual Verification
- Residue scan finds no normal-path fixed-padding contract text or code.
- `discussion validate` passes.
## Acceptance Criteria
- [x] Tests cover `palette_count = 1`, an intermediate count, and `64`.
- [x] Tests cover variable `size` and `decoded_size`.
- [x] Tests cover emitted palette byte length and RGBA order.
- [x] Tests cover metadata/payload mismatch rejection or producer validation.
- [x] Fixtures no longer rely on fixed 64-palette padding unless count is `64`.
- [x] Validation commands pass.
- [x] Residue scan results are clean or explicitly classified.
## Execution Notes
- Added packer workspace coverage for `palette_count = 1` and intermediate
`palette_count = 7`.
- Existing fixture and build paths continue to cover `palette_count = 64` where
a max-count payload is intended.
- Added parser coverage rejecting palette declaration index `64`, preserving
the v1 maximum effective count of `64` through direct ids `0..63`.
- `:prometeu-packer:prometeu-packer-v1:test` passed.
- `./gradlew build` passed.
- Residue scan found only intentional normative statements rejecting
`convertedRgb565`, `GLYPH/indexed_v2`, fixed-padding compatibility, and
sparse-to-dense remapping.
## Dependencies
- Depends on `PLN-0087`, `PLN-0088`, `PLN-0089`, and `PLN-0090`.
## Risks
- Generated project fixtures may require regeneration rather than manual edits.
- Broad residue scans may include historical discussions; scope final checks to
active specs, code, tests, and fixtures.