prometeu-runtime/discussion/workflow/plans/PLN-0005-glyph-bank-domain-naming-execution.md

id	ticket	title	status	created	completed	tags
PLN-0005	tile-bank-vs-glyph-bank-domain-naming	Glyph Bank Domain Naming Execution	accepted	2026-04-10		gfx runtime naming domain-model

Briefing

Implement DEC-0006 by renaming the concrete graphical bank artifact from TileBank to GlyphBank across runtime code, tests, documentation, and historical lessons, while preserving behavior and keeping the excluded tile-domain surfaces untouched. This is a rename-only migration. It must not alter payload format, rendering semantics, codec behavior, metadata structure, or memory layout.

Decisions de Origem

• DEC-0006: Glyph Bank Domain Naming Contract

Alvo

Land a consistent runtime-and-docs migration that:

• renames the concrete bank artifact and its module/type surface to GlyphBank;
• renames BankType::TILES to BankType::GLYPH;
• renames pool and loader/runtime bank-specific APIs accordingly;
• preserves TileLayer, TileMap, ScrollableTileLayer, HudTileLayer, and TileSize;
• rewrites maintained docs and lessons according to artifact meaning rather than blanket token replacement.

Escopo

• prometeu-hal concrete bank type/module/enum renames.
• prometeu-drivers renderer, memory-bank, hardware, and asset-manager bank-specific renames.
• prometeu-system callsites and dispatch paths that refer to the asset-bank enum variant.
• Tests, helpers, fixtures, and strings that still describe the concrete bank as TileBank.
• Discussion lessons and maintained discussion artifacts that refer to the concrete graphical bank artifact.

Fora de Escopo

• Any format, algorithm, codec, metadata, or layout change.
• Renaming TileLayer, TileMap, ScrollableTileLayer, HudTileLayer, or related layer/map structures.
• Renaming TileSize or geometric tile-size concepts.
• Redesigning tile/glyph semantics beyond the naming boundary established by DEC-0006.

Plano de Execucao

Step 1 - Rename the HAL concrete bank surface

What: Rename the concrete bank module and type surface in prometeu-hal from TileBank to GlyphBank.

How: Rename tile_bank.rs to glyph_bank.rs, update lib.rs exports/import paths, rename TileBank to GlyphBank, and rename concrete-bank-specific constants if they are artifact-specific rather than geometric. Keep TileSize unchanged even if it continues to live near the bank implementation or must be re-exported from the renamed module in a compatibility-preserving layout inside this refactor.

File(s):

• crates/console/prometeu-hal/src/tile_bank.rs
• crates/console/prometeu-hal/src/lib.rs
• any direct imports of prometeu_hal::tile_bank::* in runtime crates

Step 2 - Rename the asset-bank contract

What: Migrate the asset-bank enum and related asset-facing terminology from TILES to GLYPH.

How: Rename BankType::TILES to BankType::GLYPH, update any JSON/serde expectations and validation paths, and rename asset-facing metadata helpers only where they describe the concrete bank artifact rather than the geometric tile model. Preserve behavior and fail-fast semantics unchanged.

File(s):

• crates/console/prometeu-hal/src/asset.rs
• crates/console/prometeu-hal/src/cartridge_loader.rs
• crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs
• crates/console/prometeu-system/src/virtual_machine_runtime/tick.rs
• crates/console/prometeu-system/src/virtual_machine_runtime/tests.rs

Step 3 - Rename memory pools and concrete-bank runtime APIs

What: Rename bank-specific pool interfaces and storage paths that refer to the concrete graphical bank.

How: Rename TileBankPoolAccess, TileBankPoolInstaller, tile_bank_slot, install_tile_bank, tile_bank_pool, and related fields/traits/vars to Glyph* equivalents. Keep semantics and slot behavior unchanged.

File(s):

• crates/console/prometeu-drivers/src/memory_banks.rs
• crates/console/prometeu-drivers/src/hardware.rs
• crates/console/prometeu-drivers/src/gfx.rs
• crates/console/prometeu-drivers/src/asset.rs

Step 4 - Rename concrete-bank decode/load path and tests

What: Update the asset manager and concrete-bank decode path to the new artifact name.

How: Rename functions such as decode_tile_bank_*, perform_load_tile_bank, and related test helpers/messages to GlyphBank naming. Keep payload interpretation, palette handling, and runtime materialization identical to current behavior. Do not rename TileSize.

File(s):

• crates/console/prometeu-drivers/src/asset.rs
• affected tests in crates/console/prometeu-drivers/src/asset.rs
• any helper or stress/test utility strings such as missing_tile_bank

Step 5 - Apply renderer and hardware editorial cleanup

What: Rename only the references that describe the concrete bank artifact inside renderer and hardware documentation/comments.

How: Update comments, docs, field names, and user-facing/runtime-facing strings so that references to the bank artifact become GlyphBank/glyph bank, while preserving tile terminology for layers, maps, and geometric concepts. Review gfx.rs carefully because it contains both domains.

File(s):

• crates/console/prometeu-drivers/src/gfx.rs
• crates/console/prometeu-drivers/src/hardware.rs
• any crate-level docs/comments on the bank artifact path

Step 6 - Rewrite maintained lessons and discussion docs by meaning

What: Migrate maintained lessons and relevant discussion text to the new canonical artifact name.

How: Update published lessons and maintained discussion artifacts so that references to the concrete graphical bank become GlyphBank, but references to tile layers, tilemaps, grid semantics, or tile geometry remain tile. Use manual review, not blanket replacement.

File(s):

• discussion/lessons/DSC-0016-tilemap-empty-cell-semantics/LSN-0022-tilemap-empty-cell-convergence.md
• discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0011-mental-model-gfx.md
• discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0009-mental-model-asset-management.md
• any maintained agenda/decision/plan artifacts still intentionally retained and referencing the concrete bank artifact

Criterios de Aceite

• The canonical concrete bank type/module name in runtime code is GlyphBank.
• The canonical asset-bank enum variant is BankType::GLYPH.
• Pool interfaces and concrete-bank runtime helpers use Glyph* naming consistently.
• TileLayer, TileMap, ScrollableTileLayer, HudTileLayer, and TileSize remain unchanged.
• No behavior, payload format, or renderer semantics change as part of this migration.
• Tests, helper names, and runtime-facing strings do not keep active mixed TileBank/GlyphBank naming for the same artifact.
• Maintained lessons and docs use GlyphBank for the concrete bank artifact while preserving tile where it refers to layer/map/geometric concepts.

Tests / Validacao

Unit Tests

• Update and run unit tests that directly construct or decode the concrete graphical bank path.
• Confirm renamed bank/pool/helper symbols compile without compatibility shims.

Integration Tests

• Run prometeu-hal, prometeu-drivers, and prometeu-system test targets affected by the rename.
• Verify asset loading still succeeds for the renamed BankType::GLYPH path.

Manual Verification

• Review representative docs and lessons to confirm GlyphBank only replaces the concrete bank artifact meaning.
• Review gfx.rs and tile_layer.rs boundaries to confirm tile-domain structures were not accidentally renamed.
• Search the repository for residual TileBank references and classify any remaining occurrence as either acceptable historical residue outside scope or a migration miss.

Riscos

• The repository uses tile in two different domains, so blind search-and-replace is likely to over-rename excluded surfaces.
• Renaming the enum variant from TILES to GLYPH touches serialization contracts and can break test fixtures or external packer assumptions if not coordinated.
• Moving tile_bank.rs to glyph_bank.rs may cause broad import churn across crates and tests.
• Historical lessons can easily drift into editorial inconsistency if the rewrite is done mechanically instead of semantically.