clean up
This commit is contained in:
parent
54f65f58e6
commit
a16edcb257
SSH Key Fingerprint:
SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
@ -1,7 +1,7 @@
|
||||
{"type":"meta","next_id":{"DSC":23,"AGD":21,"DEC":7,"PLN":6,"LSN":25,"CLSN":1}}
|
||||
{"type":"meta","next_id":{"DSC":23,"AGD":21,"DEC":7,"PLN":6,"LSN":26,"CLSN":1}}
|
||||
{"type":"discussion","id":"DSC-0020","status":"done","ticket":"jenkins-gitea-integration","title":"Jenkins Gitea Integration and Relocation","created_at":"2026-04-07","updated_at":"2026-04-07","tags":["ci","jenkins","gitea"],"agendas":[{"id":"AGD-0018","file":"workflow/agendas/AGD-0018-jenkins-gitea-integration-and-relocation.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"decisions":[{"id":"DEC-0003","file":"workflow/decisions/DEC-0003-jenkins-gitea-strategy.md","status":"accepted","created_at":"2026-04-07","updated_at":"2026-04-07"}],"plans":[{"id":"PLN-0003","file":"workflow/plans/PLN-0003-jenkins-gitea-execution.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"lessons":[{"id":"LSN-0021","file":"lessons/DSC-0020-jenkins-gitea-integration/LSN-0021-jenkins-gitea-integration.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}]}
|
||||
{"type":"discussion","id":"DSC-0021","status":"done","ticket":"asset-entry-codec-enum-with-metadata","title":"Asset Entry Codec Enum Contract","created_at":"2026-04-09","updated_at":"2026-04-09","tags":["asset","runtime","codec","metadata"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0024","file":"lessons/DSC-0021-asset-entry-codec-enum-contract/LSN-0024-string-on-the-wire-enum-in-runtime.md","status":"done","created_at":"2026-04-09","updated_at":"2026-04-09"}]}
|
||||
{"type":"discussion","id":"DSC-0022","status":"open","ticket":"tile-bank-vs-glyph-bank-domain-naming","title":"Glyph Bank Domain Naming Contract","created_at":"2026-04-09","updated_at":"2026-04-10","tags":["gfx","runtime","naming","domain-model"],"agendas":[{"id":"AGD-0020","file":"AGD-0020-tile-bank-vs-glyph-bank-domain-naming.md","status":"accepted","created_at":"2026-04-09","updated_at":"2026-04-10"}],"decisions":[{"id":"DEC-0006","file":"DEC-0006-glyph-bank-domain-naming-contract.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10","ref_agenda":"AGD-0020"}],"plans":[{"id":"PLN-0005","file":"PLN-0005-glyph-bank-domain-naming-execution.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10","ref_decisions":["DEC-0006"]}],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0022","status":"done","ticket":"tile-bank-vs-glyph-bank-domain-naming","title":"Glyph Bank Domain Naming Contract","created_at":"2026-04-09","updated_at":"2026-04-10","tags":["gfx","runtime","naming","domain-model"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0025","file":"lessons/DSC-0022-glyph-bank-domain-naming/LSN-0025-rename-artifact-by-meaning-not-by-token.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
|
||||
{"type":"discussion","id":"DSC-0001","status":"done","ticket":"legacy-runtime-learn-import","title":"Import legacy runtime learn into discussion lessons","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["migration","tech-debt"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0001","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0001-prometeu-learn-index.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0002","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0002-historical-asset-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0003","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0003-historical-audio-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0004","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0004-historical-cartridge-boot-protocol-and-manifest-authority.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0005","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0005-historical-game-memcard-slots-surface-and-semantics.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0006","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0006-historical-gfx-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0007","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0007-historical-retired-fault-and-input-decisions.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0008","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0008-historical-vm-core-and-assets.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0009","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0009-mental-model-asset-management.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0010","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0010-mental-model-audio.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0011","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0011-mental-model-gfx.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0012","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0012-mental-model-input.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0013","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0013-mental-model-observability-and-debugging.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0014","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0014-mental-model-portability-and-cross-platform.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0015","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0015-mental-model-save-memory-and-memcard.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0016","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0016-mental-model-status-first-and-fault-thinking.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0017","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0017-mental-model-time-and-cycles.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0018","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0018-mental-model-touch.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
|
||||
{"type":"discussion","id":"DSC-0002","status":"open","ticket":"runtime-edge-test-plan","title":"Agenda - Runtime Edge Test Plan","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0001","file":"workflow/agendas/AGD-0001-runtime-edge-test-plan.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0003","status":"open","ticket":"packed-cartridge-loader-pmc","title":"Agenda - Packed Cartridge Loader PMC","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0002","file":"workflow/agendas/AGD-0002-packed-cartridge-loader-pmc.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
|
||||
@ -0,0 +1,45 @@
|
||||
---
|
||||
id: LSN-0025
|
||||
ticket: tile-bank-vs-glyph-bank-domain-naming
|
||||
title: Rename Artifact by Meaning, Not by Token
|
||||
created: 2026-04-10
|
||||
tags: [gfx, runtime, naming, refactor, documentation]
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
The runtime used `TileBank` as the name of the concrete graphical bank artifact while also using `tile` for map, layer, and geometric concepts such as `TileLayer`, `TileMap`, and `TileSize`. This overloaded the term `tile` across two different meanings.
|
||||
|
||||
The implemented migration renamed only the concrete bank artifact to `GlyphBank` and renamed the corresponding asset-bank contract from `BankType::TILES` to `BankType::GLYPH`, while explicitly preserving `TileLayer`, `TileMap`, and `TileSize`.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### Glyph Bank Domain Naming Contract
|
||||
|
||||
**What:**
|
||||
Rename the concrete graphical bank artifact and its runtime interfaces to `GlyphBank`, but keep tile-domain structures unchanged where `tile` still correctly describes layers, maps, grids, and geometry.
|
||||
|
||||
**Why:**
|
||||
The goal was domain clarity, not behavior change. The project needed a more precise name for the concrete graphical bank without reopening rendering architecture or erasing valid uses of `tile`.
|
||||
|
||||
**Trade-offs:**
|
||||
This requires more care than a blind search-and-replace. The migration is broader editorially, but safer semantically, because it avoids damaging concepts that still belong in the tile domain.
|
||||
|
||||
## Patterns and Algorithms
|
||||
|
||||
- Rename by artifact meaning, not by string token frequency.
|
||||
- When a term is overloaded, split the rename along domain boundaries instead of trying to enforce total lexical uniformity.
|
||||
- Let the runtime contract adopt the new canonical artifact name (`GlyphBank`, `BankType::GLYPH`) while preserving existing terms for excluded concepts (`TileLayer`, `TileMap`, `TileSize`).
|
||||
- Apply the same semantic rule to docs and lessons, not only to code.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- Blind replacement would have incorrectly renamed tile-layer and tile-size concepts that were intentionally out of scope.
|
||||
- Partial renames create mixed vocabulary, which is worse than either old or new terminology used consistently.
|
||||
- Historical documentation is especially easy to corrupt if rewritten mechanically instead of by artifact meaning.
|
||||
|
||||
## Takeaways
|
||||
|
||||
- A naming refactor can be rename-only in behavior while still requiring architectural discipline in wording.
|
||||
- Use one canonical name per artifact, but do not force unrelated domains to share that rename.
|
||||
- Documentation migrations should follow the same semantic boundary as code migrations, or the codebase will drift back into conceptual ambiguity.
|
||||
@ -1,221 +0,0 @@
|
||||
---
|
||||
id: AGD-0020
|
||||
ticket: tile-bank-vs-glyph-bank-domain-naming
|
||||
title: Agenda - Tile Bank vs Glyph Bank Domain Naming
|
||||
status: accepted
|
||||
created: 2026-04-09
|
||||
resolved: 2026-04-10
|
||||
decision: DEC-0006
|
||||
tags: [gfx, runtime, naming, domain-model]
|
||||
---
|
||||
|
||||
# Agenda - Tile Bank vs Glyph Bank Domain Naming
|
||||
|
||||
## Contexto
|
||||
|
||||
Hoje o runtime usa `TileBank`, `tile_bank.rs`, `TileBankPool*` e termos derivados para nomear o banco grafico consumido pelo renderer e pelo pipeline de assets.
|
||||
|
||||
Ao mesmo tempo, existe a vontade de elevar `Tile` para um conceito mais amplo do dominio, nao restrito ao sheet grafico concreto. Nessa leitura:
|
||||
|
||||
- `Tile` passa a ser uma ideia mais geral da grade/elemento logico;
|
||||
- o que hoje e o artefato grafico concreto chamado `TileBank` deveria passar a se chamar `GlyphBank`;
|
||||
- a intencao inicial nao e mudar formato, memoria, payload ou algoritmo, e sim alinhar a linguagem do projeto.
|
||||
|
||||
Esse tema ja encosta em documentacao e lessons existentes, porque o vocabulario atual mistura:
|
||||
|
||||
- tile como unidade de composicao visual;
|
||||
- tile bank como sheet grafico concreto;
|
||||
- referencias esparsas a glyph em lições e agendas.
|
||||
|
||||
## Problema
|
||||
|
||||
Se o projeto mudar o centro semantico de `tile` e `glyph` sem uma decisao explicita, o repositorio tende a ficar com vocabulário hibrido:
|
||||
|
||||
- tipos antigos com nome legado;
|
||||
- docs novas com nome novo;
|
||||
- renderer e assets falando uma lingua;
|
||||
- lessons e discussoes falando outra.
|
||||
|
||||
O problema principal nao e tecnico-algoritmico. E semantico e operacional: qual vocabulario o projeto quer tornar canonico para o banco grafico concreto, e qual parte dessa mudanca e apenas rename mecanico versus mudanca real de modelo.
|
||||
|
||||
## Pontos Criticos
|
||||
|
||||
1. Escopo da mudanca.
|
||||
Precisamos separar rename de dominio de qualquer mudanca de formato ou comportamento.
|
||||
|
||||
2. Contrato externo.
|
||||
Precisamos fechar quais contratos externos tambem entram no rename. Ja existe direcao para migrar `BankType::TILES` para `BankType::GLYPH`.
|
||||
|
||||
3. Consistencia de linguagem.
|
||||
A mudanca so vale a pena se atingir codigo, tests, docs e lessons de forma coordenada.
|
||||
|
||||
4. Custo de churn.
|
||||
Mesmo sem mudar comportamento, o rename atravessa muitos modulos (`hal`, `drivers`, renderer, pools, mensagens de erro, tests e docs).
|
||||
|
||||
5. Fronteira conceitual.
|
||||
Precisamos definir o que `Tile` passa a significar depois do rename, para evitar trocar um overload semantico por outro.
|
||||
|
||||
## Opcoes
|
||||
|
||||
### Opcao A - Manter `TileBank` como esta
|
||||
|
||||
- **Abordagem:** preservar `TileBank` como nome canonico do banco grafico concreto e aceitar que `tile` continue carregando tanto o lado logico quanto o lado visual.
|
||||
- **Pro:** zero churn nominal imediato e nenhuma migracao de docs/codigo.
|
||||
- **Con:** o overload conceitual de `tile` permanece e pode continuar poluindo a linguagem de dominio.
|
||||
- **Tradeoff:** economiza trabalho agora ao custo de clareza futura.
|
||||
|
||||
### Opcao B - Renomear `TileBank` para `GlyphBank` como refactor semantico
|
||||
|
||||
- **Abordagem:** tratar a mudanca como rename consistente de tipos, modulos, docs, testes e mensagens, sem alterar formato de payload, layout em memoria ou renderer.
|
||||
- **Pro:** melhora a linguagem do projeto sem reabrir a arquitetura grafica.
|
||||
- **Con:** exige disciplina para manter a promessa de “rename only” e nao misturar isso com redesign.
|
||||
- **Tradeoff:** churn mecanico relativamente alto para ganhar clareza conceitual.
|
||||
|
||||
### Opcao C - Fazer rename parcial
|
||||
|
||||
- **Abordagem:** adotar `glyph` apenas em docs novas ou em algumas camadas, preservando nomes antigos em APIs e modulos centrais.
|
||||
- **Pro:** menor custo inicial.
|
||||
- **Con:** cria o pior estado intermediario: dois vocabulários concorrentes para o mesmo conceito.
|
||||
- **Tradeoff:** parece barato, mas deixa a linguagem do projeto menos confiavel.
|
||||
|
||||
## Sugestao / Recomendacao
|
||||
|
||||
Seguir inicialmente com a **Opcao B**, desde que a discussao confirme que a mudanca e de nomenclatura e nao de semantica operacional.
|
||||
|
||||
A recomendacao provisoria e:
|
||||
|
||||
- `GlyphBank` se torna o nome do artefato grafico concreto que hoje chamamos de `TileBank`;
|
||||
- `Tile` fica livre para representar um conceito mais geral do dominio;
|
||||
- `BankType::TILES` passa a `BankType::GLYPH`;
|
||||
- a migracao deve ser consistente em codigo, tests, docs e lessons;
|
||||
- `TileLayer` e derivados nao entram automaticamente no rename, porque ja pertencem a outra fronteira de dominio e precisam de triagem separada;
|
||||
- a discussao deve explicitar quais superfícies mudam juntas para impedir vocabulario hibrido sem reabrir a arquitetura grafica.
|
||||
|
||||
## Perguntas em Aberto
|
||||
|
||||
- Confirmar a superficie exata do rename para evitar misturar banco grafico concreto com conceitos de layer/mapa.
|
||||
|
||||
## Discussao
|
||||
|
||||
### Direcao fechada ate aqui
|
||||
|
||||
1. **Natureza da mudanca**
|
||||
A mudanca e `rename-only`. Nao ha intencao de alterar formato, algoritmo, layout em memoria ou comportamento.
|
||||
|
||||
2. **Contrato externo**
|
||||
`BankType::TILES` nao deve permanecer. O contrato deve migrar para `BankType::GLYPH`.
|
||||
|
||||
3. **Escopo documental**
|
||||
A migracao deve ser completa, inclusive em documentacao e lessons historicas.
|
||||
|
||||
4. **Colisao semantica**
|
||||
`glyph` nao colide com outro artefato canonico relevante nesta etapa.
|
||||
|
||||
### Fronteira importante
|
||||
|
||||
Nem todo `Tile*` deve migrar automaticamente para `Glyph*`.
|
||||
|
||||
Existe uma fronteira entre:
|
||||
|
||||
- nomes que descrevem o banco grafico concreto e seu circuito de carga/uso; e
|
||||
- nomes que ja descrevem dominio de layer, mapa, grade ou composicao.
|
||||
|
||||
Por isso, a proxima resposta que falta precisa ser dada por superficie concreta, e nao por regra global simplista.
|
||||
|
||||
### Lista para voto `sim` / `nao`
|
||||
|
||||
Responda `sim` ou `nao` para cada grupo abaixo.
|
||||
|
||||
1. **Banco concreto e modulo base**
|
||||
Inclui `TileBank`, `tile_bank.rs`, comentarios e docs especificos desse tipo.
|
||||
|
||||
2. **Enum e contrato de asset**
|
||||
Inclui `BankType::TILES -> BankType::GLYPH`, mensagens de erro, metadata helpers e referencias equivalentes no path de assets.
|
||||
|
||||
3. **Pools e interfaces de memoria**
|
||||
Inclui `TileBankPoolAccess`, `TileBankPoolInstaller`, `tile_bank_slot`, `install_tile_bank`, campos internos como `tile_bank_pool`.
|
||||
|
||||
4. **Asset manager e loader path**
|
||||
Inclui funcoes como `decode_tile_bank_*`, `perform_load_tile_bank`, variaveis locais, testes e mensagens associadas ao load do banco grafico.
|
||||
|
||||
5. **Renderer e hardware references ao banco**
|
||||
Inclui usos em `gfx.rs` e `hardware.rs` que referenciam o banco concreto, por exemplo campos `tile_banks`, docs sobre VRAM `TileBanks`, parametros `bank: &TileBank`.
|
||||
|
||||
6. **Modulo e tipos de layer/mapa**
|
||||
Inclui `tile_layer.rs`, `TileMap`, `TileLayer`, `ScrollableTileLayer`, `HudTileLayer`.
|
||||
Este grupo e o mais sensivel porque pode nao ser rename de banco concreto, e sim outro dominio.
|
||||
|
||||
7. **TileSize**
|
||||
Inclui `TileSize` e referencias ao tamanho de tile como unidade geometrica.
|
||||
Este grupo pode continuar como `TileSize` mesmo se o banco virar `GlyphBank`.
|
||||
|
||||
8. **Strings, fixtures e test names**
|
||||
Inclui nomes de testes, helper names, snapshots, mensagens e dados de teste que ainda falam em tile bank.
|
||||
|
||||
9. **Lessons e docs historicas**
|
||||
Inclui lessons ja publicadas e material de discussao/mental model que hoje falam em `TileBank`.
|
||||
|
||||
### Votos registrados
|
||||
|
||||
1. **Banco concreto e modulo base**: `sim`
|
||||
`TileBank`, `tile_bank.rs`, modulo base e documentacao associada entram na migracao.
|
||||
|
||||
2. **Enum e contrato de asset**: `sim`
|
||||
`BankType::TILES` e o contrato textual equivalente entram na migracao para `GLYPH`.
|
||||
|
||||
3. **Pools e interfaces de memoria**: `sim`
|
||||
`TileBankPool*`, `tile_bank_slot` e derivados entram na migracao.
|
||||
|
||||
4. **Asset manager e loader path**: `sim`
|
||||
Helpers, decode path, mensagens e testes associados ao banco grafico concreto entram na migracao.
|
||||
|
||||
5. **Renderer e hardware references ao banco**: `sim`
|
||||
Referencias ao banco concreto em renderer e hardware entram na migracao.
|
||||
|
||||
6. **Modulo e tipos de layer/mapa**: `nao`
|
||||
`TileLayer`, `TileMap`, `ScrollableTileLayer` e `HudTileLayer` ficam fora desta rodada.
|
||||
|
||||
7. **TileSize**: `nao`
|
||||
`TileSize` permanece como conceito geometrico e nao entra automaticamente no rename.
|
||||
|
||||
8. **Strings, fixtures e test names**: `sim`
|
||||
Helpers, fixtures, mensagens e nomes de testes entram na migracao para evitar residuos do vocabulario antigo.
|
||||
|
||||
9. **Lessons e docs historicas**: `sim`
|
||||
A migracao documental e historica entra no escopo, seguindo a mesma fronteira desta agenda: renomear o banco grafico concreto sem arrastar automaticamente o dominio de layer/mapa.
|
||||
|
||||
## Resolucao Provisoria
|
||||
|
||||
Ha consenso provisoriamente estabelecido sobre os seguintes pontos:
|
||||
|
||||
- a mudanca e `rename-only`;
|
||||
- o vocabulario canonico do banco grafico concreto passa de `TileBank` para `GlyphBank`;
|
||||
- `BankType::TILES` deve migrar para `BankType::GLYPH`;
|
||||
- pools, contrato de asset, loader path, renderer, hardware references, fixtures e nomes de teste entram na migracao;
|
||||
- `TileLayer`/`TileMap` e derivados ficam fora desta rodada;
|
||||
- `TileSize` fica fora desta rodada;
|
||||
- docs e lessons historicas entram no escopo, respeitando essa mesma fronteira.
|
||||
|
||||
O principal ponto restante para encerrar a agenda e confirmar se essa resolucao ja e suficiente para virar decisao normativa, ou se ainda falta detalhar como a migracao documental deve tratar referencias historicas em texto corrido quando `tile` continuar correto para layer/mapa.
|
||||
|
||||
## Resolucao
|
||||
|
||||
A agenda fica encerrada com a seguinte orientacao:
|
||||
|
||||
- a mudanca e `rename-only`;
|
||||
- o banco grafico concreto passa a se chamar `GlyphBank`;
|
||||
- `BankType::TILES` passa a `BankType::GLYPH`;
|
||||
- pools, contrato de asset, loader path, renderer, hardware references, fixtures, nomes de teste, docs e lessons entram na migracao;
|
||||
- `TileLayer`, `TileMap` e derivados ficam fora;
|
||||
- `TileSize` fica fora;
|
||||
- docs e lessons antigas devem migrar referencias ao banco grafico concreto para `GlyphBank`, mantendo `tile` quando o assunto for layer, mapa, grade ou geometria.
|
||||
|
||||
## Criterio para Encerrar
|
||||
|
||||
Esta agenda pode ser encerrada quando houver consenso escrito sobre:
|
||||
|
||||
- se a mudanca e rename-only ou nao;
|
||||
- qual vocabulario passa a ser canonico;
|
||||
- quais contratos externos entram no rename;
|
||||
- quais grupos concretos entram ou nao na migracao;
|
||||
- como evitar que `TileLayer`/`TileMap` sejam arrastados automaticamente sem decisao propria.
|
||||
@ -1,93 +0,0 @@
|
||||
---
|
||||
id: DEC-0006
|
||||
ticket: tile-bank-vs-glyph-bank-domain-naming
|
||||
title: Glyph Bank Domain Naming Contract
|
||||
status: accepted
|
||||
created: 2026-04-10
|
||||
accepted: 2026-04-10
|
||||
agenda: AGD-0020
|
||||
plans: [PLN-0005]
|
||||
tags: [gfx, runtime, naming, domain-model]
|
||||
---
|
||||
|
||||
## Status
|
||||
|
||||
Accepted on 2026-04-10.
|
||||
|
||||
## Contexto
|
||||
|
||||
The runtime currently uses `TileBank` and related names for the concrete graphical bank consumed by the asset pipeline and renderer. At the same time, the project wants `Tile` to remain available as a broader domain concept for grid, layer, map, and geometric tile semantics.
|
||||
|
||||
This decision closes the naming contract by separating:
|
||||
|
||||
- the concrete graphical bank artifact;
|
||||
- the logical tile/layer/map domain;
|
||||
- the migration boundary for code, tests, docs, and historical lessons.
|
||||
|
||||
The change is explicitly rename-only. It does not alter format, runtime behavior, memory layout, payload structure, or renderer algorithms.
|
||||
|
||||
## Decisao
|
||||
|
||||
1. The concrete graphical bank currently named `TileBank` MUST be renamed to `GlyphBank`.
|
||||
2. This rename MUST be treated as nomenclature-only. It MUST NOT change payload format, runtime behavior, memory layout, codec behavior, metadata structure, or rendering semantics.
|
||||
3. `BankType::TILES` MUST be renamed to `BankType::GLYPH`.
|
||||
4. The asset contract and runtime code that refer to the concrete graphical bank MUST migrate to `Glyph*` naming consistently.
|
||||
5. The following groups MUST be included in the rename:
|
||||
- concrete bank type and module;
|
||||
- asset contract and asset-facing terminology;
|
||||
- memory pools and bank installation/access interfaces;
|
||||
- asset manager decode/load path;
|
||||
- renderer and hardware references to the concrete bank;
|
||||
- fixtures, test names, helper names, and user-facing/runtime-facing strings for the concrete bank;
|
||||
- documentation and historical lessons, subject to the editorial boundary below.
|
||||
6. The following groups MUST NOT be renamed as part of this decision:
|
||||
- `TileLayer`, `TileMap`, `ScrollableTileLayer`, `HudTileLayer`, and related layer/map structures;
|
||||
- `TileSize` and geometric tile-size concepts.
|
||||
7. Documentation and historical lessons MUST be updated with the following editorial rule:
|
||||
- references to the concrete graphical bank artifact MUST migrate to `GlyphBank` and equivalent `Glyph*` naming;
|
||||
- references to layer, map, grid, or geometric tile concepts MUST remain `tile` when that is the correct domain meaning.
|
||||
8. The project MUST NOT adopt a partial mixed vocabulary where the same concrete bank artifact is simultaneously described as both `TileBank` and `GlyphBank` in active code or maintained documentation.
|
||||
9. `glyph` is treated as a new canonical artifact name for this stage and does not conflict with an existing canonical artifact that would block adoption.
|
||||
|
||||
## Rationale
|
||||
|
||||
- The current name overloads `tile` across both logical map/layer concepts and the concrete graphical bank artifact.
|
||||
- Renaming only the concrete bank artifact improves domain clarity without reopening graphics architecture.
|
||||
- Excluding `TileLayer`, `TileMap`, and `TileSize` preserves established semantics where `tile` still means the logical or geometric concept.
|
||||
- A full migration across code, tests, docs, and lessons avoids the unstable mixed-language state that tends to follow partial renames.
|
||||
|
||||
## Invariantes / Contrato
|
||||
|
||||
- `GlyphBank` is the canonical name for the concrete graphical bank artifact.
|
||||
- `tile` remains canonical for layer/map/geometric concepts unless a later decision explicitly changes that.
|
||||
- `BankType::GLYPH` is the canonical asset-bank enum variant for the concrete graphical bank.
|
||||
- This decision is a rename boundary, not a behavior-change boundary.
|
||||
- Documentation must follow artifact meaning, not mechanical string replacement.
|
||||
|
||||
## Impactos
|
||||
|
||||
- `prometeu-hal` will need type/module/enum renames for the concrete graphical bank path.
|
||||
- `prometeu-drivers` will need renderer, memory-pool, hardware, and asset-manager naming migration for bank-specific references.
|
||||
- Tests, fixtures, and helper names need coordinated updates to avoid mixed terminology.
|
||||
- Docs and lessons need targeted rewriting rather than blind search-and-replace, because `tile` remains correct in map/layer contexts.
|
||||
|
||||
## Referencias
|
||||
|
||||
- AGD-0020: Tile Bank vs Glyph Bank Domain Naming
|
||||
- LSN-0022: Tilemap Empty Cell Convergence
|
||||
- `crates/console/prometeu-hal/src/tile_bank.rs`
|
||||
- `crates/console/prometeu-hal/src/tile_layer.rs`
|
||||
- `crates/console/prometeu-drivers/src/gfx.rs`
|
||||
- `crates/console/prometeu-drivers/src/memory_banks.rs`
|
||||
- `crates/console/prometeu-drivers/src/asset.rs`
|
||||
|
||||
## Propagacao Necessaria
|
||||
|
||||
- Write an execution plan before code and documentation migration.
|
||||
- Rename the concrete bank surface consistently across runtime crates.
|
||||
- Preserve `tile` naming in layer/map/geometric surfaces excluded by this decision.
|
||||
- Update docs and lessons according to artifact meaning, not blanket replacement.
|
||||
|
||||
## Revision Log
|
||||
|
||||
- 2026-04-10: Initial accepted decision from AGD-0020.
|
||||
@ -1,161 +0,0 @@
|
||||
---
|
||||
id: PLN-0005
|
||||
ticket: tile-bank-vs-glyph-bank-domain-naming
|
||||
title: Glyph Bank Domain Naming Execution
|
||||
status: accepted
|
||||
created: 2026-04-10
|
||||
completed:
|
||||
tags: [gfx, runtime, naming, domain-model]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
Implement DEC-0006 by renaming the concrete graphical bank artifact from `TileBank` to `GlyphBank` across runtime code, tests, documentation, and historical lessons, while preserving behavior and keeping the excluded tile-domain surfaces untouched. This is a rename-only migration. It must not alter payload format, rendering semantics, codec behavior, metadata structure, or memory layout.
|
||||
|
||||
## Decisions de Origem
|
||||
|
||||
- DEC-0006: Glyph Bank Domain Naming Contract
|
||||
|
||||
## Alvo
|
||||
|
||||
Land a consistent runtime-and-docs migration that:
|
||||
|
||||
- renames the concrete bank artifact and its module/type surface to `GlyphBank`;
|
||||
- renames `BankType::TILES` to `BankType::GLYPH`;
|
||||
- renames pool and loader/runtime bank-specific APIs accordingly;
|
||||
- preserves `TileLayer`, `TileMap`, `ScrollableTileLayer`, `HudTileLayer`, and `TileSize`;
|
||||
- rewrites maintained docs and lessons according to artifact meaning rather than blanket token replacement.
|
||||
|
||||
## Escopo
|
||||
|
||||
- `prometeu-hal` concrete bank type/module/enum renames.
|
||||
- `prometeu-drivers` renderer, memory-bank, hardware, and asset-manager bank-specific renames.
|
||||
- `prometeu-system` callsites and dispatch paths that refer to the asset-bank enum variant.
|
||||
- Tests, helpers, fixtures, and strings that still describe the concrete bank as `TileBank`.
|
||||
- Discussion lessons and maintained discussion artifacts that refer to the concrete graphical bank artifact.
|
||||
|
||||
## Fora de Escopo
|
||||
|
||||
- Any format, algorithm, codec, metadata, or layout change.
|
||||
- Renaming `TileLayer`, `TileMap`, `ScrollableTileLayer`, `HudTileLayer`, or related layer/map structures.
|
||||
- Renaming `TileSize` or geometric tile-size concepts.
|
||||
- Redesigning tile/glyph semantics beyond the naming boundary established by DEC-0006.
|
||||
|
||||
## Plano de Execucao
|
||||
|
||||
### Step 1 - Rename the HAL concrete bank surface
|
||||
|
||||
**What:**
|
||||
Rename the concrete bank module and type surface in `prometeu-hal` from `TileBank` to `GlyphBank`.
|
||||
|
||||
**How:**
|
||||
Rename `tile_bank.rs` to `glyph_bank.rs`, update `lib.rs` exports/import paths, rename `TileBank` to `GlyphBank`, and rename concrete-bank-specific constants if they are artifact-specific rather than geometric. Keep `TileSize` unchanged even if it continues to live near the bank implementation or must be re-exported from the renamed module in a compatibility-preserving layout inside this refactor.
|
||||
|
||||
**File(s):**
|
||||
- `crates/console/prometeu-hal/src/tile_bank.rs`
|
||||
- `crates/console/prometeu-hal/src/lib.rs`
|
||||
- any direct imports of `prometeu_hal::tile_bank::*` in runtime crates
|
||||
|
||||
### Step 2 - Rename the asset-bank contract
|
||||
|
||||
**What:**
|
||||
Migrate the asset-bank enum and related asset-facing terminology from `TILES` to `GLYPH`.
|
||||
|
||||
**How:**
|
||||
Rename `BankType::TILES` to `BankType::GLYPH`, update any JSON/serde expectations and validation paths, and rename asset-facing metadata helpers only where they describe the concrete bank artifact rather than the geometric tile model. Preserve behavior and fail-fast semantics unchanged.
|
||||
|
||||
**File(s):**
|
||||
- `crates/console/prometeu-hal/src/asset.rs`
|
||||
- `crates/console/prometeu-hal/src/cartridge_loader.rs`
|
||||
- `crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs`
|
||||
- `crates/console/prometeu-system/src/virtual_machine_runtime/tick.rs`
|
||||
- `crates/console/prometeu-system/src/virtual_machine_runtime/tests.rs`
|
||||
|
||||
### Step 3 - Rename memory pools and concrete-bank runtime APIs
|
||||
|
||||
**What:**
|
||||
Rename bank-specific pool interfaces and storage paths that refer to the concrete graphical bank.
|
||||
|
||||
**How:**
|
||||
Rename `TileBankPoolAccess`, `TileBankPoolInstaller`, `tile_bank_slot`, `install_tile_bank`, `tile_bank_pool`, and related fields/traits/vars to `Glyph*` equivalents. Keep semantics and slot behavior unchanged.
|
||||
|
||||
**File(s):**
|
||||
- `crates/console/prometeu-drivers/src/memory_banks.rs`
|
||||
- `crates/console/prometeu-drivers/src/hardware.rs`
|
||||
- `crates/console/prometeu-drivers/src/gfx.rs`
|
||||
- `crates/console/prometeu-drivers/src/asset.rs`
|
||||
|
||||
### Step 4 - Rename concrete-bank decode/load path and tests
|
||||
|
||||
**What:**
|
||||
Update the asset manager and concrete-bank decode path to the new artifact name.
|
||||
|
||||
**How:**
|
||||
Rename functions such as `decode_tile_bank_*`, `perform_load_tile_bank`, and related test helpers/messages to `GlyphBank` naming. Keep payload interpretation, palette handling, and runtime materialization identical to current behavior. Do not rename `TileSize`.
|
||||
|
||||
**File(s):**
|
||||
- `crates/console/prometeu-drivers/src/asset.rs`
|
||||
- affected tests in `crates/console/prometeu-drivers/src/asset.rs`
|
||||
- any helper or stress/test utility strings such as `missing_tile_bank`
|
||||
|
||||
### Step 5 - Apply renderer and hardware editorial cleanup
|
||||
|
||||
**What:**
|
||||
Rename only the references that describe the concrete bank artifact inside renderer and hardware documentation/comments.
|
||||
|
||||
**How:**
|
||||
Update comments, docs, field names, and user-facing/runtime-facing strings so that references to the bank artifact become `GlyphBank`/`glyph bank`, while preserving `tile` terminology for layers, maps, and geometric concepts. Review `gfx.rs` carefully because it contains both domains.
|
||||
|
||||
**File(s):**
|
||||
- `crates/console/prometeu-drivers/src/gfx.rs`
|
||||
- `crates/console/prometeu-drivers/src/hardware.rs`
|
||||
- any crate-level docs/comments on the bank artifact path
|
||||
|
||||
### Step 6 - Rewrite maintained lessons and discussion docs by meaning
|
||||
|
||||
**What:**
|
||||
Migrate maintained lessons and relevant discussion text to the new canonical artifact name.
|
||||
|
||||
**How:**
|
||||
Update published lessons and maintained discussion artifacts so that references to the concrete graphical bank become `GlyphBank`, but references to tile layers, tilemaps, grid semantics, or tile geometry remain `tile`. Use manual review, not blanket replacement.
|
||||
|
||||
**File(s):**
|
||||
- `discussion/lessons/DSC-0016-tilemap-empty-cell-semantics/LSN-0022-tilemap-empty-cell-convergence.md`
|
||||
- `discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0011-mental-model-gfx.md`
|
||||
- `discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0009-mental-model-asset-management.md`
|
||||
- any maintained agenda/decision/plan artifacts still intentionally retained and referencing the concrete bank artifact
|
||||
|
||||
## Criterios de Aceite
|
||||
|
||||
- The canonical concrete bank type/module name in runtime code is `GlyphBank`.
|
||||
- The canonical asset-bank enum variant is `BankType::GLYPH`.
|
||||
- Pool interfaces and concrete-bank runtime helpers use `Glyph*` naming consistently.
|
||||
- `TileLayer`, `TileMap`, `ScrollableTileLayer`, `HudTileLayer`, and `TileSize` remain unchanged.
|
||||
- No behavior, payload format, or renderer semantics change as part of this migration.
|
||||
- Tests, helper names, and runtime-facing strings do not keep active mixed `TileBank`/`GlyphBank` naming for the same artifact.
|
||||
- Maintained lessons and docs use `GlyphBank` for the concrete bank artifact while preserving `tile` where it refers to layer/map/geometric concepts.
|
||||
|
||||
## Tests / Validacao
|
||||
|
||||
### Unit Tests
|
||||
|
||||
- Update and run unit tests that directly construct or decode the concrete graphical bank path.
|
||||
- Confirm renamed bank/pool/helper symbols compile without compatibility shims.
|
||||
|
||||
### Integration Tests
|
||||
|
||||
- Run `prometeu-hal`, `prometeu-drivers`, and `prometeu-system` test targets affected by the rename.
|
||||
- Verify asset loading still succeeds for the renamed `BankType::GLYPH` path.
|
||||
|
||||
### Manual Verification
|
||||
|
||||
- Review representative docs and lessons to confirm `GlyphBank` only replaces the concrete bank artifact meaning.
|
||||
- Review `gfx.rs` and `tile_layer.rs` boundaries to confirm tile-domain structures were not accidentally renamed.
|
||||
- Search the repository for residual `TileBank` references and classify any remaining occurrence as either acceptable historical residue outside scope or a migration miss.
|
||||
|
||||
## Riscos
|
||||
|
||||
- The repository uses `tile` in two different domains, so blind search-and-replace is likely to over-rename excluded surfaces.
|
||||
- Renaming the enum variant from `TILES` to `GLYPH` touches serialization contracts and can break test fixtures or external packer assumptions if not coordinated.
|
||||
- Moving `tile_bank.rs` to `glyph_bank.rs` may cause broad import churn across crates and tests.
|
||||
- Historical lessons can easily drift into editorial inconsistency if the rewrite is done mechanically instead of semantically.
|
||||
Loading…
x
Reference in New Issue
Block a user