prometeu-studio/discussion/workflow/agendas/AGD-0028-glyph-bank-naming-alignment-with-runtime.md

id	ticket	title	status	created	resolved	decision	tags
AGD-0028	glyph-bank-naming-alignment-with-runtime	Glyph Bank Naming Alignment with Runtime DEC-0006	accepted	2026-04-10	2026-04-10	DEC-0025	packer studio naming asset-contract runtime-alignment glyph-bank

Pain

O runtime já aceitou a DEC-0006 em ../runtime, travando que o artefato gráfico concreto hoje chamado GlyphBank passa a ser canonicamente GlyphBank, com BankType::GLYPH, sem renomear TileMap, TileLayer ou TileSize.

Este repositório ainda usa vocabulário centrado em glyph bank no contrato de asset, nas specs do packer, em partes do Studio e nos fixtures. Se esse repositório não alinhar a nomenclatura, o ecossistema passa a operar com contrato misto entre runtime e studio/packer, exatamente o estado que a decisão upstream proibiu para superfícies ativas.

Context

1. A decisão externa de referência é ../runtime/discussion/workflow/decisions/DEC-0006-glyph-bank-domain-naming-contract.md.
2. Ela define que a mudança é rename-only: sem alterar formato, layout, payload, codec, metadata ou semântica de renderização.
3. Ela também fixa o boundary editorial:
   • o artefato gráfico concreto migra para GlyphBank / Glyph*;
   • conceitos geométricos e de mapa/camada continuam tile.
4. Neste repositório, os impactos visíveis hoje incluem:
   • AssetFamilyCatalog.TILE_BANK;
   • OutputFormatCatalog.TILES_INDEXED_V1;
   • specs que falam em tile_bank, TILES/indexed_v1 e bank_type = TILES;
   • classes e testes do Studio/Packer nomeados como TileBank;
   • fixtures e asset.json de teste usando type = tile_bank e format = TILES/indexed_v1.
5. O owner primário aqui parece ser packer, com impacto explícito também em studio.

Open Questions

• O alinhamento local deve migrar o contrato serializado imediatamente para glyph_bank / GLYPH/indexed_v1 / bank_type = GLYPH, ou precisamos de uma fase explícita de compatibilidade de leitura para manifests e fixtures legados? Resposta: migrar imediatamente o contrato serializado. Não haverá fase de compatibilidade.
• O AssetFamilyCatalog.TILE_BANK deve ser renomeado no código local junto com o contrato serializado, ou o código pode adotar uma estratégia temporária de alias interno sem expor vocabulário misto nas superfícies mantidas? Resposta: renomear junto com o contrato serializado. Não haverá alias nem camada de compatibilidade.
• Quais superfícies do Studio ainda são realmente específicas do artefato concreto e devem virar Glyph*, e quais continuam corretamente no domínio geométrico tile? Resposta: o Studio deve seguir a nomenclatura 1:1 do artefato concreto. Superfícies do artefato concreto migram para Glyph*; conceitos geométricos continuam tile.
• O rename local deve ser tratado como uma única wave transversal packer + studio + specs + fixtures, ou precisamos fatiar entre contrato serializado e nomenclatura interna? Resposta: uma única wave transversal. Trata-se de rename-only, sem mudança funcional.

Options

Option A - Full Local Alignment with Runtime Naming

• Approach: Migrar as superfícies mantidas deste repositório para GlyphBank/glyph_bank/GLYPH de forma consistente, preservando tile apenas onde o significado é geométrico ou de mapa/camada.
• Pro: Alinha totalmente com a DEC-0006 upstream e elimina vocabulário misto entre repositórios ativos.
• Con: Toca contrato serializado, fixtures, specs e nomes internos ao mesmo tempo.
• Maintainability: Alta, porque reduz ambiguidade estrutural entre artifact bank e tile-domain concepts.

Option B - Compatibility Alias Around a Deferred Rename

• Approach: Aceitar a direção do runtime, mas manter tile_bank / TILES/indexed_v1 como contrato serializado temporário neste repositório, renomeando só docs e algumas APIs internas por enquanto.
• Pro: Reduz churn imediato no packer e nos fixtures.
• Con: Mantém exatamente o vocabulário misto que a decisão upstream quer evitar nas superfícies ativas.
• Maintainability: Baixa, porque exige conviver com dois nomes para o mesmo artefato concreto.

Option C - Editorial Alignment Only

• Approach: Atualizar apenas specs/lessons/discussion docs para refletir GlyphBank, mantendo código e contrato serializado locais como estão até uma wave futura.
• Pro: Menor custo inicial.
• Con: Cria desalinhamento entre documentação e implementação local, além de não resolver o contrato ativo.
• Maintainability: Baixa, porque transforma o problema em dívida operacional documentada em vez de resolvê-lo.

Discussion

A DEC-0006 do runtime já fechou o ponto conceitual mais importante: tile ficou reservado para mapa/camada/geometria, enquanto o banco gráfico concreto passa a ser glyph.

O que continua aberto neste repositório não é a direção conceitual, mas a estratégia local de propagação:

• se o packer deve mudar o contrato serializado já nesta wave;
• se precisamos de leitura compatível para assets/fixtures legados;
• como separar corretamente as classes/strings do Studio entre domínio concreto de banco e domínio geométrico.

O risco dominante é fazer rename mecânico. Aqui, assim como no runtime, há superfícies onde tile ainda é o nome certo.

Resolution

Recomendação consolidada: seguir integralmente a direção da DEC-0006 do runtime e emitir uma decisão local owner packer, com impacto explícito em studio, para alinhar este repositório ao novo nome canônico do artefato concreto.

A resolução desta agenda fica:

1. o contrato serializado local migra imediatamente para glyph_bank, GLYPH/indexed_v1 e bank_type = GLYPH;
2. não haverá camada de compatibilidade, alias interno, nem fase de leitura legada para o vocabulário antigo;
3. o Studio deve seguir a nomenclatura do artefato concreto em modo 1:1;
4. tile permanece apenas onde o significado for geométrico, de layer ou de map;
5. a propagação local será uma única wave transversal em packer + studio + specs + fixtures;
6. a mudança é estritamente rename-only, sem alteração de formato, layout, payload, metadata, codec ou comportamento.

Próximo passo sugerido: converter esta agenda em decisão local e travar os propagation targets para packer, studio, specs e fixtures.