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