---
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`.