90 lines
6.3 KiB
Markdown
90 lines
6.3 KiB
Markdown
---
|
|
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.
|