feat(creative): declare tracker execution contracts

.changeset/add-tracker-execution-contracts.md

@@ -0,0 +1,9 @@
+---
+"adcontextprotocol": minor
+---
+
+Add format-scoped production tracker execution contracts for first-class pixel,
+VAST, and DAAST tracker assets. Pin effective commitments, execution versions,
+placement scope, and digests in immutable package format snapshots so buyers can
+distinguish supported, unsupported, and undeclared tracker behavior before
+spend without coupling the production promise to preview observation.

docs/contributing/x-entity-annotation.md

@@ -106,7 +106,7 @@ High-level groupings (see the registry for full descriptions). *Categories below
 | Brand & rights | `advertiser_brand`, `rights_holder_brand`, `rights_grant` |
 | Account & party | `account`, `operator` |
 | Media buy | `media_buy`, `package`, `product`, `proposal`, `product_pricing_option`, `spot_airing` |
-| Creative | `creative`, `creative_revision`, `creative_representation`, `macro_declaration`, `creative_locale_variant`, `creative_format`, `build_variant`, `served_variant` |
+| Creative | `creative`, `creative_revision`, `creative_representation`, `macro_declaration`, `tracker_execution_selector`, `creative_locale_variant`, `creative_format`, `build_variant`, `served_variant` |
 | Data & targeting | `audience`, `audience_evidence`, `audience_evidence_snapshot`, `signal`, `signal_activation_id`, `demographic_interval_id`, `event_source` |
 | Lists & catalogs | `collection_list`, `property_list`, `catalog`, `catalog_generation`, `catalog_item`, `property` |
 | Plans & governance | `media_plan`, `governance_plan`, `governance_registry_policy`, `governance_inline_policy`, `governance_check`, `governance_delivery_statement`, `governance_delivery_observation`, `governance_outcome`, `governance_adjustment`, `governance_adjustment_evidence`, `seller_adjustment`, `content_standards`, `task`, `attestation_credential` |

docs/creative/asset-types.mdx

@@ -34,7 +34,7 @@ The full set of asset types valid in a v2 format `slots` declaration's `asset_ty
 | `zip` | Zip archive (HTML5 banner bundle) | `/schemas/core/assets/zip-asset.json` |
 | `vast_tracker` | Single VAST `Tracking` event URL (decomposed) | `/schemas/core/assets/vast-tracker-asset.json` |
 | `daast_tracker` | Single DAAST `Tracking` event URL (decomposed) | `/schemas/core/assets/daast-tracker-asset.json` |
-| `pixel_tracker` | Renderer-fired HTTP tracker (image pixel or JS include) for any web-rendered canonical. `event` (impression / viewable_mrc_* / viewable_video_50 / audible_video_complete / click / custom) × `method` (img / js). Maps to IAB OpenRTB Native 1.2 `imptrackers[]` / `jstracker` / `eventtrackers[]` / `link.clicktrackers[]` event-type registry (types 1, 2, 3, 4, 500) | `/schemas/core/assets/pixel-tracker-asset.json` |
+| `pixel_tracker` | Renderer-fired HTTP tracker (image pixel or JS include) for any web-rendered canonical. `event` (impression / viewable_mrc_* / viewable_video_50 / audible_video_complete / click / custom) × `method` (img / js). Maps to IAB OpenRTB Native 1.2 `imptrackers[]` / `jstracker` / `eventtrackers[]` / `link.clicktrackers[]`; standardized event types 1-4 are reused, while audible completion is an AdCP-defined event and `custom` can carry exchange/vendor extensions | `/schemas/core/assets/pixel-tracker-asset.json` |
 | `object` | Structured object (image_carousel `cards`, `video_brief` for generative video) — sub-shape declared by the canonical | (no standalone schema; per-canonical sub-shape) |
 
 In a v2 manifest's `assets` map, the **slot key** is the canonical's `asset_group_id` (e.g., `image_main`, `video_main`, `script`, `cards`, `landing_page_url`) and the **value** carries the matching asset payload with its `asset_type` discriminator. The format declaration's `slots[].asset_type` tells the validator which payload schema applies.
