Intrepid/prometeu-studio
Intrepid/prometeu-studio
3
0
Fork 0
Code Pull Requests 1 Activity
prometeu-studio/discussion/workflow/agendas/AGD-0005-variable-tile-bank-palette-serialization.md
bQUARKz dd6c9dd718
All checks were successful
JaCoCo Coverage #### Project Overview No changes detected, that affect the code coverage. * Line Coverage: 60.67% (15274/25176) * Branch Coverage: 53.64% (5782/10779) * Lines of Code: 25176 * Cyclomatic Complexity: 9960 #### Quality Gates Summary Output truncated.
Details
Test / Build skipped: 11, passed: 545
Details
Intrepid/Prometeu/Studio/pipeline/head This commit looks good
Details
dev/glyph-bank-alignment (#3) 
Reviewed-on: #3
Co-authored-by: bQUARKz <bquarkz@gmail.com>
Co-committed-by: bQUARKz <bquarkz@gmail.com>
2026-04-10 06:14:07 +00:00

3.5 KiB
Raw Blame History

id ticket title status created resolved decision tags
AGD-0005 variable-tile-bank-palette-serialization Variable Tile Bank Palette Serialization open 2026-03-26
packer
legacy-import
tile-bank
palette-serialization
versioning

Pain

The current tile-bank contract serializes a fixed block of 64 palettes in v1 even when an asset authors far fewer palettes.

That keeps decoding simple, but it wastes cartridge space and leaves the system with a deliberate mismatch between authored and serialized palette counts.

Context

Legacy source: docs/packer/agendas/Variable Tile Bank Palette Serialization Agenda.md

Domain owner: docs/packer Cross-domain dependency:

  • runtime

Current aligned v1 contract:

  • pixels are serialized as packed u4;
  • palettes are serialized as RGB565 u16;
  • palette_count = 64;
  • payload size includes a fixed 64 * 16 * 2 palette block.

The packer now exposes:

  • metadata.palette_count = 64
  • metadata.palette_authored = <actual authored count>

Open Questions

  • Should variable palette serialization arrive as a new payload version or as an incompatible change to the current one?
  • If palette_count becomes variable, should runtime still materialize a 64-slot resident bank, or truly shrink in-memory representation too?
  • Should sparse authored palette indices remain sparse in serialization, or be canonicalized into a dense runtime block?
  • Which domain owns compatibility for existing cartridges: packer, runtime, or shipper?

Options

Option A - Keep fixed 64-palette serialization

  • Approach: Preserve the current fixed v1 payload with zero-filled unused palette slots.
  • Pro: No runtime change and current specs/tests remain stable.
  • Con: Every glyph bank keeps paying the full palette cost.
  • Maintainability: Medium.

Option B - Move to variable palette serialization now

  • Approach: Serialize only authored palettes and shrink payload size immediately.
  • Pro: Better cartridge efficiency and tighter semantics for palette_count.
  • Con: Reopens a just-stabilized cross-domain runtime contract and forces compatibility decisions now.
  • Maintainability: Medium if done carefully, risky if done incidentally.

Option C - Keep v1 fixed and design variable serialization for v2

  • Approach: Preserve v1 stability now and open a later versioned follow-up for variable palette serialization.
  • Pro: Keeps current work stable while preserving a clean path for future optimization.
  • Con: Known waste remains in v1.
  • Maintainability: Strong.

Discussion

The retained agenda recommendation is already clear: the waste is real, but it is not a correctness bug, and reopening the runtime-facing contract immediately would mix optimization work into a freshly stabilized path.

That makes versioned follow-up a cleaner vehicle than incidental mutation of the current contract.

Resolution

Recommended direction: adopt Option C.

Imported retained recommendation:

  1. keep the current fixed 64-palette contract for v1;
  2. if variable serialization is desired, design it explicitly as a versioned follow-up;
  3. treat compatibility, runtime representation, and sparse-vs-dense palette identity as explicit next-wave questions rather than silent payload tweaks.

Next step suggestion: if the team wants to remove the fixed padding, open the corresponding runtime-side discussion and close the versioning/compatibility story before planning implementation.