bQUARKz
035e9d5676
Reviewed-on: #12 Co-authored-by: bQUARKz <bquarkz@gmail.com> Co-committed-by: bQUARKz <bquarkz@gmail.com>
2.5 KiB
| id | ticket | title | created | tags | |||||
|---|---|---|---|---|---|---|---|---|---|
| LSN-0025 | tile-bank-vs-glyph-bank-domain-naming | Rename Artifact by Meaning, Not by Token | 2026-04-10 |
|
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.