--- id: AGD-0028 ticket: glyph-bank-naming-alignment-with-runtime title: Glyph Bank Naming Alignment with Runtime DEC-0006 status: accepted created: 2026-04-10 resolved: 2026-04-10 decision: DEC-0025 tags: [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 - [x] 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. - [x] 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. - [x] 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`. - [x] 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.