This commit is contained in:
2026-03-24 13:42:57 +00:00
parent d16a987949
commit 0e5e1669c2
98 changed files with 824 additions and 8449 deletions
@@ -1,295 +0,0 @@
# Pack Wizard Studio Decision Propagation Agenda
Status: Open
Domain Owner: `docs/packer`
Cross-Domain Impact: `docs/studio`
## Purpose
Converge the packer-side discussion that still remains open after the first `Pack Wizard` propagation wave: the actual `packing` operation.
`summary` and `validation` are already closed enough to implement and consume.
What is still unresolved is how `pack execution` should behave as a packer-owned operation when Studio enters the `Packing` and `Result` phases.
This agenda is therefore about execution semantics, artifact emission, progress visibility, and failure boundaries for `packWorkspace(...)`.
## Problem
The repository already closed the Studio shell boundary and the packer-side preflight boundary, but the actual pack execution contract is still underspecified.
Today the gap is concrete:
1. Studio already depends on a four-phase wizard:
`Summary`, `Validation`, `Packing`, `Result`;
2. the public packer API already exposes `packWorkspace(...)`;
3. `prometeu-packer-v1` still throws `UnsupportedOperationException` for that operation;
4. the specs define `assets.pa` authority and deterministic ordering, but they do not yet define the operational semantics for emitting that artifact through the Studio-facing service boundary.
Without this agenda, implementation risks falling into one of these traps:
- a direct file-write implementation that leaks partial artifacts;
- a Studio-visible progress model that is too vague to support the wizard honestly;
- an execution path that does not clearly separate validation failure from emission failure;
- or a result contract that is too poor for the `Result` phase even if the pack technically succeeds.
## Context
The upstream state is now clear enough to isolate the remaining question.
Already closed:
- Studio is a shell over packer-owned semantics:
[`../../studio/decisions/Pack Wizard in Assets Workspace Decision.md`](../../studio/decisions/Pack%20Wizard%20in%20Assets%20Workspace%20Decision.md)
- packer-side `summary` and `validation` contracts are accepted:
[`../decisions/Pack Wizard Summary and Validation Contracts Decision.md`](../decisions/Pack%20Wizard%20Summary%20and%20Validation%20Contracts%20Decision.md)
- runtime artifact authority is already normative:
[`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md)
- event causality and serialized operation rules are already normative:
[`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
Current code context:
- `getPackWorkspaceSummary(...)` already exists in `FileSystemPackerWorkspaceService`;
- `validatePackWorkspace(...)` already exists in `FileSystemPackerWorkspaceService`;
- `packWorkspace(...)` exists in the public API but is not implemented in `prometeu-packer-v1`;
- the current `PackWorkspaceResult` shape is minimal, but the operational meaning of its fields is not fully closed.
That means the current decision gap is no longer about whether packing should exist.
It is about what guarantees `packWorkspace(...)` must provide when it starts emitting runtime-facing artifacts.
## Options
### Option A - Direct in-place pack with minimal lifecycle semantics
Implement `packWorkspace(...)` as one serialized write-lane operation that:
- optionally reruns the validation gate;
- emits `assets.pa` and companion artifacts directly into their final locations;
- publishes a small number of lifecycle events;
- returns one final result DTO with success or failure.
### Option B - Staged pack transaction with explicit lifecycle phases
Implement `packWorkspace(...)` as one serialized packer-owned execution flow with explicit internal phases:
1. gate
2. plan/materialize
3. stage emit
4. commit/promote
5. finalize result
The operation still appears to Studio as one `packWorkspace(...)` call, but the packer gives stronger semantics:
- validation is rechecked at execution start;
- emitted files are staged before final promotion;
- final artifact visibility changes only at commit;
- progress events map to meaningful lifecycle boundaries;
- the final result distinguishes validation, emission, and persistence failure classes.
### Option C - Detached build session abstraction
Introduce a larger `PackSession`-style model or resumable build-session protocol for packing.
Studio would create a session, observe step state, and then explicitly finalize or close it.
## Tradeoffs
- Option A is the smallest implementation step, but it leaves too many failure and visibility rules implicit.
- Option A also makes it easier to leak partially written artifacts into final paths if the process fails mid-pack.
- Option B fits the existing service boundary while still making artifact visibility and progress semantics explicit.
- Option B also aligns well with the current specs:
serialized writes, causal events, deterministic outputs, and packer-owned truth.
- Option B adds some implementation structure, but that structure corresponds to real operational risk and is not ceremonial.
- Option C could become attractive later if the build system needs cancellation, resume, remote workers, or richer host orchestration.
- Option C is too heavy for the current repository state and would introduce a second interaction model before the first one is stable.
## Recommendation
Adopt `Option B`.
The packer should keep `packWorkspace(...)` as a single public service operation, but internally define and honor explicit execution phases with staged emission and an atomic final visibility boundary.
### Execution Boundary Recommendation
`packWorkspace(...)` should be the only first-wave operation that emits build artifacts.
Rules:
- it runs through the packer-owned serialized write lane for the project;
- it evaluates the active pack set as `registered + included in build`;
- it must perform an internal gate check before emitting artifacts, even if Studio already ran `validation`;
- it must freeze the execution input set before materialization begins;
- a failing gate returns a terminal result without creating final artifacts.
This avoids trusting host orchestration timing as if it were a correctness guarantee.
### Frozen Snapshot Recommendation
`packWorkspace(...)` should not pack from live filesystem rereads after execution begins.
Recommended first-wave baseline:
- the packer creates a frozen pack-execution snapshot before materialization starts;
- that frozen snapshot is derived from the current runtime snapshot but enriches build-relevant walk files with in-memory content bytes;
- content bytes are needed only for:
- registered assets included in build;
- artifact files that actually participate in the current build output;
- non-build assets and non-selected artifact files do not need in-memory content in the pack-execution snapshot;
- the current runtime snapshot model should expose file bytes as optional rather than introducing a second snapshot model in the first wave;
- `PackerRuntimeWalkFile` should therefore carry optional content bytes so the packer can freeze build-relevant inputs without forcing all runtime-backed reads to retain content unnecessarily;
- the family walkers may continue to produce full file probes with bytes loaded during probe processing;
- the variation for runtime versus packing should happen when probe results are exported into the runtime walk projection;
- walker materialization must therefore gain clearer execution context/config so build-focused flows can request content bytes intentionally instead of coupling that behavior to every normal read path.
This preserves precision without turning the general runtime snapshot into a blanket in-memory mirror of the workspace.
### Walker Policy Recommendation
The current walker baseline should remain family-oriented and generalist.
Recommended first-wave baseline:
- family walkers continue to discover files relevant to the asset family;
- that family-oriented discovery remains the normal runtime-backed mode;
- packing adds one extra selection layer instead of redefining walker discovery itself;
- the extra selection layer filters the discovered probe results down to the files that actually participate in the current build output;
- the same export layer also decides whether optional content bytes are injected into `PackerRuntimeWalkFile`.
This means the first-wave split should be:
1. family-relevant probe discovery in the walkers;
2. export/materialization policy for runtime projection;
3. packing-specific projection filter over discovered probe results;
4. optional byte injection only when the export policy requests it.
This is intentionally conservative.
It keeps the walkers on known ground and moves the packing-specific behavior into one explicit projection/materialization policy layer.
Recommended config shape:
```java
public record PackerRuntimeMaterializationConfig(
PackerWalkMode mode,
Predicate<PackerProbeResult> projectionFilter) {
public static PackerRuntimeMaterializationConfig runtimeDefault() {
return new PackerRuntimeMaterializationConfig(PackerWalkMode.RUNTIME, probe -> true);
}
public static PackerRuntimeMaterializationConfig packingBuild() {
return new PackerRuntimeMaterializationConfig(
PackerWalkMode.PACKING,
PackerProbePolicies::isIncludedInCurrentBuild);
}
}
```
With this baseline:
- `PackerWalkMode.RUNTIME` means runtime-backed general projection and suppresses optional content bytes during export;
- `PackerWalkMode.PACKING` means packing-focused projection and injects optional content bytes during export;
- `projectionFilter` decides which discovered probe results actually survive into `PackerRuntimeWalkFile`;
- the first-wave packing filter should keep only current-build probe results;
- byte injection behavior is derived from `mode` rather than from a second explicit boolean in the first wave.
### Emission Recommendation
Artifact emission should be staged before promotion into final visible locations.
Recommended first-wave baseline:
- materialize `assets.pa` and companion artifacts in a staging location owned by the packer operation;
- use `build/.staging/<operation-id>/` as the first-wave staging location;
- `<operation-id>` should be one random 20-character alphanumeric identifier;
- if a staging directory collision happens for that identifier, the packer may overwrite that staging directory rather than adding a second collision-resolution protocol in the first wave;
- treat staging output as non-authoritative until commit;
- promote staged files into final `build/` locations only after the operation reaches a coherent success point;
- if emission fails before commit, final artifact locations must remain unchanged from the caller's point of view.
This is the safest baseline for a filesystem-first packer.
It keeps durable visibility aligned with a packer-owned commit boundary rather than with incidental file-write timing.
### Progress Recommendation
Progress should continue to flow through the existing packer event path rather than through a polling-specific result shape.
The first-wave lifecycle should be observable through summaries and progress updates equivalent to:
1. `packing_started`
2. `packing_validating`
3. `packing_materializing`
4. `packing_emitting`
5. `packing_finalizing`
6. terminal success or failure
The exact event kind names can still be finalized in the decision, but the meaning must be explicit enough for Studio to render the `Packing` phase honestly without fake timers or inferred state.
### Result Recommendation
The final `PackWorkspaceResult` should stay compact but semantically explicit.
The primary result summary should expose at least:
- final status;
- whether validation failed or execution actually began;
- canonical build-relative `assets.pa` artifact reference;
- build-relative companion artifact references when emitted;
- total packed asset count;
- elapsed time in milliseconds.
The first-wave `Result` phase in Studio does not need a full build report dump, but it does need enough structure to distinguish successful pack, blocked pack, and failed pack after execution started.
### Failure Recommendation
The packer should distinguish at least three terminal classes:
1. validation gate failure before emission;
2. execution or materialization failure during pack generation;
3. persistence or promotion failure while making artifacts final.
These classes matter because they map directly to the Studio `Result` phase already decided upstream.
### Build Output Recommendation
The packer publication boundary for this flow should remain `build/`.
Recommended first-wave baseline:
- `packWorkspace(...)` publishes final outputs to `build/`;
- the canonical runtime-facing artifact is `build/assets.pa`;
- the baseline companion artifacts are:
- `build/asset_table.json`
- `build/preload.json`
- `build/asset_table_metadata.json`
- a future shipper may consume those packer outputs together with `program.pbx`;
- the shipper is mentioned here only to keep the boundary explicit, not because it participates in `packWorkspace(...)`.
This keeps the current domain boundary intact:
the packer publishes build artifacts and the shipper assembles cartridges.
## Open Questions
None for the first-wave execution shape.
The remaining work is to convert this agenda into a decision and then propagate the agreed materialization policy into code and specs.
## Recommendation Summary
This agenda recommends closing the first-wave `packing` contract as:
1. one packer-owned `packWorkspace(...)` operation;
2. internally phased and serialized through the project write lane;
3. guarded by a packer-owned validation check at execution start;
4. based on one frozen in-memory execution snapshot for the build-relevant asset bytes;
5. staged under `build/.staging/<operation-id>/` before promotion to final artifact visibility in `build/`;
6. observable through causality-preserving progress events;
7. finished with a result that distinguishes blocked, failed, and successful pack outcomes.
## Next Suggested Step
Convert this agenda into a `docs/packer` decision focused on `pack execution` semantics and propagation targets.
That decision should then drive:
1. one PR for `prometeu-packer-api` result and event-contract adjustments, if needed;
2. one PR for `prometeu-packer-v1` execution, staging, and artifact-promotion behavior;
3. one Studio PR to bind the `Packing` and `Result` phases to the final packer-owned execution contract.
+2 -4
View File
@@ -5,11 +5,9 @@ This directory contains active packer discussion agendas.
## Active Agendas
1. [`Tilemap and Metatile Runtime Binary Layout Agenda.md`](./Tilemap%20and%20Metatile%20Runtime%20Binary%20Layout%20Agenda.md)
2. [`Pack Wizard Studio Decision Propagation Agenda.md`](./Pack%20Wizard%20Studio%20Decision%20Propagation%20Agenda.md)
3. [`Tile Bank Packing Materialization Agenda.md`](./Tile%20Bank%20Packing%20Materialization%20Agenda.md)
4. [`Variable Tile Bank Palette Serialization Agenda.md`](./Variable%20Tile%20Bank%20Palette%20Serialization%20Agenda.md)
2. [`Variable Tile Bank Palette Serialization Agenda.md`](./Variable%20Tile%20Bank%20Palette%20Serialization%20Agenda.md)
The first packer agenda wave was consolidated into normative specs under [`../specs/`](../specs/) and didactic material under [`../learn/`](../learn/).
Closed packer agenda waves must be absorbed into [`../specs/`](../specs/) and [`../learn/`](../learn/) instead of remaining here as historical residue.
## Purpose
@@ -1,258 +0,0 @@
# 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`](../specs/1.%20Domain%20and%20Artifact%20Boundary%20Specification.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`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md)
- o runtime espera `assets.pa` autocontido com `asset_table` e `preload` válidos:
[`../../../runtime/docs/runtime/specs/13-cartridge.md`](../../../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`](../../../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`.
Consumer baseline now confirmed in `../runtime`:
- `TILES` now uses `codec = NONE` as the runtime-facing v1 baseline;
- serialized tile pixels are packed `u4` palette indices in payload order;
- the runtime expands those packed indices into one `u8` logical index per pixel in memory after decode;
- tile-bank palettes are serialized as `RGB565` `u16` values in little-endian order;
- runtime-facing v1 uses `64` palettes per tile bank;
- the runtime loader currently requires the following metadata fields for tile banks:
- `tile_size`
- `width`
- `height`
- `palette_count`
- for v1, `palette_count` must be `64`;
- for v1, the serialized tile-bank payload is:
1. packed indexed pixels for the full sheet, using `ceil(width * height / 2)` bytes;
2. one palette block of `64 * 16 * 2 = 2048` bytes;
- for v1, the runtime-side size expectations are:
- `size = ceil(width * height / 2) + 2048`
- `decoded_size = (width * height) + 2048`
- for the producer-side contract discussed here, `tile_id = 0` remains valid and must not be reserved away by the packer.
Relevant confirmed runtime references:
- [`../../../runtime/docs/runtime/specs/15-asset-management.md`](../../../runtime/docs/runtime/specs/15-asset-management.md)
- [`../../../runtime/docs/runtime/specs/04-gfx-peripheral.md`](../../../runtime/docs/runtime/specs/04-gfx-peripheral.md)
- [`../../../runtime/crates/console/prometeu-drivers/src/asset.rs`](../../../runtime/crates/console/prometeu-drivers/src/asset.rs)
- [`../../../runtime/crates/console/prometeu-hal/src/tile_bank.rs`](../../../runtime/crates/console/prometeu-hal/src/tile_bank.rs)
- tilemap empty-cell semantics remain under active runtime discussion and must not currently force the packer to reserve `tile_id = 0`:
[`../../../runtime/docs/runtime/agendas/023-tilemap-empty-cell-vs-tile-id-zero.md`](../../../runtime/docs/runtime/agendas/023-tilemap-empty-cell-vs-tile-id-zero.md)
Isso significa que o problema agora não é descoberta de arquivos.
O lado consumidor já está suficientemente claro.
O problema agora é fechar o contrato produtor `tile bank -> runtime asset entry + payload bytes` no packer sem contradizer esse baseline runtime.
## 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 by `artifacts[*].index`;
- for v1, `1 artifact = 1 tile`;
- for the current target, the canonical tile-bank sheet is always `256 x 256`;
- tile placement inside that fixed sheet is row-major;
- `tile_id` is the linear row-major slot and therefore matches the normalized `artifacts[*].index`;
- resulting capacity is therefore:
- `tile_size = 8` -> `32 x 32 = 1024` tiles
- `tile_size = 16` -> `16 x 16 = 256` tiles
- `tile_size = 32` -> `8 x 8 = 64` tiles
- 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;
- para `TILES/indexed_v1`, o payload v1 já deve assumir:
1. plano de pixels packed `u4`;
2. bloco de paletas `64 * 16 * u16`;
- palettes must always be materialized to `RGB565` during pack emission;
- `size` deve representar o tamanho emitido no payload region;
- `decoded_size` deve seguir a convenção runtime já confirmada:
tamanho expandido dos indices em memória mais o bloco de paletas runtime-facing.
### 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.
Baseline now fixed by the runtime consumer:
- `bank_type = TILES`
- `codec = NONE`
- metadata mínima obrigatória:
- `tile_size`
- `width`
- `height`
- `palette_count = 64`
- `width` and `height` are bank-sheet helpers, not per-artifact dimensions
- with the current v1 target, the emitted bank sheet is fixed at `256 x 256`
- producer-side metadata normalization must emit what the consumer requires while preserving segmented authoring meaning:
- `asset.json.output.metadata` -> `AssetEntry.metadata`
- `asset.json.output.codec_configuration` -> `AssetEntry.metadata.codec`
- `asset.json.output.pipeline` -> `AssetEntry.metadata.pipeline`
### 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 entram no sink runtime, pelo menos:
- `width`
- `height`
- `palette_count`;
- `AssetEntry.metadata` should aggregate normalized maps using this structure:
- `asset.json.output.metadata` -> `metadata`
- `asset.json.output.codec_configuration` -> `metadata.codec`
- `asset.json.output.pipeline` -> `metadata.pipeline`
- bank palettes are declared in `asset.json.output.pipeline.palettes` using explicit `{ index, palette }` entries and emitted in ascending numeric `index` order;
- any tile in the bank may be rendered with any palette in the bank;
- palette assignment is therefore not a per-artifact packing contract and remains a runtime draw-time concern;
- the packer must nevertheless validate whether the declared bank palette set safely covers the indices used by packed tiles.
- 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.
Additional first-wave diagnostic expectations:
- duplicate `artifacts[*].index` is `blocking`;
- gap in normalized `artifacts[*].index` ordering is `blocking`;
- sheet-capacity overflow for the fixed `256 x 256` target is `blocking`;
- bank without declared palettes in `asset.json.output.pipeline.palettes` is `blocking`;
- declared palette list above `64` is `blocking`;
- malformed palette declarations are `blocking`;
- tiles that use fragile indices, meaning indices not represented safely across the full declared bank palette set, emit a `WARNING`;
- that fragile-index warning is advisory in the first wave and does not block pack by itself unless later promoted by decision.
### 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.
- palette declarations in `asset.json.output.pipeline.palettes` carry explicit semantic identity through `index`;
- palette order is ascending numeric `index`, never raw array position;
- palette ids are the normalized declared `index` values from that pipeline palette list;
- all tiles in the bank may use any palette declared in the bank;
- palette selection is a runtime draw concern, not a tile-payload embedding concern.
## Open Questions
1. None at this stage for the tile-bank v1 producer contract.
## 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`.