prometeu-studio/docs/packer/pull-requests/PR-32-palette-declarations-with-explicit-index-contract.md

PR-32 Palette Declarations with Explicit Index Contract

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

Briefing

The current authoring shape for asset.json.output.pipeline.palettes is still too dependent on list order as semantic identity.

That is fragile:

• editorial reordering can silently change meaning;
• merges become harder to review safely;
• the packer has to infer identity from position instead of reading it explicitly.

The repository already depends on stable palette ordering for tile bank packing. That ordering should therefore be explicit in the authoring contract.

Decisions de Origem

• ../decisions/Pack Wizard Pack Execution Semantics Decision.md
• ongoing agenda: ../agendas/Tile Bank Packing Materialization Agenda.md

Objective

Replace list-position-defined palette identity with an explicit index-bearing declaration contract for asset.json.output.pipeline.palettes.

Recommended shape:

"palettes": [
  {
    "index": 0,
    "palette": { ... }
  },
  {
    "index": 1,
    "palette": { ... }
  }
]

Dependencies

• tile-bank materialization agenda in docs/packer/agendas
• runtime-side tile-bank consumer contract already aligned around stable palette ids

Scope

• define the normative authoring shape for output.pipeline.palettes
• make index the semantic identity of each declared palette
• require packer normalization to sort by index, not by list position
• define diagnostics for duplicate, missing, invalid, or malformed palette entries
• prepare propagation into:
  • packer specs
  • parser/runtime-facing normalization code
  • Studio editing surfaces if they expose palette management

Non-Goals

• no immediate migration of artifacts in this PR
• no tile-bank payload implementation in this PR
• no runtime code changes in this PR
• no speculative keyed-object JSON contract for palettes in this wave

Execution Method

1. Update the packer-side documentation/decision chain to make palette identity explicit.
2. Define output.pipeline.palettes as a list of records with:
   • index
   • palette
3. State that semantic ordering is ascending numeric index, never raw list position.
4. Define structural diagnostics:
   • duplicate index => blocking
   • negative or malformed index => blocking
   • missing palette payload => blocking
   • palette count above the runtime-facing v1 limit => blocking
5. Define whether index gaps are:
   • blocking
   • or warning/advisory
6. Prepare follow-up implementation PRs for parser, validation, and Studio surfaces.

Contract Direction

First-wave packer contract direction:

1. output.pipeline.palettes remains a JSON array for authoring ergonomics;
2. each entry must declare an explicit index;
3. each entry must declare a palette object payload;
4. packer meaning comes from numeric index, not from the physical array position;
5. the runtime-facing palette_id consumed later by tile/sprite draw paths is the normalized numeric palette index.

Acceptance Criteria

• the packer docs/spec path no longer relies on raw list order as palette identity
• the explicit-index palette shape is documented clearly enough for parser and Studio implementation
• duplicate or malformed palette indices are identified as structural diagnostics
• the contract leaves no ambiguity about whether sorting happens by array order or by index

Validation

• editorial validation across packer agenda/decision/spec material
• parser-oriented review proving the contract is implementable without hidden heuristics
• Studio-facing review confirming the editing UX can preserve stable palette identity

Affected Artifacts

• docs/packer/agendas/**
• docs/packer/decisions/**
• docs/packer/specs/3. Asset Declaration and Virtual Asset Contract Specification.md
• docs/packer/specs/4. Build Artifacts and Deterministic Packing Specification.md
• future parser/runtime materialization code under prometeu-packer-v1