feat(creative): declare tracker execution contracts

.changeset/add-creative-revision-identity.md

@@ -0,0 +1,7 @@
+---
+"adcontextprotocol": minor
+---
+
+Add buyer-authored immutable creative revision identity across sync, review,
+library readback, and delivery attribution, plus agent-unique served variant
+identity for unambiguous post-flight preview replay.

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

.changeset/creative-delivery-contracts.md

@@ -0,0 +1,5 @@
+---
+"adcontextprotocol": minor
+---
+
+Add explicit creative delivery contracts for inline display tags, atomic paired redirects, and revision-bound creative representation sets. A complete representation set is one immutable buyer revision; deterministic selection identifies one `representation_id` without creating a build or served variant and carries the complete revision digest into the seller-bound manifest. Define exact VAST asset versions versus product and seller acceptance sets, VAST MediaFile delivery/MIME/container/codec/dimension/bitrate/byte requirements, decimal file-size units, and declaration-level technical completeness. Add declared macro dialect, resolver ownership, encoding depth, capability matching, per-token validation results, structured rejection errors, documentation, and conformance vectors for issues #6761–#6764.

docs.json

@@ -356,6 +356,7 @@
                       "docs/creative/sales-agent-creative-capabilities",
                       "docs/creative/multi-agent-orchestration",
                       "docs/creative/creative-manifests",
+                      "docs/creative/representation-sets",
                       "docs/creative/private-assets",
                       "docs/creative/buyer-attached-inputs"
                     ]
@@ -366,7 +367,8 @@
                       "docs/creative/formats",
                       "docs/creative/asset-types",
                       "docs/creative/template-format-ids",
