120 lines
11 KiB
Markdown
120 lines
11 KiB
Markdown
---
|
|
id: PLN-0048
|
|
ticket: glyph-bank-naming-alignment-with-runtime
|
|
title: Implement Glyph Bank Local Alignment
|
|
status: done
|
|
created: 2026-04-10
|
|
completed: 2026-04-10
|
|
tags: [packer, studio, naming, asset-contract, runtime-alignment, glyph-bank]
|
|
---
|
|
|
|
## Objective
|
|
|
|
Implement DEC-0025 by renaming the concrete graphical bank artifact from `tile bank` to `glyph bank` across active `packer` and `studio` code, serialized contract surfaces, specs, fixtures, tests, and maintained repository documentation, with no compatibility layer and no functional behavior change.
|
|
|
|
## Background
|
|
|
|
The runtime repository already accepted `DEC-0006`, which reserves `tile` for geometric, map, and layer concepts while moving the concrete graphical bank artifact to `GlyphBank` and `GLYPH`. This repository still exposes the old naming through local asset-family values, output formats, emitted bank types, Studio asset-family handling, specs, and fixtures. The accepted local decision locks a one-wave rename with no fallback parsing, no aliasing, and no staged split between `packer` and `studio`.
|
|
|
|
## Scope
|
|
|
|
### Included
|
|
- Rename the serialized asset-family contract from `tile_bank` to `glyph_bank`.
|
|
- Rename the serialized output-format contract from `TILES/indexed_v1` to `GLYPH/indexed_v1`.
|
|
- Rename emitted runtime-facing `bank_type` values from `TILES` to `GLYPH`.
|
|
- Rename packer and Studio artifact-specific code surfaces that still describe the concrete graphical bank as `Tile*` or `glyph bank`.
|
|
- Update fixtures, tests, specs, and maintained lessons/discussion artifacts that refer to the concrete graphical bank artifact.
|
|
- Preserve `tile` terminology where the meaning remains geometric, map-related, layer-related, or otherwise outside the artifact boundary.
|
|
|
|
### Excluded
|
|
- Any payload, layout, metadata, codec, or packing behavior change.
|
|
- Any compatibility parser, alias layer, or dual support for the previous serialized names.
|
|
- Renaming geometric tile-size concepts or map/layer terminology that is still semantically correct.
|
|
- Any broader runtime-side rename work already owned by `../runtime`.
|
|
|
|
## Execution Steps
|
|
|
|
### Step 1 - Rename the packer serialized contract surface
|
|
|
|
**What:** Migrate the local packer contract enums and parser-facing surfaces from `tile_bank` / `TILES/indexed_v1` / `TILES` to `glyph_bank` / `GLYPH/indexed_v1` / `GLYPH`.
|
|
**How:** Rename `AssetFamilyCatalog.TILE_BANK`, `OutputFormatCatalog.TILES_INDEXED_V1`, parser validation strings, materialized `bank_type` values, and any packer-owned contract constants or messages tied to the concrete artifact. Keep semantics unchanged and do not introduce compatibility parsing for the old names.
|
|
**File(s):** `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/messages/assets/AssetFamilyCatalog.java`; `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/messages/assets/OutputFormatCatalog.java`; `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/PackerAssetDeclarationParser.java`; `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/PackerOutputContractCatalog.java`; `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/FileSystemPackerWorkspaceService.java`
|
|
**Dependencies:** None.
|
|
|
|
### Step 2 - Rename packer artifact-specific implementation surfaces
|
|
|
|
**What:** Rename packer implementation types, walkers, requirements, helper methods, and diagnostics that describe the concrete graphical bank artifact.
|
|
**How:** Rename artifact-specific `TileBank` classes, helpers, and strings to `Glyph*` equivalents while preserving `tile` in geometric concepts such as `tileSize`. Adjust callsites consistently so active code no longer uses mixed vocabulary for the concrete artifact.
|
|
**File(s):** `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/models/PackerGlyphBankRequirements.java`; `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`; `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/FileSystemPackerWorkspaceService.java`
|
|
**Dependencies:** Step 1.
|
|
|
|
### Step 3 - Rename Studio artifact-specific surfaces 1:1
|
|
|
|
**What:** Align Studio asset-family handling, bank composition support, palette overhauling gating, list/details presentation, and artifact labels with the new glyph naming.
|
|
**How:** Rename Studio classes, switches, and i18n keys/labels that refer to the concrete graphical bank artifact, keeping the rename artifact-specific and preserving any remaining geometric `tile` semantics outside that boundary. Studio must use the same canonical artifact vocabulary as the packer contract.
|
|
**File(s):** `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/bank/AssetDetailsGlyphBankCompositionFamilySupport.java`; `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/bank/AssetBankCapacityService.java`; `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/bank/AssetDetailsBankCompositionCoordinator.java`; `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/palette/AssetDetailsPaletteOverhaulingCoordinator.java`; `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/AssetDetailsUiSupport.java`; `prometeu-studio/src/main/java/p/studio/workspaces/assets/list/AssetListItemControl.java`; `prometeu-studio/src/main/java/p/studio/utilities/i18n/I18n.java`
|
|
**Dependencies:** Steps 1 and 2.
|
|
|
|
### Step 4 - Update specs, lessons, and maintained discussion text by meaning
|
|
|
|
**What:** Rewrite maintained documentation so the concrete graphical bank artifact uses glyph naming, while tile-domain concepts remain tile-domain concepts.
|
|
**How:** Update packer specs and maintained lessons/discussions manually by artifact meaning. Replace artifact-specific `tile bank` references with `glyph bank`, `glyph_bank`, `GLYPH/indexed_v1`, or `GLYPH` as appropriate, but preserve `tile` where it refers to tile geometry, tilemaps, layers, or palette-per-tile semantics.
|
|
**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`; `discussion/lessons/DSC-0003-packer-docs-import/LSN-0015-tile-bank-packing-contract-legacy.md`; `discussion/workflow/agendas/AGD-0002-palette-management-in-studio.md`; `discussion/workflow/agendas/AGD-0005-variable-tile-bank-palette-serialization.md`
|
|
**Dependencies:** Step 1.
|
|
|
|
### Step 5 - Migrate fixtures and tests in the same wave
|
|
|
|
**What:** Rename manifests, fixture content, test expectations, and helper names to the new serialized contract and artifact vocabulary.
|
|
**How:** Update test assets and fixtures that still use `type = tile_bank` and `format = TILES/indexed_v1`, then update unit and integration tests in `prometeu-packer` and `prometeu-studio` so expectations point to `glyph_bank`, `GLYPH/indexed_v1`, and `GLYPH`. Keep assertion coverage focused on proving no behavior change beyond naming.
|
|
**File(s):** `test-projects/main/assets/**/asset.json`; `prometeu-packer/prometeu-packer-v1/src/test/resources/fixtures/workspaces/**/asset.json`; `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`; `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/FileSystemPackerWorkspaceServiceTest.java`; `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/repositories/PackerGlyphBankWalkerTest.java`; `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/repositories/PackerRuntimeAssetMaterializerTest.java`; `prometeu-studio/src/test/java/p/studio/workspaces/assets/details/bank/AssetDetailsBankCompositionCoordinatorTest.java`; `prometeu-studio/src/test/java/p/studio/workspaces/assets/details/palette/AssetDetailsPaletteOverhaulingCoordinatorTest.java`
|
|
**Dependencies:** Steps 1 through 4.
|
|
|
|
### Step 6 - Validate the one-wave rename
|
|
|
|
**What:** Run focused verification across packer and Studio to prove the new vocabulary is canonical and behavior is unchanged.
|
|
**How:** Execute the relevant test suites, review representative specs/fixtures, and search for residual concrete-artifact `tile bank` references. Classify any remaining `tile` occurrence as either correct geometric/domain meaning or a rename miss to be fixed before completion.
|
|
**File(s):** all files touched by Steps 1 through 5
|
|
**Dependencies:** Steps 1 through 5.
|
|
|
|
## Test Requirements
|
|
|
|
### Unit Tests
|
|
|
|
- Update packer parser, walker, materializer, and workspace-service tests to use `glyph_bank`, `GLYPH/indexed_v1`, and `GLYPH`.
|
|
- Update Studio asset-details and palette/bank tests to use the renamed artifact-family symbols and labels.
|
|
|
|
### Integration Tests
|
|
|
|
- Run packer tests that exercise manifest parsing, fixture loading, pack execution, and emitted `bank_type` values.
|
|
- Run Studio tests that exercise asset-family-specific bank composition and palette overhauling paths.
|
|
|
|
### Manual Verification
|
|
|
|
- Inspect updated packer specs to confirm artifact-specific references use glyph naming while geometric tile concepts remain unchanged.
|
|
- Search the repository for residual `tile bank` / `TileBank` / `tile_bank` / `TILES/indexed_v1` references and classify each remaining hit.
|
|
- Inspect representative fixture manifests and packed output expectations to confirm the rename is contract-wide and behavior-preserving.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] Active local serialized contract surfaces use `glyph_bank`, `GLYPH/indexed_v1`, and `GLYPH` for the concrete graphical bank artifact.
|
|
- [ ] No compatibility layer or alias remains for the old serialized names on active maintained surfaces.
|
|
- [ ] Packer artifact-specific code no longer uses mixed `Tile*`/`Glyph*` vocabulary for the same concrete artifact.
|
|
- [ ] Studio artifact-specific code follows the renamed glyph vocabulary 1:1.
|
|
- [ ] Maintained specs and lessons describe the concrete graphical bank artifact with glyph naming while preserving geometric/map/layer tile terminology where appropriate.
|
|
- [ ] Fixtures and tests are migrated in the same wave as the implementation.
|
|
- [ ] Relevant packer and Studio tests pass after the rename.
|
|
- [ ] No functional behavior change is introduced beyond naming propagation.
|
|
|
|
## Dependencies
|
|
|
|
- Accepted decision `DEC-0025`.
|
|
- Upstream runtime naming contract in `../runtime` `DEC-0006`.
|
|
- Coordinated updates across `prometeu-packer`, `prometeu-studio`, maintained docs, and fixture manifests.
|
|
|
|
## Risks
|
|
|
|
- Blind mechanical renaming can incorrectly touch geometric tile semantics that are explicitly out of scope.
|
|
- Removing old serialized names without compatibility means any missed fixture or parser path will fail fast and block the wave.
|
|
- Studio and packer may drift if one side is renamed more aggressively than the other during implementation.
|
|
- Historical or maintained discussion artifacts can keep mixed terminology if they are not reviewed semantically.
|