fix App, clean up, add metadata convergence
This commit is contained in:
@@ -52,3 +52,4 @@ Start here:
|
||||
|
||||
1. [`mental-model-packer.md`](./mental-model-packer.md)
|
||||
2. [`mental-model-asset-identity-and-runtime-contract.md`](./mental-model-asset-identity-and-runtime-contract.md)
|
||||
3. [`mental-model-metadata-convergence-and-runtime-sink.md`](./mental-model-metadata-convergence-and-runtime-sink.md)
|
||||
|
||||
@@ -0,0 +1,82 @@
|
||||
# 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.
|
||||
|
||||
Decision reference:
|
||||
|
||||
- [`../decisions/Metadata Convergence to AssetEntry.metadata Decision.md`](../decisions/Metadata%20Convergence%20to%20AssetEntry.metadata%20Decision.md)
|
||||
|
||||
## 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
|
||||
|
||||
- Decision: [`../decisions/Metadata Convergence to AssetEntry.metadata Decision.md`](../decisions/Metadata%20Convergence%20to%20AssetEntry.metadata%20Decision.md)
|
||||
- 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)
|
||||
Reference in New Issue
Block a user