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

---
id: PLN-0005
ticket: tile-bank-vs-glyph-bank-domain-naming
title: Glyph Bank Domain Naming Execution
status: accepted
created: 2026-04-10
completed:
tags: [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.