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
+2 -1
View File
@@ -1,4 +1,5 @@
{"type":"meta","next_id":{"DSC":25,"AGD":28,"DEC":25,"PLN":48,"LSN":40,"CLSN":1}}
{"type":"meta","next_id":{"DSC":27,"AGD":29,"DEC":26,"PLN":49,"LSN":40,"CLSN":1}}
{"type":"discussion","id":"DSC-0026","status":"open","ticket":"glyph-bank-naming-alignment-with-runtime","title":"Glyph Bank Naming Alignment with Runtime DEC-0006","created_at":"2026-04-10","updated_at":"2026-04-10","tags":["packer","studio","naming","asset-contract","runtime-alignment","glyph-bank"],"agendas":[{"id":"AGD-0028","file":"AGD-0028-glyph-bank-naming-alignment-with-runtime.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10"}],"decisions":[{"id":"DEC-0025","file":"DEC-0025-glyph-bank-local-alignment-with-runtime.md","status":"in_progress","created_at":"2026-04-10","updated_at":"2026-04-10","ref_agenda":"AGD-0028"}],"plans":[{"id":"PLN-0048","file":"PLN-0048-implement-glyph-bank-local-alignment.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10","ref_decisions":["DEC-0025"]}],"lessons":[]}
{"type":"discussion","id":"DSC-0025","status":"done","ticket":"packer-pipeline-metadata-ownership","title":"Pipeline Metadata Ownership and Runtime Contract","created_at":"2026-04-09","updated_at":"2026-04-10","tags":["packer","metadata","runtime-contract","tooling","studio"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0039","file":"discussion/lessons/DSC-0025-packer-pipeline-metadata-ownership/LSN-0039-runtime-header-boundary-and-tooling-owned-pipeline-metadata.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
{"type":"discussion","id":"DSC-0024","status":"done","ticket":"jacoco-reports-consolidation","title":"JaCoCo Reports Consolidation in Gradle","created_at":"2026-04-07","updated_at":"2026-04-07","tags":["infra","gradle","jacoco","coverage","jenkins"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0038","file":"discussion/lessons/DSC-0024-jacoco-reports-consolidation/LSN-0038-jacoco-reports-consolidation.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}]}
{"type":"discussion","id":"DSC-0001","status":"done","ticket":"studio-docs-import","title":"Import docs/studio into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0001","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0001-assets-workspace-execution-wave-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0002","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0002-bank-composition-editor-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0003","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0003-mental-model-asset-mutations-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0004","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0004-mental-model-assets-workspace-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0005","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0005-mental-model-studio-events-and-components-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0006","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0006-mental-model-studio-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0007","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0007-pack-wizard-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0008","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0008-project-scoped-state-and-activity-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0016","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0016-studio-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]}
@@ -20,8 +20,8 @@ This lesson preserves the first-wave producer contract for tile-bank assets.
### Tile bank packing emits one canonical payload per asset with explicit normalization and early structural validation
**What:** The first-wave contract emits one canonical `TILES/indexed_v1` payload per asset, normalizes artifacts by explicit `artifacts[*].index`, packs one fixed `256 x 256` row-major sheet with packed `u4` pixels and `RGB565` palette blocks, treats palette identity as semantic rather than positional, and surfaces structural blockers early in walker/materialization.
**Why:** The repository needed one explicit producer contract for tile banks rather than a mix of implicit artifact ordering, late byte-emission surprises, and unstable palette identity.
**What:** The first-wave contract emits one canonical `GLYPH/indexed_v1` payload per asset, normalizes artifacts by explicit `artifacts[*].index`, packs one fixed `256 x 256` row-major sheet with packed `u4` pixels and `RGB565` palette blocks, treats palette identity as semantic rather than positional, and surfaces structural blockers early in walker/materialization.
**Why:** The repository needed one explicit producer contract for glyph banks rather than a mix of implicit artifact ordering, late byte-emission surprises, and unstable palette identity.
**Trade-offs:** This contract is more explicit and restrictive than ad hoc per-artifact packing, but it yields stable reviewability, predictable runtime metadata, and earlier validation.
## Patterns and Algorithms
@@ -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.
@@ -0,0 +1,76 @@
---
id: DEC-0025
ticket: glyph-bank-naming-alignment-with-runtime
title: Glyph Bank Local Alignment with Runtime
status: in_progress
created: 2026-04-10
accepted: 2026-04-10
agenda: AGD-0028
plans: [PLN-0048]
tags: [packer, studio, naming, asset-contract, runtime-alignment, glyph-bank]
---
## Decision
This repository MUST align its active `packer` and `studio` surfaces with the runtime naming contract accepted in `../runtime` `DEC-0006`.
The concrete graphical bank artifact currently referred to locally through `tile bank`, `TileBank`, `tile_bank`, `TILES/indexed_v1`, and `bank_type = TILES` MUST migrate to `GlyphBank`, `glyph_bank`, `GLYPH/indexed_v1`, and `bank_type = GLYPH`, according to the surface involved.
This migration MUST be treated as rename-only. It MUST NOT change payload layout, metadata semantics, codec behavior, packing behavior, runtime contract meaning, Studio behavior, or any other functional behavior.
The migration MUST happen as one single transversal wave across `packer`, `studio`, specs, fixtures, tests, and maintained discussion/lesson surfaces in this repository.
There MUST NOT be a compatibility layer, alias, fallback parser, or dual-vocabulary phase for the previous `tile bank` naming on active maintained surfaces.
`tile` MUST remain in place wherever the correct meaning is geometric, map-related, layer-related, or otherwise outside the concrete graphical bank artifact boundary.
Studio MUST follow the concrete artifact naming 1:1 for the renamed artifact surfaces. It MUST NOT keep local alternative terminology for the same artifact.
## Rationale
The upstream runtime decision already closed the conceptual split between the concrete graphical bank artifact and the broader tile-domain vocabulary.
If this repository keeps the old local naming while the runtime adopts `GlyphBank`, the project enters a mixed-contract state where active repositories describe the same concrete artifact through incompatible names. That directly undermines the purpose of the upstream decision.
A no-compatibility, single-wave rename is the only option that preserves one active canonical vocabulary instead of institutionalizing drift between specs, fixtures, code, and UI.
Keeping `tile` only where the meaning is geometric or map/layer-oriented preserves the domain distinction that motivated the runtime decision in the first place.
## Technical Specification
1. The canonical local asset-family name for the concrete graphical bank artifact MUST migrate from `tile_bank` to `glyph_bank`.
2. The canonical local output format name for the concrete graphical bank artifact MUST migrate from `TILES/indexed_v1` to `GLYPH/indexed_v1`.
3. The canonical runtime-facing `bank_type` value emitted by the packer for the concrete graphical bank artifact MUST migrate from `TILES` to `GLYPH`.
4. Code symbols, class names, helpers, tests, and maintained strings that refer to the concrete graphical bank artifact MUST migrate from `Tile*`/`tile bank` naming to `Glyph*`/`glyph bank` naming as appropriate to the local language surface.
5. Specs and maintained lessons/docs in this repository MUST describe the concrete graphical bank artifact using `Glyph*` naming after the migration.
6. `tile` naming MUST remain unchanged in surfaces that describe geometric tile size, tile layers, tile maps, grid semantics, or other non-artifact tile-domain concepts.
7. Implementations MUST NOT preserve active dual support for both `tile bank` and `glyph bank` terminology in the serialized contract.
8. Fixtures and test assets maintained by this repository MUST migrate to the new serialized contract names in the same wave as the implementation.
9. This decision does not authorize any behavior change beyond naming propagation.
## Constraints
- No compatibility parser or alias layer for the old serialized names.
- No staged split between `packer` and `studio`; the rename is one coordinated wave.
- No rename of geometric or map/layer `tile` concepts.
- No change to payload bytes, metadata structure, codec semantics, or packing algorithms as part of this decision.
## Propagation Targets
- Specs:
- Update packer specs that currently define `tile_bank`, `TILES/indexed_v1`, or `bank_type = TILES`.
- Update Studio-facing maintained discussion/spec text where the concrete artifact is still described as `tile bank`.
- Code:
- Rename local packer asset-family, output-format, and emitted bank-type surfaces to the new canonical glyph naming.
- Rename Studio artifact-specific composition/support/coordinator surfaces that refer to the concrete graphical bank artifact.
- Preserve `tile` naming in geometric and map/layer surfaces.
- Tests and Fixtures:
- Update fixtures and test manifests that still serialize the old `tile_bank` and `TILES/indexed_v1` contract.
- Update tests and helper names to remove mixed vocabulary for the concrete artifact.
- Docs and Lessons:
- Rewrite maintained lessons and active workflow artifacts by meaning, not mechanical token replacement.
## Revision Log
- 2026-04-10: Accepted and linked to PLN-0048 for implementation planning.
- 2026-04-10: Initial draft from AGD-0028.
@@ -0,0 +1,119 @@
---
id: PLN-0048
ticket: glyph-bank-naming-alignment-with-runtime
title: Implement Glyph Bank Local Alignment
status: done
created: 2026-04-10
completed: 2026-04-10
tags: [packer, studio, naming, asset-contract, runtime-alignment, glyph-bank]
---
## Objective
Implement DEC-0025 by renaming the concrete graphical bank artifact from `tile bank` to `glyph bank` across active `packer` and `studio` code, serialized contract surfaces, specs, fixtures, tests, and maintained repository documentation, with no compatibility layer and no functional behavior change.
## Background
The runtime repository already accepted `DEC-0006`, which reserves `tile` for geometric, map, and layer concepts while moving the concrete graphical bank artifact to `GlyphBank` and `GLYPH`. This repository still exposes the old naming through local asset-family values, output formats, emitted bank types, Studio asset-family handling, specs, and fixtures. The accepted local decision locks a one-wave rename with no fallback parsing, no aliasing, and no staged split between `packer` and `studio`.
## Scope
### Included
- Rename the serialized asset-family contract from `tile_bank` to `glyph_bank`.
- Rename the serialized output-format contract from `TILES/indexed_v1` to `GLYPH/indexed_v1`.
- Rename emitted runtime-facing `bank_type` values from `TILES` to `GLYPH`.
- Rename packer and Studio artifact-specific code surfaces that still describe the concrete graphical bank as `Tile*` or `glyph bank`.
- Update fixtures, tests, specs, and maintained lessons/discussion artifacts that refer to the concrete graphical bank artifact.
- Preserve `tile` terminology where the meaning remains geometric, map-related, layer-related, or otherwise outside the artifact boundary.
### Excluded
- Any payload, layout, metadata, codec, or packing behavior change.
- Any compatibility parser, alias layer, or dual support for the previous serialized names.
- Renaming geometric tile-size concepts or map/layer terminology that is still semantically correct.
- Any broader runtime-side rename work already owned by `../runtime`.
## Execution Steps
### Step 1 - Rename the packer serialized contract surface
**What:** Migrate the local packer contract enums and parser-facing surfaces from `tile_bank` / `TILES/indexed_v1` / `TILES` to `glyph_bank` / `GLYPH/indexed_v1` / `GLYPH`.
**How:** Rename `AssetFamilyCatalog.TILE_BANK`, `OutputFormatCatalog.TILES_INDEXED_V1`, parser validation strings, materialized `bank_type` values, and any packer-owned contract constants or messages tied to the concrete artifact. Keep semantics unchanged and do not introduce compatibility parsing for the old names.
**File(s):** `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/messages/assets/AssetFamilyCatalog.java`; `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/messages/assets/OutputFormatCatalog.java`; `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/PackerAssetDeclarationParser.java`; `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/PackerOutputContractCatalog.java`; `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/FileSystemPackerWorkspaceService.java`
**Dependencies:** None.
### Step 2 - Rename packer artifact-specific implementation surfaces
**What:** Rename packer implementation types, walkers, requirements, helper methods, and diagnostics that describe the concrete graphical bank artifact.
**How:** Rename artifact-specific `TileBank` classes, helpers, and strings to `Glyph*` equivalents while preserving `tile` in geometric concepts such as `tileSize`. Adjust callsites consistently so active code no longer uses mixed vocabulary for the concrete artifact.
**File(s):** `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/models/PackerGlyphBankRequirements.java`; `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerGlyphBankWalker.java`; `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerAssetWalker.java`; `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/FileSystemPackerWorkspaceService.java`
**Dependencies:** Step 1.
### Step 3 - Rename Studio artifact-specific surfaces 1:1
**What:** Align Studio asset-family handling, bank composition support, palette overhauling gating, list/details presentation, and artifact labels with the new glyph naming.
**How:** Rename Studio classes, switches, and i18n keys/labels that refer to the concrete graphical bank artifact, keeping the rename artifact-specific and preserving any remaining geometric `tile` semantics outside that boundary. Studio must use the same canonical artifact vocabulary as the packer contract.
**File(s):** `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/bank/AssetDetailsGlyphBankCompositionFamilySupport.java`; `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/bank/AssetBankCapacityService.java`; `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/bank/AssetDetailsBankCompositionCoordinator.java`; `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/palette/AssetDetailsPaletteOverhaulingCoordinator.java`; `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/AssetDetailsUiSupport.java`; `prometeu-studio/src/main/java/p/studio/workspaces/assets/list/AssetListItemControl.java`; `prometeu-studio/src/main/java/p/studio/utilities/i18n/I18n.java`
**Dependencies:** Steps 1 and 2.
### Step 4 - Update specs, lessons, and maintained discussion text by meaning
**What:** Rewrite maintained documentation so the concrete graphical bank artifact uses glyph naming, while tile-domain concepts remain tile-domain concepts.
**How:** Update packer specs and maintained lessons/discussions manually by artifact meaning. Replace artifact-specific `tile bank` references with `glyph bank`, `glyph_bank`, `GLYPH/indexed_v1`, or `GLYPH` as appropriate, but preserve `tile` where it refers to tile geometry, tilemaps, layers, or palette-per-tile semantics.
**File(s):** `docs/specs/packer/3. Asset Declaration and Virtual Asset Contract Specification.md`; `docs/specs/packer/4. Build Artifacts and Deterministic Packing Specification.md`; `discussion/lessons/DSC-0003-packer-docs-import/LSN-0015-tile-bank-packing-contract-legacy.md`; `discussion/workflow/agendas/AGD-0002-palette-management-in-studio.md`; `discussion/workflow/agendas/AGD-0005-variable-tile-bank-palette-serialization.md`
**Dependencies:** Step 1.
### Step 5 - Migrate fixtures and tests in the same wave
**What:** Rename manifests, fixture content, test expectations, and helper names to the new serialized contract and artifact vocabulary.
**How:** Update test assets and fixtures that still use `type = tile_bank` and `format = TILES/indexed_v1`, then update unit and integration tests in `prometeu-packer` and `prometeu-studio` so expectations point to `glyph_bank`, `GLYPH/indexed_v1`, and `GLYPH`. Keep assertion coverage focused on proving no behavior change beyond naming.
**File(s):** `test-projects/main/assets/**/asset.json`; `prometeu-packer/prometeu-packer-v1/src/test/resources/fixtures/workspaces/**/asset.json`; `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/PackerAssetDeclarationParserTest.java`; `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/PackerAssetDetailsServiceTest.java`; `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/FileSystemPackerWorkspaceServiceTest.java`; `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/repositories/PackerGlyphBankWalkerTest.java`; `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/repositories/PackerRuntimeAssetMaterializerTest.java`; `prometeu-studio/src/test/java/p/studio/workspaces/assets/details/bank/AssetDetailsBankCompositionCoordinatorTest.java`; `prometeu-studio/src/test/java/p/studio/workspaces/assets/details/palette/AssetDetailsPaletteOverhaulingCoordinatorTest.java`
**Dependencies:** Steps 1 through 4.
### Step 6 - Validate the one-wave rename
**What:** Run focused verification across packer and Studio to prove the new vocabulary is canonical and behavior is unchanged.
**How:** Execute the relevant test suites, review representative specs/fixtures, and search for residual concrete-artifact `tile bank` references. Classify any remaining `tile` occurrence as either correct geometric/domain meaning or a rename miss to be fixed before completion.
**File(s):** all files touched by Steps 1 through 5
**Dependencies:** Steps 1 through 5.
## Test Requirements
### Unit Tests
- Update packer parser, walker, materializer, and workspace-service tests to use `glyph_bank`, `GLYPH/indexed_v1`, and `GLYPH`.
- Update Studio asset-details and palette/bank tests to use the renamed artifact-family symbols and labels.
### Integration Tests
- Run packer tests that exercise manifest parsing, fixture loading, pack execution, and emitted `bank_type` values.
- Run Studio tests that exercise asset-family-specific bank composition and palette overhauling paths.
### Manual Verification
- Inspect updated packer specs to confirm artifact-specific references use glyph naming while geometric tile concepts remain unchanged.
- Search the repository for residual `tile bank` / `TileBank` / `tile_bank` / `TILES/indexed_v1` references and classify each remaining hit.
- Inspect representative fixture manifests and packed output expectations to confirm the rename is contract-wide and behavior-preserving.
## Acceptance Criteria
- [ ] Active local serialized contract surfaces use `glyph_bank`, `GLYPH/indexed_v1`, and `GLYPH` for the concrete graphical bank artifact.
- [ ] No compatibility layer or alias remains for the old serialized names on active maintained surfaces.
- [ ] Packer artifact-specific code no longer uses mixed `Tile*`/`Glyph*` vocabulary for the same concrete artifact.
- [ ] Studio artifact-specific code follows the renamed glyph vocabulary 1:1.
- [ ] Maintained specs and lessons describe the concrete graphical bank artifact with glyph naming while preserving geometric/map/layer tile terminology where appropriate.
- [ ] Fixtures and tests are migrated in the same wave as the implementation.
- [ ] Relevant packer and Studio tests pass after the rename.
- [ ] No functional behavior change is introduced beyond naming propagation.
## Dependencies
- Accepted decision `DEC-0025`.
- Upstream runtime naming contract in `../runtime` `DEC-0006`.
- Coordinated updates across `prometeu-packer`, `prometeu-studio`, maintained docs, and fixture manifests.
## Risks
- Blind mechanical renaming can incorrectly touch geometric tile semantics that are explicitly out of scope.
- Removing old serialized names without compatibility means any missed fixture or parser path will fail fast and block the wave.
- Studio and packer may drift if one side is renamed more aggressively than the other during implementation.
- Historical or maintained discussion artifacts can keep mixed terminology if they are not reviewed semantically.