Glyph Bank Naming Alignment with Runtime DEC-0006

This commit is contained in:
2026-04-10 06:33:49 +01:00
parent 76b5717cd8
commit 99e9102004
46 changed files with 467 additions and 185 deletions
@@ -16,7 +16,7 @@ tags:
## Pain
Studio already has a retained agenda for palette management in the `tile bank` form session, but that agenda exists only under `docs/studio/agendas/` and therefore sits outside the discussion-framework lifecycle.
Studio already has a retained agenda for palette management in the `glyph bank` form session, but that agenda exists only under `docs/studio/agendas/` and therefore sits outside the discussion-framework lifecycle.
Without importing it into `discussion/`, the canonical discussion surface would lose the still-open Studio question about:
@@ -32,11 +32,11 @@ Legacy source: `docs/studio/agendas/Palette Management in Studio Agenda.md`
Domain owner: `docs/studio`
Cross-domain impact: `docs/packer`
The retained agenda is intentionally scoped to `tile bank`.
The retained agenda is intentionally scoped to `glyph bank`.
The imported context keeps the same baseline:
- every `*.png` input of a tile bank is one tile;
- every `*.png` input of a glyph bank is one tile;
- each tile yields one extracted palette during cache construction;
- developers may also work with favorite palettes and asset palettes;
- each bank may integrate at most `64` palettes;
@@ -57,8 +57,8 @@ The current UI shape already converged on:
- [ ] Should extracted tile palettes always enter the candidate set automatically, or can the developer suppress some of them before curation?
- [ ] Should clicking a palette on the `selected` side be the only interaction needed to change the previewed palette in the first wave?
- [ ] Which palette operations are read-only in the first wave, and which require staged preview/apply treatment?
- [ ] Which parts of this interaction model should remain explicitly `tile bank`-specific, and which parts are reusable Studio form-session primitives?
- [ ] Does the first release need only an asset-scoped `tile bank` section, or also a project-level palette browser for discovery and favorites management?
- [ ] Which parts of this interaction model should remain explicitly `glyph bank`-specific, and which parts are reusable Studio form-session primitives?
- [ ] Does the first release need only an asset-scoped `glyph bank` section, or also a project-level palette browser for discovery and favorites management?
## Options
@@ -70,7 +70,7 @@ The current UI shape already converged on:
### Option B - Asset-Scoped Curated Selection
- **Approach:** Treat bank palettes as an asset-scoped curated selection built from tile-derived palettes, favorites, and asset palettes, with Studio owning the curation UX and packer owning persistence.
- **Pro:** Matches the concrete `tile bank` workflow and keeps authority boundaries clear.
- **Pro:** Matches the concrete `glyph bank` workflow and keeps authority boundaries clear.
- **Con:** Requires explicit UX for capacity, identity, deduplication, and preview semantics.
- **Maintainability:** Strong. It makes responsibilities explicit and keeps family-specific rules close to the workflow that needs them.
@@ -82,7 +82,7 @@ The current UI shape already converged on:
## Discussion
The imported agenda keeps the original recommendation intact: palette management should be first-class for `tile bank`, but Studio must not become the persistence authority.
The imported agenda keeps the original recommendation intact: palette management should be first-class for `glyph bank`, but Studio must not become the persistence authority.
That means the key open problem is not whether palettes exist. It is how Studio explains and curates them safely:
@@ -90,7 +90,7 @@ That means the key open problem is not whether palettes exist. It is how Studio
- clear source and identity display;
- explicit `1..64` capacity feedback;
- a preview model that stays tied to the selected bank palettes;
- a boundary between `tile bank`-specific UX and reusable Studio primitives.
- a boundary between `glyph bank`-specific UX and reusable Studio primitives.
The retained source already converged on a pragmatic first wave:
@@ -106,7 +106,7 @@ Recommended direction: adopt **Option B**.
The imported agenda preserves the retained Studio direction:
1. palette management belongs to the `tile bank` asset workflow;
1. palette management belongs to the `glyph bank` asset workflow;
2. Studio aggregates candidate palettes from tile-derived extraction, favorites, and asset palettes;
3. the first wave uses a custom-rendered transfer list with an explicit `1..64` selected range;
4. the right-side preview panel stays tied to the current selected palette set;
@@ -53,7 +53,7 @@ The packer now exposes:
### Option A - Keep fixed 64-palette serialization
- **Approach:** Preserve the current fixed v1 payload with zero-filled unused palette slots.
- **Pro:** No runtime change and current specs/tests remain stable.
- **Con:** Every tile bank keeps paying the full palette cost.
- **Con:** Every glyph bank keeps paying the full palette cost.
- **Maintainability:** Medium.
### Option B - Move to variable palette serialization now
@@ -0,0 +1,89 @@
---
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.