prometeu-studio/docs/packer/agendas/Tile Bank Packing Materialization Agenda.md

Tile Bank Packing Materialization Agenda

Status: Open Domain Owner: docs/packer Cross-Domain Impact: ../runtime, docs/studio

Purpose

Convergir a discussão sobre como um asset tile bank deve ser materializado durante o packing para produzir payload runtime-facing válido dentro de assets.pa.

Esta agenda não trata do workflow operacional do Pack Wizard. Ela trata do contrato técnico de materialização do formato TILES/indexed_v1:

• quais arquivos entram no pack;
• como eles viram payload binário final;
• quais campos do asset_table são derivados;
• quais metadados convergem para AssetEntry.metadata;
• e quais invariantes devem falhar o build.

Problem

O repositório já tem base suficiente para:

1. descobrir arquivos relevantes de tile bank;
2. validar metadados mínimos como tile_size;
3. construir snapshots runtime-backed;
4. definir assets.pa como artefato autoritativo do runtime.

Mas ainda não existe decisão formal sobre a materialização final de tile bank no pack.

Hoje falta fechar, pelo menos:

• qual é o payload binário efetivamente emitido para um tile bank;
• como múltiplos artifacts selecionados são agregados no payload final;
• como bank_type, codec, size, decoded_size e metadata são derivados para a entrada runtime;
• quais dados ficam em AssetEntry.metadata versus quais permanecem detalhe interno de pipeline;
• quais condições tornam o pack inválido para esse formato.

Sem isso, o packWorkspace(...) pode até ganhar semântica operacional correta, mas ainda ficará sem contrato suficiente para produzir assets.pa conformat para tile bank.

Context

O contrato upstream já impõe limites claros:

• assets.pa é o artefato runtime-facing autoritativo: ../specs/1. Domain and Artifact Boundary Specification.md
• asset_table é determinística por asset_id, offsets são relativos ao payload region e metadata converge para um sink único: ../specs/4. Build Artifacts and Deterministic Packing Specification.md
• o runtime espera assets.pa autocontido com asset_table e preload válidos: ../../../runtime/docs/runtime/specs/13-cartridge.md
• o runtime consome AssetEntry { asset_id, asset_name, bank_type, offset, size, decoded_size, codec, metadata }: ../../../runtime/docs/runtime/specs/15-asset-management.md

Contexto atual de código:

• PackerAssetWalker já reconhece OutputFormatCatalog.TILES_INDEXED_V1;
• PackerTileBankWalker já produz probes/metadata family-relevant;
• o snapshot atual já consegue expor arquivos candidatos e metadata de walk;
• ainda não existe materialização final de payload de tile bank dentro de assets.pa.

Isso significa que o problema agora não é descoberta de arquivos. É fechamento do contrato tile bank -> runtime asset entry + payload bytes.

Options

Option A - Concatenate selected tile artifacts as a simple raw stream

Cada artifact selecionado do tile bank vira um segmento binário simples, e o payload final do asset é a concatenação determinística desses segmentos.

metadata carrega apenas o mínimo necessário para o runtime interpretar o asset.

Option B - Emit one canonical tile-bank payload plus normalized runtime metadata

Os artifacts selecionados são primeiro normalizados para um modelo canônico de tile bank, e então o packer emite:

• um único payload binário canônico para o asset;
• um conjunto fechado de campos runtime-facing em AssetEntry.metadata.

Qualquer detalhe interno adicional de pipeline fica fora do contrato runtime principal ou vai apenas para tooling metadata.

Option C - Preserve rich per-artifact structure directly in runtime metadata

O packer mantém estrutura mais rica de artifacts individuais no próprio AssetEntry.metadata, expondo para o runtime detalhes mais próximos da pipeline de build.

Tradeoffs

