45 lines
1.9 KiB
Markdown
45 lines
1.9 KiB
Markdown
---
|
|
id: LSN-0013
|
|
ticket: packer-docs-import
|
|
title: Metadata convergence and runtime sink legacy lesson
|
|
created: 2026-03-26
|
|
tags:
|
|
- packer
|
|
- legacy-import
|
|
- metadata
|
|
- runtime-sink
|
|
---
|
|
|
|
## 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`.
|