Variable Glyph Bank Palette Serialization

This commit is contained in:
2026-07-14 16:23:42 +01:00
parent 3f99e90ac8
commit 013ca4355c
18 changed files with 1237 additions and 1491 deletions
@@ -1,136 +0,0 @@
---
id: PLN-0081
ticket: studio-packer-rgba8888-asset-pipeline
title: RGBA8888 Packer and Studio Spec Propagation
status: done
created: 2026-05-23
completed: 2026-05-23
ref_decisions:
- DEC-0037
tags:
- specs
- packer
- studio
- rgba8888
---
## Objective
Propagate `DEC-0037` into the normative Studio and packer specifications before
code implementation starts.
## Background
`DEC-0037` keeps `GLYPH/indexed_v1` but changes its palette contract from
RGB565 to RGBA8888. Specs currently still describe RGB565 palette bytes,
`convertedRgb565`, and a 2048-byte palette block.
## Scope
### Included
- Update packer specs for `asset.json` palette metadata and `assets.pa`
glyph-bank payload layout.
- Update Studio asset workspace specs if they expose palette metadata or
details/read projection behavior.
- Preserve the fixed 64-palette model and explicitly leave `DSC-0005` for a
later palette-count optimization.
### Excluded
- Code changes.
- Test changes.
- Variable palette-count serialization.
- Runtime spec changes, except references to runtime `DEC-0029`.
## Execution Steps
### Step 1 - Update asset declaration palette fields
**What:** Replace `originalArgb8888`/`convertedRgb565` examples and rules with
canonical `rgba8888`.
**How:** Edit the palette portions of the asset declaration spec so
`output.pipeline.palettes[*].palette.rgba8888` is the canonical field. State
that ARGB may be an input API detail but is not canonical authored/projected
palette data.
**File(s):**
- `docs/specs/packer/3. Asset Declaration and Virtual Asset Contract Specification.md`
### Step 2 - Update glyph-bank payload layout
**What:** Change `GLYPH/indexed_v1` palette layout from RGB565 to RGBA8888.
**How:** Keep the format name. Change the palette block from
`64 * 16 * 2 = 2048` bytes to `64 * 16 * 4 = 4096` bytes. Update size and
decoded-size formulas. State that palette entries use runtime RGBA channel
order.
**File(s):**
- `docs/specs/packer/4. Build Artifacts and Deterministic Packing Specification.md`
### Step 3 - Document alpha and index semantics
**What:** Document that palette index `0` is ordinary and all 16 palette entries
are usable.
**How:** Add normative rules that transparency and partial transparency are
encoded only by RGBA alpha, magenta color-key is removed, and partial alpha is
valid palette data.
**File(s):**
- `docs/specs/packer/3. Asset Declaration and Virtual Asset Contract Specification.md`
- `docs/specs/packer/4. Build Artifacts and Deterministic Packing Specification.md`
### Step 4 - Update Studio-facing projection rules
**What:** Ensure Studio-facing docs use `rgba8888` where palette metadata is
visible.
**How:** Update asset workspace language only where it describes palette read,
details, scene preview, or palette default behavior. Keep scene `palette_id`
semantics unchanged.
**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 `RGB565`, `convertedRgb565`, 2048-byte palette block,
reserved index `0`, and magenta color-key language.
## Acceptance Criteria
- [x] Packer specs define `rgba8888` as the canonical palette field.
- [x] `GLYPH/indexed_v1` remains named exactly that.
- [x] Palette block formulas use `64 * 16 * 4 = 4096`.
- [x] Specs state palette index `0` is ordinary and all 16 entries are usable.
- [x] Specs state partial alpha is valid and magenta color-key is removed.
- [x] Specs leave `DSC-0005` variable palette-count work out of scope.
## Dependencies
- Depends on accepted `DEC-0037`.
- Should complete before code plans are implemented.
## Risks
- Leaving stale RGB565 examples in specs will make implementation review
ambiguous.
- Over-editing scene specs could accidentally imply a scene payload change that
`DEC-0037` does not authorize.
@@ -1,144 +0,0 @@
---
id: PLN-0082
ticket: studio-packer-rgba8888-asset-pipeline
title: RGBA8888 Palette Model and ARGB Conversion
status: done
created: 2026-05-23
completed: 2026-05-23
ref_decisions:
- DEC-0037
tags:
- packer
- palette
- rgba8888
- conversion
---
## Objective
Replace the packer palette model with canonical RGBA8888 data and introduce a
single deliberate ARGB-to-RGBA conversion boundary for image inputs.
## Background
`PackerPaletteV1` currently stores `originalArgb8888` and `convertedRgb565`.
`PackerGlyphBankWalker` reads Java ARGB pixels, drops alpha semantics, reserves
index `0`, applies magenta color-key, and converts colors to RGB565.
## Scope
### Included
- Replace `PackerPaletteV1` fields with canonical `rgba8888`.
- Add or localize ARGB-to-RGBA conversion helpers.
- Preserve partial alpha.
- Remove RGB565 conversion from the normal palette model.
- Expand glyph palette extraction from 15 to 16 usable colors.
### Excluded
- Binary `assets.pa` emission changes.
- Read/detail API projection changes outside direct model compile fixes.
- Spec edits.
- Fixture regeneration for `main` and `fragments`.
## Execution Steps
### Step 1 - Replace the palette record
**What:** Change the packer palette model to carry canonical RGBA8888 values.
**How:** Replace `int[] originalArgb8888, short[] convertedRgb565` with
`int[] rgba8888`. Keep the record name only if it remains semantically useful;
otherwise rename only if all callers are updated in the same change.
**File(s):**
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/models/PackerPaletteV1.java`
### Step 2 - Convert ARGB image pixels to RGBA
**What:** Introduce one conversion path from Java `BufferedImage` ARGB to raw
runtime RGBA.
**How:** Convert `0xAARRGGBB` to `0xRRGGBBAA` when building palette entries.
Do not store ARGB in canonical packer metadata.
**File(s):**
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerGlyphBankWalker.java`
### Step 3 - Remove magenta color-key and reserved index behavior
**What:** Stop treating alpha zero or magenta as special palette-index behavior.
**How:** Remove `COLOR_KEY_RGB`. Build palette identity from full RGBA8888
values, including alpha. Assign indices from `0` through `15`.
**File(s):**
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerGlyphBankWalker.java`
### Step 4 - Preserve partial alpha
**What:** Remove partial-alpha warnings and flattening.
**How:** Delete the `partialAlphaFound` warning path. Ensure pixels with alpha
from `0` through `255` participate in palette extraction by full RGBA value.
**File(s):**
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerGlyphBankWalker.java`
### Step 5 - Update color-limit validation
**What:** Change validation from 15 usable colors to 16 usable colors.
**How:** Replace `MAX_COLORS_PER_PALETTE = 15` with a 16-entry limit and update
diagnostic wording to remove `indices 1..15`.
**File(s):**
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerGlyphBankWalker.java`
## Test Requirements
### Unit Tests
- Update `PackerGlyphBankWalkerTest` to assert:
- 16 unique RGBA colors are valid.
- a 17th unique RGBA color is blocking.
- alpha `0`, partial alpha, and alpha `255` are preserved.
- magenta is treated as an ordinary color.
- palette index `0` can hold an ordinary color.
### Integration Tests
- None for this plan; binary emission is covered by a later plan.
### Manual Verification
- Search packer model and glyph walker sources for `convertedRgb565`,
`originalArgb8888`, `COLOR_KEY_RGB`, `convertToRgb565`, and partial-alpha
warning text.
## Acceptance Criteria
- [x] `PackerPaletteV1` exposes `rgba8888` and no RGB565 field.
- [x] `PackerGlyphBankWalker` stores canonical RGBA values.
- [x] Magenta is not special.
- [x] Alpha zero and partial alpha are valid palette data.
- [x] All 16 palette indices are usable.
- [x] Unit tests cover conversion and palette indexing semantics.
## Dependencies
- Depends on `PLN-0081` for spec wording.
- Must complete before payload emission and projection plans.
## Risks
- Confusing Java ARGB input with runtime RGBA output will create hard-to-debug
byte-order failures.
- Cache reuse may keep stale palette metadata if reusable metadata checks are
not updated with the model change.
@@ -1,145 +0,0 @@
---
id: PLN-0083
ticket: studio-packer-rgba8888-asset-pipeline
title: RGBA8888 Glyph Payload Emission and Size Accounting
status: done
created: 2026-05-23
completed: 2026-05-23
ref_decisions:
- DEC-0037
tags:
- packer
- assets-pa
- glyph-bank
- rgba8888
---
## Objective
Change packer glyph-bank runtime payload emission from RGB565 palette bytes to
RGBA8888 palette bytes while keeping `GLYPH/indexed_v1` and the fixed
64-palette model.
## Background
`DEC-0037` requires `GLYPH/indexed_v1` to retain its format name and indexed
model but emit RGBA8888 palette entries. Current payload emission in
`FileSystemPackerWorkspaceService` writes RGB565 bytes, reserves index `0`, and
uses color-key bytes.
## Scope
### Included
- Update glyph-bank payload palette byte emission.
- Update measured payload size and decoded-size accounting.
- Remove RGB565 palette constants and palette color-key bytes from emission.
- Keep scene `palette_id` payload semantics unchanged.
### Excluded
- Palette model extraction changes covered by `PLN-0082`.
- Read/detail projection changes covered by `PLN-0084`.
- Variable palette count.
## Execution Steps
### Step 1 - Update glyph payload constants and formulas
**What:** Change palette entry width from 2 bytes to 4 bytes.
**How:** Introduce clear constants for palette count, colors per palette, and
RGBA bytes per color. Use `64 * 16 * 4` for palette block size.
**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 RGBA8888 palette bytes
**What:** Write each palette color as runtime RGBA channel bytes.
**How:** Replace RGB565 little-endian writes with four byte writes in `R`, `G`,
`B`, `A` order derived from the canonical `rgba8888` integer value.
**File(s):**
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/FileSystemPackerWorkspaceService.java`
### Step 3 - Remove reserved color-key emission
**What:** Stop writing a synthetic color-key value at palette index `0`.
**How:** Remove `GLYPH_BANK_COLOR_KEY_RGB565` and any emission path that fills
index `0` with magenta. Emit declared RGBA values for index `0` like every
other index.
**File(s):**
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/FileSystemPackerWorkspaceService.java`
### Step 4 - Update declared palette lookup
**What:** Read `rgba8888` from declared pipeline metadata.
**How:** Replace `originalArgb8888`/`convertedRgb565` lookup paths with
`rgba8888`. Ensure empty or malformed `rgba8888` is structural failure where
emission requires a palette.
**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`
### Step 5 - Keep scene payload stable
**What:** Preserve scene `palette_id` layout.
**How:** Do not change `writeSceneBankPayload` except compile fixes caused by
shared helper changes. Scene tile records continue carrying `palette_id` as an
index into the referenced glyph palette.
**File(s):**
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/FileSystemPackerWorkspaceService.java`
## Test Requirements
### Unit Tests
- Add or update tests asserting glyph payload size includes a 4096-byte palette
block.
- Assert emitted palette bytes for a known RGBA value, including alpha.
- Assert index `0` emits declared RGBA data, not magenta.
### Integration Tests
- Update workspace build tests that read `build/assets.pa` and assert glyph-bank
offsets/sizes.
### Manual Verification
- Search production packer code for `GLYPH_BANK_COLOR_KEY_RGB565`,
`convertedRgb565`, RGB565 palette byte writes, and hard-coded `2048`.
## Acceptance Criteria
- [x] Glyph payloads keep `GLYPH/indexed_v1`.
- [x] Glyph palette blocks are 4096 bytes.
- [x] Palette entries are emitted as RGBA bytes in runtime channel order.
- [x] No synthetic magenta/color-key value is emitted.
- [x] Size and decoded-size metadata match the new payload length.
- [x] Scene `palette_id` payload shape is unchanged.
## Dependencies
- Depends on `PLN-0082`.
- Should run before tests/fixture conformance in `PLN-0085`.
## Risks
- Updating size formulas without updating emitted bytes, or vice versa, will
corrupt payload slicing in `assets.pa`.
- Accidental scene payload edits could widen the change beyond `DEC-0037`.
@@ -1,141 +0,0 @@
---
id: PLN-0084
ticket: studio-packer-rgba8888-asset-pipeline
title: RGBA8888 Packer Projections and Workspace APIs
status: done
created: 2026-05-23
completed: 2026-05-23
ref_decisions:
- DEC-0037
tags:
- packer
- studio
- api
- rgba8888
---
## Objective
Update packer and Studio-facing read/detail/write projections so palette data
is exposed and accepted as `rgba8888`, with no normal `convertedRgb565` or
canonical `originalArgb8888` surface.
## Background
`DEC-0037` requires packer metadata, Studio read/detail projections, tests, and
fixtures to stop treating RGB565 as normal palette data. Several services still
parse or project `originalArgb8888` and `convertedRgb565`.
## Scope
### Included
- Update parser and declaration normalization for palette metadata.
- Update read/detail mappers.
- Update palette-overhauling and bank-composition support to emit `rgba8888`.
- Preserve existing DTO shapes except for palette payload field names.
### Excluded
- Binary payload byte emission.
- Renderer/runtime changes.
- Manual regeneration of `main` and `fragments`.
## Execution Steps
### Step 1 - Update asset declaration parsing
**What:** Parse canonical `rgba8888` arrays from `asset.json`.
**How:** Replace palette validation that requires `originalArgb8888` and
`convertedRgb565` with validation for `rgba8888`. Keep numeric validation.
Reject malformed or missing `rgba8888` where a palette payload is required.
**File(s):**
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/PackerAssetDeclarationParser.java`
### Step 2 - Update details projection
**What:** Return `rgba8888` from asset details.
**How:** Change `palettePayloadFromNode` to project `{ index, rgba8888 }`.
Remove `convertedRgb565` and canonical `originalArgb8888` from details output.
**File(s):**
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/PackerAssetDetailsService.java`
### Step 3 - Update read message mapping
**What:** Map `PackerPaletteV1` and cached palette metadata to `rgba8888`.
**How:** Replace `originalArgb8888` and `convertedRgb565` mapping with a single
`rgba8888` array.
**File(s):**
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/PackerReadMessageMapper.java`
### Step 4 - Update workspace write operations
**What:** Ensure packer write APIs that apply palette changes persist `rgba8888`.
**How:** Replace palette-overhauling and related write-lane logic that requires
both `originalArgb8888` and `convertedRgb565` with a `rgba8888` contract.
**File(s):**
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/FileSystemPackerWorkspaceService.java`
### Step 5 - Update cache reuse and walk projection checks
**What:** Make cache reuse validate new palette metadata.
**How:** Replace reusable metadata checks for `originalArgb8888` with
`rgba8888`. Stale cached RGB565-derived metadata must not be considered
reusable.
**File(s):**
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerGlyphBankWalker.java`
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerAssetWalker.java`
## Test Requirements
### Unit Tests
- Update parser tests to accept `rgba8888` and reject missing/malformed
`rgba8888`.
- Update details service tests to assert `rgba8888`.
- Update read mapper coverage for `PackerPaletteV1`.
- Update write operation tests for palette overhauling.
### Integration Tests
- Exercise a workspace read/build flow from `asset.json` using `rgba8888`.
### Manual Verification
- Search `prometeu-packer` for `originalArgb8888` and `convertedRgb565` after
this plan. Remaining matches must be migration-only or removed in later
fixture plan.
## Acceptance Criteria
- [x] `asset.json` palette metadata uses `rgba8888`.
- [x] Details/read projections expose `rgba8888`.
- [x] Workspace write operations persist `rgba8888`.
- [x] Stale RGB565-derived cache metadata is not reused as canonical.
- [x] No normal API requires `convertedRgb565`.
## Dependencies
- Depends on `PLN-0082`.
- Can run partly in parallel with `PLN-0083` after the palette model is stable.
## Risks
- DTO consumers may assume old map keys. Tests must cover the Studio-facing
projection boundary.
- Cache reuse can hide stale behavior if not invalidated by metadata shape.
@@ -1,141 +0,0 @@
---
id: PLN-0085
ticket: studio-packer-rgba8888-asset-pipeline
title: RGBA8888 Tests, Fixtures, and Conformance Updates
status: done
created: 2026-05-23
completed: 2026-05-23
ref_decisions:
- DEC-0037
tags:
- tests
- fixtures
- conformance
- rgba8888
---
## Objective
Update packer tests and fixtures so RGBA8888 is the asserted source of truth and
RGB565-specific expectations are removed.
## Background
`DEC-0037` requires tests and fixtures to stop proving RGB565 behavior. The code
base has parser, walker, details, materializer, and workspace service tests that
mention `convertedRgb565`, `originalArgb8888`, 15-color limits, magenta
color-key behavior, and RGB565 payload sizes.
## Scope
### Included
- Update packer unit tests and integration-style workspace tests.
- Update fixture `asset.json` files under packer test resources.
- Add conformance-oriented assertions for RGBA channel order, alpha, index `0`,
16 usable colors, and removed color-key behavior.
### Excluded
- Manual regeneration of `test-projects/main` and `fragments`.
- Production code changes except minor compile-fix test helpers.
- Runtime repository tests.
## Execution Steps
### Step 1 - Update parser and details tests
**What:** Replace palette payload fixtures with `rgba8888`.
**How:** Rewrite test JSON snippets and assertions that mention
`originalArgb8888` or `convertedRgb565`.
**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/services/PackerAssetDetailsServiceTest.java`
### Step 2 - Update glyph walker tests
**What:** Assert new palette extraction semantics.
**How:** Add image fixtures in tests that cover:
16 colors, 17-color failure, alpha 0, partial alpha, magenta as ordinary color,
and index `0` as ordinary.
**File(s):**
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/repositories/PackerGlyphBankWalkerTest.java`
### Step 3 - Update materializer and workspace service tests
**What:** Assert RGBA8888 runtime payload and metadata behavior.
**How:** Update tests that read `assets.pa`, measured bank size, payload offsets,
and palette byte expectations. Replace RGB565 byte checks with RGBA byte checks.
**File(s):**
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/repositories/PackerRuntimeAssetMaterializerTest.java`
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/FileSystemPackerWorkspaceServiceTest.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 4 - Update packer fixture assets
**What:** Replace fixture `asset.json` palette fields with `rgba8888`.
**How:** Edit packer test fixtures under `src/test/resources/fixtures` so
canonical palette declarations do not contain `convertedRgb565`.
**File(s):**
- `prometeu-packer/prometeu-packer-v1/src/test/resources/fixtures/**/asset.json`
### Step 5 - Add stale-contract guards
**What:** Add tests or quality checks that catch old RGB565 palette contract
residue.
**How:** Add assertions in existing tests or a focused repository quality test
that normal packer specs/tests/fixtures do not contain `convertedRgb565` or
RGB565 glyph palette payload expectations.
**File(s):**
- Existing packer test suites under `prometeu-packer/prometeu-packer-v1/src/test/java`
## Test Requirements
### Unit Tests
- Parser, details, mapper, glyph walker, and workspace service unit tests must
all pass.
### Integration Tests
- Run the relevant Gradle test task for `prometeu-packer-v1`.
### Manual Verification
- Search for `convertedRgb565`, `originalArgb8888`, `RGB565`, `rgb565`, `2048`,
and magenta color-key references in packer tests and fixtures.
## Acceptance Criteria
- [x] Tests use `rgba8888` as canonical palette data.
- [x] Tests assert RGBA channel order and alpha preservation.
- [x] Tests assert 16 usable palette entries.
- [x] Tests assert magenta is ordinary or no longer special.
- [x] Tests assert 4096-byte palette blocks where payload size is checked.
- [x] Packer test fixtures no longer rely on `convertedRgb565`.
## Dependencies
- Depends on `PLN-0082`, `PLN-0083`, and `PLN-0084`.
## Risks
- Some stale generated fixture data may be easier to regenerate than hand-edit.
- Overbroad residue checks could flag historical discussion artifacts; scope
checks to normal specs, code, tests, and fixtures.
@@ -1,159 +0,0 @@
---
id: PLN-0086
ticket: studio-packer-rgba8888-asset-pipeline
title: RGBA8888 Final Integration and Residue Removal
status: done
created: 2026-05-23
completed: 2026-05-23
ref_decisions:
- DEC-0037
tags:
- integration
- validation
- residue-removal
- rgba8888
---
## Objective
Run final integration checks and remove normal-path RGB565 residue after the
spec, model, emission, projection, and test plans are implemented.
## Background
`DEC-0037` prohibits RGB565 compatibility mode, normal `convertedRgb565`
projection, magenta color-key behavior, reserved palette index `0`, and partial
alpha flattening. Final validation must prove that the repository implements
those constraints coherently.
## Scope
### Included
- Repository-wide residue audit.
- Full relevant Gradle test execution.
- Discussion workflow validation.
- Final implementation notes for follow-up plan or lesson creation.
### Excluded
- New feature design.
- Runtime repository changes.
- Variable palette-count work in `DSC-0005`.
- Manual regeneration of `main` and `fragments`.
## Execution Steps
### Step 1 - Run focused residue searches
**What:** Find stale RGB565 palette-contract residue.
**How:** Search production specs/code/tests/fixtures for:
`convertedRgb565`, `originalArgb8888`, `RGB565`, `rgb565`, `COLOR_KEY`,
`magenta`, `2048`, `indices 1..15`, and partial-alpha flattening text.
Classify each match as removed, historical discussion-only, or out-of-scope.
**File(s):**
- `docs/specs/packer/**`
- `docs/specs/studio/**`
- `prometeu-packer/**`
### Step 2 - Run packer tests
**What:** Execute the packer test suite.
**How:** Run the Gradle test task that covers `prometeu-packer-v1` and related
API modules.
**File(s):**
- Gradle modules under `prometeu-packer`
### Step 3 - Run broader build validation
**What:** Verify Studio build integration still compiles.
**How:** Run the repository's standard build or the narrowest existing Gradle
task that compiles Studio plus packer consumers.
**File(s):**
- Root Gradle project
- `prometeu-app`
- `prometeu-packer`
### Step 4 - Validate discussion workflow
**What:** Ensure discussion artifacts remain consistent.
**How:** Run `discussion validate` after implementation and before any
housekeeping.
**File(s):**
- `discussion/index.ndjson`
- `discussion/workflow/**`
### Step 5 - Record remaining intentional residue
**What:** Document any allowed remaining RGB565 references.
**How:** If matches remain only in historical discussions, runtime references,
or explicit future migration notes, list them in the implementation summary so
housekeeping and lesson work can distinguish intentional context from missed
normal-path behavior.
**File(s):**
- Implementation summary or future lesson, after code work is complete.
## Test Requirements
### Unit Tests
- Packer unit tests must pass.
### Integration Tests
- Packer workspace build/materialization tests must pass.
- Studio compile/build validation must pass.
### Manual Verification
- Residue search results must contain no normal-path `convertedRgb565`,
RGB565 glyph palette payload, magenta color-key, reserved index `0`, or
partial-alpha flattening behavior.
## Acceptance Criteria
- [x] `discussion validate` passes.
- [x] Packer tests pass.
- [x] Studio/packer build validation passes.
- [x] Normal specs/code/tests/fixtures contain no stale RGB565 glyph-palette
contract residue.
- [x] Remaining stale-looking matches, if any, are documented as historical or
explicitly out of scope.
- [x] `DSC-0005` remains untouched except by explicit future work.
## Execution Notes
- `discussion validate` passed.
- `./gradlew build` passed.
- Residue search found only:
- normative spec statements explicitly saying `convertedRgb565` and magenta
color-key behavior are not normal contract;
- `test-projects/main` asset manifests, which are intentionally out of scope
for this implementation because they will be regenerated manually later.
- `DSC-0005` was not modified.
## Dependencies
- Depends on `PLN-0081` through `PLN-0085`.
## Risks
- A broad residue search may include historical discussions and cause false
positives.
- Generated project cache files may change during tests; those changes must be
reviewed separately from source edits.
@@ -0,0 +1,132 @@
---
id: PLN-0087
ticket: variable-tile-bank-palette-serialization
title: Variable Glyph Palette Spec Propagation
status: open
created: 2026-07-14
completed:
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
- [ ] Packer specs define `palette_count` as runtime-effective `1..=64`.
- [ ] Packer specs use variable palette byte and size formulas.
- [ ] Specs keep `GLYPH/indexed_v1` and reject v2 for this change.
- [ ] Specs reject fixed-padding compatibility and sparse-to-dense remapping.
- [ ] 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`.
@@ -0,0 +1,140 @@
---
id: PLN-0088
ticket: variable-tile-bank-palette-serialization
title: Variable Glyph Palette Metadata and Count Model
status: open
created: 2026-07-14
completed:
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
- [ ] 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`.
@@ -0,0 +1,140 @@
---
id: PLN-0089
ticket: variable-tile-bank-palette-serialization
title: Variable Glyph Palette Payload Emission and Size Accounting
status: open
created: 2026-07-14
completed:
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
- [ ] 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.
@@ -0,0 +1,134 @@
---
id: PLN-0090
ticket: variable-tile-bank-palette-serialization
title: Studio and Packer Projections for Variable Glyph Palettes
status: open
created: 2026-07-14
completed:
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
- [ ] Packer read/details projections expose effective `palette_count`.
- [ ] Studio consumers do not use `palette_authored` as runtime-effective count.
- [ ] `rgba8888` color projection remains unchanged.
- [ ] Scene `palette_id` payload shape is unchanged.
- [ ] Tests cover variable count projection.
## 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.
@@ -0,0 +1,153 @@
---
id: PLN-0091
ticket: variable-tile-bank-palette-serialization
title: Variable Glyph Palette Tests, Fixtures, and Final Validation
status: open
created: 2026-07-14
completed:
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
- [ ] Tests cover `palette_count = 1`, an intermediate count, and `64`.
- [ ] Tests cover variable `size` and `decoded_size`.
- [ ] Tests cover emitted palette byte length and RGBA order.
- [ ] Tests cover metadata/payload mismatch rejection or producer validation.
- [ ] Fixtures no longer rely on fixed 64-palette padding unless count is `64`.
- [ ] Validation commands pass.
- [ ] Residue scan results are clean or explicitly classified.
## 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.