• Option A é a implementação mais simples, mas corre risco de deixar semântica demais implícita no consumidor.
• Option A também pode dificultar compatibilidade futura se a concatenação simples não codificar claramente limites, forma lógica ou derivação de decoded_size.
• Option B exige fechar um modelo canônico do tile bank, mas produz o contrato mais limpo entre packer e runtime.
• Option B também respeita melhor a regra já vigente de convergência para AssetEntry.metadata sem transformar metadata runtime em espelho da pipeline.
• Option C pode parecer flexível no curto prazo, mas mistura detalhe de pipeline com contrato runtime e aumenta acoplamento.
• Option C tensiona diretamente o guardrail já documentado de que asset_table[].metadata não deve virar depósito arbitrário de estrutura interna.

Recommendation

Adotar Option B.

O primeiro formato de packing a ser fechado deve ter payload canônico e metadata runtime-facing normalizada.

Payload Recommendation

O tile bank deve produzir um payload binário único por asset incluído no build.

Regras recomendadas:

• o payload é derivado apenas dos artifacts selecionados que realmente entram no build atual;
• a ordem de agregação dos artifacts deve ser determinística;
• o payload final do asset deve ter fronteiras e interpretação definidas pelo próprio contrato do formato, não por convenção incidental de concatenação;
• size deve representar o tamanho emitido no payload region;
• decoded_size deve representar o tamanho lógico relevante para o runtime quando o codec exigir distinção entre payload armazenado e materialização decodificada.

Runtime Entry Recommendation

Cada tile bank emitido para o runtime deve preencher, no mínimo:

• asset_id
• asset_name
• bank_type = TILES
• offset
• size
• decoded_size
• codec
• metadata

O contrato de bank_type, codec e decoded_size não deve ser deixado implícito no packer implementation detail.

Metadata Recommendation

AssetEntry.metadata deve receber apenas os campos runtime-consumable e format-relevant.

Direção inicial recomendada:

• metadados declarativos como tile_size entram no sink runtime;
• metadados derivados necessários para leitura correta do runtime também entram no sink runtime;
• detalhes de pipeline úteis apenas para inspeção e tooling não devem dominar AssetEntry.metadata;
• quando um detalhe interno for necessário apenas para tooling, ele deve preferir companion tooling data em vez de inflar o contrato runtime.

Failure Recommendation

O build de tile bank deve falhar quando qualquer uma das seguintes condições acontecer:

1. não existir conjunto suficiente de artifacts selecionados para materialização válida;
2. o metadata declarativo obrigatório do formato estiver ausente ou inválido;
3. a normalização dos artifacts para o payload canônico falhar;
4. houver colisão ou ambiguidade ao convergir metadata runtime-facing;
5. o packer não conseguir derivar de forma determinística os campos exigidos para a entry runtime.

Packing Boundary Recommendation

O seletor de packing para tile bank deve operar sobre os probes já descobertos pelo walker family-oriented.

Regras:

• o walker continua generalista e orientado à family;
• a seleção do que entra no payload final acontece na policy/materialization layer de packing;
• somente probes do asset registrado, incluído no build, e efetivamente selecionados pelo contrato do formato entram na materialização final;
• quando o PackerRuntimeMaterializationConfig estiver em PACKING, esses probes relevantes devem carregar bytes opcionais preenchidos para congelar o input do pack.

Open Questions

1. Qual é o payload canônico inicial de TILES/indexed_v1: tiles brutos indexados, tiles mais tabela auxiliar, ou outro envelope mínimo?
2. Quais campos derivados além de tile_size precisam entrar em AssetEntry.metadata já na primeira versão?
3. decoded_size para tile bank deve refletir bytes lógicos pós-codec, bytes efetivos em bank, ou ambos via combinação decoded_size + metadata?
4. O formato inicial do payload precisa carregar múltiplos sub-blocos internos explícitos ou um stream único já é suficiente para v1?

Expected Follow-up

1. Converter esta agenda em uma decision de docs/packer para materialização de tile bank.
2. Propagar o contrato resultante para:
   • docs/packer/specs/4. Build Artifacts and Deterministic Packing Specification.md
   • specs runtime relevantes em ../runtime
3. Planejar PR de implementação do materializador de tile bank em prometeu-packer-v1.
4. Adicionar testes de conformance do formato: artifacts -> payload -> asset_table entry -> runtime-read assumptions.