161 lines
5.3 KiB
Markdown
161 lines
5.3 KiB
Markdown
---
|
|
id: PLN-0172
|
|
ticket: runtime-owned-variable-glyph-bank-palette-protocol
|
|
title: Runtime Spec Handoff to Packer and Studio
|
|
status: done
|
|
completed: 2026-07-14
|
|
created: 2026-07-14
|
|
ref_decisions: [DEC-0041]
|
|
tags: [runtime, packer, studio, handoff, glyph-bank, palette-serialization]
|
|
---
|
|
|
|
## Briefing
|
|
|
|
`DEC-0041` makes runtime the authority for `GLYPH/indexed_v1`. After the
|
|
runtime spec and implementation are updated, packer and studio must align as
|
|
downstream producers of runtime-conforming assets.
|
|
|
|
## Decisions de Origem
|
|
|
|
- `DEC-0041` - Variable Glyph Bank Palette Protocol
|
|
|
|
## Alvo
|
|
|
|
Prepare a clear runtime-owned handoff for packer/studio without moving protocol
|
|
authority out of the runtime repository.
|
|
|
|
## Escopo
|
|
|
|
- Summarize the accepted runtime contract for downstream repositories.
|
|
- Identify exact spec sections packer/studio must follow.
|
|
- Identify fixture and payload requirements.
|
|
- Capture any compatibility note needed for old fixed-padding payloads.
|
|
- Update runtime discussion artifacts with handoff status when implementation
|
|
is complete.
|
|
|
|
## Fora de Escopo
|
|
|
|
- Editing `../studio` or packer code from this plan.
|
|
- Reopening `AGD-0005` in `../studio`.
|
|
- Defining a v2 payload.
|
|
- Adding producer-specific runtime exceptions.
|
|
|
|
## Plano de Execucao
|
|
|
|
### Step 1 - Wait for runtime spec publication
|
|
|
|
**What:** Use runtime specs as handoff source.
|
|
|
|
**How:** Do not send or encode downstream requirements until `PLN-0167` has
|
|
landed. The published runtime spec is the contract.
|
|
|
|
**Files:** `docs/specs/runtime/15-asset-management.md`,
|
|
`docs/specs/runtime/04-gfx-peripheral.md`
|
|
|
|
### Step 2 - Write downstream contract summary
|
|
|
|
**What:** Produce a concise handoff note.
|
|
|
|
**How:** Summarize `palette_count`, payload layout, size formulas,
|
|
`palette_id` validity, absence of remapping, and incompatibility with the old
|
|
padding contract.
|
|
|
|
**Files:** Runtime discussion plan or follow-up note as appropriate.
|
|
|
|
### Step 3 - Identify downstream fixture updates
|
|
|
|
**What:** Define what packer/studio fixtures must prove.
|
|
|
|
**How:** Require fixtures with `palette_count = 1`, an intermediate count, and
|
|
`64`, plus rejection or regeneration of fixed-padding assumptions where the
|
|
metadata does not match the payload.
|
|
|
|
**Files:** Handoff note only; actual downstream files are outside this repo.
|
|
|
|
### Step 4 - Preserve runtime authority
|
|
|
|
**What:** Prevent downstream divergence.
|
|
|
|
**How:** State that packer/studio metadata such as authored palette count is
|
|
informative unless the runtime spec defines it as effective metadata.
|
|
|
|
**Files:** Handoff note; runtime spec references.
|
|
|
|
### Step 5 - Close loop after downstream acknowledgment
|
|
|
|
**What:** Track completion.
|
|
|
|
**How:** Once packer/studio work is done elsewhere, update discussion lessons or
|
|
housekeeping artifacts from the runtime side without adding new normative text
|
|
to lessons.
|
|
|
|
**Files:** `discussion/lessons/` only after implementation is complete.
|
|
|
|
## Criterios de Aceite
|
|
|
|
- [ ] Runtime specs are updated before downstream handoff.
|
|
- [ ] Handoff states that runtime owns the protocol.
|
|
- [ ] Handoff lists exact payload formulas and validity rules.
|
|
- [ ] Handoff states that no sparse-to-dense remapping exists in v1.
|
|
- [ ] Handoff states that old fixed-padding payloads are not compatibility
|
|
inputs unless they satisfy the new contract directly.
|
|
|
|
## Tests / Validacao
|
|
|
|
- Verify handoff references the final spec sections, not agenda text.
|
|
- Verify no downstream instruction contradicts `DEC-0041`.
|
|
- Run `discussion validate`.
|
|
|
|
## Riscos
|
|
|
|
- Downstream repositories may still treat `metadata.palette_authored` as
|
|
authoritative; this plan must make runtime-effective metadata explicit.
|
|
- Creating handoff text too early could freeze pre-implementation details.
|
|
|
|
## Handoff Note
|
|
|
|
Runtime is the protocol authority for `GLYPH/indexed_v1`. Downstream packer and
|
|
studio work must follow the published runtime specs, not the historical studio
|
|
agenda.
|
|
|
|
Canonical runtime references:
|
|
|
|
- `docs/specs/runtime/15-asset-management.md`, section `4.1 GLYPH asset
|
|
contract in v1`
|
|
- `docs/specs/runtime/04-gfx-peripheral.md`, section `19.4 Palette
|
|
Association`
|
|
- `docs/specs/runtime/04-gfx-peripheral.md`, section `20.1.b Scene dependency
|
|
fatal boundary`
|
|
- `docs/specs/runtime/04-gfx-peripheral.md`, section `20.2
|
|
composer.emit_sprite`
|
|
|
|
Downstream producers must emit:
|
|
|
|
- `codec = NONE`
|
|
- packed `u4` indexed pixels
|
|
- RGBA8888 palette bytes in `R, G, B, A` order
|
|
- root effective metadata fields `tile_size`, `width`, `height`, and
|
|
`palette_count`
|
|
- `palette_count` in `1..=64`
|
|
- exactly `palette_count * 16 * 4` palette bytes
|
|
- `size = ceil(width * height / 2) + palette_count * 16 * 4`
|
|
- `decoded_size = width * height + palette_count * 16 * 4`
|
|
|
|
Downstream producers must not emit:
|
|
|
|
- sparse-to-dense palette remapping metadata for v1
|
|
- a `GLYPH/indexed_v2` payload for this change
|
|
- fixed 64-palette padding unless `palette_count = 64` and the payload
|
|
directly satisfies the runtime v1 contract
|
|
- effective runtime behavior based on `palette_authored`; that field is
|
|
informative unless a later runtime spec promotes it to an effective root
|
|
metadata field
|
|
|
|
Required downstream fixture coverage:
|
|
|
|
- one glyph bank with `palette_count = 1`
|
|
- one glyph bank with an intermediate `palette_count`
|
|
- one glyph bank with `palette_count = 64`
|
|
- payload-size and decoded-size assertions for each fixture
|
|
- a negative fixture or validation case for metadata/payload mismatch
|