79 lines
2.7 KiB
Markdown
79 lines
2.7 KiB
Markdown
# Metadata Convergence and Runtime Sink (`AssetEntry.metadata`)
|
|
|
|
## Original Problem
|
|
|
|
Packer authoring contracts may carry metadata from different concerns:
|
|
|
|
- asset/runtime contract metadata;
|
|
- codec-related metadata;
|
|
- pipeline-derived metadata generated during materialization.
|
|
|
|
Without an explicit convergence rule, teams drift into ambiguous behavior:
|
|
|
|
- runtime readers are unsure where effective values must be read;
|
|
- metadata merge behavior becomes accidental and non-deterministic;
|
|
- payload slicing fields can be confused with internal indexing offsets.
|
|
|
|
## Consolidated Decision
|
|
|
|
The accepted direction is:
|
|
|
|
1. all runtime-consumable metadata converges to a single sink: `AssetEntry.metadata`;
|
|
2. source segmentation in `asset.json` is allowed for authoring ergonomics;
|
|
3. build/materialization must normalize sources deterministically;
|
|
4. collisions require explicit contract rules or must fail build;
|
|
5. `AssetEntry.offset`/`AssetEntry.size` keep payload slicing semantics and do not replace internal pipeline indexing.
|
|
|
|
## Final Model
|
|
|
|
Think in two layers:
|
|
|
|
- **Authoring layer**: source metadata may be segmented by concern;
|
|
- **Runtime layer**: one effective metadata map in each emitted asset entry.
|
|
|
|
Practical rule for runtime consumers:
|
|
|
|
- if the value is runtime-consumable metadata, read it from `AssetEntry.metadata`.
|
|
|
|
Practical rule for packer implementation:
|
|
|
|
- normalize all relevant metadata sources into `AssetEntry.metadata` during build;
|
|
- keep normalization deterministic and testable.
|
|
|
|
## Example (Audio Bank Indexing)
|
|
|
|
Illustrative normalized metadata shape:
|
|
|
|
```json
|
|
{
|
|
"metadata": {
|
|
"sample_rate": 22050,
|
|
"channels": 1,
|
|
"samples": {
|
|
"1": { "offset": 0, "length": 100 }
|
|
},
|
|
"codec": {
|
|
"parity": 10
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
In this model:
|
|
|
|
- `samples[*].offset/length` are internal indexing values for the audio payload contract;
|
|
- they are not the same thing as `AssetEntry.offset/size` in the asset table.
|
|
|
|
## Common Pitfalls and Anti-Patterns
|
|
|
|
- Treating segmented declaration metadata as multiple runtime sinks.
|
|
- Allowing silent key overwrite when two metadata sources collide.
|
|
- Mixing payload slicing semantics (`asset_table[].offset/size`) with internal indexing semantics (`metadata.samples[*].offset/length`).
|
|
- Documenting convergence behavior only in code comments and not in normative specs.
|
|
|
|
## References
|
|
|
|
- Spec: [`../specs/3. Asset Declaration and Virtual Asset Contract Specification.md`](../specs/3.%20Asset%20Declaration%20and%20Virtual%20Asset%20Contract%20Specification.md)
|
|
- Spec: [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md)
|
|
- Related learn: [`./tile-bank-packing-contract.md`](./tile-bank-packing-contract.md)
|