116 lines
3.6 KiB
Markdown
116 lines
3.6 KiB
Markdown
---
|
|
id: PLN-0167
|
|
ticket: runtime-owned-variable-glyph-bank-palette-protocol
|
|
title: Spec Contract Update for Variable Glyph Palettes
|
|
status: open
|
|
created: 2026-07-14
|
|
ref_decisions: [DEC-0041]
|
|
tags: [runtime, gfx, assets, glyph-bank, palette-serialization, protocol, specs]
|
|
---
|
|
|
|
## Briefing
|
|
|
|
`DEC-0041` accepts variable glyph-bank palette serialization for
|
|
`GLYPH/indexed_v1`. The runtime specs must become the canonical source before
|
|
code and tooling are changed.
|
|
|
|
## Decisions de Origem
|
|
|
|
- `DEC-0041` - Variable Glyph Bank Palette Protocol
|
|
|
|
## Alvo
|
|
|
|
Publish the runtime contract for variable glyph-bank palettes in the canonical
|
|
runtime specs.
|
|
|
|
## Escopo
|
|
|
|
- Update `docs/specs/runtime/15-asset-management.md`.
|
|
- Update `docs/specs/runtime/04-gfx-peripheral.md`.
|
|
- Remove or reword active spec text that requires exactly 64 serialized or
|
|
resident palettes per glyph bank.
|
|
- Define `palette_count` as serialized and resident palette count.
|
|
- Define `palette_count` as `1..=64`.
|
|
- Define `palette_id` validity as `palette_id < palette_count` for the loaded
|
|
glyph bank.
|
|
- Preserve RGBA8888, alpha-as-data, and ordinary index `0` semantics.
|
|
|
|
## Fora de Escopo
|
|
|
|
- Runtime code changes.
|
|
- Packer or studio code changes.
|
|
- New `GLYPH/indexed_v2` format text.
|
|
- Sparse-to-dense palette remapping.
|
|
|
|
## Plano de Execucao
|
|
|
|
### Step 1 - Update asset metadata contract
|
|
|
|
**What:** Change the `GLYPH` v1 metadata contract.
|
|
|
|
**How:** In `docs/specs/runtime/15-asset-management.md`, replace the exact
|
|
`palette_count = 64` requirement with `palette_count` in `1..=64`. State that
|
|
the field is both serialized palette count and resident palette count.
|
|
|
|
**Files:** `docs/specs/runtime/15-asset-management.md`
|
|
|
|
### Step 2 - Update payload and decoded-size formulas
|
|
|
|
**What:** Make payload size formulas variable.
|
|
|
|
**How:** Define `palette_bytes = palette_count * 16 * 4`, then define
|
|
`size = ceil(width * height / 2) + palette_bytes` and
|
|
`decoded_size = width * height + palette_bytes`.
|
|
|
|
**Files:** `docs/specs/runtime/15-asset-management.md`
|
|
|
|
### Step 3 - Update GFX palette reference semantics
|
|
|
|
**What:** Document bank-dependent `palette_id` validity.
|
|
|
|
**How:** In `docs/specs/runtime/04-gfx-peripheral.md`, make scene and sprite
|
|
composition text state that `palette_id` is valid only when it is lower than
|
|
the referenced glyph bank's `palette_count`.
|
|
|
|
**Files:** `docs/specs/runtime/04-gfx-peripheral.md`
|
|
|
|
### Step 4 - Document explicit failure
|
|
|
|
**What:** Remove fallback ambiguity for missing palettes.
|
|
|
|
**How:** State that canonical composition must not substitute transparent,
|
|
black, or default colors for `palette_id >= palette_count`.
|
|
|
|
**Files:** `docs/specs/runtime/04-gfx-peripheral.md`,
|
|
`docs/specs/runtime/15-asset-management.md`
|
|
|
|
### Step 5 - Run spec residue scan
|
|
|
|
**What:** Verify no active spec contradicts `DEC-0041`.
|
|
|
|
**How:** Search specs for fixed palette phrases and validate remaining hits are
|
|
historical or explicitly bounded maximums.
|
|
|
|
**Files:** `docs/specs/runtime/*.md`
|
|
|
|
## Criterios de Aceite
|
|
|
|
- [ ] `15-asset-management.md` defines `palette_count` as `1..=64`.
|
|
- [ ] `15-asset-management.md` uses variable size formulas.
|
|
- [ ] `04-gfx-peripheral.md` defines bank-dependent `palette_id` validity.
|
|
- [ ] Specs do not describe fixed 64 serialized palettes as the active
|
|
contract.
|
|
- [ ] No v2 format is introduced.
|
|
|
|
## Tests / Validacao
|
|
|
|
- Run `rg -n "palette_count|64 \\* 16|4096|palette_id" docs/specs/runtime`.
|
|
- Run `discussion validate`.
|
|
|
|
## Riscos
|
|
|
|
- The specs already contain mixed fixed and variable wording; partial edits may
|
|
preserve contradiction.
|
|
- `palette_id` failure semantics may overlap with existing scene dependency
|
|
fatal-failure text and must be worded consistently.
|