clean up

docs/runtime/agendas/023-tilemap-empty-cell-vs-tile-id-zero.md

@@ -0,0 +1,99 @@
+# Tilemap Empty Cell vs Tile ID Zero
+
+## Contexto
+
+O runtime hoje usa `tile.id == 0` como atalho para "tile ausente" no caminho de render de tilemap.
+
+Ao mesmo tempo, o contrato de `tile bank` em evolucao no packer quer permitir que `tile_id = 0` seja um tile real e valido dentro do bank.
+
+Isso cria conflito direto entre:
+
+- semantica atual do tilemap no runtime;
+- e o contrato de packing/runtime asset bank que trata `tile_id` como indice valido do bank desde zero.
+
+## Problema
+
+Precisamos decidir qual e a semantica correta para representar ausencia de tile em tilemaps.
+
+Hoje o comportamento implicito e:
+
+- `tile.id == 0` significa "nao desenhar";
+- portanto o tile de indice `0` no bank fica inutilizavel no caminho de tilemap;
+- sprites, por outro lado, nao carregam a mesma semantica implicita de vazio.
+
+Isso deixa o modelo inconsistente:
+
+1. o mesmo `tile_id` nao significa a mesma coisa em todos os consumidores;
+2. o bank `TileBank` nao explicita reserva de `tile_id = 0`;
+3. o packer teria que compensar uma regra de consumidor que nao esta modelada no contrato do asset bank.
+
+## Pontos Criticos
+
+- `tile_id` deve representar um indice valido no bank, nao um sentinel escondido, sempre que possivel;
+- ausencia de tile e um conceito de tilemap/layer, nao necessariamente de bank asset;
+- usar indices fora da faixa como sentinel tende a piorar validacao e debug;
+- mudar o shape do tilemap pode ter custo de ABI/runtime, mas pode deixar o contrato mais honesto;
+- manter o comportamento atual preserva compatibilidade local, mas cristaliza uma semantica implicita fraca.
+
+## Opcoes
+
+### Opcao A - Manter `tile.id == 0` como empty sentinel
+
+O runtime segue tratando `tile_id = 0` como ausencia de tile no tilemap.
+
+Consequencia:
+
+- o primeiro tile real do bank precisaria comecar em `1` para o caminho de tilemap;
+- o packer precisaria compensar isso;
+- sprites e tilemaps continuariam com semanticas diferentes para o mesmo id.
+
+### Opcao B - Tornar vazio explicito no tilemap model
+
+O tilemap passa a representar vazio explicitamente, por exemplo com:
+
+- `Option<Tile>`;
+- ou `Tile { active/present, ... }`.
+
+Consequencia:
+
+- `tile_id = 0` volta a ser um tile valido no bank;
+- ausencia de tile deixa de depender de valor especial do id;
+- o runtime fica semanticamente mais consistente.
+
+### Opcao C - Usar sentinel fora da faixa valida
+
+O tilemap passa a tratar um `tile_id >= tile_capacity` como "empty".
+
+Consequencia:
+
+- evita usar `0` como sentinel;
+- mas cria acoplamento ruim entre tilemap e capacidade do bank;
+- e torna a validacao mais fragil e menos didatica.
+
+## Sugestao / Recomendacao
+
+Adotar `Opcao B`.
+
+Ausencia de tile deve ser modelada explicitamente no tilemap/layer, e nao por um `tile_id` especial.
+
+Direcao recomendada:
+
+1. `tile_id` deve significar apenas "indice do tile no bank";
+2. `tile_id = 0` deve ser permitido como tile real;
+3. tilemaps devem ter vazio explicito no proprio modelo;
+4. o render do tilemap deve testar esse estado explicito, nao `tile.id == 0`.
+
+## Perguntas em Aberto
+
+1. Qual shape e melhor para o primeiro wave:
+   `Option<Tile>` ou `Tile` com flag `active/present`?
+2. Essa mudanca afeta apenas o tilemap path ou tambem deve harmonizar outros consumidores do modelo `Tile`?
+3. Precisamos de estrategia de compatibilidade/migracao para codigo e testes que hoje assumem `tile.id == 0` como vazio?
+
+## Criterio para Encerrar
+
+Esta agenda pode ser encerrada quando houver decisao clara sobre:
+
+- como vazio e representado no tilemap;
+- se `tile_id = 0` volta a ser indice valido universal do bank;
+- e quais pontos de spec/codigo do runtime precisam de propagacao.

docs/runtime/agendas/024-asset-entry-metadata-normalization-contract.md

