Runtime-Owned Variable Glyph Bank Palette Protocol
This commit is contained in:
+115
@@ -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`.
|
||||
+112
@@ -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.
|
||||
+114
@@ -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.
|
||||
Reference in New Issue
Block a user