packer (WIP)
This commit is contained in:
@@ -0,0 +1,113 @@
|
||||
# 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`](../decisions/Pack%20Wizard%20Pack%20Execution%20Semantics%20Decision.md)
|
||||
- ongoing agenda:
|
||||
[`../agendas/Tile Bank Packing Materialization Agenda.md`](../agendas/Tile%20Bank%20Packing%20Materialization%20Agenda.md)
|
||||
|
||||
## Objective
|
||||
|
||||
Replace list-position-defined palette identity with an explicit index-bearing declaration contract for `asset.json.output.pipeline.palettes`.
|
||||
|
||||
Recommended shape:
|
||||
|
||||
```json
|
||||
"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`
|
||||
Reference in New Issue
Block a user