From 340442d374a11a4faa669a70f444bcc4eb40bdd1 Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Tue, 14 Jul 2026 16:25:52 +0100 Subject: [PATCH] implements PLN-0087 --- discussion/index.ndjson | 2 +- ...variable-glyph-palette-spec-propagation.md | 14 +++++++------- ...nd Virtual Asset Contract Specification.md | 5 +++++ ...and Deterministic Packing Specification.md | 19 +++++++++++++------ .../4. Assets Workspace Specification.md | 5 +++++ 5 files changed, 31 insertions(+), 14 deletions(-) diff --git a/discussion/index.ndjson b/discussion/index.ndjson index 91256ee0..6571931f 100644 --- a/discussion/index.ndjson +++ b/discussion/index.ndjson @@ -18,7 +18,7 @@ {"type":"discussion","id":"DSC-0002","status":"done","ticket":"palette-management-in-studio","title":"Palette Management in Studio","created_at":"2026-03-26","updated_at":"2026-04-23","tags":["studio","legacy-import","palette-management","tile-bank","packer-boundary"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0042","file":"discussion/lessons/DSC-0002-palette-management-in-studio/LSN-0042-schema-driven-palette-authoring-and-local-metadata-events.md","status":"done","created_at":"2026-04-23","updated_at":"2026-04-23"}]} {"type":"discussion","id":"DSC-0003","status":"done","ticket":"packer-docs-import","title":"Import docs/packer into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0009","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0009-mental-model-packer-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0010","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0010-asset-identity-and-runtime-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0011","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0011-foundations-workspace-runtime-and-build-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0012","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0012-runtime-ownership-and-studio-boundary-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0013","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0013-metadata-convergence-and-runtime-sink-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0014","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0014-pack-wizard-summary-validation-and-pack-execution-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0015","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0015-tile-bank-packing-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0017","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0017-packer-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]} {"type":"discussion","id":"DSC-0004","status":"abandoned","ticket":"tilemap-and-metatile-runtime-binary-layout","title":"Tilemap and Metatile Runtime Binary Layout","created_at":"2026-03-26","updated_at":"2026-04-24","tags":["packer","legacy-import","tilemap","metatile","runtime-layout"],"agendas":[{"id":"AGD-0004","file":"AGD-0004-tilemap-and-metatile-runtime-binary-layout.md","status":"abandoned","created_at":"2026-03-26","updated_at":"2026-04-24","_override_reason":"Explicit user request on 2026-04-24 to abandon AGD-0004 because the agenda is no longer valid."}],"decisions":[],"plans":[],"lessons":[]} -{"type":"discussion","id":"DSC-0005","status":"open","ticket":"variable-tile-bank-palette-serialization","title":"Variable Glyph Bank Palette Serialization","created_at":"2026-03-26","updated_at":"2026-07-14","tags":["packer","legacy-import","glyph-bank","palette-serialization","rgba8888","runtime-alignment"],"agendas":[{"id":"AGD-0005","file":"AGD-0005-variable-tile-bank-palette-serialization.md","status":"accepted","created_at":"2026-03-26","updated_at":"2026-07-14"}],"decisions":[{"id":"DEC-0038","file":"DEC-0038-variable-glyph-bank-palette-serialization.md","status":"accepted","created_at":"2026-07-14","updated_at":"2026-07-14","ref_agenda":"AGD-0005"}],"plans":[{"id":"PLN-0087","file":"PLN-0087-variable-glyph-palette-spec-propagation.md","status":"open","created_at":"2026-07-14","updated_at":"2026-07-14","ref_decisions":["DEC-0038"]},{"id":"PLN-0088","file":"PLN-0088-variable-glyph-palette-metadata-and-count-model.md","status":"open","created_at":"2026-07-14","updated_at":"2026-07-14","ref_decisions":["DEC-0038"]},{"id":"PLN-0089","file":"PLN-0089-variable-glyph-palette-payload-emission-and-size-accounting.md","status":"open","created_at":"2026-07-14","updated_at":"2026-07-14","ref_decisions":["DEC-0038"]},{"id":"PLN-0090","file":"PLN-0090-studio-and-packer-projections-for-variable-glyph-palettes.md","status":"open","created_at":"2026-07-14","updated_at":"2026-07-14","ref_decisions":["DEC-0038"]},{"id":"PLN-0091","file":"PLN-0091-variable-glyph-palette-tests-fixtures-and-final-validation.md","status":"open","created_at":"2026-07-14","updated_at":"2026-07-14","ref_decisions":["DEC-0038"]}],"lessons":[]} +{"type":"discussion","id":"DSC-0005","status":"open","ticket":"variable-tile-bank-palette-serialization","title":"Variable Glyph Bank Palette Serialization","created_at":"2026-03-26","updated_at":"2026-07-14","tags":["packer","legacy-import","glyph-bank","palette-serialization","rgba8888","runtime-alignment"],"agendas":[{"id":"AGD-0005","file":"AGD-0005-variable-tile-bank-palette-serialization.md","status":"accepted","created_at":"2026-03-26","updated_at":"2026-07-14"}],"decisions":[{"id":"DEC-0038","file":"DEC-0038-variable-glyph-bank-palette-serialization.md","status":"accepted","created_at":"2026-07-14","updated_at":"2026-07-14","ref_agenda":"AGD-0005"}],"plans":[{"id":"PLN-0087","file":"PLN-0087-variable-glyph-palette-spec-propagation.md","status":"done","created_at":"2026-07-14","updated_at":"2026-07-14","ref_decisions":["DEC-0038"]},{"id":"PLN-0088","file":"PLN-0088-variable-glyph-palette-metadata-and-count-model.md","status":"open","created_at":"2026-07-14","updated_at":"2026-07-14","ref_decisions":["DEC-0038"]},{"id":"PLN-0089","file":"PLN-0089-variable-glyph-palette-payload-emission-and-size-accounting.md","status":"open","created_at":"2026-07-14","updated_at":"2026-07-14","ref_decisions":["DEC-0038"]},{"id":"PLN-0090","file":"PLN-0090-studio-and-packer-projections-for-variable-glyph-palettes.md","status":"open","created_at":"2026-07-14","updated_at":"2026-07-14","ref_decisions":["DEC-0038"]},{"id":"PLN-0091","file":"PLN-0091-variable-glyph-palette-tests-fixtures-and-final-validation.md","status":"open","created_at":"2026-07-14","updated_at":"2026-07-14","ref_decisions":["DEC-0038"]}],"lessons":[]} {"type":"discussion","id":"DSC-0006","status":"done","ticket":"pbs-game-facing-asset-refs-and-call-result-discard","title":"PBS Game-Facing Asset References and Ignored Call Result Lowering","created_at":"2026-03-27","updated_at":"2026-03-30","tags":["compiler","pbs","ergonomics","lowering","runtime","asset-identity","expression-statements"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0024","file":"discussion/lessons/DSC-0006-pbs-game-facing-asset-refs-and-call-result-discard/LSN-0024-addressable-surface-host-metadata-and-ignored-value-discipline.md","status":"done","created_at":"2026-03-30","updated_at":"2026-03-30"}]} {"type":"discussion","id":"DSC-0007","status":"done","ticket":"pbs-learn-to-discussion-lessons-migration","title":"Migrate PBS Learn Documents into Discussion Lessons","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","migration","discussion-framework","lessons","learn-prune"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0018","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0018-pbs-ast-and-parser-contract-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0019","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0019-pbs-name-resolution-and-linking-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0020","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0020-pbs-runtime-values-identity-memory-boundaries-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0021","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0021-pbs-diagnostics-and-conformance-governance-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0022","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0022-pbs-globals-lifecycle-and-published-entrypoint-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]} {"type":"discussion","id":"DSC-0008","status":"done","ticket":"pbs-low-level-asset-manager-surface","title":"PBS Low-Level Asset Manager Surface for Runtime AssetManager","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","runtime","asset-manager","host-abi","stdlib","asset"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0023","file":"discussion/lessons/DSC-0008-pbs-low-level-asset-manager-surface/LSN-0023-lowassets-runtime-aligned-sdk-surface.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]} diff --git a/discussion/workflow/plans/PLN-0087-variable-glyph-palette-spec-propagation.md b/discussion/workflow/plans/PLN-0087-variable-glyph-palette-spec-propagation.md index 392bd58b..6c59a310 100644 --- a/discussion/workflow/plans/PLN-0087-variable-glyph-palette-spec-propagation.md +++ b/discussion/workflow/plans/PLN-0087-variable-glyph-palette-spec-propagation.md @@ -2,9 +2,9 @@ id: PLN-0087 ticket: variable-tile-bank-palette-serialization title: Variable Glyph Palette Spec Propagation -status: open +status: done created: 2026-07-14 -completed: +completed: 2026-07-14 ref_decisions: - DEC-0038 tags: @@ -114,11 +114,11 @@ or pack wizard language and update only stale fixed-count wording. ## Acceptance Criteria -- [ ] Packer specs define `palette_count` as runtime-effective `1..=64`. -- [ ] Packer specs use variable palette byte and size formulas. -- [ ] Specs keep `GLYPH/indexed_v1` and reject v2 for this change. -- [ ] Specs reject fixed-padding compatibility and sparse-to-dense remapping. -- [ ] Studio specs contain no stale fixed 64-palette projection wording. +- [x] Packer specs define `palette_count` as runtime-effective `1..=64`. +- [x] Packer specs use variable palette byte and size formulas. +- [x] Specs keep `GLYPH/indexed_v1` and reject v2 for this change. +- [x] Specs reject fixed-padding compatibility and sparse-to-dense remapping. +- [x] Studio specs contain no stale fixed 64-palette projection wording. ## Dependencies diff --git a/docs/specs/packer/3. Asset Declaration and Virtual Asset Contract Specification.md b/docs/specs/packer/3. Asset Declaration and Virtual Asset Contract Specification.md index 25d0fbb8..ca4a2a09 100644 --- a/docs/specs/packer/3. Asset Declaration and Virtual Asset Contract Specification.md +++ b/docs/specs/packer/3. Asset Declaration and Virtual Asset Contract Specification.md @@ -121,6 +121,11 @@ Rules: - glyph-bank palette payloads must expose canonical `rgba8888` color values in runtime RGBA channel order; - ARGB values produced by host image APIs are import-side implementation details, not canonical declaration or projection fields; - `convertedRgb565` is not part of the normal palette contract; +- glyph-bank `palette_count` is an effective runtime metadata field and means + the number of serialized and resident RGBA8888 palettes for the bank; +- glyph-bank `palette_count` must be in the inclusive range `1..=64`; +- `palette_authored`, when present, is informative tooling metadata only and + must not be treated as runtime-effective metadata; - the packer must sort such entries by numeric `index`, not by physical array position; - duplicate or malformed indices are structural errors; - missing or malformed `palette` payloads are structural errors; diff --git a/docs/specs/packer/4. Build Artifacts and Deterministic Packing Specification.md b/docs/specs/packer/4. Build Artifacts and Deterministic Packing Specification.md index a91b9f1a..b4f9cd80 100644 --- a/docs/specs/packer/4. Build Artifacts and Deterministic Packing Specification.md +++ b/docs/specs/packer/4. Build Artifacts and Deterministic Packing Specification.md @@ -147,7 +147,8 @@ Offset ambiguity guardrail: ## Format-Specific Baseline: `GLYPH/indexed_v1` -The first-wave producer contract for `GLYPH/indexed_v1` is fixed and runtime-aligned. +The producer contract for `GLYPH/indexed_v1` is runtime-aligned and uses a +variable RGBA8888 palette block. ### Tile Selection and Identity @@ -178,7 +179,7 @@ Rules: - the serialized payload for `GLYPH/indexed_v1` is: 1. one packed `u4` pixel plane for the full emitted sheet; - 2. one palette block of `64 * 16 * 4 = 4096` bytes; + 2. one palette block of `palette_count * 16 * 4` bytes; - packed pixel bytes must be emitted by the packer, not inferred later by the runtime; - the palette block is serialized as RGBA8888 values in runtime RGBA channel order; - each palette entry is emitted as four bytes in `R`, `G`, `B`, `A` order; @@ -196,10 +197,15 @@ Rules: - `width` - `height` - `palette_count` -- tile-bank v1 requires `palette_count = 64`; +- tile-bank v1 requires `palette_count` in the inclusive range `1..=64`; +- `palette_count` is the number of serialized palettes and resident runtime + palettes for the bank; - tile-bank v1 size formulas are: - - `size = ceil(width * height / 2) + 4096` - - `decoded_size = (width * height) + 4096` + - `size = ceil(width * height / 2) + palette_count * 16 * 4` + - `decoded_size = (width * height) + palette_count * 16 * 4` +- fixed 64-palette padding is not a compatibility mode unless + `palette_count = 64` and the payload directly satisfies the v1 contract; +- `GLYPH/indexed_v2` must not be introduced for this palette-count correction. ### Palette Contract @@ -209,7 +215,8 @@ Rules: - each palette declaration uses the shape `{ "index": , "palette": { ... } }`; - each palette payload uses canonical `rgba8888` entries interpreted as `0xRRGGBBAA`; - palette ordering is ascending numeric `index`, never raw array position; -- palette ids in the emitted glyph bank are the normalized declared palette indices; +- palette ids in the emitted glyph bank are direct declared palette indices; +- v1 has no sparse-to-dense palette remapping metadata; - palette index `0` is ordinary and may carry any RGBA8888 value; - glyph palettes have 16 usable entries; - transparency and partial transparency are encoded only by RGBA alpha; diff --git a/docs/specs/studio/4. Assets Workspace Specification.md b/docs/specs/studio/4. Assets Workspace Specification.md index a721f34b..29ac5444 100644 --- a/docs/specs/studio/4. Assets Workspace Specification.md +++ b/docs/specs/studio/4. Assets Workspace Specification.md @@ -226,6 +226,11 @@ Rules: - `preload` - Glyph-bank palette projections must use canonical `rgba8888` values when palette data is shown. +- Glyph-bank runtime output projections must present `palette_count`, when + shown, as the runtime-effective serialized and resident palette count in + `1..=64`. +- Studio-facing glyph palette views must not present `palette_authored` as the + runtime-effective count. - Studio-facing glyph palette views must not expose `convertedRgb565` as normal runtime or tooling truth. - Runtime-facing output information must not require raw JSON inspection.