prometeu-runtime/discussion/workflow/plans/PLN-0172-runtime-spec-handoff-to-packer-and-studio.md

id	ticket	title	status	completed	created	ref_decisions	tags
PLN-0172	runtime-owned-variable-glyph-bank-palette-protocol	Runtime Spec Handoff to Packer and Studio	done	2026-07-14	2026-07-14	DEC-0041	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