Glyph Bank Naming Alignment with Runtime DEC-0006
This commit is contained in:
@@ -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.
|
||||
Reference in New Issue
Block a user