Intrepid/prometeu-runtime
Intrepid/prometeu-runtime
3
0
Fork 0
Code Pull Requests Activity
prometeu-runtime/discussion/workflow/decisions/DEC-0006-glyph-bank-domain-naming-contract.md

4.9 KiB
Raw Blame History

id ticket title status created accepted agenda plans tags
DEC-0006 tile-bank-vs-glyph-bank-domain-naming Glyph Bank Domain Naming Contract accepted 2026-04-10 2026-04-10 AGD-0020
PLN-0005
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.