@@ -0,0 +1,89 @@
+# 024-asset-entry-metadata-normalization-contract
+
+Status: Open
+Domain Owner: `docs/runtime`
+Cross-Domain Impact: `../studio/docs/packer`, `shipper`, `asset` loader
+
+## Purpose
+
+Normatizar como `AssetEntry.metadata` deve preservar a convergencia entre metadata autoral, metadata de codec e metadata de pipeline sem colapsar tudo num mapa plano ambiguo.
+
+## Problem
+
+O lado produtor (`packer`) ja convergiu para um contrato em que o runtime precisa ler campos obrigatorios diretamente de `AssetEntry.metadata`, mas tambem precisa manter segmentacao suficiente para nao perder significado entre:
+
+- `asset.json.output.metadata`
+- `asset.json.output.codec_configuration`
+- `asset.json.output.pipeline`
+
+Sem um contrato explicito no runtime:
+
+- o packer pode materializar estruturas diferentes entre formatos;
+- o loader/runtime pode passar a depender de flattening incidental;
+- tooling e debug surfaces perdem previsibilidade;
+- futuros formatos tendem a misturar metadata efetiva com detalhe interno de pipeline.
+
+## Context
+
+No ciclo atual de `tile bank`, o produtor ja fechou esta direcao:
+
+- `asset.json.output.metadata` -> `AssetEntry.metadata`
+- `asset.json.output.codec_configuration` -> `AssetEntry.metadata.codec`
+- `asset.json.output.pipeline` -> `AssetEntry.metadata.pipeline`
+
+Ao mesmo tempo, o runtime ainda consome alguns campos obrigatorios do tile bank diretamente no nivel raiz de `AssetEntry.metadata`, em especial:
+
+- `tile_size`
+- `width`
+- `height`
+- `palette_count`
+
+A agenda precisa fechar se esse shape vira contrato geral de runtime para metadata normalizada de assets, e como o consumidor deve tratar campos obrigatorios format-specific versus subtrees segmentadas.
+
+## Options
+
+### Option A - Flat effective metadata map only
+
+Tudo converge para um unico mapa plano em `AssetEntry.metadata`.
+
+### Option B - Root effective metadata plus stable segmented subtrees
+
+Campos runtime-obrigatorios ficam legiveis no nivel raiz, enquanto dados de codec e pipeline ficam em subtrees estaveis:
+
+- `metadata.<field>`
+- `metadata.codec.<field>`
+- `metadata.pipeline.<field>`
+
+### Option C - Fully segmented metadata only
+
+Nada fica no nivel raiz; todo consumo passa por subtrees por origem.
+
+## Tradeoffs
+
+- Option A simplifica leitura curta, mas perde origem semantica e aumenta risco de colisao.
+- Option B preserva leitura direta para campos obrigatorios do runtime e mantem segmentacao estavel para evolucao futura.
+- Option C e semanticamente limpa, mas quebra o consumo direto atual de formatos como `tile bank` e introduz custo de migracao desnecessario agora.
+
+## Recommendation
+
+Adotar `Option B`.
+
+Direcao recomendada:
+
+- campos format-specific obrigatorios para decode/runtime continuam legiveis no nivel raiz de `AssetEntry.metadata`;
+- `output.codec_configuration` materializa em `AssetEntry.metadata.codec`;
+- `output.pipeline` materializa em `AssetEntry.metadata.pipeline`;
+- o runtime nao deve exigir flattening total para consumir metadata segmentada;
+- specs format-specific devem declarar explicitamente quais campos sao obrigatorios no nivel raiz.
+
+## Open Questions
+
+1. O contrato deve tratar o subtree raiz como semanticamente equivalente a `output.metadata` ou como effective metadata map mais amplo?
+2. Quais readers/helpers do runtime devem ser criados para evitar parsing manual disperso de `metadata.codec` e `metadata.pipeline`?
+
+## Expected Follow-up
+
+1. Converter esta agenda em decision no `runtime`.
+2. Propagar a decisao para `15-asset-management.md`.
+3. Ajustar loaders format-specific para usar helpers consistentes de metadata quando necessario.
+4. Alinhar o `packer` e testes de conformance com o shape final.

docs/runtime/agendas/README.md

@@ -24,6 +24,7 @@ As agendas atuais são:
 - `020-perf-host-debug-overlay-isolation.md`
 - `021-perf-vm-allocation-and-copy-pressure.md`
 - `022-perf-cartridge-boot-and-program-ownership.md`
+- `024-asset-entry-metadata-normalization-contract.md`
 ## Sequenciamento Recomendado [PERF]
 
 Ordem sugerida para discussao das agendas de performance:
@@ -87,3 +88,4 @@ Regra de uso:
 - se a implementação exigir decisão estrutural, ela deve nascer daqui antes de virar PR de código;
 - se uma agenda já estiver resolvida, a PR derivada deve citar explicitamente qual decisão foi tomada;
 - se a agenda revelar ambiguidade demais, ela não deve ser convertida em PR até o alvo ficar preciso.
+