@@ -335,7 +335,7 @@ VAST (Video Ad Serving Template) tags for third-party video ad serving.
 - `tracking_events`: Array of supported tracking events. Valid values are defined by the [VAST Tracking Event](https://adcontextprotocol.org/schemas/v3/enums/vast-tracking-event.json) enum. Aligned to the IAB VAST 4.2 XSD `TrackingEvents_type/Tracking/@event` enumeration (vast_4.2.xsd lines 112–136), plus AdCP-flattened representations of `Impression`, `Error`, `VideoClicks`, and `ViewableImpression` elements:
   - **Playback**: `impression` (billing event), `creativeView`, `loaded`, `start`, `firstQuartile`, `midpoint`, `thirdQuartile`, `complete`
   - **Interaction**: `mute`, `unmute`, `pause`, `resume`, `rewind`, `skip`, `playerExpand`, `playerCollapse`, `fullscreen` (VAST 2.x/3.x compat), `exitFullscreen` (VAST 2.x/3.x compat), `otherAdInteraction`, `interactiveStart` (SIMID)
-  - **Non-linear / companion**: `acceptInvitation`, `adExpand`, `adCollapse`, `minimize`, `overlayViewDuration`
+  - **Non-linear**: `acceptInvitation`, `adExpand`, `adCollapse`, `minimize`, `overlayViewDuration`
   - **Progress**: `progress` (for custom progress points via VAST `offset` attribute)
   - **Click & close**: `clickTracking`, `customClick`, `close`, `closeLinear`
   - **Verification**: `viewable`, `notViewable`, `viewUndetermined`, `measurableImpression` (AdCP extension), `viewableImpression`
@@ -373,8 +373,8 @@ A single URL bound to a VAST `TrackingEvents` event. Use this when the creative
 **Properties:**
 - `vast_event`: The event this URL fires on. Any VAST tracking-event enum value **except** `impression`, `clickTracking`, `customClick`, `error`, or any of `viewable` / `notViewable` / `viewUndetermined` / `measurableImpression` / `viewableImpression` — those live in dedicated VAST elements (`Impression`, `VideoClicks`, `Error`, `ViewableImpression`), not under `TrackingEvents` (see Tracker routing normative rule below). Common values: `start`, `firstQuartile`, `midpoint`, `thirdQuartile`, `complete`, `pause`, `resume`, `mute`, `unmute`, `skip`, `progress`.
 - `url`: Tracker URL. Supports [AdCP universal macros](/docs/creative/universal-macros).
-- `offset`: Required for `vast_event: "progress"`. VAST 4.2 offset format (`Tracking@offset`): `HH:MM:SS` or `HH:MM:SS.mmm` (two-digit hours, minutes 00–59, seconds 00–59, exactly 3 fractional digits when present) for absolute time, or an integer percentage 0–100 suffixed with `%`. Negative offsets are NOT permitted — the VAST 4.2 XSD pattern does not allow a leading minus.
-- `target`: Which VAST creative element scopes this tracker — `linear` (default), `non_linear`, or `companion`. VAST 4.2 places `<TrackingEvents>` under three different parents (`<Linear>`, `<NonLinearAds>`, `<CompanionAds>/<Companion>`) with different valid event sets — e.g., `acceptInvitation` is meaningful on `non_linear`/`companion`, `closeLinear` only on `linear`. Sales agents read this to place the tracker correctly during VAST assembly.
+- `offset`: Required for `vast_event: "progress"`. On other events it is ignored for compatibility with existing 3.x manifests and removed before tracker-contract matching. VAST 4.2 offset format (`Tracking@offset`): `HH:MM:SS` or `HH:MM:SS.mmm` (two-digit hours, minutes 00–59, seconds 00–59, exactly 3 fractional digits when present) for absolute time, or an integer percentage 0–100 suffixed with `%`. Negative offsets are NOT permitted — the VAST 4.2 XSD pattern does not allow a leading minus.
+- `target`: Which VAST creative element scopes this tracker — `linear` (default), `non_linear`, or `companion`. Existing 3.x manifests remain structurally permissive. When a product declares a tracker execution contract, matching applies the closed standards matrix: `acceptInvitation` is non-linear, `creativeView` is the only companion event, and `closeLinear` is linear. Sales agents read this to place the tracker correctly during VAST assembly.
 
 **Target with non-linear event:**
 ```json
@@ -451,8 +451,8 @@ Audio-side analogue of `vast_tracker`: a single URL bound to a DAAST `TrackingEv
 **Properties:**
 - `daast_event`: Any DAAST tracking-event enum value **except** `impression`, `clickTracking`, `customClick`, `error`, or any of `viewable` / `notViewable` / `viewUndetermined` / `measurableImpression` / `viewableImpression` (same element-routing rule as `vast_tracker` — those values belong in `Impression` / `<AdInteractions>` / `Error` / AdCP-extension verification slots, not `TrackingEvents`). Common values: `start`, `firstQuartile`, `midpoint`, `thirdQuartile`, `complete`, `pause`, `resume`, `mute`, `unmute`, `rewind`, `skip`, `progress`.
 - `url`: Tracker URL. Supports AdCP universal macros.
-- `offset`: Required for `daast_event: "progress"` (DAAST 1.1 §3.2.4.3). Same format as VAST 4.2 `Tracking@offset`. Negative offsets are NOT permitted.
-- `target`: Which DAAST creative element scopes this tracker — `linear` (default, DAAST 1.1 §3.2.1.7) or `companion` (DAAST 1.1 §3.2.2.7, where the only valid event is `creativeView`). DAAST has no `<NonLinearAds>` element — audio is linear or accompanied by a visual companion.
+- `offset`: Required for `daast_event: "progress"` (DAAST 1.1 §3.2.4.3). On other events it is ignored for compatibility with existing 3.x manifests and removed before tracker-contract matching. Same format as VAST 4.2 `Tracking@offset`. Negative offsets are NOT permitted.
+- `target`: Which DAAST creative element scopes this tracker — `linear` (default, DAAST 1.1 §3.2.1.7) or `companion` (DAAST 1.1 §3.2.2.7). Existing 3.x manifests remain structurally permissive; a tracker execution contract restricts companion matching to `creativeView`. DAAST has no `<NonLinearAds>` element — audio is linear or accompanied by a visual companion.
 
 ### Pixel Tracker Asset
 
@@ -469,10 +469,10 @@ Renderer-fired HTTP tracker — image pixel or JavaScript include — bound to a
 ```
 
 **Properties:**
-- `event`: `impression` | `viewable_mrc_50` | `viewable_mrc_100` | `viewable_video_50` | `audible_video_complete` | `click` | `custom`. Event enum mirrors IAB OpenRTB Native 1.2 event-type registry (types 1, 2, 3, 4, 500). `audible_video_complete` is distinct from `viewable_video_50` — the former is full-completion with audio on; the latter is 50% pixels for ≥2 seconds with audio on. Meaningful on non-VAST video formats (Meta Reels, YouTube Shorts, TikTok Spark); VAST formats use `vast_tracker` with `vast_event: complete` instead.
+- `event`: `impression` | `viewable_mrc_50` | `viewable_mrc_100` | `viewable_video_50` | `audible_video_complete` | `click` | `custom`. The first four measurement values map to IAB OpenRTB Native 1.2 event types 1-4. Native type 4 is 50% pixels for at least two seconds and does not require audio. `audible_video_complete` is a distinct AdCP-defined full-completion event with audio on; Native leaves event types 500+ exchange-specific rather than assigning this event a standard numeric type. These video events are meaningful on non-VAST video formats; VAST formats use `vast_tracker` with `vast_event: complete` and separate audible measurement where needed.
 - `method`: `img` (fired as `<img>` pixel) or `js` (fired as `<script>` include). Matches IAB Native 1.2 method enum (1=img, 2=js). Default `img`. Sellers without JS-tracker support MUST reject `method: js` declarations at sync_creatives time.
 - `url`: Tracker URL fired when `event` occurs. May carry AdCP universal macros.
-- `custom_event_name`: REQUIRED when `event: custom`, forbidden otherwise (if/then enforced at the schema layer). Adopter-defined event name; sellers without registered handling MUST silently no-op rather than reject.
+- `custom_event_name`: REQUIRED when `event: custom`, forbidden otherwise (if/then enforced at the schema layer). When tracker execution is undeclared, an unknown custom event is a forward-compatible probe and the seller silently no-ops rather than rejecting the creative. An effective `tracker_execution_contract` overrides that fallback: under `complete: true`, an unlisted custom selector is unsupported and produces `tracker_contract_mismatch`; a listed selector is an affirmative accept-and-initiate commitment.
 
 **Maps to IAB OpenRTB Native 1.2:**
 - `imptrackers[]` → `pixel_tracker` with `event: impression`, `method: img`

docs/creative/canonical-formats.mdx

@@ -328,7 +328,7 @@ Downstream platform authorization is separate from production source. If a forma
 
 When `asset_source` is `buyer_uploaded`, the buyer ships rendered assets and any tracker URLs attached to those assets are buyer-controlled (universal_macros for impression/click; `vast_tracker` / `daast_tracker` assets for decomposed VAST/DAAST trackers). When `asset_source` is any of the seller-rendered values (`seller_pre_rendered_from_brief`, `seller_human_designed`, `agent_synthesized`) or `publisher_host_recorded`, the buyer never sees the rendered artifact directly. Two normative paths apply:
 
-- **Capability-gated macro-substituted tracking.** Tracker URLs are explicit `pixel_tracker`, `vast_tracker`, or `daast_tracker` assets (or governed tracking extensions); `landing_page_url` remains the navigated destination, not a tracker. Exact macro capabilities declare whether occurrences such as `{IMPRESSION_ID}` and `{CACHEBUSTER}` can be processed, but they do not claim that the product accepts or fires the containing tracker. When the product tracking contract declares the asset type honored, the seller embeds and fires it according to that commitment. Until that contract is present, tracker acceptance and firing are undeclared and buyers MUST NOT infer them from macro compatibility.
+- **Capability-gated macro-substituted tracking.** Tracker URLs are explicit `pixel_tracker`, `vast_tracker`, or `daast_tracker` assets (or governed tracking extensions); `landing_page_url` remains the navigated destination, not a tracker. Exact macro capabilities declare whether occurrences such as `{IMPRESSION_ID}` and `{CACHEBUSTER}` can be processed, but they do not claim that the product accepts or fires the containing tracker. The selected format option's [tracker execution contract](/docs/creative/tracker-execution-contracts) makes that separate accept-and-initiate commitment. Until that contract is present, tracker acceptance and firing are undeclared and buyers MUST NOT infer them from macro compatibility.
 - **Sync-creatives tracker block.** For products where the seller produces a serving artifact that embeds tracker URLs directly (e.g., a generated VAST tag or a stitched companion banner), the seller's `sync_creatives` response SHOULD include a `tracker_block` field listing the impression URL pattern and click URL pattern. Buyers register those with their measurement vendor at sync time. This path covers the generative-DSP pattern where the serving artifact and the tracking shape are produced together.
 
 `vast_tracker` and `daast_tracker` decomposed tracker assets work for both `buyer_uploaded` and seller-rendered sources — when the seller renders, those tracker assets are inputs to the rendered tag, attached to the appropriate VAST/DAAST `<TrackingEvents>` block at production time. When the buyer ships a complete `vast` or `daast` tag, the trackers travel inside the tag.