prometeu-studio/discussion/lessons/DSC-0026-glyph-bank-naming-alignment-with-runtime/LSN-0040-glyph-bank-artifact-naming-alignment.md

Glyph Bank Artifact Naming Alignment

The graphical bank artifact, which stores indexed graphical data (glyphs) for runtime consumption, has been aligned with the unified project vocabulary across packer, studio, and runtime.

Original Problem

Previously, the project used inconsistent terminology for the same concrete artifact:

• tile_bank in some packer configurations.
• TILES/indexed_v1 as an output format.
• TILES as a runtime-facing bank_type.
• TileBank or tile bank in Studio UI and internal code.

This created a conceptual overlap with the "tile" domain, which properly refers to geometric sizes, map layers, and grid-based rendering logic. Keeping the artifact named "tile bank" made it difficult to distinguish between the storage container (the bank) and the geometric entities (the tiles) stored within or referenced by it.

Consolidated Decision

Following DEC-0025 (this repository) and DEC-0006 (runtime repository), the concrete graphical bank artifact is now exclusively referred to as Glyph Bank.

1. Artifact Name: glyph_bank (serialized asset-family).
2. Output Format: GLYPH/indexed_v1.
3. Runtime ID: GLYPH (bank_type).
4. Vocabulary Split:
   • Use Glyph when referring to the graphical data bank, its capacity, or its storage format.
   • Use Tile only for geometric concepts (tile size, tile maps, tile layers, coordinate grids).

Implementation Results

• Packer: All AssetFamilyCatalog, OutputFormatCatalog, and walker implementations now use the Glyph* vocabulary. Parser validation now expects type: glyph_bank.
• Studio: UI labels, composition coordinators, and internal services have been renamed to Glyph Bank to match the packer and runtime contracts.
• Contract: No compatibility layer was introduced. All fixtures and test assets were migrated in a single wave to ensure a clean, unified contract.

Common Pitfalls and Anti-patterns

• Incorrect Rename: Do not rename tileSize to glyphSize. A tile is a geometric unit; a glyph is the graphical content within that unit or the bank that stores it.
• Legacy Fixtures: Since there is no compatibility layer, old asset.json files with type: tile_bank will fail to parse. They must be updated to type: glyph_bank.

References

• DEC-0025: Local decision for Glyph Bank alignment.
• PLN-0048: Implementation plan for the naming migration.
• docs/specs/packer/: Updated specifications for asset declarations.