--- 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.