# Tile Bank Packing Contract

## Original Problem

After the generic pack execution boundary was closed, `tile bank` still lacked one explicit producer contract.

The repository needed to settle:

1. how selected tile artifacts become one packed payload;
2. how palette identity is declared and normalized;
3. which runtime fields are derived for `AssetEntry`;
4. which structural problems block packing before byte emission.

## Consolidated Decision

The first-wave `tile bank` producer contract is:

1. one canonical `TILES/indexed_v1` payload per asset;
2. `1 artifact = 1 tile`;
3. artifacts are normalized by explicit `artifacts[*].index`;
4. the emitted sheet is fixed at `256 x 256` and row-major;
5. tile pixels are packed `u4`;
6. bank palettes are emitted as `RGB565` `u16`;
7. palette declarations use explicit `{ index, palette }`;
8. structural diagnostics are produced early in walker/materialization and therefore participate in validation.

## Final Model

### 1. Payload Shape

The payload is not a concatenation of artifact-local binaries.
It is one canonical bank raster:

1. packed `u4` pixel indices for the full sheet;
2. one `64 * 16 * 2` palette block.

### 2. Artifact and Tile Identity

- artifacts are normalized by ascending declared `index`;
- `tile_id` matches the normalized artifact index;
- placement is row-major in the fixed sheet;
- v1 capacities depend on `tile_size`:
  - `8 -> 1024`
  - `16 -> 256`
  - `32 -> 64`

### 3. Palette Contract

- palette identity is semantic, not positional;
- ordering is ascending numeric `index`, never raw list order;
- any tile may be rendered with any bank palette at runtime;
- palette selection is a draw-time concern, not an embedded per-tile payload field.

### 4. Metadata Contract

`AssetEntry.metadata` keeps runtime-required fields readable at the root while preserving segmented subtrees:

- `output.metadata -> metadata`
- `output.codec_configuration -> metadata.codec`
- `output.pipeline -> metadata.pipeline`

For tile banks, that means root readability for values such as:

- `tile_size`
- `width`
- `height`
- `palette_count`

### 5. Validation Boundary

Tile-bank structural issues belong in the walker/materialization path, not in a late pack-only surprise phase.

Blocking conditions include:

- duplicate artifact indices;
- gaps in normalized artifact indices;
- fixed-sheet overflow;
- missing palettes;
- palette count above `64`;
- malformed palette declarations;
- missing required metadata;
- normalization failure.

Fragile tile indices are warnings in the first wave, not blockers by themselves.

## Examples

### Example: Why palette index must be explicit

If palette identity depends on array position, a harmless editorial reorder can silently change runtime meaning.

Using `{ index, palette }` makes semantic identity reviewable and stable.

### Example: Why validation must see tile-bank structure early

If duplicate artifact indices are discovered only during final byte emission, the wizard reaches `Packing` too late.
The correct behavior is for validation to surface the blocker before emission begins, and for pack execution to rerun that same gate on a fresh execution snapshot.

## Common Pitfalls and Anti-Patterns

- Treating artifact declaration order as semantic tile identity.
- Packing per-artifact fragments instead of one canonical sheet.
- Embedding palette choice per tile in the packed payload.
- Flattening all metadata into one ambiguous map.
- Discovering tile-bank blockers only during late byte emission.

## References

- Specs:
  - [`../specs/3. Asset Declaration and Virtual Asset Contract Specification.md`](../specs/3.%20Asset%20Declaration%20and%20Virtual%20Asset%20Contract%20Specification.md)
  - [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md)
- Cross-domain:
  - [`../../../runtime/docs/runtime/specs/04-gfx-peripheral.md`](../../../runtime/docs/runtime/specs/04-gfx-peripheral.md)
  - [`../../../runtime/docs/runtime/specs/15-asset-management.md`](../../../runtime/docs/runtime/specs/15-asset-management.md)
- Related learn:
  - [`./mental-model-metadata-convergence-and-runtime-sink.md`](./mental-model-metadata-convergence-and-runtime-sink.md)