Runtime-Owned Variable Glyph Bank Palette Protocol

This commit is contained in:
2026-07-14 15:40:49 +01:00
parent 01221769cd
commit dc279fe72b
10 changed files with 1120 additions and 1 deletions
@@ -0,0 +1,115 @@
---
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.
@@ -0,0 +1,118 @@
---
id: PLN-0168
ticket: runtime-owned-variable-glyph-bank-palette-protocol
title: GlyphBank Variable Palette Resident Model
status: open
created: 2026-07-14
ref_decisions: [DEC-0041]
tags: [runtime, gfx, assets, glyph-bank, hal]
---
## Briefing
`DEC-0041` requires resident `GlyphBank` memory to materialize exactly
`palette_count` palettes. The current HAL model exposes a fixed
`[[Color; 16]; 64]` table and must be changed before decode and composition can
enforce bank-dependent palette validity cleanly.
## Decisions de Origem
- `DEC-0041` - Variable Glyph Bank Palette Protocol
## Alvo
Replace the fixed resident palette table with a variable resident palette model
that preserves direct `palette_id` identity.
## Escopo
- Update `crates/console/prometeu-hal/src/glyph_bank.rs`.
- Keep `GLYPH_BANK_COLORS_PER_PALETTE = 16`.
- Replace the fixed palette table with a variable representation.
- Expose palette count and palette validation helpers.
- Ensure `resolve_color` no longer hides invalid palette references in
canonical paths.
- Update local HAL tests and call sites that construct `GlyphBank` directly.
## Fora de Escopo
- Asset payload decode changes.
- Composer status/fault policy.
- Packer/studio changes.
- Sparse palette remapping.
## Plano de Execucao
### Step 1 - Introduce variable palette storage
**What:** Replace fixed palette storage.
**How:** Change `GlyphBank::palettes` from
`[[Color; GLYPH_BANK_COLORS_PER_PALETTE]; GLYPH_BANK_PALETTE_COUNT_V1]` to a
variable collection such as `Vec<[Color; GLYPH_BANK_COLORS_PER_PALETTE]>`.
Keep a separate maximum constant for v1 if useful.
**Files:** `crates/console/prometeu-hal/src/glyph_bank.rs`
### Step 2 - Update constructors
**What:** Make constructors explicit about palette count.
**How:** Add or update constructors so tests and loaders can create a bank with
a chosen palette count. Default constructors used only for empty test banks
must choose a valid count and not imply fixed 64 capacity.
**Files:** `crates/console/prometeu-hal/src/glyph_bank.rs`
### Step 3 - Add validation helpers
**What:** Provide canonical palette validity APIs.
**How:** Add methods such as `palette_count()`, `contains_palette(palette_id)`,
and a fallible color lookup that distinguishes invalid palette references from
transparent colors.
**Files:** `crates/console/prometeu-hal/src/glyph_bank.rs`
### Step 4 - Update direct palette mutations in tests
**What:** Fix tests that write directly into fixed array slots.
**How:** Replace direct `bank.palettes[id][color] = value` call sites with
helpers or ensure the test bank was created with enough palettes first.
**Files:** `crates/console/prometeu-drivers/src/frame_composer.rs`,
`crates/console/prometeu-drivers/src/gfx.rs`,
`crates/console/prometeu-system/src/services/vm_runtime/tests.rs`
### Step 5 - Keep direct identity
**What:** Preserve `palette_id` identity.
**How:** Do not introduce maps, compaction tables, or translated palette ids.
Index `N` in the vector is palette identity `N`.
**Files:** `crates/console/prometeu-hal/src/glyph_bank.rs`
## Criterios de Aceite
- [ ] Resident `GlyphBank` stores exactly the loaded palette count.
- [ ] `GlyphBank` exposes bank-dependent palette validity.
- [ ] Invalid palette lookup can be detected separately from a transparent
color.
- [ ] No sparse-to-dense remapping structure is added.
- [ ] Direct test constructors no longer rely on implicit 64 palette capacity.
## Tests / Validacao
- Run HAL and driver unit tests that cover glyph bank construction and color
lookup.
- Add focused tests for `palette_count = 1` and `palette_count = 64`.
- Add a test proving invalid palette lookup is not silently equivalent to
transparent color.
## Riscos
- Many tests directly mutate `palettes[id]`; the migration can be noisy.
- Existing renderer paths may rely on `resolve_color` returning transparent for
invalid ids, which conflicts with `DEC-0041`.
@@ -0,0 +1,112 @@
---
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.
@@ -0,0 +1,125 @@
---
id: PLN-0170
ticket: runtime-owned-variable-glyph-bank-palette-protocol
title: Composer Palette Reference Failure Semantics
status: open
created: 2026-07-14
ref_decisions: [DEC-0041]
tags: [runtime, gfx, composer, scene, sprite, validation]
---
## Briefing
`DEC-0041` requires invalid palette references to fail explicitly when
scene/sprite/composer logic uses `palette_id >= palette_count` against a loaded
glyph bank. Current color resolution can silently return transparent for
missing palettes, which is no longer canonical behavior.
## Decisions de Origem
- `DEC-0041` - Variable Glyph Bank Palette Protocol
## Alvo
Define and implement explicit runtime failure behavior for invalid palette
references in canonical composition paths.
## Escopo
- Inspect scene binding, scene composition, sprite emission, and render
resolution paths.
- Choose existing status/fault behavior where it fits the current ABI.
- Prevent canonical composition from substituting transparent/default color for
invalid palette references.
- Update tests for scene and sprite invalid palette references.
## Fora de Escopo
- Adding new public ABI status values unless existing statuses cannot represent
the error.
- Packer or scene authoring validation.
- Sparse palette remapping.
## Plano de Execucao
### Step 1 - Map current composition paths
**What:** Identify where palette ids are consumed.
**How:** Trace `composer.emit_sprite`, scene binding/composition, frame
composer packet creation, and software GFX resolution from `Glyph` to
`GlyphBank::resolve_color`.
**Files:** `crates/console/prometeu-system/src/services/vm_runtime/dispatch.rs`,
`crates/console/prometeu-drivers/src/frame_composer.rs`,
`crates/console/prometeu-drivers/src/gfx.rs`,
`crates/console/prometeu-hal/src/glyph_bank.rs`
### Step 2 - Select explicit failure behavior
**What:** Choose the runtime-visible failure route.
**How:** Use existing semantics where possible: status-returning sprite calls
should use an existing invalid status if it accurately describes the failure;
scene dependency failures that occur during binding/composition should follow
the existing fatal dependency-failure model documented in the GFX spec.
**Files:** `docs/specs/runtime/04-gfx-peripheral.md`,
`crates/console/prometeu-system/src/services/vm_runtime/dispatch.rs`,
`crates/console/prometeu-drivers/src/frame_composer.rs`
### Step 3 - Validate sprite references
**What:** Prevent invalid sprite palette references.
**How:** When `emit_sprite` has access to the target glyph bank, reject
`palette_id >= palette_count` before the sprite is accepted for canonical
composition.
**Files:** `crates/console/prometeu-system/src/services/vm_runtime/dispatch.rs`,
`crates/console/prometeu-drivers/src/frame_composer.rs`,
`crates/console/prometeu-drivers/src/hardware.rs`
### Step 4 - Validate scene references
**What:** Prevent invalid scene palette references.
**How:** During scene bind or scene composition, validate tile palette ids
against each referenced loaded glyph bank. Fail explicitly if a scene layer
references a palette not present in its glyph dependency.
**Files:** `crates/console/prometeu-drivers/src/gfx.rs`,
`crates/console/prometeu-hal/src/scene_viewport_cache.rs`,
`crates/console/prometeu-hal/src/scene_viewport_resolver.rs`
### Step 5 - Remove silent fallback from canonical paths
**What:** Stop hiding invalid palette ids as transparent.
**How:** Use fallible palette lookup in canonical render paths. Transparent is
valid only when produced by an actual RGBA palette entry with alpha `0`.
**Files:** `crates/console/prometeu-drivers/src/gfx.rs`,
`crates/console/prometeu-hal/src/glyph_bank.rs`
## Criterios de Aceite
- [ ] Invalid sprite `palette_id` is rejected before canonical composition.
- [ ] Invalid scene tile `palette_id` fails explicitly against the loaded bank.
- [ ] Canonical render paths do not use invalid palette lookup as transparent.
- [ ] Valid transparent RGBA palette entries still render as transparent.
- [ ] The selected status/fault behavior is documented in the spec.
## Tests / Validacao
- Add sprite test for `palette_id == palette_count`.
- Add scene test for a tile palette id above the referenced bank's count.
- Add regression test proving alpha `0` in a valid palette still works.
- Run VM runtime and GFX driver tests.
## Riscos
- Some paths may not have easy access to the loaded glyph bank when accepting a
sprite packet.
- Existing ABI statuses may be less precise than a new status, but adding a new
status has wider compatibility cost.
@@ -0,0 +1,114 @@
---
id: PLN-0171
ticket: runtime-owned-variable-glyph-bank-palette-protocol
title: Variable Glyph Palette Tests Fixtures and Residue Scan
status: open
created: 2026-07-14
ref_decisions: [DEC-0041]
tags: [runtime, tests, fixtures, glyph-bank, palette-serialization]
---
## Briefing
`DEC-0041` changes a cross-cutting asset contract. Tests and fixtures must be
updated as a dedicated pass so fixed 64-palette assumptions do not survive in
helpers, generated data, or residue.
## Decisions de Origem
- `DEC-0041` - Variable Glyph Bank Palette Protocol
## Alvo
Convert runtime tests and fixtures to exercise variable glyph palette counts
and prove fixed-padding assumptions are gone from active behavior.
## Escopo
- Update test helpers that build glyph payloads.
- Add minimum, maximum, and intermediate palette-count tests.
- Add invalid palette-count tests.
- Add invalid palette-reference tests once `PLN-0170` is implemented.
- Run residue scans for fixed palette payload assumptions.
## Fora de Escopo
- Production decode implementation.
- Production composer implementation.
- Packer/studio fixture generation.
## Plano de Execucao
### Step 1 - Inventory glyph payload helpers
**What:** Find all runtime test helpers with fixed glyph palette sizes.
**How:** Search for `GLYPH_BANK_PALETTE_COUNT_V1`,
`GLYPH_BANK_PALETTE_BYTES_V1`, `64 * 16 * 4`, `4096`, and helper names such as
`test_glyph_asset_data`.
**Files:** `crates/console/prometeu-drivers/src/asset.rs`,
`crates/console/prometeu-system/src/services/vm_runtime/tests.rs`,
`crates/console/prometeu-system/src/services/vm_runtime/tests_asset_bank.rs`
### Step 2 - Create variable payload builders
**What:** Make tests express palette count deliberately.
**How:** Replace fixed helpers with helpers that accept `palette_count`, build
exactly `palette_count * 16 * 4` palette bytes, and compute matching `size` and
`decoded_size`.
**Files:** Runtime test modules that construct glyph assets.
### Step 3 - Add decode boundary coverage
**What:** Prove valid and invalid counts.
**How:** Add tests for `palette_count = 1`, an intermediate value, `64`, `0`,
and `65`.
**Files:** `crates/console/prometeu-drivers/src/asset.rs`
### Step 4 - Add composition coverage
**What:** Prove invalid palette references fail.
**How:** After `PLN-0170`, add scene and sprite tests where
`palette_id == palette_count` and confirm explicit failure behavior.
**Files:** `crates/console/prometeu-drivers/src/gfx.rs`,
`crates/console/prometeu-drivers/src/frame_composer.rs`,
`crates/console/prometeu-system/src/services/vm_runtime/tests.rs`
### Step 5 - Run residue scan
**What:** Catch leftover active fixed-palette assumptions.
**How:** Scan code, tests, and specs for fixed palette byte formulas. Keep only
maximum-bound constants and historical documentation.
**Files:** `crates/`, `docs/specs/runtime/`, `discussion/`
## Criterios de Aceite
- [ ] Tests no longer need a fixed 4096-byte palette payload for every glyph
bank.
- [ ] Decode tests cover `1`, intermediate counts, `64`, `0`, and `65`.
- [ ] Composition tests cover invalid palette references.
- [ ] Residue scan finds no active fixed serialized palette block assumption.
- [ ] Historical or maximum-bound uses of `64` are clearly named.
## Tests / Validacao
- Run targeted crate tests for asset decode, GFX, frame composer, and VM asset
bank flows.
- Run `rg -n "4096|64 \\* 16|GLYPH_BANK_PALETTE_BYTES_V1|palette_count"`
against `crates`, `docs/specs/runtime`, and active discussion artifacts.
- Run `discussion validate`.
## Riscos
- Residue scans can produce legitimate hits for the v1 maximum of `64`; those
must be classified instead of mechanically removed.
- Test helper churn can obscure the behavioral assertions if not kept focused.
@@ -0,0 +1,112 @@
---
id: PLN-0172
ticket: runtime-owned-variable-glyph-bank-palette-protocol
title: Runtime Spec Handoff to Packer and Studio
status: open
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.