---
id: DEC-0006
ticket: tile-bank-vs-glyph-bank-domain-naming
title: Glyph Bank Domain Naming Contract
status: accepted
created: 2026-04-10
accepted: 2026-04-10
agenda: AGD-0020
plans: [PLN-0005]
tags: [gfx, runtime, naming, domain-model]
---

## Status

Accepted on 2026-04-10.

## Contexto

The runtime currently uses `TileBank` and related names for the concrete graphical bank consumed by the asset pipeline and renderer. At the same time, the project wants `Tile` to remain available as a broader domain concept for grid, layer, map, and geometric tile semantics.

This decision closes the naming contract by separating:

- the concrete graphical bank artifact;
- the logical tile/layer/map domain;
- the migration boundary for code, tests, docs, and historical lessons.

The change is explicitly rename-only. It does not alter format, runtime behavior, memory layout, payload structure, or renderer algorithms.

## Decisao

1. The concrete graphical bank currently named `TileBank` MUST be renamed to `GlyphBank`.
2. This rename MUST be treated as nomenclature-only. It MUST NOT change payload format, runtime behavior, memory layout, codec behavior, metadata structure, or rendering semantics.
3. `BankType::TILES` MUST be renamed to `BankType::GLYPH`.
4. The asset contract and runtime code that refer to the concrete graphical bank MUST migrate to `Glyph*` naming consistently.
5. The following groups MUST be included in the rename:
   - concrete bank type and module;
   - asset contract and asset-facing terminology;
   - memory pools and bank installation/access interfaces;
   - asset manager decode/load path;
   - renderer and hardware references to the concrete bank;
   - fixtures, test names, helper names, and user-facing/runtime-facing strings for the concrete bank;
   - documentation and historical lessons, subject to the editorial boundary below.
6. The following groups MUST NOT be renamed as part of this decision:
   - `TileLayer`, `TileMap`, `ScrollableTileLayer`, `HudTileLayer`, and related layer/map structures;
   - `TileSize` and geometric tile-size concepts.
7. Documentation and historical lessons MUST be updated with the following editorial rule:
   - references to the concrete graphical bank artifact MUST migrate to `GlyphBank` and equivalent `Glyph*` naming;
   - references to layer, map, grid, or geometric tile concepts MUST remain `tile` when that is the correct domain meaning.
8. The project MUST NOT adopt a partial mixed vocabulary where the same concrete bank artifact is simultaneously described as both `TileBank` and `GlyphBank` in active code or maintained documentation.
9. `glyph` is treated as a new canonical artifact name for this stage and does not conflict with an existing canonical artifact that would block adoption.

## Rationale

- The current name overloads `tile` across both logical map/layer concepts and the concrete graphical bank artifact.
- Renaming only the concrete bank artifact improves domain clarity without reopening graphics architecture.
- Excluding `TileLayer`, `TileMap`, and `TileSize` preserves established semantics where `tile` still means the logical or geometric concept.
- A full migration across code, tests, docs, and lessons avoids the unstable mixed-language state that tends to follow partial renames.

## Invariantes / Contrato

- `GlyphBank` is the canonical name for the concrete graphical bank artifact.
- `tile` remains canonical for layer/map/geometric concepts unless a later decision explicitly changes that.
- `BankType::GLYPH` is the canonical asset-bank enum variant for the concrete graphical bank.
- This decision is a rename boundary, not a behavior-change boundary.
- Documentation must follow artifact meaning, not mechanical string replacement.

## Impactos

- `prometeu-hal` will need type/module/enum renames for the concrete graphical bank path.
- `prometeu-drivers` will need renderer, memory-pool, hardware, and asset-manager naming migration for bank-specific references.
- Tests, fixtures, and helper names need coordinated updates to avoid mixed terminology.
- Docs and lessons need targeted rewriting rather than blind search-and-replace, because `tile` remains correct in map/layer contexts.

## Referencias

- AGD-0020: Tile Bank vs Glyph Bank Domain Naming
- LSN-0022: Tilemap Empty Cell Convergence
- `crates/console/prometeu-hal/src/tile_bank.rs`
- `crates/console/prometeu-hal/src/tile_layer.rs`
- `crates/console/prometeu-drivers/src/gfx.rs`
- `crates/console/prometeu-drivers/src/memory_banks.rs`
- `crates/console/prometeu-drivers/src/asset.rs`

## Propagacao Necessaria

- Write an execution plan before code and documentation migration.
- Rename the concrete bank surface consistently across runtime crates.
- Preserve `tile` naming in layer/map/geometric surfaces excluded by this decision.
- Update docs and lessons according to artifact meaning, not blanket replacement.

## Revision Log

- 2026-04-10: Initial accepted decision from AGD-0020.