feat(schemas): metric_aggregates partition — row-symmetric delivery aggregation (closes #3848)

[bokelley]

Summary

Closes #3848 (and supersedes the already-closed #3631 / #3833). Adds aggregated_totals.metric_aggregates to get_media_buy_delivery — a qualifier-aware delivery rollup row-symmetric with package.committed_metrics and by_package[].missing_metrics.

The atomic unit is now identical across contract, diff, and delivery:

committed_metrics row : (scope, metric_id, qualifier, committed_at)
missing_metrics row   : (scope, metric_id, qualifier)
metric_aggregates row : (scope, metric_id, qualifier, value, ...components)

Reconciliation collapses to a row-level join on (scope, metric_id, qualifier).

Why

The taxonomy doc's "atomic unit" claim becomes load-bearing in code. Today, contract and diff use the row shape; delivery aggregation uses bespoke per-metric scalars. With this PR, all three surfaces share one shape — buyer reconciliation code becomes one path instead of three.

Solves the apples-to-oranges sum problem at the aggregate layer: MRC and GroupM viewability never combine into a single rate. Future qualifier-aware metrics (completion threshold; attention methodology if it standardizes) plug in with no schema change.

Design decisions (per #3848)

• Component fields inlined as siblings of value, matching the per-buy viewability block's flat shape.
• Granularity rule: one row per (metric_id, full-qualifier-set) at the finest available granularity. Buyers re-aggregate up.
• Closed contract vocabulary, open delivery vocabulary: delivery qualifier is a deliberate superset reserving space for transparency disclosures buyers don't commit to (e.g., tracker_firing pending Tracker firing path (client / server / mixed) — is this a buyer concern AdCP needs to model, and where? #3832).
• Unqualified metrics stay top-level (impressions, spend, media_buy_count); metric_aggregates only for metrics with non-empty qualifier sets.
• Per-buy totals stays flat — each individual buy is single-qualifier by definition; only the aggregate spans qualifiers.
• oneOf discriminated on metric_id deferred — current schema does not enforce per-metric required components in JSON Schema (would be 31+ branches). Required fields documented in the description; future minor can tighten via oneOf if conformance testing demands.

Files

• static/schemas/source/media-buy/get-media-buy-delivery-response.json — adds metric_aggregates array
• static/schemas/source/core/package.json — committed_metrics description cross-links the new surface
• docs/media-buy/task-reference/get_media_buy_delivery.mdx — adds "Aggregated metric partitions" section
• .changeset/metric-aggregates.md — minor

Test plan

• Schema validates (build:schemas during commit hook)
• TypeScript build passes
• Doc renders cleanly

Related

• Add metric_aggregates partition to aggregated_totals — qualifier-aware delivery rollups symmetric to committed_metrics #3848 — origin issue (this PR closes it)
• feat(schemas): unify metric accountability — timestamped contract + symmetric audit #3576 — committed_metrics / missing_metrics (the contract-side row shape this mirrors)
• docs(measurement): add three-layer taxonomy doc #3843 — measurement taxonomy doc (atomic-unit framing)
• Add standard-keyed viewability rollup to aggregated_totals on get_media_buy_delivery #3631, Partition viewability rollup by tracker_firing mode — follow-up to #3631 #3833 — superseded
• Tracker firing path (client / server / mixed) — is this a buyer concern AdCP needs to model, and where? #3832 — tracker_firing question (delivery qualifier reserves space for it)

🤖 Generated with Claude Code