---
id: LSN-0015
ticket: packer-docs-import
title: Tile bank packing contract legacy lesson
created: 2026-03-26
tags:
  - packer
  - legacy-import
  - tile-bank
  - packing-contract
---

## Context

Legacy import from `docs/packer/learn/tile-bank-packing-contract.md`.

This lesson preserves the first-wave producer contract for tile-bank assets.

## Key Decisions

### Tile bank packing emits one canonical payload per asset with explicit normalization and early structural validation

**What:** The first-wave contract emits one canonical `GLYPH/indexed_v1` payload per asset, normalizes artifacts by explicit `artifacts[*].index`, packs one fixed `256 x 256` row-major sheet with packed `u4` pixels and `RGB565` palette blocks, treats palette identity as semantic rather than positional, and surfaces structural blockers early in walker/materialization.
**Why:** The repository needed one explicit producer contract for glyph banks rather than a mix of implicit artifact ordering, late byte-emission surprises, and unstable palette identity.
**Trade-offs:** This contract is more explicit and restrictive than ad hoc per-artifact packing, but it yields stable reviewability, predictable runtime metadata, and earlier validation.

## Patterns and Algorithms

- Treat `1 artifact = 1 tile`.
- Normalize artifact identity by ascending declared `index`.
- Emit one canonical bank raster rather than concatenated artifact-local binaries.
- Keep palette identity explicit with `{ index, palette }`.
- Produce structural diagnostics before late pack-only phases.

## Pitfalls

- Treating artifact declaration order as semantic tile identity.
- Embedding per-tile palette choice in packed payload.
- Flattening all metadata into one ambiguous map.
- Discovering tile-bank blockers only during final byte emission.

## Takeaways

- The tile-bank producer contract depends on canonical normalization and early structural validation.
- Palette identity should be semantic and explicit, not positional by list order.
- Legacy source attribution: `docs/packer/learn/tile-bank-packing-contract.md`.