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.
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>
72 lines
4.3 KiB
Markdown
72 lines
4.3 KiB
Markdown
---
|
|
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.
|