dev/glyph-bank-alignment (#3)
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.
Test / Build skipped: 11, passed: 545
Intrepid/Prometeu/Studio/pipeline/head This commit looks good
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.
Test / Build skipped: 11, passed: 545
Intrepid/Prometeu/Studio/pipeline/head This commit looks good
Reviewed-on: #3 Co-authored-by: bQUARKz <bquarkz@gmail.com> Co-committed-by: bQUARKz <bquarkz@gmail.com>
This commit was merged in pull request #3.
This commit is contained in:
+2
-2
@@ -20,8 +20,8 @@ This lesson preserves the first-wave producer contract for tile-bank assets.
|
||||
|
||||
### Tile bank packing emits one canonical payload per asset with explicit normalization and early structural validation
|
||||
|
||||
**What:** The first-wave contract emits one canonical `TILES/indexed_v1` payload per asset, normalizes artifacts by explicit `artifacts[*].index`, packs one fixed `256 x 256` row-major sheet with packed `u4` pixels and `RGB565` palette blocks, treats palette identity as semantic rather than positional, and surfaces structural blockers early in walker/materialization.
|
||||
**Why:** The repository needed one explicit producer contract for tile banks rather than a mix of implicit artifact ordering, late byte-emission surprises, and unstable palette identity.
|
||||
**What:** The first-wave contract emits one canonical `GLYPH/indexed_v1` payload per asset, normalizes artifacts by explicit `artifacts[*].index`, packs one fixed `256 x 256` row-major sheet with packed `u4` pixels and `RGB565` palette blocks, treats palette identity as semantic rather than positional, and surfaces structural blockers early in walker/materialization.
|
||||
**Why:** The repository needed one explicit producer contract for glyph banks rather than a mix of implicit artifact ordering, late byte-emission surprises, and unstable palette identity.
|
||||
**Trade-offs:** This contract is more explicit and restrictive than ad hoc per-artifact packing, but it yields stable reviewability, predictable runtime metadata, and earlier validation.
|
||||
|
||||
## Patterns and Algorithms
|
||||
|
||||
+71
@@ -0,0 +1,71 @@
|
||||
---
|
||||
id: LSN-0039
|
||||
ticket: packer-pipeline-metadata-ownership
|
||||
title: Runtime Header Boundary and Tooling-Owned Pipeline Metadata
|
||||
created: 2026-04-10
|
||||
tags: [packer, metadata, runtime-contract, tooling, codec, assets-pa]
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
The packer had drift between implementation and spec around `output.pipeline` ownership. The runtime-facing artifact `assets.pa` was documented as if pipeline metadata should materialize under `asset_table[].metadata.pipeline`, while the implementation already treated at least part of that surface as tooling-oriented and excluded palette payloads from the runtime header.
|
||||
|
||||
This created the wrong architectural pressure: Studio and third-party tools could start depending on `assets.pa` for authoring/build provenance, and runtime-facing specs could silently absorb build-time structures that do not belong in the execution contract.
|
||||
|
||||
The discussion resolved that split explicitly and implemented it end to end in specs, packer materialization, and tests.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### Tooling Metadata Must Not Leak Into the Runtime Header
|
||||
|
||||
**What:**
|
||||
`output.pipeline` remains tooling-only metadata in `asset.json` and related sidecar outputs. The runtime-facing `assets.pa` header must not mirror `output.pipeline` by default. Runtime-owned metadata remains under explicit, normalized fields in `asset_table[].metadata`.
|
||||
|
||||
**Why:**
|
||||
`assets.pa` is the authoritative runtime artifact. If it starts carrying build provenance, editor-oriented structures, or reverse-sync payloads merely because they exist in the authoring manifest, the runtime contract becomes larger, noisier, and harder to evolve safely.
|
||||
|
||||
**Trade-offs:**
|
||||
Tools that want provenance cannot rely on one binary artifact alone. They must read `asset.json` and/or `build/asset_table_metadata.json`. That is a deliberate trade-off in favor of a cleaner runtime boundary.
|
||||
|
||||
### Promotion Must Be Explicit, Not a Bulk Mirror
|
||||
|
||||
**What:**
|
||||
If pipeline-derived information is needed at runtime, it must be promoted into an explicit normative field under runtime-owned metadata. The packer must not reintroduce a generic mirrored `pipeline` object under another name.
|
||||
|
||||
**Why:**
|
||||
Bulk mirroring hides product decisions inside implementation convenience. Explicit promotion forces each field to justify its presence in the runtime contract.
|
||||
|
||||
**Trade-offs:**
|
||||
This adds small editorial and implementation work whenever a new runtime-facing derived field is introduced, but it keeps the contract intentional and testable.
|
||||
|
||||
### Codec Serialization Must Stay in `SCREAMING_SNAKE_CASE`
|
||||
|
||||
**What:**
|
||||
Serialized asset entry `codec` values are locked to `SCREAMING_SNAKE_CASE`. The currently known `NONE` value remains serialized as `NONE`.
|
||||
|
||||
**Why:**
|
||||
The implementation already had a stable manifest/runtime representation through `OutputCodecCatalog`. Recording that casing in spec prevents future drift when more codecs are added.
|
||||
|
||||
**Trade-offs:**
|
||||
Future codec additions must preserve the established serialized style unless a new decision explicitly revises the contract.
|
||||
|
||||
## Patterns and Algorithms
|
||||
|
||||
- Use separate surfaces for separate consumers: `assets.pa` for runtime contract, `asset_table_metadata.json` for tooling-oriented provenance, and `asset.json` for authoring intent.
|
||||
- Build runtime metadata from explicit normalized fields first, then derive tooling sidecars from a superset when needed.
|
||||
- Keep the runtime header free of raw authoring/build objects even if the sidecar keeps them intact for Studio or inspection tools.
|
||||
- Lock serialized enum casing in spec as soon as the first value ships, even if the current catalog is minimal.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- Do not treat “already present in the manifest” as sufficient reason to serialize a field into the runtime header.
|
||||
- Do not let sidecar convenience become implicit runtime compatibility.
|
||||
- Do not partially filter a tooling object and leave an empty placeholder in runtime metadata unless that placeholder has explicit runtime meaning.
|
||||
- Do not leave enum casing as an implementation accident. If the manifest value matters, the spec must say so.
|
||||
|
||||
## Takeaways
|
||||
|
||||
- The runtime header is a contract surface, not a metadata dump.
|
||||
- Tooling provenance belongs in `asset.json` and `build/asset_table_metadata.json`, not in `assets.pa`.
|
||||
- Runtime-facing derived metadata must be promoted explicitly field by field.
|
||||
- Stable serialized casing rules should be fixed in spec before the value set grows.
|
||||
+41
@@ -0,0 +1,41 @@
|
||||
# Glyph Bank Artifact Naming Alignment
|
||||
|
||||
The graphical bank artifact, which stores indexed graphical data (glyphs) for runtime consumption, has been aligned with the unified project vocabulary across `packer`, `studio`, and `runtime`.
|
||||
|
||||
### Original Problem
|
||||
|
||||
Previously, the project used inconsistent terminology for the same concrete artifact:
|
||||
- `tile_bank` in some packer configurations.
|
||||
- `TILES/indexed_v1` as an output format.
|
||||
- `TILES` as a runtime-facing `bank_type`.
|
||||
- `TileBank` or `tile bank` in Studio UI and internal code.
|
||||
|
||||
This created a conceptual overlap with the "tile" domain, which properly refers to geometric sizes, map layers, and grid-based rendering logic. Keeping the artifact named "tile bank" made it difficult to distinguish between the storage container (the bank) and the geometric entities (the tiles) stored within or referenced by it.
|
||||
|
||||
### Consolidated Decision
|
||||
|
||||
Following `DEC-0025` (this repository) and `DEC-0006` (runtime repository), the concrete graphical bank artifact is now exclusively referred to as **Glyph Bank**.
|
||||
|
||||
1. **Artifact Name**: `glyph_bank` (serialized asset-family).
|
||||
2. **Output Format**: `GLYPH/indexed_v1`.
|
||||
3. **Runtime ID**: `GLYPH` (bank_type).
|
||||
4. **Vocabulary Split**:
|
||||
- Use **Glyph** when referring to the graphical data bank, its capacity, or its storage format.
|
||||
- Use **Tile** only for geometric concepts (tile size, tile maps, tile layers, coordinate grids).
|
||||
|
||||
### Implementation Results
|
||||
|
||||
- **Packer**: All `AssetFamilyCatalog`, `OutputFormatCatalog`, and walker implementations now use the `Glyph*` vocabulary. Parser validation now expects `type: glyph_bank`.
|
||||
- **Studio**: UI labels, composition coordinators, and internal services have been renamed to `Glyph Bank` to match the packer and runtime contracts.
|
||||
- **Contract**: No compatibility layer was introduced. All fixtures and test assets were migrated in a single wave to ensure a clean, unified contract.
|
||||
|
||||
### Common Pitfalls and Anti-patterns
|
||||
|
||||
- **Incorrect Rename**: Do not rename `tileSize` to `glyphSize`. A tile is a geometric unit; a glyph is the graphical content within that unit or the bank that stores it.
|
||||
- **Legacy Fixtures**: Since there is no compatibility layer, old `asset.json` files with `type: tile_bank` will fail to parse. They must be updated to `type: glyph_bank`.
|
||||
|
||||
### References
|
||||
|
||||
- `DEC-0025`: Local decision for Glyph Bank alignment.
|
||||
- `PLN-0048`: Implementation plan for the naming migration.
|
||||
- `docs/specs/packer/`: Updated specifications for asset declarations.
|
||||
Reference in New Issue
Block a user