-                      "docs/creative/universal-macros"
+                      "docs/creative/universal-macros",
+                      "docs/creative/tracker-execution-contracts"
                     ]
                   },
                   {

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_format` |
+| 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

@@ -63,6 +63,8 @@ For payload schemas (the structure of the actual asset data supplied in creative
 - `duration_ms` (when applicable)
 - `format` (declared container type)
 
+File-size limits use decimal, exact units throughout AdCP: `*_kb` means 1 KB = 1,000 bytes, `*_mb` means 1 MB = 1,000,000 bytes, and `*_bytes` is an exact byte count. Do not interpret KB/MB fields as KiB/MiB.
+
 ## Asset Type Schema
 
 The official JSON schema for asset types is available at:
@@ -97,7 +99,7 @@ Video assets represent video files with specific technical requirements.
 - `acceptable_codecs`: Video codecs (h264, h265, vp8, vp9, av1)
 - `acceptable_resolutions`: List of width x height strings
 - `aspect_ratio`: Required aspect ratio (16:9, 9:16, 1:1, etc.)
-- `max_file_size_mb`: Maximum file size in megabytes
+- `max_file_size_mb`: Maximum file size in decimal megabytes (1 MB = 1,000,000 bytes)
 - `min_bitrate_mbps` / `max_bitrate_mbps`: Bitrate range in Mbps
 - `features`: Additional requirements (e.g., ["non-skippable", "sound on"])
 
@@ -123,7 +125,7 @@ Static image assets for banners, logos, and visual content.
 - `min_width` / `min_height`: Minimum dimensions (px; typically used by responsive/sizeless formats)
 - `aspect_ratio`: Required aspect ratio
 - `acceptable_formats`: Image formats (jpg, png, gif, webp, svg)
-- `max_file_size_kb`: Maximum file size in kilobytes
+- `max_file_size_kb`: Maximum file size in decimal kilobytes (1 KB = 1,000 bytes)
 - `transparency`: Whether transparency is required/supported
 - `animation_allowed`: Whether animated GIFs are accepted
 - `notes`: Additional requirements (e.g., "Must be free of text")
@@ -175,6 +177,7 @@ Senders **SHOULD** include `url_type` on every URL asset. The valid values are:
 | Value | Mechanism |
 |---|---|
 | `clickthrough` | User-click destination (landing page or ad-tech redirector) |
+| `ad_request` | Invokes a third-party display creative endpoint at impression time |
 | `tracker_pixel` | Fires HTTP GET, expects 1×1 pixel or 204 response (impression / event / 3P trackers) |
 | `tracker_script` | Loads as a `<script>` tag — measurement SDKs (OMID verification, native event trackers using `method: 2`) |
 
@@ -197,6 +200,8 @@ If `url_type` is **absent**, receivers SHOULD fall back to the format's `url-ass
 | `viewability_tracker` | `tracker_script` — OMID and equivalent verification SDKs **require** a `<script>` tag; firing them as a pixel produces no measurement |
 | `third_party_tracker` | **No safe fallback.** Mechanism is integration-specific (DV/IAS ship both pixel and script forms). Receivers MAY reject or warn. |
 
+Display ad-request URLs also have no role-based fallback. Declare `url_type: "ad_request"` explicitly.
+
 If neither `url_type` nor a format-side `role` is available, receivers MUST NOT silently pick a mechanism — firing a clickthrough URL as a pixel (or vice versa) silently corrupts measurement and breaks the user flow. Receivers SHOULD reject the manifest.
 
 > **VAST/DAAST URLs are not URL assets.** A URL pointing to ad-server XML markup is parsed, not GET-fired. Use `asset_type: "vast"` with `delivery_type: "url"` for VAST tags, and the dedicated tracker types (`vast_tracker` / `daast_tracker`) once those land per [RFC #2915](https://github.com/adcontextprotocol/adcp/issues/2915). A VAST tag declared as `asset_type: "url"` with `url_type: "tracker_pixel"` is non-conformant under these mechanism semantics.
@@ -249,12 +254,12 @@ Audio files for audio ads and podcasts.
 - `duration_seconds`: Expected duration
 - `acceptable_formats`: Audio formats (mp3, m4a, aac, ogg)
 - `min_bitrate_kbps`: Minimum bitrate in kilobits per second
-- `max_file_size_mb`: Maximum file size in megabytes
+- `max_file_size_mb`: Maximum file size in decimal megabytes (1 MB = 1,000,000 bytes)
 - `stereo_required`: Whether stereo audio is required
 
 ### HTML Asset
 
-HTML5 creative assets for rich media formats and third-party display tags.
+Inline HTML content assets. Seller-hosted HTML5 creative bundles use a `zip` asset. Third-party display markup uses the `display_tag` asset below.
 
 ```json
 {
@@ -276,6 +281,21 @@ HTML5 creative assets for rich media formats and third-party display tags.
 - `allowed_features`: Allowed HTML5 features
 - `restricted_features`: Features that must not be used
 
+### Display Tag Asset
+
+An atomic third-party display representation. `delivery_type` is one of `tag_url`, `inline_markup`, or `paired_redirect`. The paired form requires both `ad_request_url` and `clickthrough_url`; they cannot be trafficked or revised independently.
+
+```json
+{
+  "asset_type": "display_tag",
+  "delivery_type": "paired_redirect",
+  "ad_request_url": "https://ads.acme-example.com/ad?slot=42",
+  "clickthrough_url": "https://click.acme-example.com/redirect"
+}
+```
+
+Inline markup also records `markup_type` as `iframe_javascript`, `javascript`, or `standard`. Preserve markup bytes exactly. Do not classify it as `html5`, which means a seller-hosted zip bundle.
+
 ### VAST Asset
 
 VAST (Video Ad Serving Template) tags for third-party video ad serving.
@@ -308,14 +328,14 @@ VAST (Video Ad Serving Template) tags for third-party video ad serving.
 - `delivery_type`: "url" or "inline" (required discriminator)
 - `url`: URL endpoint that returns VAST XML (required when delivery_type is "url")
 - `content`: Inline VAST XML content (required when delivery_type is "inline")
-- `vast_version`: VAST specification version (2.0, 3.0, 4.0, 4.1, 4.2, 4.3)
+- `vast_version`: Exact VAST specification version supplied by this asset (2.0, 3.0, 4.0, 4.1, 4.2, 4.3). Product format options use plural `vast_versions` for their accepted set.
 - `vpaid_enabled`: Whether VPAID (Video Player-Ad Interface Definition) is supported
 - `max_wrapper_depth`: Maximum allowed wrapper/redirect depth
 - `duration_ms`: Expected video duration in milliseconds (if known)
 - `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`
@@ -354,7 +374,7 @@ A single URL bound to a VAST `TrackingEvents` event. Use this when the creative
 - `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.
+- `target`: Which VAST creative element scopes this tracker — `linear` (default), `non_linear`, or `companion`. VAST places `<TrackingEvents>` under three different parents (`<Linear>`, `<NonLinearAds>`, `<CompanionAds>/<Companion>`) with different valid event sets: `acceptInvitation` is non-linear, `creativeView` is the only companion event in the closed AdCP matrix, and `closeLinear` is linear. Sales agents read this to place the tracker correctly during VAST assembly.
 
 **Target with non-linear event:**
 ```json
@@ -452,7 +472,7 @@ Renderer-fired HTTP tracker — image pixel or JavaScript include — bound to a
 - `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.
 - `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`