# 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)