Intrepid/prometeu-runtime

Fork 0

bQUARKz 54f65f58e6

Glyph Bank Domain Naming Contract

2026-04-10 06:00:47 +01:00

10 KiB

Raw Blame History

ticket

title

status

created

resolved

decision

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

Escopo da mudanca. Precisamos separar rename de dominio de qualquer mudanca de formato ou comportamento.
Contrato externo. Precisamos fechar quais contratos externos tambem entram no rename. Ja existe direcao para migrar BankType::TILES para BankType::GLYPH.
Consistencia de linguagem. A mudanca so vale a pena se atingir codigo, tests, docs e lessons de forma coordenada.
Custo de churn. Mesmo sem mudar comportamento, o rename atravessa muitos modulos (hal, drivers, renderer, pools, mensagens de erro, tests e docs).
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

Natureza da mudanca A mudanca e rename-only. Nao ha intencao de alterar formato, algoritmo, layout em memoria ou comportamento.
Contrato externo BankType::TILES nao deve permanecer. O contrato deve migrar para BankType::GLYPH.
Escopo documental A migracao deve ser completa, inclusive em documentacao e lessons historicas.
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.

Banco concreto e modulo base Inclui TileBank, tile_bank.rs, comentarios e docs especificos desse tipo.
Enum e contrato de asset Inclui BankType::TILES -> BankType::GLYPH, mensagens de erro, metadata helpers e referencias equivalentes no path de assets.
Pools e interfaces de memoria Inclui TileBankPoolAccess, TileBankPoolInstaller, tile_bank_slot, install_tile_bank, campos internos como tile_bank_pool.
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.
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.
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.
TileSize Inclui TileSize e referencias ao tamanho de tile como unidade geometrica. Este grupo pode continuar como TileSize mesmo se o banco virar GlyphBank.
Strings, fixtures e test names Inclui nomes de testes, helper names, snapshots, mensagens e dados de teste que ainda falam em tile bank.
Lessons e docs historicas Inclui lessons ja publicadas e material de discussao/mental model que hoje falam em TileBank.

Votos registrados

Banco concreto e modulo base: sim TileBank, tile_bank.rs, modulo base e documentacao associada entram na migracao.
Enum e contrato de asset: sim BankType::TILES e o contrato textual equivalente entram na migracao para GLYPH.
Pools e interfaces de memoria: sim TileBankPool*, tile_bank_slot e derivados entram na migracao.
Asset manager e loader path: sim Helpers, decode path, mensagens e testes associados ao banco grafico concreto entram na migracao.
Renderer e hardware references ao banco: sim Referencias ao banco concreto em renderer e hardware entram na migracao.
Modulo e tipos de layer/mapa: nao TileLayer, TileMap, ScrollableTileLayer e HudTileLayer ficam fora desta rodada.
TileSize: nao TileSize permanece como conceito geometrico e nao entra automaticamente no rename.
Strings, fixtures e test names: sim Helpers, fixtures, mensagens e nomes de testes entram na migracao para evitar residuos do vocabulario antigo.
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.

10 KiB Raw Blame History