# PR-33 Tile Bank Spec Propagation and Runtime Contract Alignment

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

## Briefing

The `Tile Bank Packing Materialization Decision` is now closed.

Before more code lands, the normative spec path needs to be updated so implementation is not forced to infer format details from agendas and decisions.

This PR is editorial-first.
Its job is to propagate the accepted tile-bank producer contract into the relevant packer specs and to make the runtime alignment explicit.

## Objective

Update the normative spec corpus so `tile bank` v1 packing has one unambiguous producer contract.

## Dependencies

- [`../decisions/Tile Bank Packing Materialization Decision.md`](../decisions/Tile%20Bank%20Packing%20Materialization%20Decision.md)
- [`../decisions/Pack Wizard Pack Execution Semantics Decision.md`](../decisions/Pack%20Wizard%20Pack%20Execution%20Semantics%20Decision.md)
- [`../../../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)

## Scope

- propagate the accepted `tile bank` v1 contract into packer specs
- define canonical payload semantics for `TILES/indexed_v1`
- define metadata convergence shape for tile-bank runtime entries
- make runtime-aligned size and decoded-size formulas explicit
- document the fixed `256 x 256` target and row-major slot semantics

## Non-Goals

- no production code changes
- no walker refactor
- no payload emitter implementation
- no runtime implementation work

## Method

1. Update [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md).
2. Define `TILES/indexed_v1` producer semantics explicitly:
   - `1 artifact = 1 tile`
   - `tile_id = normalized artifacts[*].index`
   - fixed `256 x 256` emitted sheet
   - row-major placement
   - packed `u4` pixel plane
   - `64 * 16 * u16` RGB565 palette block
3. Document runtime entry derivation:
   - `bank_type = TILES`
   - `codec = NONE`
   - `size = ceil(width * height / 2) + 2048`
   - `decoded_size = (width * height) + 2048`
4. Document metadata normalization:
   - `output.metadata -> metadata`
   - `output.codec_configuration -> metadata.codec`
   - `output.pipeline -> metadata.pipeline`
5. Cross-reference the runtime-side metadata normalization discussion without pretending it is already closed there.

## Acceptance Criteria

- the packer spec corpus contains one explicit producer contract for tile-bank v1
- the payload shape no longer needs to be reconstructed from agenda text
- size, decoded-size, palette count, and metadata shape are all normative
- the spec states what the producer emits because that is what the consumer requires

## Validation

- editorial review against the accepted decision
- consistency check against runtime specs and loader assumptions
- terminology review for `tile_id`, `palette_id`, `size`, `decoded_size`, and metadata segmentation

## Affected Artifacts

- `docs/packer/specs/4. Build Artifacts and Deterministic Packing Specification.md`
- possibly `docs/packer/specs/1. Domain and Artifact Boundary Specification.md`
- possibly `docs/packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md`