1.9 KiB
| id | ticket | title | created | tags | ||||
|---|---|---|---|---|---|---|---|---|
| LSN-0013 | packer-docs-import | Metadata convergence and runtime sink legacy lesson | 2026-03-26 |
|
Context
Legacy import from docs/packer/learn/mental-model-metadata-convergence-and-runtime-sink.md.
This lesson preserves the rule that runtime-consumable metadata converges into one effective sink.
Key Decisions
Runtime-consumable metadata converges to AssetEntry.metadata
What: Authoring contracts may segment metadata by concern, but all runtime-consumable metadata must normalize deterministically into AssetEntry.metadata. Payload slicing fields such as AssetEntry.offset and AssetEntry.size keep their own semantics and do not replace internal indexing values.
Why: Without an explicit convergence rule, runtime readers, normalization behavior, and metadata collision handling all become accidental and non-deterministic.
Trade-offs: Deterministic convergence requires explicit normalization rules and collision handling, but it gives runtime consumers one clear reading surface.
Patterns and Algorithms
- Segment metadata in source declarations when useful for authoring ergonomics.
- Normalize all runtime-consumable metadata into one root map in emitted asset entries.
- Fail or use explicit rules on collisions rather than silently overwriting.
- Keep payload slicing and internal indexing semantics distinct.
Pitfalls
- Treating segmented declaration metadata as multiple runtime sinks.
- Allowing silent key overwrite.
- Mixing asset-table slicing semantics with internal indexing offsets.
Takeaways
- Runtime consumers should read runtime metadata from
AssetEntry.metadata. - Convergence behavior must live in specs and tests, not only in code comments.
- Legacy source attribution:
docs/packer/learn/mental-model-metadata-convergence-and-runtime-sink.md.