---
id: LSN-0025
ticket: tile-bank-vs-glyph-bank-domain-naming
title: Rename Artifact by Meaning, Not by Token
created: 2026-04-10
tags: [gfx, runtime, naming, refactor, documentation]
---

## Context

The runtime used `TileBank` as the name of the concrete graphical bank artifact while also using `tile` for map, layer, and geometric concepts such as `TileLayer`, `TileMap`, and `TileSize`. This overloaded the term `tile` across two different meanings.

The implemented migration renamed only the concrete bank artifact to `GlyphBank` and renamed the corresponding asset-bank contract from `BankType::TILES` to `BankType::GLYPH`, while explicitly preserving `TileLayer`, `TileMap`, and `TileSize`.

## Key Decisions

### Glyph Bank Domain Naming Contract

**What:**
Rename the concrete graphical bank artifact and its runtime interfaces to `GlyphBank`, but keep tile-domain structures unchanged where `tile` still correctly describes layers, maps, grids, and geometry.

**Why:**
The goal was domain clarity, not behavior change. The project needed a more precise name for the concrete graphical bank without reopening rendering architecture or erasing valid uses of `tile`.

**Trade-offs:**
This requires more care than a blind search-and-replace. The migration is broader editorially, but safer semantically, because it avoids damaging concepts that still belong in the tile domain.

## Patterns and Algorithms

- Rename by artifact meaning, not by string token frequency.
- When a term is overloaded, split the rename along domain boundaries instead of trying to enforce total lexical uniformity.
- Let the runtime contract adopt the new canonical artifact name (`GlyphBank`, `BankType::GLYPH`) while preserving existing terms for excluded concepts (`TileLayer`, `TileMap`, `TileSize`).
- Apply the same semantic rule to docs and lessons, not only to code.

## Pitfalls

- Blind replacement would have incorrectly renamed tile-layer and tile-size concepts that were intentionally out of scope.
- Partial renames create mixed vocabulary, which is worse than either old or new terminology used consistently.
- Historical documentation is especially easy to corrupt if rewritten mechanically instead of by artifact meaning.

## Takeaways

- A naming refactor can be rename-only in behavior while still requiring architectural discipline in wording.
- Use one canonical name per artifact, but do not force unrelated domains to share that rename.
- Documentation migrations should follow the same semantic boundary as code migrations, or the codebase will drift back into conceptual ambiguity.