113 lines
3.5 KiB
Markdown
113 lines
3.5 KiB
Markdown
---
|
|
id: PLN-0169
|
|
ticket: runtime-owned-variable-glyph-bank-palette-protocol
|
|
title: Asset Decode Validation for Variable Glyph Palettes
|
|
status: open
|
|
created: 2026-07-14
|
|
ref_decisions: [DEC-0041]
|
|
tags: [runtime, assets, glyph-bank, decode, validation]
|
|
---
|
|
|
|
## Briefing
|
|
|
|
`DEC-0041` changes glyph-bank decode from a fixed 4096-byte palette block to a
|
|
variable `palette_count * 16 * 4` block. The asset manager is the runtime gate
|
|
that must reject malformed glyph payloads before residency.
|
|
|
|
## Decisions de Origem
|
|
|
|
- `DEC-0041` - Variable Glyph Bank Palette Protocol
|
|
|
|
## Alvo
|
|
|
|
Update glyph asset layout validation and decode to accept `palette_count` in
|
|
`1..=64` and materialize exactly that many palettes.
|
|
|
|
## Escopo
|
|
|
|
- Update `crates/console/prometeu-drivers/src/asset.rs`.
|
|
- Replace exact `palette_count == 64` validation.
|
|
- Replace fixed `GLYPH_BANK_PALETTE_BYTES_V1` usage in decode.
|
|
- Validate `size` and `decoded_size` using variable formulas.
|
|
- Read exactly `palette_count * 16 * 4` bytes.
|
|
- Preserve RGBA byte order.
|
|
|
|
## Fora de Escopo
|
|
|
|
- HAL storage changes except as required by `PLN-0168`.
|
|
- Composer invalid-reference behavior.
|
|
- Packer output changes.
|
|
|
|
## Plano de Execucao
|
|
|
|
### Step 1 - Change layout return data
|
|
|
|
**What:** Carry palette count through layout validation.
|
|
|
|
**How:** Update `decode_glyph_bank_layout` to return `palette_count` and
|
|
palette byte count along with tile size, dimensions, and serialized pixel byte
|
|
count.
|
|
|
|
**Files:** `crates/console/prometeu-drivers/src/asset.rs`
|
|
|
|
### Step 2 - Replace exact palette-count validation
|
|
|
|
**What:** Accept only the DEC-0041 range.
|
|
|
|
**How:** Reject `palette_count = 0` and `palette_count > 64`; accept all values
|
|
in `1..=64`.
|
|
|
|
**Files:** `crates/console/prometeu-drivers/src/asset.rs`
|
|
|
|
### Step 3 - Use variable size formulas
|
|
|
|
**What:** Align entry validation with the spec.
|
|
|
|
**How:** Compute `palette_bytes = palette_count * 16 * size_of::<u32>()`,
|
|
`serialized_size = packed_pixels + palette_bytes`, and
|
|
`decoded_size = logical_pixels + palette_bytes`.
|
|
|
|
**Files:** `crates/console/prometeu-drivers/src/asset.rs`
|
|
|
|
### Step 4 - Decode variable palette data
|
|
|
|
**What:** Read only materialized palettes.
|
|
|
|
**How:** In buffer and reader decode paths, slice/read exactly `palette_bytes`.
|
|
Populate the new variable `GlyphBank` palette representation in order.
|
|
|
|
**Files:** `crates/console/prometeu-drivers/src/asset.rs`
|
|
|
|
### Step 5 - Remove fixed-byte assumptions
|
|
|
|
**What:** Retire the fixed payload block from active decode.
|
|
|
|
**How:** Replace helper functions and tests that assume
|
|
`GLYPH_BANK_PALETTE_BYTES_V1` is always in the payload. Keep a maximum constant
|
|
only if it is named as a maximum, not a payload size.
|
|
|
|
**Files:** `crates/console/prometeu-drivers/src/asset.rs`
|
|
|
|
## Criterios de Aceite
|
|
|
|
- [ ] Decode accepts valid `palette_count` values from `1` through `64`.
|
|
- [ ] Decode rejects `palette_count = 0`.
|
|
- [ ] Decode rejects `palette_count > 64`.
|
|
- [ ] `size` and `decoded_size` validation use variable palette bytes.
|
|
- [ ] Buffer and reader decode paths behave consistently.
|
|
- [ ] RGBA channel order remains unchanged.
|
|
|
|
## Tests / Validacao
|
|
|
|
- Add unit tests for `palette_count = 1`, an intermediate count, and `64`.
|
|
- Add rejection tests for `0`, `65`, short palette data, oversized metadata
|
|
size, and mismatched `decoded_size`.
|
|
- Run the crate tests that cover asset manager glyph decode.
|
|
|
|
## Riscos
|
|
|
|
- Existing tests may use generated glyph payload helpers with fixed 64-palette
|
|
size.
|
|
- Reader and buffer paths can drift if only one path receives the variable-size
|
|
change.
|