From a16edcb2572dd3f23d1f3d1311474d52dd93963c Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Fri, 10 Apr 2026 06:04:25 +0100 Subject: [PATCH] clean up --- discussion/index.ndjson | 4 +- ...rename-artifact-by-meaning-not-by-token.md | 45 ++++ ...0-tile-bank-vs-glyph-bank-domain-naming.md | 221 ------------------ ...-0006-glyph-bank-domain-naming-contract.md | 93 -------- ...0005-glyph-bank-domain-naming-execution.md | 161 ------------- 5 files changed, 47 insertions(+), 477 deletions(-) create mode 100644 discussion/lessons/DSC-0022-glyph-bank-domain-naming/LSN-0025-rename-artifact-by-meaning-not-by-token.md delete mode 100644 discussion/workflow/agendas/AGD-0020-tile-bank-vs-glyph-bank-domain-naming.md delete mode 100644 discussion/workflow/decisions/DEC-0006-glyph-bank-domain-naming-contract.md delete mode 100644 discussion/workflow/plans/PLN-0005-glyph-bank-domain-naming-execution.md diff --git a/discussion/index.ndjson b/discussion/index.ndjson index eb065250..cc0aa485 100644 --- a/discussion/index.ndjson +++ b/discussion/index.ndjson @@ -1,7 +1,7 @@ -{"type":"meta","next_id":{"DSC":23,"AGD":21,"DEC":7,"PLN":6,"LSN":25,"CLSN":1}} +{"type":"meta","next_id":{"DSC":23,"AGD":21,"DEC":7,"PLN":6,"LSN":26,"CLSN":1}} {"type":"discussion","id":"DSC-0020","status":"done","ticket":"jenkins-gitea-integration","title":"Jenkins Gitea Integration and Relocation","created_at":"2026-04-07","updated_at":"2026-04-07","tags":["ci","jenkins","gitea"],"agendas":[{"id":"AGD-0018","file":"workflow/agendas/AGD-0018-jenkins-gitea-integration-and-relocation.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"decisions":[{"id":"DEC-0003","file":"workflow/decisions/DEC-0003-jenkins-gitea-strategy.md","status":"accepted","created_at":"2026-04-07","updated_at":"2026-04-07"}],"plans":[{"id":"PLN-0003","file":"workflow/plans/PLN-0003-jenkins-gitea-execution.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"lessons":[{"id":"LSN-0021","file":"lessons/DSC-0020-jenkins-gitea-integration/LSN-0021-jenkins-gitea-integration.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}]} {"type":"discussion","id":"DSC-0021","status":"done","ticket":"asset-entry-codec-enum-with-metadata","title":"Asset Entry Codec Enum Contract","created_at":"2026-04-09","updated_at":"2026-04-09","tags":["asset","runtime","codec","metadata"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0024","file":"lessons/DSC-0021-asset-entry-codec-enum-contract/LSN-0024-string-on-the-wire-enum-in-runtime.md","status":"done","created_at":"2026-04-09","updated_at":"2026-04-09"}]} -{"type":"discussion","id":"DSC-0022","status":"open","ticket":"tile-bank-vs-glyph-bank-domain-naming","title":"Glyph Bank Domain Naming Contract","created_at":"2026-04-09","updated_at":"2026-04-10","tags":["gfx","runtime","naming","domain-model"],"agendas":[{"id":"AGD-0020","file":"AGD-0020-tile-bank-vs-glyph-bank-domain-naming.md","status":"accepted","created_at":"2026-04-09","updated_at":"2026-04-10"}],"decisions":[{"id":"DEC-0006","file":"DEC-0006-glyph-bank-domain-naming-contract.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10","ref_agenda":"AGD-0020"}],"plans":[{"id":"PLN-0005","file":"PLN-0005-glyph-bank-domain-naming-execution.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10","ref_decisions":["DEC-0006"]}],"lessons":[]} +{"type":"discussion","id":"DSC-0022","status":"done","ticket":"tile-bank-vs-glyph-bank-domain-naming","title":"Glyph Bank Domain Naming Contract","created_at":"2026-04-09","updated_at":"2026-04-10","tags":["gfx","runtime","naming","domain-model"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0025","file":"lessons/DSC-0022-glyph-bank-domain-naming/LSN-0025-rename-artifact-by-meaning-not-by-token.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]} {"type":"discussion","id":"DSC-0001","status":"done","ticket":"legacy-runtime-learn-import","title":"Import legacy runtime learn into discussion lessons","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["migration","tech-debt"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0001","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0001-prometeu-learn-index.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0002","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0002-historical-asset-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0003","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0003-historical-audio-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0004","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0004-historical-cartridge-boot-protocol-and-manifest-authority.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0005","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0005-historical-game-memcard-slots-surface-and-semantics.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0006","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0006-historical-gfx-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0007","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0007-historical-retired-fault-and-input-decisions.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0008","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0008-historical-vm-core-and-assets.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0009","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0009-mental-model-asset-management.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0010","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0010-mental-model-audio.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0011","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0011-mental-model-gfx.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0012","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0012-mental-model-input.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0013","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0013-mental-model-observability-and-debugging.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0014","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0014-mental-model-portability-and-cross-platform.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0015","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0015-mental-model-save-memory-and-memcard.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0016","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0016-mental-model-status-first-and-fault-thinking.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0017","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0017-mental-model-time-and-cycles.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0018","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0018-mental-model-touch.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]} {"type":"discussion","id":"DSC-0002","status":"open","ticket":"runtime-edge-test-plan","title":"Agenda - Runtime Edge Test Plan","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0001","file":"workflow/agendas/AGD-0001-runtime-edge-test-plan.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]} {"type":"discussion","id":"DSC-0003","status":"open","ticket":"packed-cartridge-loader-pmc","title":"Agenda - Packed Cartridge Loader PMC","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0002","file":"workflow/agendas/AGD-0002-packed-cartridge-loader-pmc.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]} diff --git a/discussion/lessons/DSC-0022-glyph-bank-domain-naming/LSN-0025-rename-artifact-by-meaning-not-by-token.md b/discussion/lessons/DSC-0022-glyph-bank-domain-naming/LSN-0025-rename-artifact-by-meaning-not-by-token.md new file mode 100644 index 00000000..07a8c3d6 --- /dev/null +++ b/discussion/lessons/DSC-0022-glyph-bank-domain-naming/LSN-0025-rename-artifact-by-meaning-not-by-token.md @@ -0,0 +1,45 @@ +--- +id: LSN-0025 +ticket: tile-bank-vs-glyph-bank-domain-naming +title: Rename Artifact by Meaning, Not by Token +created: 2026-04-10 +tags: [gfx, runtime, naming, refactor, documentation] +--- + +## Context + +The runtime used `TileBank` as the name of the concrete graphical bank artifact while also using `tile` for map, layer, and geometric concepts such as `TileLayer`, `TileMap`, and `TileSize`. This overloaded the term `tile` across two different meanings. + +The implemented migration renamed only the concrete bank artifact to `GlyphBank` and renamed the corresponding asset-bank contract from `BankType::TILES` to `BankType::GLYPH`, while explicitly preserving `TileLayer`, `TileMap`, and `TileSize`. + +## Key Decisions + +### Glyph Bank Domain Naming Contract + +**What:** +Rename the concrete graphical bank artifact and its runtime interfaces to `GlyphBank`, but keep tile-domain structures unchanged where `tile` still correctly describes layers, maps, grids, and geometry. + +**Why:** +The goal was domain clarity, not behavior change. The project needed a more precise name for the concrete graphical bank without reopening rendering architecture or erasing valid uses of `tile`. + +**Trade-offs:** +This requires more care than a blind search-and-replace. The migration is broader editorially, but safer semantically, because it avoids damaging concepts that still belong in the tile domain. + +## Patterns and Algorithms + +- Rename by artifact meaning, not by string token frequency. +- When a term is overloaded, split the rename along domain boundaries instead of trying to enforce total lexical uniformity. +- Let the runtime contract adopt the new canonical artifact name (`GlyphBank`, `BankType::GLYPH`) while preserving existing terms for excluded concepts (`TileLayer`, `TileMap`, `TileSize`). +- Apply the same semantic rule to docs and lessons, not only to code. + +## Pitfalls + +- Blind replacement would have incorrectly renamed tile-layer and tile-size concepts that were intentionally out of scope. +- Partial renames create mixed vocabulary, which is worse than either old or new terminology used consistently. +- Historical documentation is especially easy to corrupt if rewritten mechanically instead of by artifact meaning. + +## Takeaways + +- A naming refactor can be rename-only in behavior while still requiring architectural discipline in wording. +- Use one canonical name per artifact, but do not force unrelated domains to share that rename. +- Documentation migrations should follow the same semantic boundary as code migrations, or the codebase will drift back into conceptual ambiguity. diff --git a/discussion/workflow/agendas/AGD-0020-tile-bank-vs-glyph-bank-domain-naming.md b/discussion/workflow/agendas/AGD-0020-tile-bank-vs-glyph-bank-domain-naming.md deleted file mode 100644 index 7eda50a4..00000000 --- a/discussion/workflow/agendas/AGD-0020-tile-bank-vs-glyph-bank-domain-naming.md +++ /dev/null @@ -1,221 +0,0 @@ ---- -id: AGD-0020 -ticket: tile-bank-vs-glyph-bank-domain-naming -title: Agenda - Tile Bank vs Glyph Bank Domain Naming -status: accepted -created: 2026-04-09 -resolved: 2026-04-10 -decision: DEC-0006 -tags: [gfx, runtime, naming, domain-model] ---- - -# Agenda - Tile Bank vs Glyph Bank Domain Naming - -## Contexto - -Hoje o runtime usa `TileBank`, `tile_bank.rs`, `TileBankPool*` e termos derivados para nomear o banco grafico consumido pelo renderer e pelo pipeline de assets. - -Ao mesmo tempo, existe a vontade de elevar `Tile` para um conceito mais amplo do dominio, nao restrito ao sheet grafico concreto. Nessa leitura: - -- `Tile` passa a ser uma ideia mais geral da grade/elemento logico; -- o que hoje e o artefato grafico concreto chamado `TileBank` deveria passar a se chamar `GlyphBank`; -- a intencao inicial nao e mudar formato, memoria, payload ou algoritmo, e sim alinhar a linguagem do projeto. - -Esse tema ja encosta em documentacao e lessons existentes, porque o vocabulario atual mistura: - -- tile como unidade de composicao visual; -- tile bank como sheet grafico concreto; -- referencias esparsas a glyph em lições e agendas. - -## Problema - -Se o projeto mudar o centro semantico de `tile` e `glyph` sem uma decisao explicita, o repositorio tende a ficar com vocabulário hibrido: - -- tipos antigos com nome legado; -- docs novas com nome novo; -- renderer e assets falando uma lingua; -- lessons e discussoes falando outra. - -O problema principal nao e tecnico-algoritmico. E semantico e operacional: qual vocabulario o projeto quer tornar canonico para o banco grafico concreto, e qual parte dessa mudanca e apenas rename mecanico versus mudanca real de modelo. - -## Pontos Criticos - -1. Escopo da mudanca. - Precisamos separar rename de dominio de qualquer mudanca de formato ou comportamento. - -2. Contrato externo. - Precisamos fechar quais contratos externos tambem entram no rename. Ja existe direcao para migrar `BankType::TILES` para `BankType::GLYPH`. - -3. Consistencia de linguagem. - A mudanca so vale a pena se atingir codigo, tests, docs e lessons de forma coordenada. - -4. Custo de churn. - Mesmo sem mudar comportamento, o rename atravessa muitos modulos (`hal`, `drivers`, renderer, pools, mensagens de erro, tests e docs). - -5. Fronteira conceitual. - Precisamos definir o que `Tile` passa a significar depois do rename, para evitar trocar um overload semantico por outro. - -## Opcoes - -### Opcao A - Manter `TileBank` como esta - -- **Abordagem:** preservar `TileBank` como nome canonico do banco grafico concreto e aceitar que `tile` continue carregando tanto o lado logico quanto o lado visual. -- **Pro:** zero churn nominal imediato e nenhuma migracao de docs/codigo. -- **Con:** o overload conceitual de `tile` permanece e pode continuar poluindo a linguagem de dominio. -- **Tradeoff:** economiza trabalho agora ao custo de clareza futura. - -### Opcao B - Renomear `TileBank` para `GlyphBank` como refactor semantico - -- **Abordagem:** tratar a mudanca como rename consistente de tipos, modulos, docs, testes e mensagens, sem alterar formato de payload, layout em memoria ou renderer. -- **Pro:** melhora a linguagem do projeto sem reabrir a arquitetura grafica. -- **Con:** exige disciplina para manter a promessa de “rename only” e nao misturar isso com redesign. -- **Tradeoff:** churn mecanico relativamente alto para ganhar clareza conceitual. - -### Opcao C - Fazer rename parcial - -- **Abordagem:** adotar `glyph` apenas em docs novas ou em algumas camadas, preservando nomes antigos em APIs e modulos centrais. -- **Pro:** menor custo inicial. -- **Con:** cria o pior estado intermediario: dois vocabulários concorrentes para o mesmo conceito. -- **Tradeoff:** parece barato, mas deixa a linguagem do projeto menos confiavel. - -## Sugestao / Recomendacao - -Seguir inicialmente com a **Opcao B**, desde que a discussao confirme que a mudanca e de nomenclatura e nao de semantica operacional. - -A recomendacao provisoria e: - -- `GlyphBank` se torna o nome do artefato grafico concreto que hoje chamamos de `TileBank`; -- `Tile` fica livre para representar um conceito mais geral do dominio; -- `BankType::TILES` passa a `BankType::GLYPH`; -- a migracao deve ser consistente em codigo, tests, docs e lessons; -- `TileLayer` e derivados nao entram automaticamente no rename, porque ja pertencem a outra fronteira de dominio e precisam de triagem separada; -- a discussao deve explicitar quais superfícies mudam juntas para impedir vocabulario hibrido sem reabrir a arquitetura grafica. - -## Perguntas em Aberto - -- Confirmar a superficie exata do rename para evitar misturar banco grafico concreto com conceitos de layer/mapa. - -## Discussao - -### Direcao fechada ate aqui - -1. **Natureza da mudanca** - A mudanca e `rename-only`. Nao ha intencao de alterar formato, algoritmo, layout em memoria ou comportamento. - -2. **Contrato externo** - `BankType::TILES` nao deve permanecer. O contrato deve migrar para `BankType::GLYPH`. - -3. **Escopo documental** - A migracao deve ser completa, inclusive em documentacao e lessons historicas. - -4. **Colisao semantica** - `glyph` nao colide com outro artefato canonico relevante nesta etapa. - -### Fronteira importante - -Nem todo `Tile*` deve migrar automaticamente para `Glyph*`. - -Existe uma fronteira entre: - -- nomes que descrevem o banco grafico concreto e seu circuito de carga/uso; e -- nomes que ja descrevem dominio de layer, mapa, grade ou composicao. - -Por isso, a proxima resposta que falta precisa ser dada por superficie concreta, e nao por regra global simplista. - -### Lista para voto `sim` / `nao` - -Responda `sim` ou `nao` para cada grupo abaixo. - -1. **Banco concreto e modulo base** - Inclui `TileBank`, `tile_bank.rs`, comentarios e docs especificos desse tipo. - -2. **Enum e contrato de asset** - Inclui `BankType::TILES -> BankType::GLYPH`, mensagens de erro, metadata helpers e referencias equivalentes no path de assets. - -3. **Pools e interfaces de memoria** - Inclui `TileBankPoolAccess`, `TileBankPoolInstaller`, `tile_bank_slot`, `install_tile_bank`, campos internos como `tile_bank_pool`. - -4. **Asset manager e loader path** - Inclui funcoes como `decode_tile_bank_*`, `perform_load_tile_bank`, variaveis locais, testes e mensagens associadas ao load do banco grafico. - -5. **Renderer e hardware references ao banco** - Inclui usos em `gfx.rs` e `hardware.rs` que referenciam o banco concreto, por exemplo campos `tile_banks`, docs sobre VRAM `TileBanks`, parametros `bank: &TileBank`. - -6. **Modulo e tipos de layer/mapa** - Inclui `tile_layer.rs`, `TileMap`, `TileLayer`, `ScrollableTileLayer`, `HudTileLayer`. - Este grupo e o mais sensivel porque pode nao ser rename de banco concreto, e sim outro dominio. - -7. **TileSize** - Inclui `TileSize` e referencias ao tamanho de tile como unidade geometrica. - Este grupo pode continuar como `TileSize` mesmo se o banco virar `GlyphBank`. - -8. **Strings, fixtures e test names** - Inclui nomes de testes, helper names, snapshots, mensagens e dados de teste que ainda falam em tile bank. - -9. **Lessons e docs historicas** - Inclui lessons ja publicadas e material de discussao/mental model que hoje falam em `TileBank`. - -### Votos registrados - -1. **Banco concreto e modulo base**: `sim` - `TileBank`, `tile_bank.rs`, modulo base e documentacao associada entram na migracao. - -2. **Enum e contrato de asset**: `sim` - `BankType::TILES` e o contrato textual equivalente entram na migracao para `GLYPH`. - -3. **Pools e interfaces de memoria**: `sim` - `TileBankPool*`, `tile_bank_slot` e derivados entram na migracao. - -4. **Asset manager e loader path**: `sim` - Helpers, decode path, mensagens e testes associados ao banco grafico concreto entram na migracao. - -5. **Renderer e hardware references ao banco**: `sim` - Referencias ao banco concreto em renderer e hardware entram na migracao. - -6. **Modulo e tipos de layer/mapa**: `nao` - `TileLayer`, `TileMap`, `ScrollableTileLayer` e `HudTileLayer` ficam fora desta rodada. - -7. **TileSize**: `nao` - `TileSize` permanece como conceito geometrico e nao entra automaticamente no rename. - -8. **Strings, fixtures e test names**: `sim` - Helpers, fixtures, mensagens e nomes de testes entram na migracao para evitar residuos do vocabulario antigo. - -9. **Lessons e docs historicas**: `sim` - A migracao documental e historica entra no escopo, seguindo a mesma fronteira desta agenda: renomear o banco grafico concreto sem arrastar automaticamente o dominio de layer/mapa. - -## Resolucao Provisoria - -Ha consenso provisoriamente estabelecido sobre os seguintes pontos: - -- a mudanca e `rename-only`; -- o vocabulario canonico do banco grafico concreto passa de `TileBank` para `GlyphBank`; -- `BankType::TILES` deve migrar para `BankType::GLYPH`; -- pools, contrato de asset, loader path, renderer, hardware references, fixtures e nomes de teste entram na migracao; -- `TileLayer`/`TileMap` e derivados ficam fora desta rodada; -- `TileSize` fica fora desta rodada; -- docs e lessons historicas entram no escopo, respeitando essa mesma fronteira. - -O principal ponto restante para encerrar a agenda e confirmar se essa resolucao ja e suficiente para virar decisao normativa, ou se ainda falta detalhar como a migracao documental deve tratar referencias historicas em texto corrido quando `tile` continuar correto para layer/mapa. - -## Resolucao - -A agenda fica encerrada com a seguinte orientacao: - -- a mudanca e `rename-only`; -- o banco grafico concreto passa a se chamar `GlyphBank`; -- `BankType::TILES` passa a `BankType::GLYPH`; -- pools, contrato de asset, loader path, renderer, hardware references, fixtures, nomes de teste, docs e lessons entram na migracao; -- `TileLayer`, `TileMap` e derivados ficam fora; -- `TileSize` fica fora; -- docs e lessons antigas devem migrar referencias ao banco grafico concreto para `GlyphBank`, mantendo `tile` quando o assunto for layer, mapa, grade ou geometria. - -## Criterio para Encerrar - -Esta agenda pode ser encerrada quando houver consenso escrito sobre: - -- se a mudanca e rename-only ou nao; -- qual vocabulario passa a ser canonico; -- quais contratos externos entram no rename; -- quais grupos concretos entram ou nao na migracao; -- como evitar que `TileLayer`/`TileMap` sejam arrastados automaticamente sem decisao propria. diff --git a/discussion/workflow/decisions/DEC-0006-glyph-bank-domain-naming-contract.md b/discussion/workflow/decisions/DEC-0006-glyph-bank-domain-naming-contract.md deleted file mode 100644 index 65a66ebf..00000000 --- a/discussion/workflow/decisions/DEC-0006-glyph-bank-domain-naming-contract.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -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. diff --git a/discussion/workflow/plans/PLN-0005-glyph-bank-domain-naming-execution.md b/discussion/workflow/plans/PLN-0005-glyph-bank-domain-naming-execution.md deleted file mode 100644 index 77465faf..00000000 --- a/discussion/workflow/plans/PLN-0005-glyph-bank-domain-naming-execution.md +++ /dev/null @@ -1,161 +0,0 @@ ---- -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.