81 lines
3.3 KiB
Markdown
81 lines
3.3 KiB
Markdown
# 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`
|
|
|