94 lines
4.9 KiB
Markdown
94 lines
4.9 KiB
Markdown
---
|
|
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.
|