bQUARKz
035e9d5676
All checks were successful
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
Reviewed-on: #12 Co-authored-by: bQUARKz <bquarkz@gmail.com> Co-committed-by: bQUARKz <bquarkz@gmail.com>
46 lines
2.5 KiB
Markdown
46 lines
2.5 KiB
Markdown
---
|
|
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.
|