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:

all runtime-consumable metadata converges to a single sink: AssetEntry.metadata;
source segmentation in asset.json is allowed for authoring ergonomics;
build/materialization must normalize sources deterministically;
collisions require explicit contract rules or must fail build;
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

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:

{
  "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.

3.0 KiB Raw Blame History

Metadata Convergence and Runtime Sink (AssetEntry.metadata)