Intrepid/prometeu-studio
Intrepid/prometeu-studio
3
0
Fork 0
Code Pull Requests 1 Activity
prometeu-studio/discussion/workflow/plans/PLN-0048-implement-glyph-bank-local-alignment.md

11 KiB
Raw Blame History

id ticket title status created completed tags
PLN-0048 glyph-bank-naming-alignment-with-runtime Implement Glyph Bank Local Alignment done 2026-04-10 2026-04-10
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.