prometeu-studio/docs/packer/pull-requests/PR-33-tile-bank-spec-propagation-and-runtime-contract-alignment.md

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/Pack Wizard Pack Execution Semantics Decision.md
• ../../../runtime/docs/runtime/specs/04-gfx-peripheral.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.
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