Glyph Bank Domain Naming Contract
This commit is contained in:
@@ -0,0 +1,93 @@
|
||||
---
|
||||
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.
|
||||
Reference in New Issue
Block a user