@adcp/sdk 8.1.0-beta.7 → 8.1.0-beta.8

package/dist/lib/types/list-creative-formats.d.ts

@@ -0,0 +1,3132 @@
+// AUTO-GENERATED — DO NOT EDIT.
+// Per-tool .d.ts slice for `list_creative_formats`. Built from the published
+// `tools.generated.d.ts` + `core.generated.d.ts` + `enums.generated.d.ts`
+// by `scripts/generate-per-tool-types.ts`.
+//
+// Self-contained: imports nothing from the broader SDK. Adopters who
+// import only this slice pay a fraction of the tsc cost of pulling in
+// `@adcp/sdk` root — useful when strict + skipLibCheck:false adopters
+// hit memory pressure on the full surface.
+
+/**
+ * Request parameters for discovering supported creative formats
+ */
+export interface ListCreativeFormatsRequest {
+    /**
+     * Release-precision AdCP version (VERSION.RELEASE, e.g. "3.0", "3.1", "3.1-beta"). On a request: the buyer's release pin — the seller validates against its supported_versions and returns VERSION_UNSUPPORTED on cross-major mismatch, or downshifts to the highest supported release within the same major. On a response: the release the seller actually served — clients SHOULD validate the response against that release's schema, not against their pin. Patches are not negotiated; surface them as build_version on capabilities for operational visibility. When omitted, falls back to adcp_major_version (deprecated) or server default. Buyers SHOULD emit both adcp_version and adcp_major_version through 3.x to remain compatible with sellers that only read the legacy field. NORMALIZATION: SDKs that read full-semver values from bundle metadata (e.g. ComplianceIndex.published_version = "3.1.0-beta.1") MUST normalize to release-precision ("3.1-beta.1") before emitting on the wire — meta-field values are NOT valid wire values.
+     */
+    adcp_version?: string;
+    /**
+     * DEPRECATED in favor of adcp_version (release-precision string). Servers MUST continue to honor this field through 3.x. Removed in 4.0. Original semantics: the AdCP major version the buyer's payloads conform to. Sellers validate against their supported major_versions and return VERSION_UNSUPPORTED if unsupported. When omitted, the seller assumes its highest supported version.
+     */
+    adcp_major_version?: number;
+    /**
+     * Return only these specific format IDs (e.g., from get_products response)
+     */
+    format_ids?: FormatReferenceStructuredObject[];
+    /**
+     * Filter to formats that include these asset types. For third-party tags, search for 'html' or 'javascript'. E.g., ['image', 'text'] returns formats with images and text, ['javascript'] returns formats accepting JavaScript tags.
+     */
+    asset_types?: AssetContentType[];
+    /**
+     * Maximum width in pixels (inclusive). Returns formats where ANY render has width <= this value. For multi-render formats, matches if at least one render fits.
+     */
+    max_width?: number;
+    /**
+     * Maximum height in pixels (inclusive). Returns formats where ANY render has height <= this value. For multi-render formats, matches if at least one render fits.
+     */
+    max_height?: number;
+    /**
+     * Minimum width in pixels (inclusive). Returns formats where ANY render has width >= this value.
+     */
+    min_width?: number;
+    /**
+     * Minimum height in pixels (inclusive). Returns formats where ANY render has height >= this value.
+     */
+    min_height?: number;
+    /**
+     * Filter for responsive formats that adapt to container size. When true, returns formats without fixed dimensions.
+     */
+    is_responsive?: boolean;
+    /**
+     * Search for formats by name (case-insensitive partial match)
+     */
+    name_search?: string;
+    /**
+     * Filter to formats supported by the named publisher. Agents resolve via the three-tier order documented in `docs/creative/canonical-formats.mdx#format-discovery` (publisher's hosted adagents.json → AAO community mirror → agent-derived from own products' format_options). All fetches in the chain MUST follow the same transport contract as `format_schema` (https-only, SSRF guards, ≤5s timeout, 1 MiB cap, no redirects — see `static/schemas/source/core/product-format-declaration.json#format_schema`). Response carries `source: "publisher" | "aao_mirror" | "agent_derived"` so buyers know which tier produced the list. The pattern below is a syntactic floor — NOT an SSRF guard; agents MUST resolve the hostname and reject private/loopback/link-local/metadata IPs before fetching.
+     * @pattern ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$
+     */
+    publisher_domain?: string;
+    property_id?: PropertyID;
+    wcag_level?: WCAGLevel;
+    /**
+     * Filter to formats that support all of these disclosure positions. When a format has disclosure_capabilities, match against those positions. Otherwise fall back to supported_disclosure_positions. Use to find formats compatible with a brief's compliance requirements.
+     */
+    disclosure_positions?: DisclosurePosition[];
+    /**
+     * Filter to formats where each requested persistence mode is supported by at least one position in disclosure_capabilities. Different positions may satisfy different modes. Use to find formats compatible with jurisdiction-specific persistence requirements (e.g., continuous for EU AI Act).
+     */
+    disclosure_persistence?: DisclosurePersistence[];
+    /**
+     * Filter to formats whose output_format_ids includes any of these format IDs. Returns formats that can produce these outputs — inspect each result's input_format_ids to see what inputs they accept.
+     */
+    output_format_ids?: FormatReferenceStructuredObject[];
+    /**
+     * Filter to formats whose input_format_ids includes any of these format IDs. Returns formats that accept these creatives as input — inspect each result's output_format_ids to see what they can produce.
+     */
+    input_format_ids?: FormatReferenceStructuredObject[];
+    pagination?: PaginationRequest;
+    context?: ContextObject;
+    ext?: ExtensionObject;
+}
+
+/**
+ * Response payload for list_creative_formats task
+ */
+export interface ListCreativeFormatsResponse {
+    /**
+     * Session/conversation identifier for tracking related operations across multiple task invocations. Managed by the protocol layer to maintain conversational context. Distinct from `context` (per-request opaque echo, see below).
+     */
+    context_id?: string;
+    context?: ContextObject;
+    /**
+     * Unique identifier for tracking asynchronous operations. Present when a task requires extended processing time. Used to query task status and retrieve results when complete.
+     */
+    task_id?: string;
+    status: TaskStatus;
+    /**
+     * Human-readable summary of the task result. Provides natural language explanation of what happened, suitable for display to end users or for AI agent comprehension. Generated by the protocol layer based on the task response.
+     */
+    message?: string;
+    /**
+     * ISO 8601 timestamp when the response was generated. Useful for debugging, logging, cache validation, and tracking async operation progress.
+     */
+    timestamp?: string;
+    /**
+     * Set to true when this response was returned from the idempotency cache rather than from a fresh execution. Set to false (or omitted) when the request was executed fresh. Buyers use this to distinguish cached replays from new executions — matters for billing reconciliation, audit logs, state-machine routing (cached state-tracking fields are historical snapshots, not current state — re-read via the resource's read endpoint), and any downstream system that assumes exactly-once event semantics. From 3.1 onward, `replayed` MAY appear on responses to any request that resolved via the idempotency cache, including read tools — universal `idempotency_key` (see security.mdx §Idempotency) means the cache holds read responses too.
+     */
+    replayed?: boolean;
+    adcp_error?: Error;
+    push_notification_config?: PushNotificationConfig;
+    /**
+     * Governance context token issued by the account's governance agent during check_governance. Buyers attach it to governed purchase requests (media buys, rights acquisitions, signal activations, creative services); sellers persist it and include it on all subsequent governance calls for that action's lifecycle. An account binds to one governance agent (see sync_governance); governance is phased across `purchase` / `modification` / `delivery`, not partitioned across specialist agents, so the envelope carries a single token for the full lifecycle.
+     *
+     * Value format: governance agents MUST emit a compact JWS per the AdCP JWS profile (see Security — Signed Governance Context). Sellers MAY verify; sellers that do not verify MUST persist and forward the token unchanged. In 3.1 all sellers MUST verify. Non-JWS values from pre-3.0 governance agents are deprecated.
+     *
+     * This is the primary correlation key for audit and reporting across the governance lifecycle.
+     */
+    governance_context?: string;
+    /**
+     * Conceptual grouping for the task-specific response data defined by individual task response schemas (e.g., get-products-response.json, create-media-buy-response.json). `payload` is a documentary construct — it is NOT a required wire field, and its on-the-wire shape depends on transport (see Transport serialization below). Task response schemas declare body fields without wrapping them in a `payload` object; the wire representation places those body fields per transport convention. On MCP the body fields appear as siblings of envelope fields at the root of the tool response; on A2A they appear inside `task.artifacts[0].parts[].DataPart`; on REST they appear at the root of the JSON body.
+     */
+    payload?: {};
+    /**
+     * Release-precision AdCP version (VERSION.RELEASE, e.g. "3.0", "3.1", "3.1-beta"). On a request: the buyer's release pin — the seller validates against its supported_versions and returns VERSION_UNSUPPORTED on cross-major mismatch, or downshifts to the highest supported release within the same major. On a response: the release the seller actually served — clients SHOULD validate the response against that release's schema, not against their pin. Patches are not negotiated; surface them as build_version on capabilities for operational visibility. When omitted, falls back to adcp_major_version (deprecated) or server default. Buyers SHOULD emit both adcp_version and adcp_major_version through 3.x to remain compatible with sellers that only read the legacy field. NORMALIZATION: SDKs that read full-semver values from bundle metadata (e.g. ComplianceIndex.published_version = "3.1.0-beta.1") MUST normalize to release-precision ("3.1-beta.1") before emitting on the wire — meta-field values are NOT valid wire values.
+     */
+    adcp_version?: string;
+    /**
+     * DEPRECATED in favor of adcp_version (release-precision string). Servers MUST continue to honor this field through 3.x. Removed in 4.0. Original semantics: the AdCP major version the buyer's payloads conform to. Sellers validate against their supported major_versions and return VERSION_UNSUPPORTED if unsupported. When omitted, the seller assumes its highest supported version.
+     */
+    adcp_major_version?: number;
+    /**
+     * Full format definitions for all formats this agent supports. Each format's authoritative source is indicated by its agent_url field.
+     */
+    formats: Format[];
+    /**
+     * Which tier of the resolution order produced this `formats[]` list when the request carried a `publisher_domain` filter. `publisher`: agent fetched `<publisher_domain>/.well-known/adagents.json` and returned its `formats[]` directly (publisher-authoritative). `aao_mirror`: publisher's hosted file was 404 / lacked `formats[]`, agent fell back to `https://creative.adcontextprotocol.org/translated/<platform>/adagents.json` (community-curated; lower authority — buyer SHOULD treat as advisory until platform adopts). `agent_derived`: neither tier 1 nor tier 2 returned a catalog, so the agent synthesized `formats[]` from the union of its own products' `format_options[]` for products selling the publisher's inventory (lowest authority — agent's view of what it sells, not the publisher's catalog). When two SDKs query the same agent for the same publisher and the agent-derived tier is in play, results may diverge by product set; buyers SHOULD record `source` for telemetry. When the request did NOT carry `publisher_domain`, this field MAY be omitted.
+     */
+    source?: 'publisher' | 'aao_mirror' | 'agent_derived';
+    /**
+     * Optional: Creative agents that provide additional formats. Buyers can recursively query these agents to discover more formats. No authentication required for list_creative_formats.
+     */
+    creative_agents?: {
+        /**
+         * Base URL for the creative agent (e.g., 'https://reference.adcp.org', 'https://dco.example.com'). Call list_creative_formats on this URL to get its formats.
+         */
+        agent_url: string;
+        /**
+         * Human-readable name for the creative agent
+         */
+        agent_name?: string;
+        /**
+         * Capabilities this creative agent provides
+         */
+        capabilities?: CreativeAgentCapability[];
+    }[];
+    /**
+     * Task-specific errors and warnings (e.g., format availability issues)
+     */
+    errors?: Error[];
+    pagination?: PaginationResponse;
+    /**
+     * When true, this response contains simulated data from sandbox mode.
+     */
+    sandbox?: boolean;
+    ext?: ExtensionObject;
+}
+
+export interface AgentPlacementFormatDeclaration {
+    format_kind: 'agent_placement';
+    params: CanonicalFormatAgentPlacementAISurfaceSponsoredPlacement;
+}
+
+/**
+ * Types of content that can be used as creative assets. Describes what KIND of content an asset contains (image, video, code, etc.), not where it displays.
+ */
+export type AssetContentType = 'image' | 'video' | 'audio' | 'text' | 'markdown' | 'html' | 'css' | 'javascript' | 'vast' | 'daast' | 'url' | 'webhook' | 'brief' | 'catalog';
+
+/**
+ * Requirements for audio creative assets.
+ */
+export interface AudioAssetRequirements {
+    /**
+     * Minimum duration in milliseconds
+     * @minimum 1
+     */
+    min_duration_ms?: number;
+    /**
+     * Maximum duration in milliseconds
+     * @minimum 1
+     */
+    max_duration_ms?: number;
+    /**
+     * Accepted audio file formats
+     */
+    formats?: ('mp3' | 'aac' | 'wav' | 'ogg' | 'flac')[];
+    /**
+     * Maximum file size in kilobytes
+     * @minimum 1
+     */
+    max_file_size_kb?: number;
+    /**
+     * Accepted sample rates in Hz (e.g., [44100, 48000])
+     */
+    sample_rates?: number[];
+    /**
+     * Accepted audio channel configurations
+     */
+    channels?: ('mono' | 'stereo')[];
+    /**
+     * Minimum audio bitrate in kilobits per second
+     * @minimum 1
+     */
+    min_bitrate_kbps?: number;
+    /**
+     * Maximum audio bitrate in kilobits per second
+     * @minimum 1
+     */
+    max_bitrate_kbps?: number;
+}
+
+/**
+ * Audio channel configuration
+ */
+export type AudioChannelLayout = 'mono' | 'stereo' | '5.1' | '7.1';
+
+/**
+ * Legacy authentication schemes for the webhook auth block. Bearer: token sent in Authorization header. HMAC-SHA256: legacy shared-secret signing. Both are deprecated; new integrations SHOULD omit the authentication block and use the RFC 9421 webhook signing profile (applicable on schemas where authentication is optional). Removed in AdCP 4.0.
+ */
+export type AuthenticationScheme = 'Bearer' | 'HMAC-SHA256';
+
+/**
+ * Standard delivery and performance metrics available for reporting
+ */
+export type AvailableMetric = 'impressions' | 'spend' | 'clicks' | 'ctr' | 'views' | 'completed_views' | 'completion_rate' | 'conversions' | 'conversion_value' | 'roas' | 'cost_per_acquisition' | 'new_to_brand_rate' | 'leads' | 'reach' | 'frequency' | 'grps' | 'engagements' | 'engagement_rate' | 'follows' | 'saves' | 'profile_visits' | 'viewability' | 'quartile_data' | 'dooh_metrics' | 'cost_per_click' | 'cost_per_completed_view' | 'cpm' | 'downloads' | 'units_sold' | 'new_to_brand_units' | 'plays' | 'incremental_sales_lift' | 'brand_lift' | 'foot_traffic' | 'conversion_lift' | 'brand_search_lift';
+
+export interface BaseGroupAsset {
+    /**
+     * Identifier for this asset within the group
+     */
+    asset_id: string;
+    /**
+     * Descriptive label for this asset's purpose. For documentation and UI display only — manifests key assets by asset_id, not asset_role.
+     */
+    asset_role?: string;
+    /**
+     * Optional canonical asset_group_id this slot fills, drawn from /schemas/core/asset-group-vocabulary.json. Same semantics as on baseIndividualAsset — lets buyers and migration tools resolve v1 author-invented slot names to canonical names.
+     */
+    asset_group_id?: string;
+    /**
+     * Whether this asset is required within each repetition of the group
+     */
+    required: boolean;
+    /**
+     * Publisher-controlled elements rendered on top of buyer content at this asset's position (e.g., carousel navigation arrows, slide indicators). Creative agents should avoid placing critical content within overlay bounds.
+     */
+    overlays?: Overlay[];
+}
+
+export interface BaseIndividualAsset {
+    /**
+     * Discriminator indicating this is an individual asset
+     */
+    item_type: 'individual';
+    /**
+     * Unique identifier for this asset. Creative manifests MUST use this exact value as the key in the assets object.
+     */
+    asset_id: string;
+    /**
+     * Descriptive label for this asset's purpose (e.g., 'hero_image', 'logo', 'third_party_tracking'). For documentation and UI display only — manifests key assets by asset_id, not asset_role.
+     */
+    asset_role?: string;
+    /**
+     * Whether this asset is required (true) or optional (false). Required assets must be provided for a valid creative. Optional assets enhance the creative but are not mandatory.
+     */
+    required: boolean;
+    /**
+     * Publisher-controlled elements rendered on top of buyer content at this asset's position (e.g., video player controls, publisher logos). Creative agents should avoid placing critical content (CTAs, logos, key copy) within overlay bounds.
+     */
+    overlays?: Overlay[];
+    /**
+     * Optional canonical asset_group_id this slot fills, drawn from /schemas/core/asset-group-vocabulary.json. Lets buyers and migration tools resolve v1 author-invented slot names (e.g., `click_url`) to canonical names (e.g., `landing_page_url`). Validators MAY soft-warn when a v1 slot's asset_id is a known alias but no asset_group_id is declared.
+     */
+    asset_group_id?: string;
+}
+
+/**
+ * Requirements for CSS creative assets.
+ */
+export interface CSSAssetRequirements {
+    /**
+     * Maximum file size in kilobytes
+     * @minimum 1
+     */
+    max_file_size_kb?: number;
+}
+
+/**
+ * **3.2-track canonical.** The structural shape (algorithmic composition + brand-context input + optional offering/landing_page) is captured here so adopters can declare against it in 3.1 catalogs, but the **mention-level tracking contract is intentionally underspecified for 3.1**: no normative macro vocabulary, no postback shape, no cross-surface dedup model. Adopters claiming `agent_placement` in 3.1 ship private tracking integrations and SHOULD set `runtime_status: 'preview'` or `'declared_only'` on the declaration; buyer agents MUST treat agent_placement attribution as adapter-defined until the 3.2 tracking-macro spec lands. The canonical promotes to a normatively-buyer-callable surface in 3.2 (or later) once the tracking contract is specified.
+ *
+ * Sponsored placement integrated into an AI-surface's response to a user. Buyer supplies a `BrandRef` (resolving brand.json for context), an optional `offering_ref` to focus the mention on a specific offering, and an optional `landing_page_url` the surface MAY attach as a citation. The surface (LLM, voice assistant, sponsored-search ranker) composes a natural-language mention, sponsored card, or audio snippet within its response to a user query. **Composition is algorithmic** — the agent chooses phrasing and presentation. Output asset_type varies by surface: `text` for chat UIs and sponsored search snippets; `audio` (synthesized) for voice assistants; `card` for structured AI-surface result cards. Tracking model: mention-level impression + attribution events; per-mention id keys back to brand and offering — but see the 3.2-track note above; the wire shape of these events is not yet specified. Distinct from `si_chat` (which is the user-converses-with-brand's-agent pattern — brand owns the conversational surface) and from `sponsored_placement` (retail-media catalog-driven). Parallels `sponsored_placement` structurally: both are surface-composed placements; agent_placement is for AI/agentic surfaces, sponsored_placement is for retail media.
+ */
+export interface CanonicalFormatAgentPlacementAISurfaceSponsoredPlacement {
+    /**
+     * Marked experimental at 3.1 GA: the canonical's tracking model (mention-level impression + attribution, postback shape, cross-surface dedup) is intentionally underspecified for 3.1. Adopters claiming `agent_placement` ship private tracking integrations; buyer agents MUST treat attribution as adapter-defined until the 3.2 tracking-macro spec lands. Promotion to non-experimental gated on the 3.2 tracking-contract spec.
+     */
+    experimental?: unknown;
+    /**
+     * When true, this canonical (or a seller's specific narrowing of it) is going away. Existing adopters are supported through the deprecation cycle; new adoption is discouraged. Pair with `migration_target_version` to indicate when the canonical is expected to be removed. Distinct from `experimental`: an experimental canonical may stabilize and stop being experimental; a deprecated canonical is on a sunset path.
+     */
+    deprecated?: boolean;
+    /**
+     * Inherently new in v2 — AI-surface sponsored mentions weren't expressible as v1 named formats. SDKs MUST NOT emit `FORMAT_PROJECTION_FAILED` for products using this canonical; the v1-unreachability is structural.
+     */
+    v1_translatable?: unknown;
+    /**
+     * AdCP MAJOR.MINOR version that introduced this canonical (e.g., '3.1', '3.2'). Lets adopters reason about minimum protocol version requirements when consuming a format declaration. Patch precision is intentionally rejected — canonicals are introduced at minor-version boundaries.
+     */
+    since_version?: string;
+    /**
+     * AdCP MAJOR.MINOR version by which the working group expects this canonical to stabilize, surface a breaking revision, or (when `deprecated: true`) be removed. Patch precision is intentionally rejected — canonicals shift at minor-version boundaries. Absence signals 'no specific target' (omit the field rather than use a placeholder like 'unknown').
+     */
+    migration_target_version?: string;
+    /**
+     * Whether the surface composes deterministically (buyer can predict per-slot rendering — sponsored_placement, image, video) or algorithmically (surface chooses combinations or phrasing — responsive_creative, agent_placement).
+     */
+    composition_model?: 'deterministic' | 'algorithmic';
+    /**
+     * When true, the product rejects unsigned synthesized assets. Builders calling build_creative MUST attach a C2PA-compatible provenance manifest attributing synthesis to the creative agent.
+     */
+    provenance_required?: boolean;
+    /**
+     * Platform-specific extensions narrowing the canonical (pixel ID shapes, conversion event taxonomies, platform-specific CTAs/destinations). Each extension is a URI+digest reference resolved against the bundled `extensions` map in get_products responses or fetched directly.
+     *
+     * **Collision precedence (normative).** When two or more `platform_extensions[]` entries on the same declaration extend the same target (e.g., both extend `tracking`) with overlapping field names, **array order is authoritative — later entries override earlier ones on a per-field basis** (last-in-array-wins). SDKs MUST surface the overlap via the `errors[]` array on the `get_products` response with a structured code (`FORMAT_DECLARATION_DIVERGENT` is appropriate when the overlap appears across dual-emitted shapes; a producer-self-emitted overlap on a single declaration SHOULD use the same code with `error.details: { collision_kind: "platform_extension_field", target, overlapping_fields, winning_extension_uri }`). Producers SHOULD avoid the collision by emitting one extension per target or by partitioning fields across extensions; the deterministic precedence is for last-resort consistency across SDK implementations, not a sanctioned merging strategy.
+     */
+    platform_extensions?: PlatformExtensionReference[];
+    /**
+     * When true, the format's production pipeline is genuinely nondeterministic — the platform cannot guarantee that synthesis from a given input set produces in-spec output. Veo / Sora / Runway-class generative video, and other AI-synthesis flows where output dimensions, duration, or quality vary per run. Implies a different validation contract: predictive `validate_input` is impossible; the platform's own post-synthesis QA loop applies; if the QA loop exhausts without producing a valid artifact, `build_creative` returns task_failed with a synthesis_failed reason. Distinct from `composition_model` (which describes how the surface composes per-slot rendering, not whether synthesis is deterministic). When false or absent, the format's production is predictable enough that `validate_input` can predict output properties from input properties.
+     *
+     * **Compatibility with `asset_source` / `item_production_model`**: `synthesis_nondeterministic: true` MAY pair with any of `seller_pre_rendered_from_brief`, `seller_human_designed`, or `agent_synthesized` (the QA loop is concept-level, not source-specific — 'seller renders from brief but each retry differs' is just as nondeterministic as Veo). It MUST NOT pair with `buyer_uploaded` (the buyer ships pre-rendered bytes; there's no synthesis step to be nondeterministic about). It MUST NOT pair with `publisher_host_recorded` (the publisher's host produces a deterministic-from-script output even if the human voice varies). When `synthesis_nondeterministic: true` is set with an incompatible source, validators SHOULD reject with a structured error.
+     */
+    synthesis_nondeterministic?: boolean;
+    /**
+     * agent_placement has minimal buyer-shipped slots — the surface composes the rendered output from brand context (resolved via the manifest's top-level `brand` BrandRef) plus optional offering_ref and landing_page_url assets. None of these assets are rendered verbatim by the buyer; the agent chooses how to use them.
+     */
+    slots?: unknown;
+    /**
+     * Typical production turnaround in business days when the format requires seller-side production (e.g., host-recording from a buyer-supplied script). 0 for synchronous (e.g., generative AI); >0 for human-produced (e.g., podcast host-read). Absent when no production is required (buyer uploads complete creative).
+     */
+    production_window_business_days?: number;
+    /**
+     * How the surface presents the mention. `text` = inline text (chat, search snippet). `audio` = TTS-synthesized voice. `card` = structured card with optional image + text.
+     */
+    output_modality?: 'text' | 'audio' | 'card';
+    /**
+     * For text output: maximum length of the surface-composed mention text.
+     * @minimum 1
+     */
+    max_mention_length_chars?: number;
+    /**
+     * For audio output: maximum duration of the spoken mention in milliseconds.
+     * @minimum 1
+     */
+    max_mention_duration_ms?: number;
+    /**
+     * Whether the product accepts an offering reference (specific product/service to promote within the mention) in addition to brand context.
+     */
+    supports_offering_reference?: boolean;
+    /**
+     * Whether the surface attaches a landing page URL to the mention (citation, learn-more link).
+     */
+    supports_landing_page_url?: boolean;
+    /**
+     * **Advisory only.** Buyer-declared brand-voice preferences the surface SHOULD honor (e.g., ['formal', 'no_superlatives']). LLM/agentic surfaces have no protocol-level mechanism to verify enforcement — adopters that need hard guarantees should rely on brand.json voice declarations and post-mention review rather than this field. Future revisions may tie this to a structured tone vocabulary; for now treat as free-text guidance.
+     */
+    tone_constraints?: string[];
+    /**
+     * Whether the surface must include an explicit sponsorship disclosure label.
+     */
+    disclosure_required?: boolean;
+}
+
+/**
+ * DAAST-tag-delivered audio creative (audio analog of VAST). Slot: `daast_tag` (daast asset, URL or inline XML). Tracking model: DAAST events inherent to the spec — `impression`, `firstQuartile`, `midpoint`, `thirdQuartile`, `complete`, `start`, `pause`, `resume`, `mute`, `unmute`, `clickTracking`, `error`. Distinct from `audio_hosted` (direct file with external tracking).
+ */
+export interface CanonicalFormatDAASTAudio {
+    /**
+     * When true, this canonical (or a seller's specific narrowing of it) may not work as declared — adopters SHOULD have a v1 fallback ready and SHOULD NOT route production budget without testing. Same semantics as `experimental` on protocols: 'this is shipping but may break, evolve, or fail.' Buyers reading `experimental: true` SHOULD prefer the v1 path when a v1 fallback exists for the same product (via `format_ids` on the parent product or via the v2 declaration's `v1_format_ref`).
+     *
+     * Three drivers of `experimental: true`:
+     * 1. **Spec maturity** — the canonical's tracking model or parameter shape is still being settled (`agent_placement`'s tracking macros, `sponsored_placement`'s per-adapter contracts, `responsive_creative`'s algorithmic composition).
+     * 2. **Adopter runtime gap** — the seller has declared the canonical in their catalog but their runtime doesn't yet honor it cleanly.
+     * 3. **Custom shapes** — `format_kind: "custom"` is inherently experimental until the working group promotes a `format_shape` to a first-class canonical.
+     *
+     * Replaces the earlier `status` enum (`stable | preview | deprecated`) + `runtime_status` enum (`stable | preview | declared_only`) — two axes with subtle overlap. The single boolean is what buyers actually care about: do I treat this as production-stable or as 'try at my own risk.' Sellers SHOULD set `experimental: true` on canonicals or product declarations that aren't yet production-ready, regardless of which axis (spec, runtime, custom) drives the experimentation. The 6 IAB/VAST/DAAST re-encodings (`image`, `display_tag`, `video_hosted`, `video_vast`, `audio_hosted`, `audio_daast`) default to non-experimental at the canonical level; sellers MAY still mark a specific product declaration experimental (e.g., a beta runtime path for an existing product).
+     */
+    experimental?: boolean;
+    /**
+     * When true, this canonical (or a seller's specific narrowing of it) is going away. Existing adopters are supported through the deprecation cycle; new adoption is discouraged. Pair with `migration_target_version` to indicate when the canonical is expected to be removed. Distinct from `experimental`: an experimental canonical may stabilize and stop being experimental; a deprecated canonical is on a sunset path.
+     */
+    deprecated?: boolean;
+    /**
+     * Whether this canonical has any v1 named-format equivalent. `true` (default) — the canonical is structurally expressible as one or more v1 named formats (IAB display sizes, VAST tags, DAAST tags, etc.); v1→v2 projection via `v1-canonical-mapping.json` is meaningful. `false` — the canonical is inherently new in v2 and has no v1 form; v1's `list_creative_formats` couldn't express it because the underlying concept (algorithmic surface composition, AI-surface mentions, retail-media catalog placements, multi-card carousels) didn't exist as a v1 named-format archetype.
+     *
+     * Lets SDKs distinguish two failure modes that today look identical: (a) the registry hasn't covered this canonical yet (correctable — seller adds explicit `canonical` field or files a registry entry) vs (b) no v1 path is possible (informational — buyer needs v2-aware consumption, or seller declares `canonical_formats_only: true` on the product declaration). SDKs encountering `v1_translatable: false` on a canonical SHOULD NOT emit `FORMAT_PROJECTION_FAILED` (which signals registry-coverage gap) — instead surface the inherent v1-unreachability as a different diagnostic or skip silently. The 4 inherently-v2 canonicals at 3.1 GA: `image_carousel`, `sponsored_placement`, `responsive_creative`, `agent_placement`.
+     */
+    v1_translatable?: boolean;
+    /**
+     * AdCP MAJOR.MINOR version that introduced this canonical (e.g., '3.1', '3.2'). Lets adopters reason about minimum protocol version requirements when consuming a format declaration. Patch precision is intentionally rejected — canonicals are introduced at minor-version boundaries.
+     */
+    since_version?: string;
+    /**
+     * AdCP MAJOR.MINOR version by which the working group expects this canonical to stabilize, surface a breaking revision, or (when `deprecated: true`) be removed. Patch precision is intentionally rejected — canonicals shift at minor-version boundaries. Absence signals 'no specific target' (omit the field rather than use a placeholder like 'unknown').
+     */
+    migration_target_version?: string;
+    /**
+     * Whether the surface composes deterministically (buyer can predict per-slot rendering — sponsored_placement, image, video) or algorithmically (surface chooses combinations or phrasing — responsive_creative, agent_placement).
+     */
+    composition_model?: 'deterministic' | 'algorithmic';
+    /**
+     * When true, the product rejects unsigned synthesized assets. Builders calling build_creative MUST attach a C2PA-compatible provenance manifest attributing synthesis to the creative agent.
+     */
+    provenance_required?: boolean;
+    /**
+     * Platform-specific extensions narrowing the canonical (pixel ID shapes, conversion event taxonomies, platform-specific CTAs/destinations). Each extension is a URI+digest reference resolved against the bundled `extensions` map in get_products responses or fetched directly.
+     *
+     * **Collision precedence (normative).** When two or more `platform_extensions[]` entries on the same declaration extend the same target (e.g., both extend `tracking`) with overlapping field names, **array order is authoritative — later entries override earlier ones on a per-field basis** (last-in-array-wins). SDKs MUST surface the overlap via the `errors[]` array on the `get_products` response with a structured code (`FORMAT_DECLARATION_DIVERGENT` is appropriate when the overlap appears across dual-emitted shapes; a producer-self-emitted overlap on a single declaration SHOULD use the same code with `error.details: { collision_kind: "platform_extension_field", target, overlapping_fields, winning_extension_uri }`). Producers SHOULD avoid the collision by emitting one extension per target or by partitioning fields across extensions; the deterministic precedence is for last-resort consistency across SDK implementations, not a sanctioned merging strategy.
+     */
+    platform_extensions?: PlatformExtensionReference[];
+    /**
+     * When true, the format's production pipeline is genuinely nondeterministic — the platform cannot guarantee that synthesis from a given input set produces in-spec output. Veo / Sora / Runway-class generative video, and other AI-synthesis flows where output dimensions, duration, or quality vary per run. Implies a different validation contract: predictive `validate_input` is impossible; the platform's own post-synthesis QA loop applies; if the QA loop exhausts without producing a valid artifact, `build_creative` returns task_failed with a synthesis_failed reason. Distinct from `composition_model` (which describes how the surface composes per-slot rendering, not whether synthesis is deterministic). When false or absent, the format's production is predictable enough that `validate_input` can predict output properties from input properties.
+     *
+     * **Compatibility with `asset_source` / `item_production_model`**: `synthesis_nondeterministic: true` MAY pair with any of `seller_pre_rendered_from_brief`, `seller_human_designed`, or `agent_synthesized` (the QA loop is concept-level, not source-specific — 'seller renders from brief but each retry differs' is just as nondeterministic as Veo). It MUST NOT pair with `buyer_uploaded` (the buyer ships pre-rendered bytes; there's no synthesis step to be nondeterministic about). It MUST NOT pair with `publisher_host_recorded` (the publisher's host produces a deterministic-from-script output even if the human voice varies). When `synthesis_nondeterministic: true` is set with an incompatible source, validators SHOULD reject with a structured error.
+     */
+    synthesis_nondeterministic?: boolean;
+    /**
+     * Default slots for audio_daast canonical. Buyer ships a DAAST tag (URL or inline XML, 1.0 or 1.1) plus an optional clickthrough URL. Tracking events are inherent to DAAST and don't require explicit slots.
+     */
+    slots?: unknown;
+    /**
+     * Typical production turnaround in business days when the format requires seller-side production (e.g., host-recording from a buyer-supplied script). 0 for synchronous (e.g., generative AI); >0 for human-produced (e.g., podcast host-read). Absent when no production is required (buyer uploads complete creative).
+     */
+    production_window_business_days?: number;
+    daast_version?: '1.0' | '1.1';
+    /**
+     * [min, max] duration in milliseconds. **Precedence**: `duration_ms_exact` takes precedence when both ship. SDKs SHOULD lint a warning when both fields ship.
+     */
+    duration_ms_range?: number[];
+    /**
+     * When set, duration must equal exactly this value. Takes precedence over `duration_ms_range` when both ship.
+     * @minimum 1
+     */
+    duration_ms_exact?: number;
+    linear_required?: boolean;
+    /**
+     * @minimum 0
+     */
+    max_wrapper_depth?: number;
+    ssl_required?: boolean;
+    companion_image_required?: boolean;
+}
+
+/**
+ * Third-party-served display tag (JS, iframe, or 1×1 redirect). The buyer's adserver hosts the creative; the seller calls the tag URL at impression time. Slot: `tag_url` (url asset with appropriate `url_type`). Tracking model: opaque to seller — third party serves and measures. Click tracking via redirect URL substitution using universal_macros. Distinct from `image` (static asset hosted by seller) and `html5` (zip bundle hosted by seller).
+ */
+export type CanonicalFormatDisplayTag = SizeModeMutex & {
+    /**
+     * When true, this canonical (or a seller's specific narrowing of it) may not work as declared — adopters SHOULD have a v1 fallback ready and SHOULD NOT route production budget without testing. Same semantics as `experimental` on protocols: 'this is shipping but may break, evolve, or fail.' Buyers reading `experimental: true` SHOULD prefer the v1 path when a v1 fallback exists for the same product (via `format_ids` on the parent product or via the v2 declaration's `v1_format_ref`).
+     *
+     * Three drivers of `experimental: true`:
+     * 1. **Spec maturity** — the canonical's tracking model or parameter shape is still being settled (`agent_placement`'s tracking macros, `sponsored_placement`'s per-adapter contracts, `responsive_creative`'s algorithmic composition).
+     * 2. **Adopter runtime gap** — the seller has declared the canonical in their catalog but their runtime doesn't yet honor it cleanly.
+     * 3. **Custom shapes** — `format_kind: "custom"` is inherently experimental until the working group promotes a `format_shape` to a first-class canonical.
+     *
+     * Replaces the earlier `status` enum (`stable | preview | deprecated`) + `runtime_status` enum (`stable | preview | declared_only`) — two axes with subtle overlap. The single boolean is what buyers actually care about: do I treat this as production-stable or as 'try at my own risk.' Sellers SHOULD set `experimental: true` on canonicals or product declarations that aren't yet production-ready, regardless of which axis (spec, runtime, custom) drives the experimentation. The 6 IAB/VAST/DAAST re-encodings (`image`, `display_tag`, `video_hosted`, `video_vast`, `audio_hosted`, `audio_daast`) default to non-experimental at the canonical level; sellers MAY still mark a specific product declaration experimental (e.g., a beta runtime path for an existing product).
+     */
+    experimental?: boolean;
+    /**
+     * When true, this canonical (or a seller's specific narrowing of it) is going away. Existing adopters are supported through the deprecation cycle; new adoption is discouraged. Pair with `migration_target_version` to indicate when the canonical is expected to be removed. Distinct from `experimental`: an experimental canonical may stabilize and stop being experimental; a deprecated canonical is on a sunset path.
+     */
+    deprecated?: boolean;
+    /**
+     * Whether this canonical has any v1 named-format equivalent. `true` (default) — the canonical is structurally expressible as one or more v1 named formats (IAB display sizes, VAST tags, DAAST tags, etc.); v1→v2 projection via `v1-canonical-mapping.json` is meaningful. `false` — the canonical is inherently new in v2 and has no v1 form; v1's `list_creative_formats` couldn't express it because the underlying concept (algorithmic surface composition, AI-surface mentions, retail-media catalog placements, multi-card carousels) didn't exist as a v1 named-format archetype.
+     *
+     * Lets SDKs distinguish two failure modes that today look identical: (a) the registry hasn't covered this canonical yet (correctable — seller adds explicit `canonical` field or files a registry entry) vs (b) no v1 path is possible (informational — buyer needs v2-aware consumption, or seller declares `canonical_formats_only: true` on the product declaration). SDKs encountering `v1_translatable: false` on a canonical SHOULD NOT emit `FORMAT_PROJECTION_FAILED` (which signals registry-coverage gap) — instead surface the inherent v1-unreachability as a different diagnostic or skip silently. The 4 inherently-v2 canonicals at 3.1 GA: `image_carousel`, `sponsored_placement`, `responsive_creative`, `agent_placement`.
+     */
+    v1_translatable?: boolean;
+    /**
+     * AdCP MAJOR.MINOR version that introduced this canonical (e.g., '3.1', '3.2'). Lets adopters reason about minimum protocol version requirements when consuming a format declaration. Patch precision is intentionally rejected — canonicals are introduced at minor-version boundaries.
+     */
+    since_version?: string;
+    /**
+     * AdCP MAJOR.MINOR version by which the working group expects this canonical to stabilize, surface a breaking revision, or (when `deprecated: true`) be removed. Patch precision is intentionally rejected — canonicals shift at minor-version boundaries. Absence signals 'no specific target' (omit the field rather than use a placeholder like 'unknown').
+     */
+    migration_target_version?: string;
+    /**
+     * Whether the surface composes deterministically (buyer can predict per-slot rendering — sponsored_placement, image, video) or algorithmically (surface chooses combinations or phrasing — responsive_creative, agent_placement).
+     */
+    composition_model?: 'deterministic' | 'algorithmic';
+    /**
+     * When true, the product rejects unsigned synthesized assets. Builders calling build_creative MUST attach a C2PA-compatible provenance manifest attributing synthesis to the creative agent.
+     */
+    provenance_required?: boolean;
+    /**
+     * Platform-specific extensions narrowing the canonical (pixel ID shapes, conversion event taxonomies, platform-specific CTAs/destinations). Each extension is a URI+digest reference resolved against the bundled `extensions` map in get_products responses or fetched directly.
+     *
+     * **Collision precedence (normative).** When two or more `platform_extensions[]` entries on the same declaration extend the same target (e.g., both extend `tracking`) with overlapping field names, **array order is authoritative — later entries override earlier ones on a per-field basis** (last-in-array-wins). SDKs MUST surface the overlap via the `errors[]` array on the `get_products` response with a structured code (`FORMAT_DECLARATION_DIVERGENT` is appropriate when the overlap appears across dual-emitted shapes; a producer-self-emitted overlap on a single declaration SHOULD use the same code with `error.details: { collision_kind: "platform_extension_field", target, overlapping_fields, winning_extension_uri }`). Producers SHOULD avoid the collision by emitting one extension per target or by partitioning fields across extensions; the deterministic precedence is for last-resort consistency across SDK implementations, not a sanctioned merging strategy.
+     */
+    platform_extensions?: PlatformExtensionReference[];
+    /**
+     * When true, the format's production pipeline is genuinely nondeterministic — the platform cannot guarantee that synthesis from a given input set produces in-spec output. Veo / Sora / Runway-class generative video, and other AI-synthesis flows where output dimensions, duration, or quality vary per run. Implies a different validation contract: predictive `validate_input` is impossible; the platform's own post-synthesis QA loop applies; if the QA loop exhausts without producing a valid artifact, `build_creative` returns task_failed with a synthesis_failed reason. Distinct from `composition_model` (which describes how the surface composes per-slot rendering, not whether synthesis is deterministic). When false or absent, the format's production is predictable enough that `validate_input` can predict output properties from input properties.
+     *
+     * **Compatibility with `asset_source` / `item_production_model`**: `synthesis_nondeterministic: true` MAY pair with any of `seller_pre_rendered_from_brief`, `seller_human_designed`, or `agent_synthesized` (the QA loop is concept-level, not source-specific — 'seller renders from brief but each retry differs' is just as nondeterministic as Veo). It MUST NOT pair with `buyer_uploaded` (the buyer ships pre-rendered bytes; there's no synthesis step to be nondeterministic about). It MUST NOT pair with `publisher_host_recorded` (the publisher's host produces a deterministic-from-script output even if the human voice varies). When `synthesis_nondeterministic: true` is set with an incompatible source, validators SHOULD reject with a structured error.
+     */
+    synthesis_nondeterministic?: boolean;
+    /**
+     * Default slots for display_tag canonical. Buyer ships a URL pointing at the third-party-served creative (JS, iframe, or 1×1 redirect) plus an optional backup image. Click and impression macros are substituted into the tag URL by the seller using `universal_macros`.
+     */
+    slots?: unknown;
+    /**
+     * Typical production turnaround in business days when the format requires seller-side production (e.g., host-recording from a buyer-supplied script). 0 for synchronous (e.g., generative AI); >0 for human-produced (e.g., podcast host-read). Absent when no production is required (buyer uploads complete creative).
+     */
+    production_window_business_days?: number;
+    /**
+     * Required tag rendering width in pixels — use for fixed-size slots. For multi-size flexible slots use `sizes[]`; for responsive use `min_width`/`max_width`/`min_height`/`max_height`. Exactly one of `(width, height)`, `sizes[]`, or `min/max_width` + `min/max_height` ranges MUST be set.
+     * @minimum 1
+     */
+    width?: number;
+    /**
+     * Required tag rendering height in pixels. See `width` for size-mode mutual exclusion.
+     * @minimum 1
+     */
+    height?: number;
+    /**
+     * List of accepted (width, height) pairs for a multi-size flexible slot. The buyer's third-party tag must render at one of the listed sizes; the seller picks which size to request at impression time. Mutually exclusive with `(width, height)` and with responsive ranges.
+     */
+    sizes?: {
+        /**
+         * @minimum 1
+         */
+        width: number;
+        /**
+         * @minimum 1
+         */
+        height: number;
+    }[];
+    /**
+     * Minimum accepted width for responsive third-party tags. Pair with `max_width`. Mutually exclusive with `(width, height)` and `sizes[]`.
+     * @minimum 1
+     */
+    min_width?: number;
+    /**
+     * Maximum accepted width for responsive third-party tags. Pair with `min_width`.
+     * @minimum 1
+     */
+    max_width?: number;
+    /**
+     * Minimum accepted height for responsive third-party tags. Pair with `max_height`.
+     * @minimum 1
+     */
+    min_height?: number;
+    /**
+     * Maximum accepted height for responsive third-party tags. Pair with `min_height`.
+     * @minimum 1
+     */
+    max_height?: number;
+    /**
+     * Tag delivery mechanisms accepted.
+     */
+    supported_tag_types?: ('iframe' | 'javascript' | '1x1_redirect')[];
+    /**
+     * Whether the tag URL must be HTTPS.
+     */
+    ssl_required?: boolean;
+    /**
+     * Maximum redirect chain depth permitted.
+     * @minimum 0
+     */
+    max_redirect_depth?: number;
+    /**
+     * Maximum tag-server response time in milliseconds.
+     * @minimum 1
+     */
+    max_response_time_ms?: number;
+    /**
+     * Whether a backup image must accompany the tag for environments that cannot render the third-party tag.
+     */
+    backup_image_required?: boolean;
+    /**
+     * @minimum 1
+     */
+    backup_image_max_size_kb?: number;
+    /**
+     * Whether the buyer's tag must integrate IAB Open Measurement SDK for viewability.
+     */
+    om_sdk_required?: boolean;
+};
+
+/**
+ * Interactive HTML5 banner delivered as a zip archive. Slot: `html5_bundle` (zip asset). Tracking model: MRAID + IAB Open Measurement (OM-SDK) + click-tag macro substitution + backup image fallback. Receivers unpack the zip, validate internal structure, and serve from CDN. Distinct from `image` (static, non-interactive) and `display_tag` (third-party served). The zip's entry point is typically `index.html`; click handling uses `clickTag` (or `clickTAG`) macro substitution.
+ */
+export type CanonicalFormatHTML5Banner = SizeModeMutex & {
+    /**
+     * When true, this canonical (or a seller's specific narrowing of it) may not work as declared — adopters SHOULD have a v1 fallback ready and SHOULD NOT route production budget without testing. Same semantics as `experimental` on protocols: 'this is shipping but may break, evolve, or fail.' Buyers reading `experimental: true` SHOULD prefer the v1 path when a v1 fallback exists for the same product (via `format_ids` on the parent product or via the v2 declaration's `v1_format_ref`).
+     *
+     * Three drivers of `experimental: true`:
+     * 1. **Spec maturity** — the canonical's tracking model or parameter shape is still being settled (`agent_placement`'s tracking macros, `sponsored_placement`'s per-adapter contracts, `responsive_creative`'s algorithmic composition).
+     * 2. **Adopter runtime gap** — the seller has declared the canonical in their catalog but their runtime doesn't yet honor it cleanly.
+     * 3. **Custom shapes** — `format_kind: "custom"` is inherently experimental until the working group promotes a `format_shape` to a first-class canonical.
+     *
+     * Replaces the earlier `status` enum (`stable | preview | deprecated`) + `runtime_status` enum (`stable | preview | declared_only`) — two axes with subtle overlap. The single boolean is what buyers actually care about: do I treat this as production-stable or as 'try at my own risk.' Sellers SHOULD set `experimental: true` on canonicals or product declarations that aren't yet production-ready, regardless of which axis (spec, runtime, custom) drives the experimentation. The 6 IAB/VAST/DAAST re-encodings (`image`, `display_tag`, `video_hosted`, `video_vast`, `audio_hosted`, `audio_daast`) default to non-experimental at the canonical level; sellers MAY still mark a specific product declaration experimental (e.g., a beta runtime path for an existing product).
+     */
+    experimental?: boolean;
+    /**
+     * When true, this canonical (or a seller's specific narrowing of it) is going away. Existing adopters are supported through the deprecation cycle; new adoption is discouraged. Pair with `migration_target_version` to indicate when the canonical is expected to be removed. Distinct from `experimental`: an experimental canonical may stabilize and stop being experimental; a deprecated canonical is on a sunset path.
+     */
+    deprecated?: boolean;
+    /**
+     * Whether this canonical has any v1 named-format equivalent. `true` (default) — the canonical is structurally expressible as one or more v1 named formats (IAB display sizes, VAST tags, DAAST tags, etc.); v1→v2 projection via `v1-canonical-mapping.json` is meaningful. `false` — the canonical is inherently new in v2 and has no v1 form; v1's `list_creative_formats` couldn't express it because the underlying concept (algorithmic surface composition, AI-surface mentions, retail-media catalog placements, multi-card carousels) didn't exist as a v1 named-format archetype.
+     *
+     * Lets SDKs distinguish two failure modes that today look identical: (a) the registry hasn't covered this canonical yet (correctable — seller adds explicit `canonical` field or files a registry entry) vs (b) no v1 path is possible (informational — buyer needs v2-aware consumption, or seller declares `canonical_formats_only: true` on the product declaration). SDKs encountering `v1_translatable: false` on a canonical SHOULD NOT emit `FORMAT_PROJECTION_FAILED` (which signals registry-coverage gap) — instead surface the inherent v1-unreachability as a different diagnostic or skip silently. The 4 inherently-v2 canonicals at 3.1 GA: `image_carousel`, `sponsored_placement`, `responsive_creative`, `agent_placement`.
+     */
+    v1_translatable?: boolean;
+    /**
+     * AdCP MAJOR.MINOR version that introduced this canonical (e.g., '3.1', '3.2'). Lets adopters reason about minimum protocol version requirements when consuming a format declaration. Patch precision is intentionally rejected — canonicals are introduced at minor-version boundaries.
+     */
+    since_version?: string;
+    /**
+     * AdCP MAJOR.MINOR version by which the working group expects this canonical to stabilize, surface a breaking revision, or (when `deprecated: true`) be removed. Patch precision is intentionally rejected — canonicals shift at minor-version boundaries. Absence signals 'no specific target' (omit the field rather than use a placeholder like 'unknown').
+     */
+    migration_target_version?: string;
+    /**
+     * Whether the surface composes deterministically (buyer can predict per-slot rendering — sponsored_placement, image, video) or algorithmically (surface chooses combinations or phrasing — responsive_creative, agent_placement).
+     */
+    composition_model?: 'deterministic' | 'algorithmic';
+    /**
+     * When true, the product rejects unsigned synthesized assets. Builders calling build_creative MUST attach a C2PA-compatible provenance manifest attributing synthesis to the creative agent.
+     */
+    provenance_required?: boolean;
+    /**
+     * Platform-specific extensions narrowing the canonical (pixel ID shapes, conversion event taxonomies, platform-specific CTAs/destinations). Each extension is a URI+digest reference resolved against the bundled `extensions` map in get_products responses or fetched directly.
+     *
+     * **Collision precedence (normative).** When two or more `platform_extensions[]` entries on the same declaration extend the same target (e.g., both extend `tracking`) with overlapping field names, **array order is authoritative — later entries override earlier ones on a per-field basis** (last-in-array-wins). SDKs MUST surface the overlap via the `errors[]` array on the `get_products` response with a structured code (`FORMAT_DECLARATION_DIVERGENT` is appropriate when the overlap appears across dual-emitted shapes; a producer-self-emitted overlap on a single declaration SHOULD use the same code with `error.details: { collision_kind: "platform_extension_field", target, overlapping_fields, winning_extension_uri }`). Producers SHOULD avoid the collision by emitting one extension per target or by partitioning fields across extensions; the deterministic precedence is for last-resort consistency across SDK implementations, not a sanctioned merging strategy.
+     */
+    platform_extensions?: PlatformExtensionReference[];
+    /**
+     * When true, the format's production pipeline is genuinely nondeterministic — the platform cannot guarantee that synthesis from a given input set produces in-spec output. Veo / Sora / Runway-class generative video, and other AI-synthesis flows where output dimensions, duration, or quality vary per run. Implies a different validation contract: predictive `validate_input` is impossible; the platform's own post-synthesis QA loop applies; if the QA loop exhausts without producing a valid artifact, `build_creative` returns task_failed with a synthesis_failed reason. Distinct from `composition_model` (which describes how the surface composes per-slot rendering, not whether synthesis is deterministic). When false or absent, the format's production is predictable enough that `validate_input` can predict output properties from input properties.
+     *
+     * **Compatibility with `asset_source` / `item_production_model`**: `synthesis_nondeterministic: true` MAY pair with any of `seller_pre_rendered_from_brief`, `seller_human_designed`, or `agent_synthesized` (the QA loop is concept-level, not source-specific — 'seller renders from brief but each retry differs' is just as nondeterministic as Veo). It MUST NOT pair with `buyer_uploaded` (the buyer ships pre-rendered bytes; there's no synthesis step to be nondeterministic about). It MUST NOT pair with `publisher_host_recorded` (the publisher's host produces a deterministic-from-script output even if the human voice varies). When `synthesis_nondeterministic: true` is set with an incompatible source, validators SHOULD reject with a structured error.
+     */
+    synthesis_nondeterministic?: boolean;
+    /**
+     * Default slots for html5 canonical. Buyer ships a zip bundle plus optional backup image (required when `backup_image_required: true`) and clickthrough URL. The zip's entry point is typically `index.html`; click handling uses the `clickTag` (or `clickTAG`) macro substituted by the seller at serve time.
+     */
+    slots?: unknown;
+    /**
+     * Typical production turnaround in business days when the format requires seller-side production (e.g., host-recording from a buyer-supplied script). 0 for synchronous (e.g., generative AI); >0 for human-produced (e.g., podcast host-read). Absent when no production is required (buyer uploads complete creative).
+     */
+    production_window_business_days?: number;
+    /**
+     * Required banner width in pixels — use for fixed-size slots. For multi-size flexible slots use `sizes[]`; for responsive use `min_width`/`max_width`/`min_height`/`max_height`. Exactly one of `(width, height)`, `sizes[]`, or `min/max_width` + `min/max_height` ranges MUST be set.
+     * @minimum 1
+     */
+    width?: number;
+    /**
+     * Required banner height in pixels. See `width` for size-mode mutual exclusion.
+     * @minimum 1
+     */
+    height?: number;
+    /**
+     * List of accepted (width, height) pairs for a multi-size flexible slot (publisher banner that accepts 300×250 OR 728×90 OR 970×250). Mirrors OpenRTB `banner.format[]`. Mutually exclusive with `(width, height)` and with responsive ranges.
+     */
+    sizes?: {
+        /**
+         * @minimum 1
+         */
+        width: number;
+        /**
+         * @minimum 1
+         */
+        height: number;
+    }[];
+    /**
+     * Minimum accepted width for responsive HTML5 banners that adapt within a range. Pair with `max_width`. Mutually exclusive with `(width, height)` and `sizes[]`.
+     * @minimum 1
+     */
+    min_width?: number;
+    /**
+     * Maximum accepted width for responsive HTML5 banners. Pair with `min_width`.
+     * @minimum 1
+     */
+    max_width?: number;
+    /**
+     * Minimum accepted height for responsive HTML5 banners. Pair with `max_height`.
+     * @minimum 1
+     */
+    min_height?: number;
+    /**
+     * Maximum accepted height for responsive HTML5 banners. Pair with `min_height`.
+     * @minimum 1
+     */
+    max_height?: number;
+    /**
+     * Maximum initial-load file size (zip + above-the-fold assets) in kilobytes. IAB display standards: 200 KB for fixed sizes, 100 KB for mobile.
+     * @minimum 1
+     */
+    max_initial_load_kb?: number;
+    /**
+     * Maximum polite-load file size after host-initiated subload, in kilobytes. IAB display standards: 500 KB for fixed sizes.
+     * @minimum 1
+     */
+    max_polite_load_kb?: number;
+    /**
+     * Whether the host page must initiate the polite-load phase. IAB-compliant banners require true.
+     */
+    host_initiated_subload?: boolean;
+    /**
+     * Maximum total animation duration in milliseconds. IAB standard: 30000 (30 seconds).
+     * @minimum 0
+     */
+    max_animation_duration_ms?: number;
+    /**
+     * Maximum CPU load percentage during render.
+     * @minimum 1
+     * @maximum 100
+     */
+    max_cpu_load_percent?: number;
+    /**
+     * Whether MRAID compatibility is required (mobile in-app).
+     */
+    mraid_required?: boolean;
+    /**
+     * Required MRAID version when mraid_required is true.
+     */
+    mraid_version?: '2.0' | '3.0';
+    /**
+     * Whether IAB Open Measurement SDK integration is required.
+     */
+    om_sdk_required?: boolean;
+    /**
+     * Name of the click-tag macro the bundle must use.
+     */
+    clicktag_macro?: 'clickTag' | 'clickTAG';
+    /**
+     * Whether a backup image must accompany the zip for non-HTML5 environments.
+     */
+    backup_image_required?: boolean;
+    /**
+     * Maximum backup image file size in kilobytes.
+     * @minimum 1
+     */
+    backup_image_max_size_kb?: number;
+    ssl_required?: boolean;
+};
+
+/**
+ * Direct audio creative — buyer ships an `audio` asset (mp3/aac/wav) for asset-driven products, or ships a `script` / `creative_brief` text asset for products where the seller produces audio internally (podcast host-reads, TTS synthesis). Optional companion slots: `companion_image`, `brand_name`, `landing_page_url`. Tracking model: standard impression + completion + companion-image-click pixels via universal_macros. Distinct from `audio_daast` (DAAST tag, inherent DAAST event tracking). For host-reads and synthesized audio, the format declares `asset_source: 'publisher_host_recorded'` or `'agent_synthesized'` plus `buyer_asset_acceptance: 'rejected'`; the format's `slots` declaration enumerates which assets the buyer ships (e.g., `script` text asset for host-reads). The seller decides how to consume each asset (render verbatim vs produce audio from text) — there is no separate manifest 'inputs' map; everything the buyer ships goes in `assets`.
+ */
+export interface CanonicalFormatHostedAudio {
+    /**
+     * When true, this canonical (or a seller's specific narrowing of it) may not work as declared — adopters SHOULD have a v1 fallback ready and SHOULD NOT route production budget without testing. Same semantics as `experimental` on protocols: 'this is shipping but may break, evolve, or fail.' Buyers reading `experimental: true` SHOULD prefer the v1 path when a v1 fallback exists for the same product (via `format_ids` on the parent product or via the v2 declaration's `v1_format_ref`).
+     *
+     * Three drivers of `experimental: true`:
+     * 1. **Spec maturity** — the canonical's tracking model or parameter shape is still being settled (`agent_placement`'s tracking macros, `sponsored_placement`'s per-adapter contracts, `responsive_creative`'s algorithmic composition).
+     * 2. **Adopter runtime gap** — the seller has declared the canonical in their catalog but their runtime doesn't yet honor it cleanly.
+     * 3. **Custom shapes** — `format_kind: "custom"` is inherently experimental until the working group promotes a `format_shape` to a first-class canonical.
+     *
+     * Replaces the earlier `status` enum (`stable | preview | deprecated`) + `runtime_status` enum (`stable | preview | declared_only`) — two axes with subtle overlap. The single boolean is what buyers actually care about: do I treat this as production-stable or as 'try at my own risk.' Sellers SHOULD set `experimental: true` on canonicals or product declarations that aren't yet production-ready, regardless of which axis (spec, runtime, custom) drives the experimentation. The 6 IAB/VAST/DAAST re-encodings (`image`, `display_tag`, `video_hosted`, `video_vast`, `audio_hosted`, `audio_daast`) default to non-experimental at the canonical level; sellers MAY still mark a specific product declaration experimental (e.g., a beta runtime path for an existing product).
+     */
+    experimental?: boolean;
+    /**
+     * When true, this canonical (or a seller's specific narrowing of it) is going away. Existing adopters are supported through the deprecation cycle; new adoption is discouraged. Pair with `migration_target_version` to indicate when the canonical is expected to be removed. Distinct from `experimental`: an experimental canonical may stabilize and stop being experimental; a deprecated canonical is on a sunset path.
+     */
+    deprecated?: boolean;
+    /**
+     * Whether this canonical has any v1 named-format equivalent. `true` (default) — the canonical is structurally expressible as one or more v1 named formats (IAB display sizes, VAST tags, DAAST tags, etc.); v1→v2 projection via `v1-canonical-mapping.json` is meaningful. `false` — the canonical is inherently new in v2 and has no v1 form; v1's `list_creative_formats` couldn't express it because the underlying concept (algorithmic surface composition, AI-surface mentions, retail-media catalog placements, multi-card carousels) didn't exist as a v1 named-format archetype.
+     *
+     * Lets SDKs distinguish two failure modes that today look identical: (a) the registry hasn't covered this canonical yet (correctable — seller adds explicit `canonical` field or files a registry entry) vs (b) no v1 path is possible (informational — buyer needs v2-aware consumption, or seller declares `canonical_formats_only: true` on the product declaration). SDKs encountering `v1_translatable: false` on a canonical SHOULD NOT emit `FORMAT_PROJECTION_FAILED` (which signals registry-coverage gap) — instead surface the inherent v1-unreachability as a different diagnostic or skip silently. The 4 inherently-v2 canonicals at 3.1 GA: `image_carousel`, `sponsored_placement`, `responsive_creative`, `agent_placement`.
+     */
+    v1_translatable?: boolean;
+    /**
+     * AdCP MAJOR.MINOR version that introduced this canonical (e.g., '3.1', '3.2'). Lets adopters reason about minimum protocol version requirements when consuming a format declaration. Patch precision is intentionally rejected — canonicals are introduced at minor-version boundaries.
+     */
+    since_version?: string;
+    /**
+     * AdCP MAJOR.MINOR version by which the working group expects this canonical to stabilize, surface a breaking revision, or (when `deprecated: true`) be removed. Patch precision is intentionally rejected — canonicals shift at minor-version boundaries. Absence signals 'no specific target' (omit the field rather than use a placeholder like 'unknown').
+     */
+    migration_target_version?: string;
+    /**
+     * Whether the surface composes deterministically (buyer can predict per-slot rendering — sponsored_placement, image, video) or algorithmically (surface chooses combinations or phrasing — responsive_creative, agent_placement).
+     */
+    composition_model?: 'deterministic' | 'algorithmic';
+    /**
+     * When true, the product rejects unsigned synthesized assets. Builders calling build_creative MUST attach a C2PA-compatible provenance manifest attributing synthesis to the creative agent.
+     */
+    provenance_required?: boolean;
+    /**
+     * Platform-specific extensions narrowing the canonical (pixel ID shapes, conversion event taxonomies, platform-specific CTAs/destinations). Each extension is a URI+digest reference resolved against the bundled `extensions` map in get_products responses or fetched directly.
+     *
+     * **Collision precedence (normative).** When two or more `platform_extensions[]` entries on the same declaration extend the same target (e.g., both extend `tracking`) with overlapping field names, **array order is authoritative — later entries override earlier ones on a per-field basis** (last-in-array-wins). SDKs MUST surface the overlap via the `errors[]` array on the `get_products` response with a structured code (`FORMAT_DECLARATION_DIVERGENT` is appropriate when the overlap appears across dual-emitted shapes; a producer-self-emitted overlap on a single declaration SHOULD use the same code with `error.details: { collision_kind: "platform_extension_field", target, overlapping_fields, winning_extension_uri }`). Producers SHOULD avoid the collision by emitting one extension per target or by partitioning fields across extensions; the deterministic precedence is for last-resort consistency across SDK implementations, not a sanctioned merging strategy.
+     */
+    platform_extensions?: PlatformExtensionReference[];
+    /**
+     * When true, the format's production pipeline is genuinely nondeterministic — the platform cannot guarantee that synthesis from a given input set produces in-spec output. Veo / Sora / Runway-class generative video, and other AI-synthesis flows where output dimensions, duration, or quality vary per run. Implies a different validation contract: predictive `validate_input` is impossible; the platform's own post-synthesis QA loop applies; if the QA loop exhausts without producing a valid artifact, `build_creative` returns task_failed with a synthesis_failed reason. Distinct from `composition_model` (which describes how the surface composes per-slot rendering, not whether synthesis is deterministic). When false or absent, the format's production is predictable enough that `validate_input` can predict output properties from input properties.
+     *
+     * **Compatibility with `asset_source` / `item_production_model`**: `synthesis_nondeterministic: true` MAY pair with any of `seller_pre_rendered_from_brief`, `seller_human_designed`, or `agent_synthesized` (the QA loop is concept-level, not source-specific — 'seller renders from brief but each retry differs' is just as nondeterministic as Veo). It MUST NOT pair with `buyer_uploaded` (the buyer ships pre-rendered bytes; there's no synthesis step to be nondeterministic about). It MUST NOT pair with `publisher_host_recorded` (the publisher's host produces a deterministic-from-script output even if the human voice varies). When `synthesis_nondeterministic: true` is set with an incompatible source, validators SHOULD reject with a structured error.
+     */
+    synthesis_nondeterministic?: boolean;
+    /**
+     * Default slots for buyer-uploaded audio. Host-read products override with a `script` (asset_type: text) or `creative_brief` (asset_type: brief) slot in place of `audio_main`, plus `asset_source: 'publisher_host_recorded'` and `buyer_asset_acceptance: 'rejected'`. TTS-from-script products override similarly with `asset_source: 'seller_pre_rendered_from_brief'`.
+     */
+    slots?: unknown;
+    /**
+     * Typical production turnaround in business days when the format requires seller-side production (e.g., host-recording from a buyer-supplied script). 0 for synchronous (e.g., generative AI); >0 for human-produced (e.g., podcast host-read). Absent when no production is required (buyer uploads complete creative).
+     */
+    production_window_business_days?: number;
+    /**
+     * [min, max] duration in milliseconds. **Precedence**: `duration_ms_exact` takes precedence when both ship on the same product. SDKs SHOULD lint a warning when both fields ship.
+     */
+    duration_ms_range?: number[];
+    /**
+     * When set, duration must equal exactly this value. Takes precedence over `duration_ms_range` when both ship.
+     * @minimum 1
+     */
+    duration_ms_exact?: number;
+    audio_codecs?: ('mp3' | 'aac' | 'wav' | 'opus' | 'flac')[];
+    audio_sample_rates?: number[];
+    audio_channels?: ('mono' | 'stereo')[];
+    /**
+     * @minimum 1
+     */
+    min_bitrate_kbps?: number;
+    /**
+     * @minimum 1
+     */
+    max_bitrate_kbps?: number;
+    /**
+     * Required integrated loudness in LUFS (typical: -16 for streaming/podcast, -23 for broadcast). Negative values.
+     */
+    loudness_lufs?: number;
+    /**
+     * Permitted deviation from loudness_lufs in dB.
+     * @minimum 0
+     */
+    loudness_tolerance_db?: number;
+    /**
+     * Maximum true-peak level in dBFS (typical: -2).
+     */
+    true_peak_dbfs?: number;
+    /**
+     * Where the rendered audio bytes come from. Single shared enum across canonicals (see `image.json#asset_source` for the full semantics). `publisher_host_recorded`: the publisher's host records the audio (podcast host-read pattern); buyer must use the publisher's build_creative capability. This value is audio-specific.
+     */
+    asset_source?: 'buyer_uploaded' | 'publisher_host_recorded' | 'seller_pre_rendered_from_brief' | 'seller_human_designed' | 'agent_synthesized';
+    /**
+     * Whether the product accepts buyer-uploaded audio. When `rejected`, the buyer cannot ship an audio asset directly — they must use build_creative (or sync_creatives with brief inputs) so the seller produces the audio. Combined with `asset_source`, lets a product declare 'I produce audio from briefs and refuse buyer uploads' (asset_source=`seller_pre_rendered_from_brief`, buyer_asset_acceptance=`rejected`).
+     */
+    buyer_asset_acceptance?: 'accepted' | 'rejected';
+    companion_image_required?: boolean;
+    companion_image_aspect_ratio?: string;
+    /**
+     * @minimum 1
+     */
+    companion_image_max_file_size_kb?: number;
+    /**
+     * @minimum 1
+     */
+    brand_name_max_chars?: number;
+}
+
+/**
+ * Direct video file (mp4/webm/mov) hosted by the buyer. Slot: `video_main` (video asset, file or hosted URL), optional `headline`, `brand_name`, `cta`, `companion_banner`, `landing_page_url`. Tracking model: IAB Open Measurement SDK + external impression/click/quartile pixels via universal_macros. Orientation is a parameter (vertical 9:16 / horizontal 16:9 / square 1:1); slot shape includes optional `brand_name` (typical for vertical short-form) and optional `companion_banner` (typical for horizontal instream). Distinct from `video_vast` (VAST tag, inherent VAST event tracking) — receivers fire impression and click pixels at delivery time.
+ */
+export interface CanonicalFormatHostedVideo {
+    /**
+     * When true, this canonical (or a seller's specific narrowing of it) may not work as declared — adopters SHOULD have a v1 fallback ready and SHOULD NOT route production budget without testing. Same semantics as `experimental` on protocols: 'this is shipping but may break, evolve, or fail.' Buyers reading `experimental: true` SHOULD prefer the v1 path when a v1 fallback exists for the same product (via `format_ids` on the parent product or via the v2 declaration's `v1_format_ref`).
+     *
+     * Three drivers of `experimental: true`:
+     * 1. **Spec maturity** — the canonical's tracking model or parameter shape is still being settled (`agent_placement`'s tracking macros, `sponsored_placement`'s per-adapter contracts, `responsive_creative`'s algorithmic composition).
+     * 2. **Adopter runtime gap** — the seller has declared the canonical in their catalog but their runtime doesn't yet honor it cleanly.
+     * 3. **Custom shapes** — `format_kind: "custom"` is inherently experimental until the working group promotes a `format_shape` to a first-class canonical.
+     *
+     * Replaces the earlier `status` enum (`stable | preview | deprecated`) + `runtime_status` enum (`stable | preview | declared_only`) — two axes with subtle overlap. The single boolean is what buyers actually care about: do I treat this as production-stable or as 'try at my own risk.' Sellers SHOULD set `experimental: true` on canonicals or product declarations that aren't yet production-ready, regardless of which axis (spec, runtime, custom) drives the experimentation. The 6 IAB/VAST/DAAST re-encodings (`image`, `display_tag`, `video_hosted`, `video_vast`, `audio_hosted`, `audio_daast`) default to non-experimental at the canonical level; sellers MAY still mark a specific product declaration experimental (e.g., a beta runtime path for an existing product).
+     */
+    experimental?: boolean;
+    /**
+     * When true, this canonical (or a seller's specific narrowing of it) is going away. Existing adopters are supported through the deprecation cycle; new adoption is discouraged. Pair with `migration_target_version` to indicate when the canonical is expected to be removed. Distinct from `experimental`: an experimental canonical may stabilize and stop being experimental; a deprecated canonical is on a sunset path.
+     */
+    deprecated?: boolean;
+    /**
+     * Whether this canonical has any v1 named-format equivalent. `true` (default) — the canonical is structurally expressible as one or more v1 named formats (IAB display sizes, VAST tags, DAAST tags, etc.); v1→v2 projection via `v1-canonical-mapping.json` is meaningful. `false` — the canonical is inherently new in v2 and has no v1 form; v1's `list_creative_formats` couldn't express it because the underlying concept (algorithmic surface composition, AI-surface mentions, retail-media catalog placements, multi-card carousels) didn't exist as a v1 named-format archetype.
+     *
+     * Lets SDKs distinguish two failure modes that today look identical: (a) the registry hasn't covered this canonical yet (correctable — seller adds explicit `canonical` field or files a registry entry) vs (b) no v1 path is possible (informational — buyer needs v2-aware consumption, or seller declares `canonical_formats_only: true` on the product declaration). SDKs encountering `v1_translatable: false` on a canonical SHOULD NOT emit `FORMAT_PROJECTION_FAILED` (which signals registry-coverage gap) — instead surface the inherent v1-unreachability as a different diagnostic or skip silently. The 4 inherently-v2 canonicals at 3.1 GA: `image_carousel`, `sponsored_placement`, `responsive_creative`, `agent_placement`.
+     */
+    v1_translatable?: boolean;
+    /**
+     * AdCP MAJOR.MINOR version that introduced this canonical (e.g., '3.1', '3.2'). Lets adopters reason about minimum protocol version requirements when consuming a format declaration. Patch precision is intentionally rejected — canonicals are introduced at minor-version boundaries.
+     */
+    since_version?: string;
+    /**
+     * AdCP MAJOR.MINOR version by which the working group expects this canonical to stabilize, surface a breaking revision, or (when `deprecated: true`) be removed. Patch precision is intentionally rejected — canonicals shift at minor-version boundaries. Absence signals 'no specific target' (omit the field rather than use a placeholder like 'unknown').
+     */
+    migration_target_version?: string;
+    /**
+     * Whether the surface composes deterministically (buyer can predict per-slot rendering — sponsored_placement, image, video) or algorithmically (surface chooses combinations or phrasing — responsive_creative, agent_placement).
+     */
+    composition_model?: 'deterministic' | 'algorithmic';
+    /**
+     * When true, the product rejects unsigned synthesized assets. Builders calling build_creative MUST attach a C2PA-compatible provenance manifest attributing synthesis to the creative agent.
+     */
+    provenance_required?: boolean;
+    /**
+     * Platform-specific extensions narrowing the canonical (pixel ID shapes, conversion event taxonomies, platform-specific CTAs/destinations). Each extension is a URI+digest reference resolved against the bundled `extensions` map in get_products responses or fetched directly.
+     *
+     * **Collision precedence (normative).** When two or more `platform_extensions[]` entries on the same declaration extend the same target (e.g., both extend `tracking`) with overlapping field names, **array order is authoritative — later entries override earlier ones on a per-field basis** (last-in-array-wins). SDKs MUST surface the overlap via the `errors[]` array on the `get_products` response with a structured code (`FORMAT_DECLARATION_DIVERGENT` is appropriate when the overlap appears across dual-emitted shapes; a producer-self-emitted overlap on a single declaration SHOULD use the same code with `error.details: { collision_kind: "platform_extension_field", target, overlapping_fields, winning_extension_uri }`). Producers SHOULD avoid the collision by emitting one extension per target or by partitioning fields across extensions; the deterministic precedence is for last-resort consistency across SDK implementations, not a sanctioned merging strategy.
+     */
+    platform_extensions?: PlatformExtensionReference[];
+    /**
+     * When true, the format's production pipeline is genuinely nondeterministic — the platform cannot guarantee that synthesis from a given input set produces in-spec output. Veo / Sora / Runway-class generative video, and other AI-synthesis flows where output dimensions, duration, or quality vary per run. Implies a different validation contract: predictive `validate_input` is impossible; the platform's own post-synthesis QA loop applies; if the QA loop exhausts without producing a valid artifact, `build_creative` returns task_failed with a synthesis_failed reason. Distinct from `composition_model` (which describes how the surface composes per-slot rendering, not whether synthesis is deterministic). When false or absent, the format's production is predictable enough that `validate_input` can predict output properties from input properties.
+     *
+     * **Compatibility with `asset_source` / `item_production_model`**: `synthesis_nondeterministic: true` MAY pair with any of `seller_pre_rendered_from_brief`, `seller_human_designed`, or `agent_synthesized` (the QA loop is concept-level, not source-specific — 'seller renders from brief but each retry differs' is just as nondeterministic as Veo). It MUST NOT pair with `buyer_uploaded` (the buyer ships pre-rendered bytes; there's no synthesis step to be nondeterministic about). It MUST NOT pair with `publisher_host_recorded` (the publisher's host produces a deterministic-from-script output even if the human voice varies). When `synthesis_nondeterministic: true` is set with an incompatible source, validators SHOULD reject with a structured error.
+     */
+    synthesis_nondeterministic?: boolean;
+    /**
+     * Default slots for video_hosted canonical. Buyer ships a video asset (file or hosted URL); optional headline, primary text (long-form caption), CTA (typically constrained via `cta_values`), brand_name (typical for vertical short-form), companion_banner (typical for horizontal instream), and clickthrough URL. Products MAY override or extend the default — e.g., remove `companion_banner` for short-form vertical, narrow `cta` to a value enum, mark `landing_page_url` as required.
+     */
+    slots?: unknown;
+    /**
+     * Typical production turnaround in business days when the format requires seller-side production (e.g., host-recording from a buyer-supplied script). 0 for synchronous (e.g., generative AI); >0 for human-produced (e.g., podcast host-read). Absent when no production is required (buyer uploads complete creative).
+     */
+    production_window_business_days?: number;
+    /**
+     * Video orientation. Vertical = 9:16 (Reels, Stories, Shorts). Horizontal = 16:9 (instream, CTV). Square = 1:1 (in-feed).
+     */
+    orientation?: 'vertical' | 'horizontal' | 'square';
+    /**
+     * Aspect ratio. Inferred from orientation if omitted.
+     * @pattern ^[0-9]+(\.[0-9]+)?:[0-9]+(\.[0-9]+)?$
+     */
+    aspect_ratio?: string;
+    /**
+     * @minimum 1
+     */
+    min_width?: number;
+    /**
+     * @minimum 1
+     */
+    min_height?: number;
+    /**
+     * @minimum 1
+     */
+    max_width?: number;
+    /**
+     * @minimum 1
+     */
+    max_height?: number;
+    /**
+     * [min, max] duration in milliseconds. **Precedence**: when both `duration_ms_exact` and `duration_ms_range` ship on the same product, `duration_ms_exact` takes precedence — buyers MUST validate against the exact value and ignore the range. The range is treated as advisory metadata in that case (e.g., for UI display showing the broader product family). SDKs SHOULD lint a warning when both fields ship; producers SHOULD pick one.
+     */
+    duration_ms_range?: number[];
+    /**
+     * When set, duration must equal exactly this value. Takes precedence over `duration_ms_range` when both ship (see `duration_ms_range` description).
+     * @minimum 1
+     */
+    duration_ms_exact?: number;
+    video_codecs?: ('h264' | 'h265' | 'vp8' | 'vp9' | 'av1' | 'prores')[];
+    audio_codecs?: ('aac' | 'mp3' | 'opus' | 'pcm')[];
+    containers?: ('mp4' | 'webm' | 'mov')[];
+    /**
+     * @minimum 1
+     */
+    min_bitrate_kbps?: number;
+    /**
+     * @minimum 1
+     */
+    max_bitrate_kbps?: number;
+    /**
+     * @minimum 1
+     */
+    max_file_size_mb?: number;
+    frame_rates?: number[];
+    captions?: 'required' | 'recommended' | 'not_required';
+    om_sdk_required?: boolean;
+    /**
+     * @minimum 1
+     */
+    headline_max_chars?: number;
+    /**
+     * @minimum 1
+     */
+    primary_text_max_chars?: number;
+    /**
+     * @minimum 1
+     */
+    brand_name_max_chars?: number;
+    cta_values?: string[];
+    /**
+     * Permitted companion banner widths (instream video).
+     */
+    companion_banner_widths?: number[];
+    companion_banner_heights?: number[];
+    /**
+     * Where the rendered asset bytes come from. Single shared enum across canonicals. See `image.json#asset_source` for the full semantics. `publisher_host_recorded` is audio-specific and has no defined behavior on video — adopters MUST select a value appropriate to the canonical.
+     */
+    asset_source?: 'buyer_uploaded' | 'publisher_host_recorded' | 'seller_pre_rendered_from_brief' | 'seller_human_designed' | 'agent_synthesized';
+    /**
+     * Whether the product accepts buyer-uploaded video. When `rejected`, the buyer cannot ship a video asset directly — they must use build_creative (or sync_creatives with brief inputs) so the seller produces the video.
+     */
+    buyer_asset_acceptance?: 'accepted' | 'rejected';
+}
+
+/**
+ * Static image creative format. Slots: `image_main` (image asset, file or hosted URL), optional `headline` (text), `body_text` (text), `cta` (text/enum), `landing_page_url` (url). Tracking model: impression pixel + click URL via universal_macros, with optional viewability pixel. Distinct from `html5` (interactive bundles) and `display_tag` (third-party served). AR/dimensions narrow to specific sizes via product parameters — covers IAB display sizes (300x250, 728x90, 970x250, etc.) without a separate iab_size enum.
+ */
+export type CanonicalFormatImage = SizeModeMutex & {
+    /**
+     * When true, this canonical (or a seller's specific narrowing of it) may not work as declared — adopters SHOULD have a v1 fallback ready and SHOULD NOT route production budget without testing. Same semantics as `experimental` on protocols: 'this is shipping but may break, evolve, or fail.' Buyers reading `experimental: true` SHOULD prefer the v1 path when a v1 fallback exists for the same product (via `format_ids` on the parent product or via the v2 declaration's `v1_format_ref`).
+     *
+     * Three drivers of `experimental: true`:
+     * 1. **Spec maturity** — the canonical's tracking model or parameter shape is still being settled (`agent_placement`'s tracking macros, `sponsored_placement`'s per-adapter contracts, `responsive_creative`'s algorithmic composition).
+     * 2. **Adopter runtime gap** — the seller has declared the canonical in their catalog but their runtime doesn't yet honor it cleanly.
+     * 3. **Custom shapes** — `format_kind: "custom"` is inherently experimental until the working group promotes a `format_shape` to a first-class canonical.
+     *
+     * Replaces the earlier `status` enum (`stable | preview | deprecated`) + `runtime_status` enum (`stable | preview | declared_only`) — two axes with subtle overlap. The single boolean is what buyers actually care about: do I treat this as production-stable or as 'try at my own risk.' Sellers SHOULD set `experimental: true` on canonicals or product declarations that aren't yet production-ready, regardless of which axis (spec, runtime, custom) drives the experimentation. The 6 IAB/VAST/DAAST re-encodings (`image`, `display_tag`, `video_hosted`, `video_vast`, `audio_hosted`, `audio_daast`) default to non-experimental at the canonical level; sellers MAY still mark a specific product declaration experimental (e.g., a beta runtime path for an existing product).
+     */
+    experimental?: boolean;
+    /**
+     * When true, this canonical (or a seller's specific narrowing of it) is going away. Existing adopters are supported through the deprecation cycle; new adoption is discouraged. Pair with `migration_target_version` to indicate when the canonical is expected to be removed. Distinct from `experimental`: an experimental canonical may stabilize and stop being experimental; a deprecated canonical is on a sunset path.
+     */
+    deprecated?: boolean;
+    /**
+     * Whether this canonical has any v1 named-format equivalent. `true` (default) — the canonical is structurally expressible as one or more v1 named formats (IAB display sizes, VAST tags, DAAST tags, etc.); v1→v2 projection via `v1-canonical-mapping.json` is meaningful. `false` — the canonical is inherently new in v2 and has no v1 form; v1's `list_creative_formats` couldn't express it because the underlying concept (algorithmic surface composition, AI-surface mentions, retail-media catalog placements, multi-card carousels) didn't exist as a v1 named-format archetype.
+     *
+     * Lets SDKs distinguish two failure modes that today look identical: (a) the registry hasn't covered this canonical yet (correctable — seller adds explicit `canonical` field or files a registry entry) vs (b) no v1 path is possible (informational — buyer needs v2-aware consumption, or seller declares `canonical_formats_only: true` on the product declaration). SDKs encountering `v1_translatable: false` on a canonical SHOULD NOT emit `FORMAT_PROJECTION_FAILED` (which signals registry-coverage gap) — instead surface the inherent v1-unreachability as a different diagnostic or skip silently. The 4 inherently-v2 canonicals at 3.1 GA: `image_carousel`, `sponsored_placement`, `responsive_creative`, `agent_placement`.
+     */
+    v1_translatable?: boolean;
+    /**
+     * AdCP MAJOR.MINOR version that introduced this canonical (e.g., '3.1', '3.2'). Lets adopters reason about minimum protocol version requirements when consuming a format declaration. Patch precision is intentionally rejected — canonicals are introduced at minor-version boundaries.
+     */
+    since_version?: string;
+    /**
+     * AdCP MAJOR.MINOR version by which the working group expects this canonical to stabilize, surface a breaking revision, or (when `deprecated: true`) be removed. Patch precision is intentionally rejected — canonicals shift at minor-version boundaries. Absence signals 'no specific target' (omit the field rather than use a placeholder like 'unknown').
+     */
+    migration_target_version?: string;
+    /**
+     * Whether the surface composes deterministically (buyer can predict per-slot rendering — sponsored_placement, image, video) or algorithmically (surface chooses combinations or phrasing — responsive_creative, agent_placement).
+     */
+    composition_model?: 'deterministic' | 'algorithmic';
+    /**
+     * When true, the product rejects unsigned synthesized assets. Builders calling build_creative MUST attach a C2PA-compatible provenance manifest attributing synthesis to the creative agent.
+     */
+    provenance_required?: boolean;
+    /**
+     * Platform-specific extensions narrowing the canonical (pixel ID shapes, conversion event taxonomies, platform-specific CTAs/destinations). Each extension is a URI+digest reference resolved against the bundled `extensions` map in get_products responses or fetched directly.
+     *
+     * **Collision precedence (normative).** When two or more `platform_extensions[]` entries on the same declaration extend the same target (e.g., both extend `tracking`) with overlapping field names, **array order is authoritative — later entries override earlier ones on a per-field basis** (last-in-array-wins). SDKs MUST surface the overlap via the `errors[]` array on the `get_products` response with a structured code (`FORMAT_DECLARATION_DIVERGENT` is appropriate when the overlap appears across dual-emitted shapes; a producer-self-emitted overlap on a single declaration SHOULD use the same code with `error.details: { collision_kind: "platform_extension_field", target, overlapping_fields, winning_extension_uri }`). Producers SHOULD avoid the collision by emitting one extension per target or by partitioning fields across extensions; the deterministic precedence is for last-resort consistency across SDK implementations, not a sanctioned merging strategy.
+     */
+    platform_extensions?: PlatformExtensionReference[];
+    /**
+     * When true, the format's production pipeline is genuinely nondeterministic — the platform cannot guarantee that synthesis from a given input set produces in-spec output. Veo / Sora / Runway-class generative video, and other AI-synthesis flows where output dimensions, duration, or quality vary per run. Implies a different validation contract: predictive `validate_input` is impossible; the platform's own post-synthesis QA loop applies; if the QA loop exhausts without producing a valid artifact, `build_creative` returns task_failed with a synthesis_failed reason. Distinct from `composition_model` (which describes how the surface composes per-slot rendering, not whether synthesis is deterministic). When false or absent, the format's production is predictable enough that `validate_input` can predict output properties from input properties.
+     *
+     * **Compatibility with `asset_source` / `item_production_model`**: `synthesis_nondeterministic: true` MAY pair with any of `seller_pre_rendered_from_brief`, `seller_human_designed`, or `agent_synthesized` (the QA loop is concept-level, not source-specific — 'seller renders from brief but each retry differs' is just as nondeterministic as Veo). It MUST NOT pair with `buyer_uploaded` (the buyer ships pre-rendered bytes; there's no synthesis step to be nondeterministic about). It MUST NOT pair with `publisher_host_recorded` (the publisher's host produces a deterministic-from-script output even if the human voice varies). When `synthesis_nondeterministic: true` is set with an incompatible source, validators SHOULD reject with a structured error.
+     */
+    synthesis_nondeterministic?: boolean;
+    /**
+     * Default slots for image canonical. Buyer ships an image asset (file or hosted URL) plus optional headline, body text, primary text (long-form caption), CTA (typically constrained to an enum via `cta_values`), and clickthrough URL. Products MAY override the default — make `headline` required, narrow `cta` to a value enum, or remove slots the surface doesn't consume.
+     */
+    slots?: unknown;
+    /**
+     * Typical production turnaround in business days when the format requires seller-side production (e.g., host-recording from a buyer-supplied script). 0 for synchronous (e.g., generative AI); >0 for human-produced (e.g., podcast host-read). Absent when no production is required (buyer uploads complete creative).
+     */
+    production_window_business_days?: number;
+    /**
+     * Required image width in pixels — use for fixed-size slots (e.g., a 300×250 IAB MREC). For multi-size flexible slots (publisher MREC slot that accepts 300×250 OR 728×90 OR 970×250), use `sizes[]` instead; for responsive slots that adapt to viewport, use `min_width`/`max_width`/`min_height`/`max_height`. The three modes are mutually exclusive — set exactly one of `(width+height)`, `sizes[]`, or `min/max_width` + `min/max_height` ranges.
+     * @minimum 1
+     */
+    width?: number;
+    /**
+     * Required image height in pixels. See `width` for size-mode mutual exclusion.
+     * @minimum 1
+     */
+    height?: number;
+    /**
+     * List of accepted (width, height) pairs for a multi-size flexible slot. Buyer ships an asset matching one of the listed sizes; SDK validates `assets.image_main.{width,height}` against the list (any-match). Mirrors OpenRTB `banner.format[]` semantics — one declaration with N accepted sizes is cleaner than N format_options entries. Mutually exclusive with `(width, height)` and with `min/max_width` + `min/max_height` ranges.
+     */
+    sizes?: {
+        /**
+         * @minimum 1
+         */
+        width: number;
+        /**
+         * @minimum 1
+         */
+        height: number;
+    }[];
+    /**
+     * Minimum accepted width in pixels for responsive slots that adapt within a range (e.g., 'any width from 300 to 970'). Use with `max_width` (and optionally `min_height`/`max_height`). Mutually exclusive with `(width, height)` and `sizes[]`.
+     * @minimum 1
+     */
+    min_width?: number;
+    /**
+     * Maximum accepted width in pixels for responsive slots. Pair with `min_width`. See `min_width` for size-mode mutual exclusion.
+     * @minimum 1
+     */
+    max_width?: number;
+    /**
+     * Minimum accepted height in pixels for responsive slots. Pair with `max_height`.
+     * @minimum 1
+     */
+    min_height?: number;
+    /**
+     * Maximum accepted height in pixels for responsive slots. Pair with `min_height`.
+     * @minimum 1
+     */
+    max_height?: number;
+    /**
+     * Optional aspect ratio constraint (e.g., '1.91:1', '1:1'). When provided alongside `width`/`height`, must agree. When used with `sizes[]` or responsive ranges, narrows accepted entries to those matching the aspect ratio.
+     * @pattern ^[0-9]+(\.[0-9]+)?:[0-9]+(\.[0-9]+)?$
+     */
+    aspect_ratio?: string;
+    /**
+     * Maximum file size in kilobytes.
+     * @minimum 1
+     */
+    max_file_size_kb?: number;
+    /**
+     * Permitted image file formats.
+     */
+    image_formats?: ('jpg' | 'jpeg' | 'png' | 'gif' | 'webp' | 'svg')[];
+    /**
+     * Whether the image and its trackers must be served over HTTPS.
+     */
+    ssl_required?: boolean;
+    /**
+     * @minimum 1
+     */
+    headline_max_chars?: number;
+    /**
+     * @minimum 1
+     */
+    body_text_max_chars?: number;
+    /**
+     * Permitted CTA values for this product (e.g., ['LEARN_MORE', 'SHOP_NOW']).
+     */
+    cta_values?: string[];
+    /**
+     * Where the rendered asset bytes come from. Single shared enum across all canonicals (`image`, `video_hosted`, `audio_hosted` — replaces the earlier per-canonical `image_source` / `video_source` / `audio_source` fields). `buyer_uploaded` (default): buyer ships a pre-rendered asset. `publisher_host_recorded`: publisher's host records the asset (audio-specific; podcast host-read pattern). `seller_pre_rendered_from_brief`: buyer ships a brief plus structured copy; seller renders ONE asset at sync_creatives or build_creative time (generative-DSP pattern). `seller_human_designed`: seller's design team renders manually from a brief. `agent_synthesized`: AI synthesis pipeline; pair with `synthesis_nondeterministic: true` when the platform cannot guarantee in-spec output (Veo/Sora/Imagen-class).
+     *
+     * Not every value is meaningful on every canonical — `publisher_host_recorded` is audio-specific; on `image` or `video_hosted` it has no defined behavior. Adopters MUST select a value appropriate to the canonical's asset type. The `slots` declaration is the binding contract for what the buyer ships; `asset_source` is informational and lets buyers understand the production model when picking products.
+     */
+    asset_source?: 'buyer_uploaded' | 'publisher_host_recorded' | 'seller_pre_rendered_from_brief' | 'seller_human_designed' | 'agent_synthesized';
+    /**
+     * Whether the product accepts buyer-uploaded assets. When `rejected`, the buyer cannot ship pre-rendered bytes directly — they must use build_creative (or sync_creatives with brief inputs) so the seller produces the asset. Combined with `asset_source`, lets a product declare 'I produce assets from briefs and refuse buyer uploads' (asset_source=`seller_pre_rendered_from_brief`, buyer_asset_acceptance=`rejected`).
+     */
+    buyer_asset_acceptance?: 'accepted' | 'rejected';
+};
+
+/**
+ * Multi-card swipeable carousel. The buyer ships a `cards` slot whose value is an **array** of [card-asset](/schemas/core/assets/card-asset.json) objects (a single key with an array value — NOT one key per card, NOT dotted/bracketed paths). Each card-asset carries: `asset_type: "card"`, `media` (an image or video asset), optional `headline` (text), optional `landing_page_url` (url asset). Per-card structure is the same across all cards; mixed orientations not allowed within a single carousel. Tracking model: per-card impression and engagement pixels + carousel-level engagement (swipe, view-time). Allowed asset types for a card's `media` field: `image` and `video` (Meta-style mixed-media); platforms can narrow to image-only or video-only via `allowed_card_media_asset_types`.
+ *
+ * The manifest's `assets.cards` value is an array of card-asset objects. Example: `"cards": [{"asset_type": "card", "media": {"asset_type": "image", "url": "..."}, "headline": "Buy now", "landing_page_url": {"asset_type": "url", "url_type": "clickthrough", "url": "..."}}, ...]`. Each card-asset validates against the card schema; per-card platform extensions attach via the card's `platform_extensions` field, never via inline non-canonical keys.
+ */
+export interface CanonicalFormatImageCarousel {
+    /**
+     * When true, this canonical (or a seller's specific narrowing of it) may not work as declared — adopters SHOULD have a v1 fallback ready and SHOULD NOT route production budget without testing. Same semantics as `experimental` on protocols: 'this is shipping but may break, evolve, or fail.' Buyers reading `experimental: true` SHOULD prefer the v1 path when a v1 fallback exists for the same product (via `format_ids` on the parent product or via the v2 declaration's `v1_format_ref`).
+     *
+     * Three drivers of `experimental: true`:
+     * 1. **Spec maturity** — the canonical's tracking model or parameter shape is still being settled (`agent_placement`'s tracking macros, `sponsored_placement`'s per-adapter contracts, `responsive_creative`'s algorithmic composition).
+     * 2. **Adopter runtime gap** — the seller has declared the canonical in their catalog but their runtime doesn't yet honor it cleanly.
+     * 3. **Custom shapes** — `format_kind: "custom"` is inherently experimental until the working group promotes a `format_shape` to a first-class canonical.
+     *
+     * Replaces the earlier `status` enum (`stable | preview | deprecated`) + `runtime_status` enum (`stable | preview | declared_only`) — two axes with subtle overlap. The single boolean is what buyers actually care about: do I treat this as production-stable or as 'try at my own risk.' Sellers SHOULD set `experimental: true` on canonicals or product declarations that aren't yet production-ready, regardless of which axis (spec, runtime, custom) drives the experimentation. The 6 IAB/VAST/DAAST re-encodings (`image`, `display_tag`, `video_hosted`, `video_vast`, `audio_hosted`, `audio_daast`) default to non-experimental at the canonical level; sellers MAY still mark a specific product declaration experimental (e.g., a beta runtime path for an existing product).
+     */
+    experimental?: boolean;
+    /**
+     * When true, this canonical (or a seller's specific narrowing of it) is going away. Existing adopters are supported through the deprecation cycle; new adoption is discouraged. Pair with `migration_target_version` to indicate when the canonical is expected to be removed. Distinct from `experimental`: an experimental canonical may stabilize and stop being experimental; a deprecated canonical is on a sunset path.
+     */
+    deprecated?: boolean;
+    /**
+     * Inherently new in v2 — multi-card carousels (Meta carousel, Pinterest pin collections, Snap collection ads) weren't expressible as v1 named formats. SDKs MUST NOT emit `FORMAT_PROJECTION_FAILED` for products using this canonical; the v1-unreachability is structural.
+     */
+    v1_translatable?: unknown;
+    /**
+     * AdCP MAJOR.MINOR version that introduced this canonical (e.g., '3.1', '3.2'). Lets adopters reason about minimum protocol version requirements when consuming a format declaration. Patch precision is intentionally rejected — canonicals are introduced at minor-version boundaries.
+     */
+    since_version?: string;
+    /**
+     * AdCP MAJOR.MINOR version by which the working group expects this canonical to stabilize, surface a breaking revision, or (when `deprecated: true`) be removed. Patch precision is intentionally rejected — canonicals shift at minor-version boundaries. Absence signals 'no specific target' (omit the field rather than use a placeholder like 'unknown').
+     */
+    migration_target_version?: string;
+    /**
+     * Whether the surface composes deterministically (buyer can predict per-slot rendering — sponsored_placement, image, video) or algorithmically (surface chooses combinations or phrasing — responsive_creative, agent_placement).
+     */
+    composition_model?: 'deterministic' | 'algorithmic';
+    /**
+     * When true, the product rejects unsigned synthesized assets. Builders calling build_creative MUST attach a C2PA-compatible provenance manifest attributing synthesis to the creative agent.
+     */
+    provenance_required?: boolean;
+    /**
+     * Platform-specific extensions narrowing the canonical (pixel ID shapes, conversion event taxonomies, platform-specific CTAs/destinations). Each extension is a URI+digest reference resolved against the bundled `extensions` map in get_products responses or fetched directly.
+     *
+     * **Collision precedence (normative).** When two or more `platform_extensions[]` entries on the same declaration extend the same target (e.g., both extend `tracking`) with overlapping field names, **array order is authoritative — later entries override earlier ones on a per-field basis** (last-in-array-wins). SDKs MUST surface the overlap via the `errors[]` array on the `get_products` response with a structured code (`FORMAT_DECLARATION_DIVERGENT` is appropriate when the overlap appears across dual-emitted shapes; a producer-self-emitted overlap on a single declaration SHOULD use the same code with `error.details: { collision_kind: "platform_extension_field", target, overlapping_fields, winning_extension_uri }`). Producers SHOULD avoid the collision by emitting one extension per target or by partitioning fields across extensions; the deterministic precedence is for last-resort consistency across SDK implementations, not a sanctioned merging strategy.
+     */
+    platform_extensions?: PlatformExtensionReference[];
+    /**
+     * When true, the format's production pipeline is genuinely nondeterministic — the platform cannot guarantee that synthesis from a given input set produces in-spec output. Veo / Sora / Runway-class generative video, and other AI-synthesis flows where output dimensions, duration, or quality vary per run. Implies a different validation contract: predictive `validate_input` is impossible; the platform's own post-synthesis QA loop applies; if the QA loop exhausts without producing a valid artifact, `build_creative` returns task_failed with a synthesis_failed reason. Distinct from `composition_model` (which describes how the surface composes per-slot rendering, not whether synthesis is deterministic). When false or absent, the format's production is predictable enough that `validate_input` can predict output properties from input properties.
+     *
+     * **Compatibility with `asset_source` / `item_production_model`**: `synthesis_nondeterministic: true` MAY pair with any of `seller_pre_rendered_from_brief`, `seller_human_designed`, or `agent_synthesized` (the QA loop is concept-level, not source-specific — 'seller renders from brief but each retry differs' is just as nondeterministic as Veo). It MUST NOT pair with `buyer_uploaded` (the buyer ships pre-rendered bytes; there's no synthesis step to be nondeterministic about). It MUST NOT pair with `publisher_host_recorded` (the publisher's host produces a deterministic-from-script output even if the human voice varies). When `synthesis_nondeterministic: true` is set with an incompatible source, validators SHOULD reject with a structured error.
+     */
+    synthesis_nondeterministic?: boolean;
+    /**
+     * Default slots for image_carousel. The `cards` slot's value in the manifest is an array of [card-asset](/schemas/core/assets/card-asset.json) objects; `min` / `max` constrain card count.
+     */
+    slots?: unknown;
+    /**
+     * Typical production turnaround in business days when the format requires seller-side production (e.g., host-recording from a buyer-supplied script). 0 for synchronous (e.g., generative AI); >0 for human-produced (e.g., podcast host-read). Absent when no production is required (buyer uploads complete creative).
+     */
+    production_window_business_days?: number;
+    /**
+     * Aspect ratio shared across all cards (e.g., '1:1', '1.91:1', '4:5').
+     * @pattern ^[0-9]+(\.[0-9]+)?:[0-9]+(\.[0-9]+)?$
+     */
+    card_aspect_ratio?: string;
+    /**
+     * Minimum card count (typical: 2 or 3).
+     * @minimum 2
+     */
+    min_cards?: number;
+    /**
+     * Maximum card count (typical: 6, 10, or 35 depending on platform).
+     */
+    max_cards?: number;
+    /**
+     * Asset types each card's `media` field may carry. Default: ['image']. Polymorphic carousels (Meta) allow ['image', 'video']. Renamed from `allowed_card_asset_types` to disambiguate that this constrains the card's media payload, not the card-asset itself (which is always asset_type: "card").
+     */
+    allowed_card_media_asset_types?: ('image' | 'video')[];
+    /**
+     * DEPRECATED — alias for `allowed_card_media_asset_types`. Kept for back-compat; prefer the new field name. Removed in 5.0.
+     */
+    allowed_card_asset_types?: ('image' | 'video')[];
+    /**
+     * @minimum 1
+     */
+    card_image_max_file_size_kb?: number;
+    /**
+     * @minimum 1
+     */
+    card_video_max_duration_ms?: number;
+    /**
+     * Maximum length of the carousel-level primary text.
+     * @minimum 1
+     */
+    primary_text_max_chars?: number;
+    /**
+     * Per-card headline character limit. Governs the `headline` field on each card-asset in the `cards` slot.
+     * @minimum 1
+     */
+    card_headline_max_chars?: number;
+    /**
+     * Per-card description character limit. Governs the `description` field on each card-asset in the `cards` slot. Distinct from `card_headline_max_chars`: description is longer body copy (typically 100-500 chars); headline is the short label (typically 25-40 chars).
+     * @minimum 1
+     */
+    card_description_max_chars?: number;
+    ssl_required?: boolean;
+}
+
+/**
+ * The v2 canonical-format-kind this v1 format projects to (`image`, `html5`, `display_tag`, `image_carousel`, `video_hosted`, `video_vast`, `audio_hosted`, `audio_daast`, `sponsored_placement`, `responsive_creative`, `agent_placement`, or `custom`).
+ */
+export type CanonicalFormatKind = 'image' | 'html5' | 'display_tag' | 'image_carousel' | 'video_hosted' | 'video_vast' | 'audio_hosted' | 'audio_daast' | 'sponsored_placement' | 'native_in_feed' | 'responsive_creative' | 'agent_placement' | 'custom';
+
+/**
+ * IAB-shaped native creative for in-feed and content-recommendation surfaces. Default slots cover the primary IAB OpenRTB Native 1.2 asset types — `title` (Title Asset), `body_text` (Data Asset type 2), `main_image` (Image Asset main), `icon` (Image Asset icon), `cta` (Data Asset type 12), `advertiser_name` (Data Asset type 1), `sponsored_label` (Title-adjacent), `landing_page_url` (Link Asset), `display_url` (Data Asset type 11 — visible URL/domain, distinct from clickthrough), `rating` (Data Asset type 3 — app/product rating), `price` (Data Asset type 6 — product price), plus renderer-fired `impression_tracker` / `viewability_tracker` / `click_tracker` (`pixel_tracker`). Products MAY use `slots_override` to add other IAB Native data asset types (likes — type 4, downloads — type 5, saleprice — type 7, phone_number — type 8, address — type 9, desc2 — type 10, etc.) or to remove slots the surface doesn't render. The publisher's renderer assembles these into its own look-and-feel — feed card, content-recommendation slot, in-stream native unit. Buyer ships a single asset bundle; the surface chooses presentation.
+ *
+ * **Scope (normative — buyer-agent routing).** This canonical is the home for:
+ * - IAB OpenRTB Native 1.2 in-feed native ads (publisher feeds, app feeds)
+ * - Content-recommendation widgets (Taboola, Outbrain, Yahoo Recommendations)
+ * - AdMob Native / Yahoo Native publisher slots
+ * - In-feed sponsored placements without catalog dependency
+ *
+ * **Not this canonical:**
+ * - Catalog-driven retail-media (Amazon SP, Criteo SP, CitrusAd SP) — use `sponsored_placement` (requires `source_catalog`).
+ * - Algorithmic surface that picks from a buyer-supplied asset pool (Google PMax, Meta Advantage+) — use `responsive_creative`.
+ * - Multi-card carousel — use `image_carousel`.
+ * - Video-first native units where the asset is a hosted video file — use `video_hosted` with `applies_to_channels: ["native"]`.
+ *
+ * Distinct from `sponsored_placement` along the catalog axis: native_in_feed is asset-bundle composition; sponsored_placement is catalog-row composition. A buyer agent reading `format_kind: native_in_feed` knows to assemble title + image + body + CTA; reading `format_kind: sponsored_placement` knows to attach a catalog feed.
+ */
+export interface CanonicalFormatNativeInFeed {
+    /**
+     * Stable at 3.1 GA. Shape mirrors IAB OpenRTB Native 1.2 — the renderer contract is well-established across in-feed native and content-recommendation adopters.
+     */
+    experimental?: unknown;
+    /**
+     * When true, this canonical (or a seller's specific narrowing of it) is going away. Existing adopters are supported through the deprecation cycle; new adoption is discouraged. Pair with `migration_target_version` to indicate when the canonical is expected to be removed. Distinct from `experimental`: an experimental canonical may stabilize and stop being experimental; a deprecated canonical is on a sunset path.
+     */
+    deprecated?: boolean;
+    /**
+     * Translates to v1 named native formats (e.g., `native_standard`, `native_content`) via the projection registry. Sellers with existing v1 named native formats SHOULD point `v1_format_ref[]` at them.
+     */
+    v1_translatable?: unknown;
+    /**
+     * AdCP MAJOR.MINOR version that introduced this canonical (e.g., '3.1', '3.2'). Lets adopters reason about minimum protocol version requirements when consuming a format declaration. Patch precision is intentionally rejected — canonicals are introduced at minor-version boundaries.
+     */
+    since_version?: string;
+    /**
+     * AdCP MAJOR.MINOR version by which the working group expects this canonical to stabilize, surface a breaking revision, or (when `deprecated: true`) be removed. Patch precision is intentionally rejected — canonicals shift at minor-version boundaries. Absence signals 'no specific target' (omit the field rather than use a placeholder like 'unknown').
+     */
+    migration_target_version?: string;
+    /**
+     * Whether the surface composes deterministically (buyer can predict per-slot rendering — sponsored_placement, image, video) or algorithmically (surface chooses combinations or phrasing — responsive_creative, agent_placement).
+     */
+    composition_model?: 'deterministic' | 'algorithmic';
+    /**
+     * When true, the product rejects unsigned synthesized assets. Builders calling build_creative MUST attach a C2PA-compatible provenance manifest attributing synthesis to the creative agent.
+     */
+    provenance_required?: boolean;
+    /**
+     * Platform-specific extensions narrowing the canonical (pixel ID shapes, conversion event taxonomies, platform-specific CTAs/destinations). Each extension is a URI+digest reference resolved against the bundled `extensions` map in get_products responses or fetched directly.
+     *
+     * **Collision precedence (normative).** When two or more `platform_extensions[]` entries on the same declaration extend the same target (e.g., both extend `tracking`) with overlapping field names, **array order is authoritative — later entries override earlier ones on a per-field basis** (last-in-array-wins). SDKs MUST surface the overlap via the `errors[]` array on the `get_products` response with a structured code (`FORMAT_DECLARATION_DIVERGENT` is appropriate when the overlap appears across dual-emitted shapes; a producer-self-emitted overlap on a single declaration SHOULD use the same code with `error.details: { collision_kind: "platform_extension_field", target, overlapping_fields, winning_extension_uri }`). Producers SHOULD avoid the collision by emitting one extension per target or by partitioning fields across extensions; the deterministic precedence is for last-resort consistency across SDK implementations, not a sanctioned merging strategy.
+     */
+    platform_extensions?: PlatformExtensionReference[];
+    /**
+     * When true, the format's production pipeline is genuinely nondeterministic — the platform cannot guarantee that synthesis from a given input set produces in-spec output. Veo / Sora / Runway-class generative video, and other AI-synthesis flows where output dimensions, duration, or quality vary per run. Implies a different validation contract: predictive `validate_input` is impossible; the platform's own post-synthesis QA loop applies; if the QA loop exhausts without producing a valid artifact, `build_creative` returns task_failed with a synthesis_failed reason. Distinct from `composition_model` (which describes how the surface composes per-slot rendering, not whether synthesis is deterministic). When false or absent, the format's production is predictable enough that `validate_input` can predict output properties from input properties.
+     *
+     * **Compatibility with `asset_source` / `item_production_model`**: `synthesis_nondeterministic: true` MAY pair with any of `seller_pre_rendered_from_brief`, `seller_human_designed`, or `agent_synthesized` (the QA loop is concept-level, not source-specific — 'seller renders from brief but each retry differs' is just as nondeterministic as Veo). It MUST NOT pair with `buyer_uploaded` (the buyer ships pre-rendered bytes; there's no synthesis step to be nondeterministic about). It MUST NOT pair with `publisher_host_recorded` (the publisher's host produces a deterministic-from-script output even if the human voice varies). When `synthesis_nondeterministic: true` is set with an incompatible source, validators SHOULD reject with a structured error.
+     */
+    synthesis_nondeterministic?: boolean;
+    /**
+     * Default slot shape for native_in_feed. Mirrors IAB OpenRTB Native 1.2 asset types. Products MAY override (`slots_override` on the projection ref) to narrow per-slot limits (`max_chars` on title/body) or remove unused slots (a content-recommendation slot that doesn't display an icon).
+     */
+    slots?: unknown;
+    /**
+     * Typical production turnaround in business days when the format requires seller-side production (e.g., host-recording from a buyer-supplied script). 0 for synchronous (e.g., generative AI); >0 for human-produced (e.g., podcast host-read). Absent when no production is required (buyer uploads complete creative).
+     */
+    production_window_business_days?: number;
+    /**
+     * Maximum character length for the title slot. IAB native typical: 25 (short) to 90 (long). Buyer agents SHOULD validate ship-time title length against this.
+     * @minimum 1
+     */
+    title_max_chars?: number;
+    /**
+     * Maximum character length for the body_text slot. IAB native typical: 90 (mainline) to 140 (extended).
+     * @minimum 1
+     */
+    body_text_max_chars?: number;
+    /**
+     * Maximum character length for the cta slot. Typical: 15–25.
+     * @minimum 1
+     */
+    cta_max_chars?: number;
+    /**
+     * Permitted CTA values for this product (e.g., ['LEARN_MORE', 'SHOP_NOW', 'SIGN_UP', 'DOWNLOAD']). When set, narrows the cta slot to a closed enum.
+     */
+    cta_values?: string[];
+    /**
+     * Accepted (width, height) pairs for the main_image slot. Common IAB native sizes: 1200×627 (1.91:1), 1080×1080 (1:1), 1080×1350 (4:5).
+     */
+    main_image_sizes?: {
+        /**
+         * @minimum 1
+         */
+        width: number;
+        /**
+         * @minimum 1
+         */
+        height: number;
+    }[];
+    /**
+     * Required (width, height) for the icon slot when present (typical: 80×80 or 100×100).
+     */
+    icon_size?: {
+        /**
+         * @minimum 1
+         */
+        width: number;
+        /**
+         * @minimum 1
+         */
+        height: number;
+    };
+    /**
+     * Maximum file size in kilobytes for main_image and icon.
+     * @minimum 1
+     */
+    max_image_file_size_kb?: number;
+    /**
+     * Permitted image file formats.
+     */
+    image_formats?: ('jpg' | 'jpeg' | 'png' | 'gif' | 'webp')[];
+    /**
+     * Whether trackers, landing pages, and image URLs must be served over HTTPS.
+     */
+    ssl_required?: boolean;
+    /**
+     * Where the rendered native assets come from. `publisher_host_recorded` is omitted (audio-specific and not meaningful for native). Other values mirror the shared production-source axis used on `image` / `video_hosted`. `buyer_uploaded` (default): buyer ships pre-rendered title/image/body. `seller_pre_rendered_from_brief`: buyer ships a brief, seller renders the native bundle. `agent_synthesized`: AI synthesis pipeline produces title + image + body from a brief; pair with `synthesis_nondeterministic: true` for generative pipelines that can't guarantee in-spec output.
+     */
+    asset_source?: 'buyer_uploaded' | 'seller_pre_rendered_from_brief' | 'seller_human_designed' | 'agent_synthesized';
+    /**
+     * Whether the product accepts buyer-uploaded native assets. When `rejected`, the buyer cannot ship pre-rendered title/image/body — they must use `build_creative` (or `sync_creatives` with brief inputs) so the seller produces the native bundle from a brief.
+     */
+    buyer_asset_acceptance?: 'accepted' | 'rejected';
+}
+
+/**
+ * Buyer supplies a pool of typed assets (multiple headlines, descriptions, images, videos, logos); the surface algorithmically composes combinations per placement. **Composition is algorithmic** — surface picks combinations and reports per-asset performance breakdowns. Covers Google Responsive Display Ads (RDA), Responsive Search Ads (RSA), Performance Max (PMax), Demand Gen, and Meta Advantage+ creative. Industry term: "Responsive" (Google) / "Advantage+ creative" (Meta) / "Dynamic Creative" (older Meta term). Distinct from `sponsored_placement` (catalog-driven, deterministic) and `agent_placement` (AI-surface composition). The structured `slots` field below enumerates expected canonical asset_group_id slots; per-slot count/length narrowing lives in flat parameters (`headlines_min`, `headline_max_chars`, etc.).
+ */
+export interface CanonicalFormatResponsiveCreative {
+    /**
+     * Marked experimental at 3.1 GA: composition is algorithmic (the surface picks combinations and reports per-asset breakdowns), and there's no clean v1-translatable equivalent. Buyers ship asset pools rather than rendered creatives; the surface's per-impression composition cannot be predicted by `validate_input`. Adopters SHOULD validate behavior per surface (Google PMax vs Meta Advantage+ creative differ meaningfully).
+     */
+    experimental?: unknown;
+    /**
+     * When true, this canonical (or a seller's specific narrowing of it) is going away. Existing adopters are supported through the deprecation cycle; new adoption is discouraged. Pair with `migration_target_version` to indicate when the canonical is expected to be removed. Distinct from `experimental`: an experimental canonical may stabilize and stop being experimental; a deprecated canonical is on a sunset path.
+     */
+    deprecated?: boolean;
+    /**
+     * Inherently new in v2 — algorithmic asset-pool composition (Google PMax / Meta Advantage+ creative) wasn't expressible as v1 named formats. SDKs MUST NOT emit `FORMAT_PROJECTION_FAILED` for products using this canonical; the v1-unreachability is structural.
+     */
+    v1_translatable?: unknown;
+    /**
+     * AdCP MAJOR.MINOR version that introduced this canonical (e.g., '3.1', '3.2'). Lets adopters reason about minimum protocol version requirements when consuming a format declaration. Patch precision is intentionally rejected — canonicals are introduced at minor-version boundaries.
+     */
+    since_version?: string;
+    /**
+     * AdCP MAJOR.MINOR version by which the working group expects this canonical to stabilize, surface a breaking revision, or (when `deprecated: true`) be removed. Patch precision is intentionally rejected — canonicals shift at minor-version boundaries. Absence signals 'no specific target' (omit the field rather than use a placeholder like 'unknown').
+     */
+    migration_target_version?: string;
+    /**
+     * Whether the surface composes deterministically (buyer can predict per-slot rendering — sponsored_placement, image, video) or algorithmically (surface chooses combinations or phrasing — responsive_creative, agent_placement).
+     */
+    composition_model?: 'deterministic' | 'algorithmic';
+    /**
+     * When true, the product rejects unsigned synthesized assets. Builders calling build_creative MUST attach a C2PA-compatible provenance manifest attributing synthesis to the creative agent.
+     */
+    provenance_required?: boolean;
+    /**
+     * Platform-specific extensions narrowing the canonical (pixel ID shapes, conversion event taxonomies, platform-specific CTAs/destinations). Each extension is a URI+digest reference resolved against the bundled `extensions` map in get_products responses or fetched directly.
+     *
+     * **Collision precedence (normative).** When two or more `platform_extensions[]` entries on the same declaration extend the same target (e.g., both extend `tracking`) with overlapping field names, **array order is authoritative — later entries override earlier ones on a per-field basis** (last-in-array-wins). SDKs MUST surface the overlap via the `errors[]` array on the `get_products` response with a structured code (`FORMAT_DECLARATION_DIVERGENT` is appropriate when the overlap appears across dual-emitted shapes; a producer-self-emitted overlap on a single declaration SHOULD use the same code with `error.details: { collision_kind: "platform_extension_field", target, overlapping_fields, winning_extension_uri }`). Producers SHOULD avoid the collision by emitting one extension per target or by partitioning fields across extensions; the deterministic precedence is for last-resort consistency across SDK implementations, not a sanctioned merging strategy.
+     */
+    platform_extensions?: PlatformExtensionReference[];
+    /**
+     * When true, the format's production pipeline is genuinely nondeterministic — the platform cannot guarantee that synthesis from a given input set produces in-spec output. Veo / Sora / Runway-class generative video, and other AI-synthesis flows where output dimensions, duration, or quality vary per run. Implies a different validation contract: predictive `validate_input` is impossible; the platform's own post-synthesis QA loop applies; if the QA loop exhausts without producing a valid artifact, `build_creative` returns task_failed with a synthesis_failed reason. Distinct from `composition_model` (which describes how the surface composes per-slot rendering, not whether synthesis is deterministic). When false or absent, the format's production is predictable enough that `validate_input` can predict output properties from input properties.
+     *
+     * **Compatibility with `asset_source` / `item_production_model`**: `synthesis_nondeterministic: true` MAY pair with any of `seller_pre_rendered_from_brief`, `seller_human_designed`, or `agent_synthesized` (the QA loop is concept-level, not source-specific — 'seller renders from brief but each retry differs' is just as nondeterministic as Veo). It MUST NOT pair with `buyer_uploaded` (the buyer ships pre-rendered bytes; there's no synthesis step to be nondeterministic about). It MUST NOT pair with `publisher_host_recorded` (the publisher's host produces a deterministic-from-script output even if the human voice varies). When `synthesis_nondeterministic: true` is set with an incompatible source, validators SHOULD reject with a structured error.
+     */
+    synthesis_nondeterministic?: boolean;
+    slots?: unknown;
+    /**
+     * Typical production turnaround in business days when the format requires seller-side production (e.g., host-recording from a buyer-supplied script). 0 for synchronous (e.g., generative AI); >0 for human-produced (e.g., podcast host-read). Absent when no production is required (buyer uploads complete creative).
+     */
+    production_window_business_days?: number;
+    /**
+     * @minimum 0
+     */
+    headlines_min?: number;
+    /**
+     * @minimum 0
+     */
+    headlines_max?: number;
+    /**
+     * @minimum 1
+     */
+    headline_max_chars?: number;
+    /**
+     * @minimum 0
+     */
+    long_headlines_min?: number;
+    /**
+     * @minimum 0
+     */
+    long_headlines_max?: number;
+    /**
+     * @minimum 1
+     */
+    long_headline_max_chars?: number;
+    /**
+     * @minimum 0
+     */
+    descriptions_min?: number;
+    /**
+     * @minimum 0
+     */
+    descriptions_max?: number;
+    /**
+     * @minimum 1
+     */
+    description_max_chars?: number;
+    /**
+     * @minimum 0
+     */
+    images_landscape_min?: number;
+    /**
+     * @minimum 0
+     */
+    images_landscape_max?: number;
+    images_landscape_aspect_ratio?: string;
+    /**
+     * @minimum 0
+     */
+    images_square_min?: number;
+    /**
+     * @minimum 0
+     */
+    images_square_max?: number;
+    /**
+     * @minimum 0
+     */
+    images_vertical_min?: number;
+    /**
+     * @minimum 0
+     */
+    images_vertical_max?: number;
+    /**
+     * @minimum 0
+     */
+    videos_min?: number;
+    /**
+     * @minimum 0
+     */
+    videos_max?: number;
+    /**
+     * @minimum 1
+     */
+    video_min_duration_ms?: number;
+    /**
+     * @minimum 1
+     */
+    video_max_duration_ms?: number;
+    /**
+     * @minimum 0
+     */
+    logo_min?: number;
+    /**
+     * @minimum 0
+     */
+    logo_max?: number;
+    logo_aspect_ratios?: string[];
+    /**
+     * @minimum 1
+     */
+    business_name_max_chars?: number;
+    /**
+     * @minimum 1
+     */
+    asset_image_max_file_size_kb?: number;
+    /**
+     * Whether the product can additionally consume a catalog reference (e.g., PMax with product feed).
+     */
+    supports_catalog_input?: boolean;
+}
+
+/**
+ * Catalog-driven retail-media format. Slot: `source_catalog` (catalog asset — product/SKU/ASIN/GTIN catalog reference, REQUIRED), optional `hero_asset`, optional `landing_page_url`. Buyer supplies the catalog reference; surface composes per-item or multi-item rendering using its native placement template. **Composition is deterministic** — buyer can predict per-slot rendering from the catalog item structure. Tracking model: per-item impression + click + conversion (catalog-keyed via offering_id/sku/gtin macros). Covers Amazon Sponsored Products, Criteo Sponsored Products, CitrusAd Sponsored Products, Walmart Connect Sponsored Products, Pinterest Collection (catalog-driven mode).
+ *
+ * **Scope (normative — buyer-agent routing).** This canonical is the home for catalog-driven retail-media placements ONLY. The defining feature is the `source_catalog` slot — products under this canonical compose their creative *per catalog item* using the buyer-supplied catalog feed. Without a catalog feed there is nothing to render against. Buyer agents reading `format_kind: sponsored_placement` MUST attach a catalog reference; sellers MUST require `source_catalog` in the manifest.
+ *
+ * **Not this canonical (route elsewhere):**
+ * - IAB in-feed native ads, content-recommendation widgets (Taboola, Outbrain, Yahoo Native, AdMob Native, in-feed sponsored cards) — use `native_in_feed` (asset-bundle composition; no catalog).
+ * - Algorithmic surface that picks from a buyer-supplied asset pool (Google PMax, Meta Advantage+) — use `responsive_creative`.
+ * - Single-image or single-video creative — use `image` or `video_hosted`.
+ *
+ * The earlier broader framing ('any sponsored placement') was too loose for buyer-agent routing — a buyer reading `sponsored_placement` couldn't disambiguate a catalog-driven Amazon SP from an in-feed Taboola widget. As of 3.1, the canonical is narrowed to catalog-keyed retail-media; native moves to `native_in_feed`. Distinct from `responsive_creative` (algorithmic combinator from buyer pool) and `agent_placement` (text/audio AI-surface composition).
+ */
+export interface CanonicalFormatSponsoredPlacementRetailMediaCatalogDriven {
+    /**
+     * Marked experimental at 3.1 GA: the canonical covers 4 meaningfully different retail-media adapter contracts (Amazon SP, Criteo SP / CitrusAd SP, Pinterest Collection, generative-per-SKU). Adopter contracts vary; buyers MUST validate per-adapter behavior before routing budget. Promotion to non-experimental gated on the #4592 adapter-contract docs work.
+     */
+    experimental?: unknown;
+    /**
+     * When true, this canonical (or a seller's specific narrowing of it) is going away. Existing adopters are supported through the deprecation cycle; new adoption is discouraged. Pair with `migration_target_version` to indicate when the canonical is expected to be removed. Distinct from `experimental`: an experimental canonical may stabilize and stop being experimental; a deprecated canonical is on a sunset path.
+     */
+    deprecated?: boolean;
+    /**
+     * Inherently new in v2 — retail-media catalog placements weren't expressible as v1 named formats. SDKs MUST NOT emit `FORMAT_PROJECTION_FAILED` for products using this canonical; the v1-unreachability is structural, not a registry-coverage gap.
+     */
+    v1_translatable?: unknown;
+    /**
+     * AdCP MAJOR.MINOR version that introduced this canonical (e.g., '3.1', '3.2'). Lets adopters reason about minimum protocol version requirements when consuming a format declaration. Patch precision is intentionally rejected — canonicals are introduced at minor-version boundaries.
+     */
+    since_version?: string;
+    /**
+     * AdCP MAJOR.MINOR version by which the working group expects this canonical to stabilize, surface a breaking revision, or (when `deprecated: true`) be removed. Patch precision is intentionally rejected — canonicals shift at minor-version boundaries. Absence signals 'no specific target' (omit the field rather than use a placeholder like 'unknown').
+     */
+    migration_target_version?: string;
+    /**
+     * Whether the surface composes deterministically (buyer can predict per-slot rendering — sponsored_placement, image, video) or algorithmically (surface chooses combinations or phrasing — responsive_creative, agent_placement).
+     */
+    composition_model?: 'deterministic' | 'algorithmic';
+    /**
+     * When true, the product rejects unsigned synthesized assets. Builders calling build_creative MUST attach a C2PA-compatible provenance manifest attributing synthesis to the creative agent.
+     */
+    provenance_required?: boolean;
+    /**
+     * Platform-specific extensions narrowing the canonical (pixel ID shapes, conversion event taxonomies, platform-specific CTAs/destinations). Each extension is a URI+digest reference resolved against the bundled `extensions` map in get_products responses or fetched directly.
+     *
+     * **Collision precedence (normative).** When two or more `platform_extensions[]` entries on the same declaration extend the same target (e.g., both extend `tracking`) with overlapping field names, **array order is authoritative — later entries override earlier ones on a per-field basis** (last-in-array-wins). SDKs MUST surface the overlap via the `errors[]` array on the `get_products` response with a structured code (`FORMAT_DECLARATION_DIVERGENT` is appropriate when the overlap appears across dual-emitted shapes; a producer-self-emitted overlap on a single declaration SHOULD use the same code with `error.details: { collision_kind: "platform_extension_field", target, overlapping_fields, winning_extension_uri }`). Producers SHOULD avoid the collision by emitting one extension per target or by partitioning fields across extensions; the deterministic precedence is for last-resort consistency across SDK implementations, not a sanctioned merging strategy.
+     */
+    platform_extensions?: PlatformExtensionReference[];
+    /**
+     * When true, the format's production pipeline is genuinely nondeterministic — the platform cannot guarantee that synthesis from a given input set produces in-spec output. Veo / Sora / Runway-class generative video, and other AI-synthesis flows where output dimensions, duration, or quality vary per run. Implies a different validation contract: predictive `validate_input` is impossible; the platform's own post-synthesis QA loop applies; if the QA loop exhausts without producing a valid artifact, `build_creative` returns task_failed with a synthesis_failed reason. Distinct from `composition_model` (which describes how the surface composes per-slot rendering, not whether synthesis is deterministic). When false or absent, the format's production is predictable enough that `validate_input` can predict output properties from input properties.
+     *
+     * **Compatibility with `asset_source` / `item_production_model`**: `synthesis_nondeterministic: true` MAY pair with any of `seller_pre_rendered_from_brief`, `seller_human_designed`, or `agent_synthesized` (the QA loop is concept-level, not source-specific — 'seller renders from brief but each retry differs' is just as nondeterministic as Veo). It MUST NOT pair with `buyer_uploaded` (the buyer ships pre-rendered bytes; there's no synthesis step to be nondeterministic about). It MUST NOT pair with `publisher_host_recorded` (the publisher's host produces a deterministic-from-script output even if the human voice varies). When `synthesis_nondeterministic: true` is set with an incompatible source, validators SHOULD reject with a structured error.
+     */
+    synthesis_nondeterministic?: boolean;
+    slots?: unknown;
+    /**
+     * Typical production turnaround in business days when the format requires seller-side production (e.g., host-recording from a buyer-supplied script). 0 for synchronous (e.g., generative AI); >0 for human-produced (e.g., podcast host-read). Absent when no production is required (buyer uploads complete creative).
+     */
+    production_window_business_days?: number;
+    /**
+     * Catalog types this product accepts.
+     */
+    supported_catalog_types?: ('product' | 'store' | 'offering' | 'hotel' | 'flight' | 'vehicle' | 'real_estate' | 'education' | 'destination' | 'app' | 'job' | 'inventory')[];
+    /**
+     * Minimum catalog item count buyer must supply.
+     * @minimum 1
+     */
+    min_items?: number;
+    /**
+     * Maximum items considered for placement.
+     */
+    max_items?: number;
+    /**
+     * How items map to delivery: per_item = one ad per catalog item; multi_item_in_creative = composed multi-item ad (Pinterest Collection, Snap Collection); single_item = one ad showing one item.
+     */
+    fanout_mode?: 'per_item' | 'multi_item_in_creative' | 'single_item';
+    /**
+     * Catalog item fields the seller requires (e.g., ['title', 'image_url', 'price']).
+     */
+    required_catalog_fields?: string[];
+    /**
+     * Catalog identifier types the placement renders against.
+     */
+    supported_id_types?: ('asin' | 'sku' | 'gtin' | 'offering_id' | 'store_id' | 'hotel_id' | 'flight_id' | 'vehicle_id' | 'listing_id' | 'program_id' | 'destination_id' | 'app_id' | 'job_id')[];
+    /**
+     * Whether the buyer can supply a hero/banner asset alongside the catalog (Pinterest Collection pattern).
+     */
+    hero_asset_supported?: boolean;
+    /**
+     * How each per-item creative is produced. Covers the same production-source axis as `asset_source` on `image` / `video_hosted` / `audio_hosted` but with a 4-value subset — drops `publisher_host_recorded` because it's audio-specific and doesn't apply to retail-media catalog placements. SDK codegen MAY share a base enum and narrow per-canonical, or emit two distinct enums; either way the wire values overlap exactly for the 4 retained values. `buyer_uploaded` (default, current Amazon/Criteo/CitrusAd pattern): the buyer's catalog already contains rendered assets per item; the seller composes the placement using those assets. ("Uploaded" reads slightly off for catalog-keyed items where the buyer didn't actively upload bytes — the catalog ingestion already supplied them — but the semantic is the same: rendered bytes are buyer-supplied, not seller-produced.) `seller_pre_rendered_from_brief`: the buyer ships a brief plus the catalog reference; the seller renders one creative per catalog item from the brief at sync_creatives time. `seller_human_designed`: seller's design team produces per-item renders manually. `agent_synthesized`: AI synthesis pipeline produces per-item renders; pair with `synthesis_nondeterministic: true` for Veo/Sora-class generative video applied per item. Captures the multi-output generative pattern (1 brief × N catalog items → N rendered creatives) under the existing canonical without requiring a separate canonical. Distinct from `fanout_mode`, which describes how items map to delivery slots after rendering.
+     */
+    item_production_model?: 'buyer_uploaded' | 'seller_pre_rendered_from_brief' | 'seller_human_designed' | 'agent_synthesized';
+}
+
+/**
+ * VAST-tag-delivered video creative. Slot: `vast_tag` (vast asset, URL or inline XML, VAST 2.x-4.x). Tracking model: VAST events inherent to the spec — `impression`, `firstQuartile`, `midpoint`, `thirdQuartile`, `complete`, `start`, `pause`, `resume`, `mute`, `unmute`, `expand`, `collapse`, `fullscreen`, `creativeView`, `clickTracking`, `error`. VPAID interactivity via `vpaid_enabled: true` flag. SIMID extensions for interactive video supported as VAST extensions. Orientation is a parameter (vertical / horizontal / square). Distinct from `video_hosted` (direct file with external tracking).
+ */
+export interface CanonicalFormatVASTVideo {
+    /**
+     * When true, this canonical (or a seller's specific narrowing of it) may not work as declared — adopters SHOULD have a v1 fallback ready and SHOULD NOT route production budget without testing. Same semantics as `experimental` on protocols: 'this is shipping but may break, evolve, or fail.' Buyers reading `experimental: true` SHOULD prefer the v1 path when a v1 fallback exists for the same product (via `format_ids` on the parent product or via the v2 declaration's `v1_format_ref`).
+     *
+     * Three drivers of `experimental: true`:
+     * 1. **Spec maturity** — the canonical's tracking model or parameter shape is still being settled (`agent_placement`'s tracking macros, `sponsored_placement`'s per-adapter contracts, `responsive_creative`'s algorithmic composition).
+     * 2. **Adopter runtime gap** — the seller has declared the canonical in their catalog but their runtime doesn't yet honor it cleanly.
+     * 3. **Custom shapes** — `format_kind: "custom"` is inherently experimental until the working group promotes a `format_shape` to a first-class canonical.
+     *
+     * Replaces the earlier `status` enum (`stable | preview | deprecated`) + `runtime_status` enum (`stable | preview | declared_only`) — two axes with subtle overlap. The single boolean is what buyers actually care about: do I treat this as production-stable or as 'try at my own risk.' Sellers SHOULD set `experimental: true` on canonicals or product declarations that aren't yet production-ready, regardless of which axis (spec, runtime, custom) drives the experimentation. The 6 IAB/VAST/DAAST re-encodings (`image`, `display_tag`, `video_hosted`, `video_vast`, `audio_hosted`, `audio_daast`) default to non-experimental at the canonical level; sellers MAY still mark a specific product declaration experimental (e.g., a beta runtime path for an existing product).
+     */
+    experimental?: boolean;
+    /**
+     * When true, this canonical (or a seller's specific narrowing of it) is going away. Existing adopters are supported through the deprecation cycle; new adoption is discouraged. Pair with `migration_target_version` to indicate when the canonical is expected to be removed. Distinct from `experimental`: an experimental canonical may stabilize and stop being experimental; a deprecated canonical is on a sunset path.
+     */
+    deprecated?: boolean;
+    /**
+     * Whether this canonical has any v1 named-format equivalent. `true` (default) — the canonical is structurally expressible as one or more v1 named formats (IAB display sizes, VAST tags, DAAST tags, etc.); v1→v2 projection via `v1-canonical-mapping.json` is meaningful. `false` — the canonical is inherently new in v2 and has no v1 form; v1's `list_creative_formats` couldn't express it because the underlying concept (algorithmic surface composition, AI-surface mentions, retail-media catalog placements, multi-card carousels) didn't exist as a v1 named-format archetype.
+     *
+     * Lets SDKs distinguish two failure modes that today look identical: (a) the registry hasn't covered this canonical yet (correctable — seller adds explicit `canonical` field or files a registry entry) vs (b) no v1 path is possible (informational — buyer needs v2-aware consumption, or seller declares `canonical_formats_only: true` on the product declaration). SDKs encountering `v1_translatable: false` on a canonical SHOULD NOT emit `FORMAT_PROJECTION_FAILED` (which signals registry-coverage gap) — instead surface the inherent v1-unreachability as a different diagnostic or skip silently. The 4 inherently-v2 canonicals at 3.1 GA: `image_carousel`, `sponsored_placement`, `responsive_creative`, `agent_placement`.
+     */
+    v1_translatable?: boolean;
+    /**
+     * AdCP MAJOR.MINOR version that introduced this canonical (e.g., '3.1', '3.2'). Lets adopters reason about minimum protocol version requirements when consuming a format declaration. Patch precision is intentionally rejected — canonicals are introduced at minor-version boundaries.
+     */
+    since_version?: string;
+    /**
+     * AdCP MAJOR.MINOR version by which the working group expects this canonical to stabilize, surface a breaking revision, or (when `deprecated: true`) be removed. Patch precision is intentionally rejected — canonicals shift at minor-version boundaries. Absence signals 'no specific target' (omit the field rather than use a placeholder like 'unknown').
+     */
+    migration_target_version?: string;
+    /**
+     * Whether the surface composes deterministically (buyer can predict per-slot rendering — sponsored_placement, image, video) or algorithmically (surface chooses combinations or phrasing — responsive_creative, agent_placement).
+     */
+    composition_model?: 'deterministic' | 'algorithmic';
+    /**
+     * When true, the product rejects unsigned synthesized assets. Builders calling build_creative MUST attach a C2PA-compatible provenance manifest attributing synthesis to the creative agent.
+     */
+    provenance_required?: boolean;
+    /**
+     * Platform-specific extensions narrowing the canonical (pixel ID shapes, conversion event taxonomies, platform-specific CTAs/destinations). Each extension is a URI+digest reference resolved against the bundled `extensions` map in get_products responses or fetched directly.
+     *
+     * **Collision precedence (normative).** When two or more `platform_extensions[]` entries on the same declaration extend the same target (e.g., both extend `tracking`) with overlapping field names, **array order is authoritative — later entries override earlier ones on a per-field basis** (last-in-array-wins). SDKs MUST surface the overlap via the `errors[]` array on the `get_products` response with a structured code (`FORMAT_DECLARATION_DIVERGENT` is appropriate when the overlap appears across dual-emitted shapes; a producer-self-emitted overlap on a single declaration SHOULD use the same code with `error.details: { collision_kind: "platform_extension_field", target, overlapping_fields, winning_extension_uri }`). Producers SHOULD avoid the collision by emitting one extension per target or by partitioning fields across extensions; the deterministic precedence is for last-resort consistency across SDK implementations, not a sanctioned merging strategy.
+     */
+    platform_extensions?: PlatformExtensionReference[];
+    /**
+     * When true, the format's production pipeline is genuinely nondeterministic — the platform cannot guarantee that synthesis from a given input set produces in-spec output. Veo / Sora / Runway-class generative video, and other AI-synthesis flows where output dimensions, duration, or quality vary per run. Implies a different validation contract: predictive `validate_input` is impossible; the platform's own post-synthesis QA loop applies; if the QA loop exhausts without producing a valid artifact, `build_creative` returns task_failed with a synthesis_failed reason. Distinct from `composition_model` (which describes how the surface composes per-slot rendering, not whether synthesis is deterministic). When false or absent, the format's production is predictable enough that `validate_input` can predict output properties from input properties.
+     *
+     * **Compatibility with `asset_source` / `item_production_model`**: `synthesis_nondeterministic: true` MAY pair with any of `seller_pre_rendered_from_brief`, `seller_human_designed`, or `agent_synthesized` (the QA loop is concept-level, not source-specific — 'seller renders from brief but each retry differs' is just as nondeterministic as Veo). It MUST NOT pair with `buyer_uploaded` (the buyer ships pre-rendered bytes; there's no synthesis step to be nondeterministic about). It MUST NOT pair with `publisher_host_recorded` (the publisher's host produces a deterministic-from-script output even if the human voice varies). When `synthesis_nondeterministic: true` is set with an incompatible source, validators SHOULD reject with a structured error.
+     */
+    synthesis_nondeterministic?: boolean;
+    /**
+     * Default slots for video_vast canonical. Buyer ships a VAST tag (URL or inline XML, VAST 2.x-4.x) plus an optional clickthrough URL (which falls back to the VAST `ClickThrough` element when omitted). Tracking events are inherent to VAST and don't require explicit slots.
+     */
+    slots?: unknown;
+    /**
+     * Typical production turnaround in business days when the format requires seller-side production (e.g., host-recording from a buyer-supplied script). 0 for synchronous (e.g., generative AI); >0 for human-produced (e.g., podcast host-read). Absent when no production is required (buyer uploads complete creative).
+     */
+    production_window_business_days?: number;
+    orientation?: 'vertical' | 'horizontal' | 'square';
+    /**
+     * @pattern ^[0-9]+(\.[0-9]+)?:[0-9]+(\.[0-9]+)?$
+     */
+    aspect_ratio?: string;
+    /**
+     * Required VAST version.
+     */
+    vast_version?: '2.0' | '3.0' | '4.0' | '4.1' | '4.2';
+    /**
+     * Whether VPAID interactivity is supported. When true, the VAST tag may carry VPAID JS/Flash payloads.
+     */
+    vpaid_enabled?: boolean;
+    vpaid_version?: '1.0' | '2.0';
+    /**
+     * Whether IAB SIMID interactive video extensions are supported.
+     */
+    simid_supported?: boolean;
+    /**
+     * [min, max] duration in milliseconds. **Precedence**: `duration_ms_exact` takes precedence when both ship. SDKs SHOULD lint a warning when both fields ship.
+     */
+    duration_ms_range?: number[];
+    /**
+     * When set, duration must equal exactly this value. Takes precedence over `duration_ms_range` when both ship.
+     * @minimum 1
+     */
+    duration_ms_exact?: number;
+    /**
+     * @minimum 1
+     */
+    min_width?: number;
+    /**
+     * @minimum 1
+     */
+    max_width?: number;
+    /**
+     * @minimum 1
+     */
+    min_height?: number;
+    /**
+     * @minimum 1
+     */
+    max_height?: number;
+    /**
+     * Whether the VAST creative must be linear (non-skippable in-stream).
+     */
+    linear_required?: boolean;
+    /**
+     * When skippable, the buyer-side skip threshold in milliseconds (e.g., 5000 for 5-second skippable pre-roll).
+     * @minimum 0
+     */
+    skippable_after_ms?: number;
+    /**
+     * Maximum VAST wrapper redirect depth permitted.
+     * @minimum 0
+     */
+    max_wrapper_depth?: number;
+    ssl_required?: boolean;
+}
+
+/**
+ * Optional v2 canonical-projection annotation. Always an object — bare-string shorthand (`canonical: "image"`) is not supported; the minimal form is `canonical: { "kind": "image" }`. Carries `kind` (which canonical the v1 format projects to) plus optional `asset_source` and `slots_override` for cases where the v1 format's shape doesn't follow the canonical's defaults (e.g., generative entries whose input is `generation_prompt: text` instead of `image_main: image`).
+ *
+ * When set, SDKs use this annotation as the authoritative v1 → v2 mapping for this format, bypassing the [v1 canonical mapping registry](/schemas/registries/v1-canonical-mapping.json) lookup. Combined with the slot-level `asset_group_id` declarations on each `assets[i]` entry, a v1 format declaration with `canonical` set is fully self-describing for v1↔v2 translation.
+ *
+ * Resolution order for SDK projection from v1 wire shape to v2 (per RFC #3305 amendment #3767):
+ * 1. If this `canonical` field is set, use it (seller-declared, highest priority). Apply `asset_source` and `slots_override` from the projection ref when present; otherwise inherit the canonical's defaults.
+ * 2. Else, look up `format_id` in the canonical mapping registry's `format_id_glob` entries.
+ * 3. Else, attempt structural match against the registry's `structural` entries (asset types, slot shape, vast_versions, etc.).
+ * 4. Else, fail closed: SDK MUST NOT emit `format_options` for products carrying this format. Surface `FORMAT_PROJECTION_FAILED` on the response `errors[]` suggesting the seller add an explicit `canonical` annotation or file a registry entry.
+ *
+ * When `canonical.kind` is `custom`, the seller MUST also declare `canonical_format_shape` and `canonical_format_schema` (parallel to ProductFormatDeclaration's `format_shape` and `format_schema`) so buyer SDKs can fetch the seller's custom format schema.
+ *
+ * See `canonical-projection-ref.json` for full projection semantics and examples (default-slot case, generative case, brief-driven case).
+ */
+export interface CanonicalProjectionReference {
+    kind: CanonicalFormatKind;
+    /**
+     * Where the rendered asset bytes come from on the projected v2 declaration. Default (when omitted) is `buyer_uploaded` — the canonical's default. Set explicitly when the v1 named format doesn't follow that default. Required for generative entries (`agent_synthesized` or `seller_pre_rendered_from_brief`) because their asset shape doesn't carry image/video/audio bytes — projection without this hint produces a lossy v2 declaration that claims buyer-uploaded bytes.
+     */
+    asset_source?: 'buyer_uploaded' | 'publisher_host_recorded' | 'seller_pre_rendered_from_brief' | 'seller_human_designed' | 'agent_synthesized';
+    /**
+     * When the v1 named format's slot shape differs from the canonical's default slots, this carries the override that the projected v2 declaration's `params.slots[]` should use. REPLACES (does not merge with) the canonical's default slots — projection-time semantics. The slot vocabulary follows `asset-group-vocabulary.json`. Asset IDs in the v1 format's `assets[*]` MUST resolve (directly or via the vocabulary's aliases) to the `asset_group_id` values declared here.
+     */
+    slots_override?: {
+        /**
+         * Asset group identifier from `asset-group-vocabulary.json` (e.g., `generation_prompt`, `creative_brief`, `image_main`, `video_main`).
+         */
+        asset_group_id: string;
+        /**
+         * Asset type — `image`, `video`, `audio`, `text`, `html`, `javascript`, `url`, `zip`, `brief`.
+         */
+        asset_type: string;
+        /**
+         * Whether the slot is required in the projected declaration.
+         */
+        required?: boolean;
+        /**
+         * Max character count for text slots.
+         * @minimum 1
+         */
+        max_chars?: number;
+        /**
+         * When false, slot is for moderation/review only and is NOT consumed by the seller's renderer (e.g., a brand-safety brief that informs review but doesn't appear in the rendered ad).
+         */
+        consumed_for_production?: boolean;
+    }[];
+}
+
+/**
+ * Opaque correlation data that is echoed unchanged in responses. Used for internal tracking, UI session IDs, trace IDs, and other caller-specific identifiers that don't affect protocol behavior. Context data is never parsed by AdCP agents - it's simply preserved and returned.
+ */
+export interface ContextObject {
+}
+
+/**
+ * Fixed cost per thousand impressions
+ */
+export interface CpmPricing {
+    model: 'cpm';
+    /**
+     * Cost per thousand impressions
+     * @minimum 0
+     */
+    cpm: number;
+    /**
+     * ISO 4217 currency code
+     * @pattern ^[A-Z]{3}$
+     */
+    currency: string;
+    ext?: ExtensionObject;
+}
+
+/**
+ * Capabilities supported by creative agents for format handling
+ */
+export type CreativeAgentCapability = 'validation' | 'assembly' | 'generation' | 'preview' | 'delivery';
+
+/**
+ * Adopter-defined shape that doesn't fit the 12 canonicals. Requires `format_shape` (vocabulary-registered global pattern) and `format_schema` (URI+digest reference to a fetchable schema describing the actual params/slots). `params` shape is governed by the fetched schema rather than baked into AdCP — kept as `type: object` here with `additionalProperties: true` because the canonical schema validates dynamically post-fetch.
+ */
+export interface CustomFormatDeclaration {
+    format_kind: 'custom';
+    /**
+     * Custom shape's params. Validated against the schema fetched from `format_schema.uri` at the cached `format_schema.digest`.
+     */
+    params: {};
+}
+
+/**
+ * Escape hatch for pricing constructs that do not fit cpm, percent_of_media, flat_fee, or per_unit. Use when a vendor prices via performance kickers, tiered volume, hybrid formulas, outcome-sharing, or any other model the standard forms cannot express. Requires a human-readable description and a structured metadata object that captures the parameters a buyer needs to reason about the charge. Buyers SHOULD route custom pricing through operator review before commitment — automatic selection is not recommended.
+ */
+export interface CustomPricing {
+    model: 'custom';
+    /**
+     * Human-readable description of the custom pricing model. Buyers display this to the operator when requesting approval.
+     * @minLength 1
+     */
+    description: string;
+    /**
+     * Structured parameters for the custom model. Keys follow lowercase_snake_case. Values may be primitives, arrays, or nested objects. Must be sufficient for a human to understand the pricing basis and for a downstream system to reconstruct the charge. Vendors SHOULD include a `summary_for_operator` string (one or two sentences, suitable for display in a buyer's operator-review UI) so reviewers across vendors see a consistent prompt. Required operator-review fields (approver role, dollar threshold for automatic approval, escalation contact) MAY be surfaced via additional keys the buyer's review surface recognizes.
+     */
+    metadata: {
+        /**
+         * One or two sentences describing the pricing construct in plain language, displayed to the buyer's operator when requesting approval. Should not repeat the top-level `description` verbatim — summarize the charge mechanic instead (e.g., 'Base $12 CPM plus $0.50 per qualifying post-view conversion, capped at $45 CPM').
+         * @minLength 1
+         */
+        summary_for_operator?: string;
+    };
+    /**
+     * ISO 4217 currency code. Present when the pricing resolves to a monetary charge in a specific currency.
+     * @pattern ^[A-Z]{3}$
+     */
+    currency?: string;
+    ext?: ExtensionObject;
+}
+
+/**
+ * Requirements for DAAST (Digital Audio Ad Serving Template) creative assets.
+ */
+export interface DAASTAssetRequirements {
+    /**
+     * Required DAAST version. DAAST 1.0 is the current IAB standard.
+     */
+    daast_version?: '1.0';
+}
+
+export interface DAASTAudioFormatDeclaration {
+    format_kind: 'audio_daast';
+    params: CanonicalFormatDAASTAudio;
+}
+
+/**
+ * Unit of measurement for width/height values. Defaults to 'px' when absent. Print formats use 'inches' or 'cm'.
+ */
+export type DimensionUnit = 'px' | 'dp' | 'inches' | 'cm' | 'mm' | 'pt';
+
+/**
+ * How long the disclosure must persist during content playback or display
+ */
+export type DisclosurePersistence = 'continuous' | 'initial' | 'flexible';
+
+/**
+ * Where a required disclosure should appear within a creative. Used by creative briefs to specify disclosure placement and by formats to declare which positions they can render.
+ */
+export type DisclosurePosition = 'prominent' | 'footer' | 'audio' | 'subtitle' | 'overlay' | 'end_card' | 'pre_roll' | 'companion';
+
+export interface DisplayTagFormatDeclaration {
+    format_kind: 'display_tag';
+    params: CanonicalFormatDisplayTag;
+}
+
+/**
+ * Extension object for platform-specific, vendor-namespaced parameters. Extensions are always optional and must be namespaced under a vendor/platform key (e.g., ext.gam, ext.roku). Used for custom capabilities, partner-specific configuration, and features being proposed for standardization.
+ */
+export interface ExtensionObject {
+}
+
+export interface Fixed {
+    [k: string]: unknown | undefined;
+}
+
+/**
+ * Fixed charge per billing period, regardless of impressions or spend. Used for licensed data bundles and audience subscriptions.
+ */
+export interface FlatFeePricing {
+    model: 'flat_fee';
+    /**
+     * Fixed charge for the billing period
+     * @minimum 0
+     */
+    amount: number;
+    /**
+     * Billing period for the flat fee.
+     */
+    period: 'monthly' | 'quarterly' | 'annual' | 'campaign';
+    /**
+     * ISO 4217 currency code
+     * @pattern ^[A-Z]{3}$
+     */
+    currency: string;
+    ext?: ExtensionObject;
+}
+
+/**
+ * Represents a creative format with its requirements
+ */
+export interface Format {
+    format_id: FormatReferenceStructuredObject;
+    /**
+     * Human-readable format name
+     */
+    name: string;
+    /**
+     * Plain text explanation of what this format does and what assets it requires
+     */
+    description?: string;
+    /**
+     * Optional URL to showcase page with examples and interactive demos of this format
+     */
+    example_url?: string;
+    /**
+     * List of parameters this format accepts in format_id. Template formats define which parameters (dimensions, duration, etc.) can be specified when instantiating the format. Empty or omitted means this is a concrete format with fixed parameters.
+     */
+    accepts_parameters?: FormatIDParameter[];
+    /**
+     * Specification of rendered pieces for this format. Most formats produce a single render. Companion ad formats (video + banner), adaptive formats, and multi-placement formats produce multiple renders. Each render specifies its role and dimensions.
+     */
+    renders?: ({
+        /**
+         * Semantic role of this rendered piece (e.g., 'primary', 'companion', 'mobile_variant')
+         */
+        role: string;
+        /**
+         * Dimensions for this rendered piece. Defaults to pixels when unit is absent.
+         */
+        dimensions: {
+            /**
+             * Fixed width. Interpretation depends on unit (default: pixels).
+             */
+            width?: number;
+            /**
+             * Fixed height. Interpretation depends on unit (default: pixels).
+             */
+            height?: number;
+            /**
+             * Minimum width for responsive renders
+             */
+            min_width?: number;
+            /**
+             * Minimum height for responsive renders
+             */
+            min_height?: number;
+            /**
+             * Maximum width for responsive renders
+             */
+            max_width?: number;
+            /**
+             * Maximum height for responsive renders
+             */
+            max_height?: number;
+            unit?: DimensionUnit;
+            /**
+             * Indicates which dimensions are responsive/fluid
+             */
+            responsive?: {
+                width: boolean;
+                height: boolean;
+            };
+            /**
+             * Fixed aspect ratio constraint (e.g., '16:9', '4:3', '1:1', '1.91:1')
+             * @pattern ^\d+(\.\d+)?:\d+(\.\d+)?$
+             */
+            aspect_ratio?: string;
+        };
+    } | {
+        /**
+         * Semantic role of this rendered piece (e.g., 'primary', 'companion', 'mobile_variant')
+         */
+        role: string;
+        parameters_from_format_id: true;
+    })[];
+    /**
+     * Array of all assets supported for this format. Each asset is identified by its asset_id, which must be used as the key in creative manifests. Use the 'required' boolean on each asset to indicate whether it's mandatory.
+     */
+    assets?: FormatAssetSlot[];
+    /**
+     * Delivery method specifications (e.g., hosted, VAST, third-party tags)
+     */
+    delivery?: {};
+    /**
+     * List of universal macros supported by this format (e.g., MEDIA_BUY_ID, CACHEBUSTER, DEVICE_ID). Used for validation and developer tooling. See docs/creative/universal-macros.mdx for full documentation.
+     */
+    supported_macros?: (UniversalMacro | string)[];
+    /**
+     * Array of format IDs this format accepts as input creative manifests. When present, indicates this format can take existing creatives in these formats as input. Omit for formats that work from raw assets (images, text, etc.) rather than existing creatives.
+     */
+    input_format_ids?: FormatReferenceStructuredObject[];
+    /**
+     * Array of format IDs that this format can produce as output. When present, indicates this format can build creatives in these output formats (e.g., a multi-publisher template format might produce standard display formats across many publishers). Omit for formats that produce a single fixed output (the format itself).
+     */
+    output_format_ids?: FormatReferenceStructuredObject[];
+    /**
+     * Optional standard visual card (300x400px) for displaying this format in user interfaces. Can be rendered via preview_creative or pre-generated.
+     */
+    format_card?: {
+        format_id: FormatReferenceStructuredObject;
+        /**
+         * Asset manifest for rendering the card, structure defined by the format
+         */
+        manifest: {};
+    };
+    /**
+     * Accessibility posture of this format. Declares the WCAG conformance level that creatives produced by this format will meet.
+     */
+    accessibility?: {
+        wcag_level: WCAGLevel;
+        /**
+         * When true, all assets with x-accessibility fields must include those fields. For inspectable assets (image, video, audio), this means providing accessibility metadata like alt_text or captions. For opaque assets (HTML, JavaScript), this means providing self-declared accessibility properties.
+         */
+        requires_accessible_assets?: boolean;
+    };
+    /**
+     * Disclosure positions this format can render. Buyers use this to determine whether a format can satisfy their compliance requirements before submitting a creative. When omitted, the format makes no disclosure rendering guarantees — creative agents SHOULD treat this as incompatible with briefs that require specific disclosure positions. Values correspond to positions on creative-brief.json required_disclosures.
+     */
+    supported_disclosure_positions?: DisclosurePosition[];
+    /**
+     * Structured disclosure capabilities per position with persistence modes. Declares which persistence behaviors each disclosure position supports, enabling persistence-aware matching against provenance render guidance and brief requirements. When present, supersedes supported_disclosure_positions for persistence-aware queries. The flat supported_disclosure_positions field is retained for backward compatibility. Each position MUST appear at most once; validators and agents SHOULD reject duplicates.
+     */
+    disclosure_capabilities?: {
+        position: DisclosurePosition;
+        /**
+         * Persistence modes this position supports
+         */
+        persistence: DisclosurePersistence[];
+    }[];
+    /**
+     * Optional detailed card with carousel and full specifications. Provides rich format documentation similar to ad spec pages.
+     */
+    format_card_detailed?: {
+        format_id: FormatReferenceStructuredObject;
+        /**
+         * Asset manifest for rendering the detailed card, structure defined by the format
+         */
+        manifest: {};
+    };
+    /**
+     * Metrics this format can produce in delivery reporting. Buyers receive the intersection of format reported_metrics and product available_metrics. If omitted, the format defers entirely to product-level metric declarations.
+     */
+    reported_metrics?: AvailableMetric[];
+    /**
+     * Pricing options for this format. Used by transformation and generation agents that charge per format adapted, per image generated, or per unit of work. Present when the request included include_pricing=true and account. Ad servers and library-based agents expose pricing on list_creatives instead.
+     */
+    pricing_options?: VendorPricingOption[];
+    canonical?: CanonicalProjectionReference;
+    canonical_parameters?: ProductFormatDeclaration;
+}
+
+export type FormatAssetSlot = IndividualAssetSlot | RepeatableGroupAsset;
+
+/**
+ * Types of parameters that template formats accept in format_id objects to create parameterized format identifiers
+ */
+export type FormatIDParameter = 'dimensions' | 'duration';
+
+/**
+ * A JSON object — never a plain string — that identifies a creative format by its declaring agent and local slug. Required properties: agent_url (URI of the agent that owns the format) and id (slug matching [a-zA-Z0-9_-]+). Example: {"agent_url": "https://creative.adcontextprotocol.org", "id": "display_300x250"}. Can reference: (1) a concrete format with fixed dimensions (id only), (2) a template format without parameters (id only), or (3) a template format with parameters (id + dimensions/duration). Template formats accept parameters in format_id while concrete formats have fixed dimensions in their definition. Parameterized format IDs create unique, specific format variants. Using a plain string here is a schema violation.
+ */
+export interface FormatReferenceStructuredObject {
+    /**
+     * URL of the agent that defines this format (e.g., 'https://creative.adcontextprotocol.org' for standard formats, or 'https://publisher.com/.well-known/adcp/sales' for custom formats). Callers comparing two `format-id` values MUST canonicalize `agent_url` per the AdCP URL canonicalization rules before treating two formats as the same. See docs/reference/url-canonicalization.
+     */
+    agent_url: string;
+    /**
+     * Format identifier within the agent's namespace (e.g., 'display_static', 'video_hosted', 'audio_standard'). When used alone, references a template format. When combined with dimension/duration fields, creates a parameterized format ID for a specific variant.
+     * @pattern ^[a-zA-Z0-9_-]+$
+     */
+    id: string;
+    /**
+     * Width in pixels for visual formats. When specified, height must also be specified. Both fields together create a parameterized format ID for dimension-specific variants.
+     * @minimum 1
+     */
+    width?: number;
+    /**
+     * Height in pixels for visual formats. When specified, width must also be specified. Both fields together create a parameterized format ID for dimension-specific variants.
+     * @minimum 1
+     */
+    height?: number;
+    /**
+     * Duration in milliseconds for time-based formats (video, audio). When specified, creates a parameterized format ID. Omit to reference a template format without parameters.
+     * @minimum 1
+     */
+    duration_ms?: number;
+}
+
+/**
+ * Whether the video uses a constant or variable frame rate. Broadcast and SSAI contexts require constant frame rate for seamless splicing.
+ */
+export type FrameRateType = 'constant' | 'variable';
+
+/**
+ * Group of Pictures structure. SSAI and broadcast require closed GOPs for clean splice points; open GOPs may produce artifacts at ad boundaries.
+ */
+export type GOPType = 'closed' | 'open';
+
+export type GroupAssetSlot = GroupImageAsset | GroupVideoAsset | GroupAudioAsset | GroupTextAsset | GroupMarkdownAsset | GroupHtmlAsset | GroupCssAsset | GroupJavaScriptAsset | GroupVastAsset | GroupDaastAsset | GroupUrlAsset | GroupWebhookAsset;
+
+/**
+ * Audio asset in group
+ */
+export type GroupAudioAsset = BaseGroupAsset & {
+    asset_type: 'audio';
+    requirements?: AudioAssetRequirements;
+};
+
+/**
+ * CSS asset in group
+ */
+export type GroupCssAsset = BaseGroupAsset & {
+    asset_type: 'css';
+    requirements?: CSSAssetRequirements;
+};
+
+/**
+ * DAAST asset in group
+ */
+export type GroupDaastAsset = BaseGroupAsset & {
+    asset_type: 'daast';
+    requirements?: DAASTAssetRequirements;
+};
+
+/**
+ * HTML asset in group
+ */
+export type GroupHtmlAsset = BaseGroupAsset & {
+    asset_type: 'html';
+    requirements?: HTMLAssetRequirements;
+};
+
+/**
+ * Image asset in group
+ */
+export type GroupImageAsset = BaseGroupAsset & {
+    asset_type: 'image';
+    requirements?: ImageAssetRequirements;
+};
+
+/**
+ * JavaScript asset in group
+ */
+export type GroupJavaScriptAsset = BaseGroupAsset & {
+    asset_type: 'javascript';
+    requirements?: JavaScriptAssetRequirements;
+};
+
+/**
+ * Markdown asset in group
+ */
+export type GroupMarkdownAsset = BaseGroupAsset & {
+    asset_type: 'markdown';
+    requirements?: MarkdownAssetRequirements;
+};
+
+/**
+ * Text asset in group
+ */
+export type GroupTextAsset = BaseGroupAsset & {
+    asset_type: 'text';
+    requirements?: TextAssetRequirements;
+};
+
+/**
+ * URL asset in group
+ */
+export type GroupUrlAsset = BaseGroupAsset & {
+    asset_type: 'url';
+    requirements?: URLAssetRequirements;
+};
+
+/**
+ * VAST asset in group
+ */
+export type GroupVastAsset = BaseGroupAsset & {
+    asset_type: 'vast';
+    requirements?: VASTAssetRequirements;
+};
+
+/**
+ * Video asset in group
+ */
+export type GroupVideoAsset = BaseGroupAsset & {
+    asset_type: 'video';
+    requirements?: VideoAssetRequirements;
+};
+
+/**
+ * Webhook asset in group
+ */
+export type GroupWebhookAsset = BaseGroupAsset & {
+    asset_type: 'webhook';
+    requirements?: WebhookAssetRequirements;
+};
+
+export interface HTML5FormatDeclaration {
+    format_kind: 'html5';
+    params: CanonicalFormatHTML5Banner;
+}
+
+/**
+ * Requirements for HTML creative assets. These define the execution environment constraints that the HTML must be compatible with.
+ */
+export interface HTMLAssetRequirements {
+    /**
+     * Maximum file size in kilobytes for the HTML asset
+     * @minimum 1
+     */
+    max_file_size_kb?: number;
+    /**
+     * Sandbox environment the HTML must be compatible with. 'none' = direct DOM access, 'iframe' = standard iframe isolation, 'safeframe' = IAB SafeFrame container, 'fencedframe' = Privacy Sandbox fenced frame
+     */
+    sandbox?: 'none' | 'iframe' | 'safeframe' | 'fencedframe';
+    /**
+     * Whether the HTML creative can load external resources (scripts, images, fonts, etc.). When false, all resources must be inlined or bundled.
+     */
+    external_resources_allowed?: boolean;
+    /**
+     * List of domains the HTML creative may reference for external resources. Only applicable when external_resources_allowed is true.
+     */
+    allowed_external_domains?: string[];
+}
+
+export interface HostedAudioFormatDeclaration {
+    format_kind: 'audio_hosted';
+    params: CanonicalFormatHostedAudio;
+}
+
+export interface HostedVideoFormatDeclaration {
+    format_kind: 'video_hosted';
+    params: CanonicalFormatHostedVideo;
+}
+
+/**
+ * Requirements for image creative assets. These define the technical constraints for image files.
+ */
+export interface ImageAssetRequirements {
+    /**
+     * Minimum width. Interpretation depends on unit (default: pixels). For exact dimensions, set min_width = max_width.
+     */
+    min_width?: number;
+    /**
+     * Maximum width. Interpretation depends on unit (default: pixels). For exact dimensions, set min_width = max_width.
+     */
+    max_width?: number;
+    /**
+     * Minimum height. Interpretation depends on unit (default: pixels). For exact dimensions, set min_height = max_height.
+     */
+    min_height?: number;
+    /**
+     * Maximum height. Interpretation depends on unit (default: pixels). For exact dimensions, set min_height = max_height.
+     */
+    max_height?: number;
+    unit?: DimensionUnit;
+    /**
+     * Required aspect ratio (e.g., '16:9', '1:1', '1.91:1')
+     * @pattern ^\d+(\.\d+)?:\d+(\.\d+)?$
+     */
+    aspect_ratio?: string;
+    /**
+     * Accepted image file formats
+     */
+    formats?: ('jpg' | 'jpeg' | 'png' | 'gif' | 'webp' | 'svg' | 'avif' | 'tiff' | 'pdf' | 'eps')[];
+    /**
+     * Minimum resolution in dots per inch. Always in DPI regardless of the dimension unit. Standard print requires 300 DPI, newspaper 150 DPI.
+     * @minimum 1
+     */
+    min_dpi?: number;
+    /**
+     * Required bleed area beyond the trim size. The submitted image must be larger than the declared dimensions: total width = trim width + left bleed + right bleed, total height = trim height + top bleed + bottom bleed. For uniform bleed: total = trim + (2 * uniform). Uses the same unit as the parent dimensions.
+     */
+    bleed?: {
+        /**
+         * Same bleed on all four sides
+         * @minimum 0
+         */
+        uniform: number;
+    } | {
+        /**
+         * @minimum 0
+         */
+        top: number;
+        /**
+         * @minimum 0
+         */
+        right: number;
+        /**
+         * @minimum 0
+         */
+        bottom: number;
+        /**
+         * @minimum 0
+         */
+        left: number;
+    };
+    /**
+     * Required color space. Print typically requires CMYK.
+     */
+    color_space?: 'rgb' | 'cmyk' | 'grayscale';
+    /**
+     * Maximum file size in kilobytes
+     * @minimum 1
+     */
+    max_file_size_kb?: number;
+    /**
+     * Whether the image must support transparency (requires PNG, WebP, or GIF)
+     */
+    transparency_required?: boolean;
+    /**
+     * Whether animated images (GIF, animated WebP) are accepted
+     */
+    animation_allowed?: boolean;
+    /**
+     * Maximum animation duration in milliseconds (if animation_allowed is true)
+     * @minimum 0
+     */
+    max_animation_duration_ms?: number;
+    /**
+     * Maximum weight in grams for the finished physical piece (print inserts, flyers). Affects postage calculations and production constraints. Only applicable to print channels.
+     */
+    max_weight_grams?: number;
+}
+
+export interface ImageCarouselFormatDeclaration {
+    format_kind: 'image_carousel';
+    params: CanonicalFormatImageCarousel;
+}
+
+export interface ImageFormatDeclaration {
+    format_kind: 'image';
+    params: CanonicalFormatImage;
+}
+
+export type IndividualAssetSlot = IndividualImageAsset | IndividualVideoAsset | IndividualAudioAsset | IndividualTextAsset | IndividualMarkdownAsset | IndividualHtmlAsset | IndividualCssAsset | IndividualJavaScriptAsset | IndividualVastAsset | IndividualDaastAsset | IndividualUrlAsset | IndividualWebhookAsset | IndividualBriefAsset | IndividualCatalogAsset;
+
+/**
+ * Audio asset
+ */
+export type IndividualAudioAsset = BaseIndividualAsset & {
+    asset_type: 'audio';
+    requirements?: AudioAssetRequirements;
+};
+
+/**
+ * Brief asset
+ */
+export type IndividualBriefAsset = BaseIndividualAsset & {
+    asset_type: 'brief';
+};
+
+/**
+ * Catalog asset
+ */
+export type IndividualCatalogAsset = BaseIndividualAsset & {
+    asset_type: 'catalog';
+};
+
+/**
+ * CSS asset
+ */
+export type IndividualCssAsset = BaseIndividualAsset & {
+    asset_type: 'css';
+    requirements?: CSSAssetRequirements;
+};
+
+/**
+ * DAAST asset
+ */
+export type IndividualDaastAsset = BaseIndividualAsset & {
+    asset_type: 'daast';
+    requirements?: DAASTAssetRequirements;
+};
+
+/**
+ * HTML asset
+ */
+export type IndividualHtmlAsset = BaseIndividualAsset & {
+    asset_type: 'html';
+    requirements?: HTMLAssetRequirements;
+};
+
+/**
+ * Image asset
+ */
+export type IndividualImageAsset = BaseIndividualAsset & {
+    asset_type: 'image';
+    requirements?: ImageAssetRequirements;
+};
+
+/**
+ * JavaScript asset
+ */
+export type IndividualJavaScriptAsset = BaseIndividualAsset & {
+    asset_type: 'javascript';
+    requirements?: JavaScriptAssetRequirements;
+};
+
+/**
+ * Markdown asset
+ */
+export type IndividualMarkdownAsset = BaseIndividualAsset & {
+    asset_type: 'markdown';
+    requirements?: MarkdownAssetRequirements;
+};
+
+/**
+ * Text asset
+ */
+export type IndividualTextAsset = BaseIndividualAsset & {
+    asset_type: 'text';
+    requirements?: TextAssetRequirements;
+};
+
+/**
+ * URL asset
+ */
+export type IndividualUrlAsset = BaseIndividualAsset & {
+    asset_type: 'url';
+    requirements?: URLAssetRequirements;
+};
+
+/**
+ * VAST asset
+ */
+export type IndividualVastAsset = BaseIndividualAsset & {
+    asset_type: 'vast';
+    requirements?: VASTAssetRequirements;
+};
+
+/**
+ * Video asset
+ */
+export type IndividualVideoAsset = BaseIndividualAsset & {
+    asset_type: 'video';
+    requirements?: VideoAssetRequirements;
+};
+
+/**
+ * Webhook asset
+ */
+export type IndividualWebhookAsset = BaseIndividualAsset & {
+    asset_type: 'webhook';
+    requirements?: WebhookAssetRequirements;
+};
+
+/**
+ * Requirements for JavaScript creative assets. These define the execution environment constraints that the JavaScript must be compatible with.
+ */
+export interface JavaScriptAssetRequirements {
+    /**
+     * Maximum file size in kilobytes for the JavaScript asset
+     * @minimum 1
+     */
+    max_file_size_kb?: number;
+    /**
+     * Required JavaScript module format. 'script' = classic script, 'module' = ES modules, 'iife' = immediately invoked function expression
+     */
+    module_type?: 'script' | 'module' | 'iife';
+    /**
+     * Whether the JavaScript must use strict mode
+     */
+    strict_mode_required?: boolean;
+    /**
+     * Whether the JavaScript can load external resources dynamically
+     */
+    external_resources_allowed?: boolean;
+    /**
+     * List of domains the JavaScript may reference for external resources. Only applicable when external_resources_allowed is true.
+     */
+    allowed_external_domains?: string[];
+}
+
+/**
+ * Requirements for markdown creative assets.
+ */
+export interface MarkdownAssetRequirements {
+    /**
+     * Maximum character length
+     * @minimum 1
+     */
+    max_length?: number;
+}
+
+/**
+ * Standardized advertising media channels describing how buyers allocate budget. Channels are planning abstractions, not technical substrates. See the Media Channel Taxonomy specification for detailed definitions.
+ */
+export type MediaChannel = 'display' | 'olv' | 'social' | 'search' | 'ctv' | 'linear_tv' | 'radio' | 'streaming_audio' | 'podcast' | 'dooh' | 'ooh' | 'print' | 'cinema' | 'email' | 'gaming' | 'retail_media' | 'influencer' | 'affiliate' | 'product_placement' | 'sponsored_intelligence';
+
+/**
+ * Position of the moov atom in an MP4 container. 'start' enables progressive download without buffering the entire file; required for streaming ad delivery.
+ */
+export type MoovAtomPosition = 'start' | 'end';
+
+export interface MultiSize {
+    [k: string]: unknown | undefined;
+}
+
+export interface NativeInFeedFormatDeclaration {
+    format_kind: 'native_in_feed';
+    params: CanonicalFormatNativeInFeed;
+}
+
+export interface None {
+    [k: string]: unknown | undefined;
+}
+
+/**
+ * A publisher-controlled element that renders on top of buyer creative content within the ad placement. Creative agents should avoid placing critical content (CTAs, logos, key copy) within overlay bounds.
+ */
+export interface Overlay {
+    /**
+     * Identifier for this overlay (e.g., 'play_pause', 'volume', 'publisher_logo', 'carousel_prev', 'carousel_next')
+     */
+    id: string;
+    /**
+     * Human-readable explanation of what this overlay is and how buyers should account for it
+     */
+    description?: string;
+    /**
+     * Optional visual reference for this overlay element. Useful for creative agents compositing previews and for buyers understanding what will appear over their content. Must include at least one of: url, light, or dark.
+     */
+    visual?: {
+        /**
+         * URL to a theme-neutral overlay graphic (SVG or PNG). Use when a single file works for all backgrounds, e.g. an SVG using CSS custom properties or currentColor.
+         */
+        url?: string;
+        /**
+         * URL to the overlay graphic for use on light/bright backgrounds (SVG or PNG)
+         */
+        light?: string;
+        /**
+         * URL to the overlay graphic for use on dark backgrounds (SVG or PNG)
+         */
+        dark?: string;
+    };
+    /**
+     * Position and size of the overlay relative to the asset's own top-left corner. See 'unit' for coordinate interpretation.
+     */
+    bounds: {
+        /**
+         * Horizontal offset from the asset's left edge
+         */
+        x: number;
+        /**
+         * Vertical offset from the asset's top edge
+         */
+        y: number;
+        /**
+         * Width of the overlay
+         * @minimum 0
+         */
+        width: number;
+        /**
+         * Height of the overlay
+         * @minimum 0
+         */
+        height: number;
+        /**
+         * 'px' = absolute pixels from asset top-left. 'fraction' = proportional to asset dimensions (0.0 = edge, 1.0 = opposite edge). 'inches', 'cm', 'mm', 'pt' (1/72 inch) = physical units for print overlays, measured from asset top-left.
+         */
+        unit: 'px' | 'fraction' | 'inches' | 'cm' | 'mm' | 'pt';
+    };
+}
+
+/**
+ * Standard cursor-based pagination parameters for list operations
+ */
+export interface PaginationRequest {
+    /**
+     * Maximum number of items to return per page
+     * @minimum 1
+     * @maximum 100
+     */
+    max_results?: number;
+    /**
+     * Opaque cursor from a previous response to fetch the next page
+     */
+    cursor?: string;
+}
+
+/**
+ * Standard cursor-based pagination metadata for list responses
+ */
+export interface PaginationResponse {
+    /**
+     * Whether more results are available beyond this page
+     */
+    has_more: boolean;
+    /**
+     * Opaque cursor to pass in the next request to fetch the next page. Only present when has_more is true.
+     */
+    cursor?: string;
+    /**
+     * Total number of items matching the query across all pages. Optional because not all backends can efficiently compute this.
+     * @minimum 0
+     */
+    total_count?: number;
+}
+
+/**
+ * Fixed price per unit of work. Used for creative transformation (per format), AI generation (per image, per token), and rendering (per variant). The unit field describes what is counted; unit_price is the cost per one unit.
+ */
+export interface PerUnitPricing {
+    model: 'per_unit';
+    /**
+     * What is counted — e.g. 'format', 'image', 'token', 'variant', 'render', 'evaluation'.
+     */
+    unit: string;
+    /**
+     * Cost per one unit
+     * @minimum 0
+     */
+    unit_price: number;
+    /**
+     * ISO 4217 currency code
+     * @pattern ^[A-Z]{3}$
+     */
+    currency: string;
+    ext?: ExtensionObject;
+}
+
+/**
+ * Percentage of media spend charged for this signal. When max_cpm is set, the effective rate is capped at that CPM — useful for platforms like The Trade Desk that use percent-of-media pricing with a CPM ceiling.
+ */
+export interface PercentOfMediaPricing {
+    model: 'percent_of_media';
+    /**
+     * Percentage of media spend, e.g. 15 = 15%
+     * @minimum 0
+     * @maximum 100
+     */
+    percent: number;
+    /**
+     * Optional CPM cap. When set, the effective charge is min(percent × media_spend_per_mille, max_cpm).
+     * @minimum 0
+     */
+    max_cpm?: number;
+    /**
+     * ISO 4217 currency code for the resulting charge
+     * @pattern ^[A-Z]{3}$
+     */
+    currency: string;
+    ext?: ExtensionObject;
+}
+
+/**
+ * REQUIRED when `format_kind: "custom"`; otherwise MUST be absent. URI+digest reference to a fetchable schema describing this custom shape's actual `params` and `slots`. Same hosting model as `platform_extensions`: open-ecosystem publishers host the artifact at the canonical URI on their subdomain; closed-platform / walled-garden shapes resolve through the AAO mirror at `https://creative.adcontextprotocol.org/translated/...`. Buyer agents fetch by `uri@digest` (immutable per digest, aggressive caching, `Cache-Control: public, max-age=31536000, immutable`), validate `params` and `slots` against the fetched schema, and reason about manifests structurally — same mechanic as platform_extensions but at the format-structure level. Without `format_schema`, custom shapes would be opaque to buyer agents and the protocol would regress to per-seller integration code; that's why the schema is required, not optional.
+ *
+ * **Fetch contract (normative)** — `format_schema` is load-bearing for validation (unlike `platform_extensions`, which is informational on the *consumption* side). The *transport* rules below apply identically to BOTH fields — any SDK fetching a `platform-extension-ref.json` URI MUST apply this contract regardless of whether the field name is `format_schema` or `platform_extensions`. A shared SDK fetch path that drops to the weakest bar undermines `format_schema`'s hardening. The consumption distinction (load-bearing vs informational) is about *what the body means*; the transport distinction is `https`-and-allowlisted regardless.
+ *
+ * - **Transport**: `https` only. Buyers MUST reject `http://`, `file://`, `data:`, and any non-`https` scheme. The URI MUST resolve to a JSON document that is itself a valid JSON Schema (Draft 07 or 2020-12; producers MUST declare `$schema`).
+ * - **SSRF protection**: buyers MUST resolve the URI hostname and reject if any resolved address is in RFC 1918 private space (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`), loopback (`127.0.0.0/8`, `::1`), link-local (`169.254.0.0/16`, `fe80::/10`), CGNAT (`100.64.0.0/10`), or any RFC 6761 special-use name (`.local`, `.localhost`, `.internal`, `.test`, `.example`, `.invalid`). Cloud metadata endpoints (`169.254.169.254`, `metadata.google.internal`, `kubernetes.default.svc`) are explicitly forbidden — these are credential-leak primitives. Buyers MUST pin the connection to the resolved IP (or re-resolve and re-validate the allowlist per request) to defeat DNS rebinding.
+ * - **HTTP redirects**: MUST be disabled. If a follow is implemented at all, the redirect target MUST pass the same scheme + SSRF + allowlist checks; otherwise the fetch hard-fails. Open redirects on same-origin paths are otherwise a free SSRF primitive.
+ * - **Response size cap**: response body MUST be capped at 1 MiB. Enforce during streaming, not after full buffering. Over-cap hard-fails identically to digest mismatch.
+ * - **Timeout**: SDKs SHOULD apply a fetch timeout ≤5 seconds. Timeout SHOULD be treated identically to an HTTP 5xx response (transient — retry policy at the SDK's discretion; on persistent failure surface as unresolved and skip the declaration for this session).
+ * - **Digest verification**: SHA-256 of the response body MUST equal `digest`. **Digest mismatch is a hard fail** — the buyer MUST treat the format declaration as unresolvable and MUST NOT validate manifests against the mismatched body. A divergent digest is either a malicious substitution or producer error; either way, falling back to the un-verified body breaks the trust model. Digest format: `sha256:` prefix + 64 lowercase hex characters. Cache key is `uri@digest`; digest mismatch MUST NOT be cached as a negative result keyed on `uri` alone (defeats CDN-flap recovery), and MUST be distinguishable in telemetry from network 5xx / 404 (sustained mismatch is a substitution-attack signal, not a flap).
+ * - **Sandboxing of `$ref`**: fetched schemas MAY use `$ref`. Buyers MUST resolve `$ref` only to URIs that are (a) same-origin as the parent `format_schema.uri` after RFC 3986 §6 normalization (lowercase scheme + host, strip default port, normalize path dot-segments, no userinfo component), OR (b) hosted under the AAO catalog domain (`https://creative.adcontextprotocol.org/...`), OR (c) intra-document JSON Pointer refs (`#/...`) bounded to the parent document's parsed tree. Cross-origin `$ref` to arbitrary URIs MUST be rejected. `$ref: file://...` MUST be rejected unconditionally. Transitive `$ref` chains MUST be bounded at depth ≤8 AND `$ref` count ≤256 across the resolved tree (depth 8 with breadth 100 per level is 10^16 nodes — depth alone is not enough). Publishers SHOULD inline rather than $ref where possible.
+ * - **Schema-compile bounds (DoS protection)**: validators MUST bound CPU/memory on fetched schemas. Recommended: compiled-schema keyword count ≤10 000, `pattern` regexes evaluated with a non-backtracking engine (re2) OR under a per-pattern timeout, per-manifest validation budget ≤250 ms (exceeded budget → treat manifest as invalid, surface telemetry signal). Without these, a 'valid' schema with catastrophic regex backtracking or exponential `allOf`/`anyOf` expansion pins a CPU forever.
+ * - **Cache**: buyers cache fetched schemas by `uri@digest` and treat them as immutable (the same hosting contract as `platform_extensions`). On `404`, network partition, or persistent fetch failure, buyers SHOULD degrade gracefully (treat the declaration as unresolved, skip it for the current `get_products` response, surface via `errors[]` with the relevant code) rather than failing the entire session.
+ * - **Schema-not-valid handling**: if the fetched body parses as JSON but is not a valid JSON Schema, the buyer MUST treat the declaration as unresolvable (same as digest mismatch) and surface via `errors[]`. Validators MUST NOT attempt partial validation against an invalid schema.
+ * - **AAO catalog trust**: `https://creative.adcontextprotocol.org/*` is a single trust anchor in the same-origin allowlist; compromise of the catalog domain or its CA compromises every buyer agent. Catalog-served bodies MUST be digest-pinned identically to origin fetches (the digest is on the *parent* `format_schema.uri@digest`, not on the catalog response). Future hardening (signed bodies, transparency log) is tracked separately.
+ */
+export interface PlatformExtensionReference {
+    /**
+     * HTTPS URL identifying the extension. `https://` is mandatory — `http://`, `file://`, `data:`, and other schemes are rejected at the schema layer (defense-in-depth on top of the fetch-contract normative rules). The URI base is the owning agent's URL; the path identifies the extension within that agent. Example: 'https://creative.adcontextprotocol.org/translated/meta/extensions/meta_pixel'. The full fetch contract — SSRF allowlist, response-size cap, $ref sandbox, schema-compile bounds — is documented on `product-format-declaration.json#format_schema` and applies to ALL fetches of this reference shape regardless of whether the field is named `format_schema` (load-bearing for validation) or `platform_extensions` (informational); the *transport* rules are identical, only the *consumption* semantics differ.
+     * @pattern ^https:\/\/
+     */
+    uri: string;
+    /**
+     * SHA-256 content digest of the extension definition (sha256:<hex>). Used to detect drift — if the agent revises the extension, the digest changes and cached definitions become invalid.
+     * @pattern ^sha256:[a-f0-9]{64}$
+     */
+    digest: string;
+}
+
+/**
+ * Inline format declaration on a product. The `format_kind` discriminator names which canonical format the product narrows; `params` carries the canonical's parameter schema (slots, dimensions, durations, codecs, character limits, platform_extensions, etc.). Optional `capability_id` (stable identifier for routing when a product's `format_options` contains multiple declarations sharing the same `format_kind`), `display_name` (seller-controlled human-readable label for dashboard and catalog UIs), and `applies_to_channels` (subset of the product's declared channels this declaration applies to — lets a multi-channel product carry distinct format_options per channel). Discriminated-union shape generates clean tagged unions in TypeScript and Pydantic codegen. Replaces v1's named-format pattern (where products referenced a separately-defined format file via compound `format_id`). v1 named formats remain supported through the deprecation cycle; v2 product-bound declarations are opt-in.
+ *
+ * **Closed-set semantics (normative).** `format_options[]` is the closed set of accepted formats for this product. Sellers MUST reject `create_media_buy` requests targeting any `format_kind` (or `capability_id`) not present in this list — typically with `UNSUPPORTED_FEATURE` or a seller-specific code; the rejection is structural, not negotiable. `seller_preference` modulates *within* the accepted set (a soft ranking hint between equally-acceptable options), it is NOT an enforcement axis. A product wanting to say 'this format is the only one that works' lists exactly that one entry in `format_options[]`; everything else falls outside the set and is rejected by the closed-set rule.
+ *
+ * **Custom format_kind** (`format_kind: "custom"`): for adopter-defined shapes that don't fit the 12 canonicals (multi-placement takeover, roadblock, branded content, cross-screen sponsorship, sponsorship lockup, newsletter sponsorship, AR lens, playable, live event sponsorship). When `format_kind` is `custom`, the declaration MUST carry `format_shape` (recognized global pattern from the [format-shape vocabulary registry](/schemas/core/format-shape-vocabulary.json)) AND `format_schema` (URI+digest reference to a fetchable schema describing the actual `params` and `slots`). Buyer agents fetch the schema, validate manifests structurally, and reason about manifests without per-seller integration code. See [adcp#3666](https://github.com/adcontextprotocol/adcp/issues/3666) for the canonical promotion queue.
+ */
+export type ProductFormatDeclaration = {
+    [k: string]: unknown | undefined;
+} & {
+    /**
+     * Stable identifier for this format declaration. REQUIRED when the parent product's `format_options` contains multiple declarations sharing the same `format_kind` (so buyers can disambiguate which option a manifest targets via `manifest.capability_id`). SHOULD be set on EVERY `format_options[]` entry — not just when structurally required to break a `format_kind` collision — so V2-mental-model buyers can use the V2 authoring path (`PackageRequest.capability_ids[]`, `creative-manifest.capability_id`) against the product. A product that ships without `capability_id` on its `format_options[]` entries is structurally 3.1-conformant but is not V2-authorable: buyers fall back to v1 `format_ids[]` and lose the cross-publisher-stable naming the V2 path was designed to provide. Sellers MUST reject V2 authoring against such products with `UNSUPPORTED_FEATURE` and `error.details.reason` set to `capability_ids_not_published` per `package-request.json`. The 4.0 cutover will tighten this from SHOULD to MUST (see #4857). Format-internal (not a URI). Examples: 'flashtalking_image_300x250', 'pmax_responsive_search', 'nytimes_homepage_image'.
+     */
+    capability_id?: string;
+    /**
+     * Optional seller-controlled human-readable label for this format declaration. Used by buyer dashboards, catalog UIs, and reporting surfaces to show a seller's own naming ('Homepage Takeover', 'Branded Canvas', 'Reels Premium Video') rather than the raw `format_kind` or `capability_id`. Has no machine semantics — buyer agents route on `format_kind` and `capability_id`; `display_name` is purely for human presentation. Freeform; no enumeration. Sellers SHOULD keep it stable once published to avoid dashboard churn.
+     */
+    display_name?: string;
+    /**
+     * Optional subset of the parent product's `channels` to which this declaration applies. When omitted, the declaration applies to ALL channels declared on the product. Lets a multi-channel product (e.g., `channels: ['display', 'video']`) carry distinct format_options per channel — `format_options: [{format_kind: 'image', applies_to_channels: ['display']}, {format_kind: 'video_hosted', applies_to_channels: ['video']}]`. Buyers ship channel-appropriate manifests per `applies_to_channels`.
+     */
+    applies_to_channels?: MediaChannel[];
+    /**
+     * Optional soft routing hint *within* a product's accepted set of formats — NOT an enforcement axis. `preferred` — seller actively recommends this format (often because of measurement, viewability, or render-quality differences); `accepted` — supported on equal footing with other format_options (default when omitted); `discouraged` — supported but suboptimal (e.g., legacy 3p-tag where the seller would prefer html5 for OM-SDK coverage). Buyer agents picking between format_options SHOULD respect seller preferences when their own constraints don't override.
+     *
+     * **Not an enforcement axis (normative).** `seller_preference` does NOT carry the meaning of 'this format won't work / required-only'. That case is structural: `format_options[]` IS the closed set of accepted formats; anything outside the list is rejected at `create_media_buy` regardless of preference. A seller that accepts only one format lists exactly that one entry — the structural fact does the enforcement work, no enum value needed. There is intentionally no `required` value; preference is bounded to *ranking within the already-accepted set*, not gating into it.
+     */
+    seller_preference?: 'preferred' | 'accepted' | 'discouraged';
+    /**
+     * When true, this format declaration has no clean v1 projection and SDKs MUST NOT synthesize a v1 `format_id` for it. Buyers reading the product on the v1 wire path see this declaration absent from `format_ids`; only v2-aware buyers (reading `format_options`) discover it. Set explicitly for `format_kind: "custom"` declarations (no canonical exists in v1 to project onto) and for declarations whose canonical/parameter shape cannot round-trip through a v1 named format without semantic loss. The protocol does NOT mint synthetic v1 format_ids for unmappable declarations — the alternative (an `aao-synth/*` namespace populated automatically) was considered and rejected because adopters would index on synthetic IDs that have no stable identity. Producers SHOULD set `canonical_formats_only: true` rather than omit the declaration from `format_options` — explicit v2-only is more useful than silent absence.
+     */
+    canonical_formats_only?: boolean;
+    /**
+     * When true, THIS seller's specific product declaration may not work as declared — even if the underlying canonical is stable. Use for beta runtime paths, forward-looking catalog entries the runtime doesn't yet honor, or experimental products where the seller wants buyer-side caution. Buyers reading `experimental: true` on a product declaration SHOULD prefer the v1 path when a v1 fallback exists for the same product (via `format_ids` on the parent product or via this declaration's `v1_format_ref`) and SHOULD validate via `validate_input` or a sandbox before routing production budget.
+     *
+     * Independent of the canonical's own `experimental` flag — a stable canonical (e.g., `image`, `video_hosted`) can carry an experimental product declaration when the seller is shipping a new runtime path that isn't fully wired yet. Conversely, an experimental canonical (`sponsored_placement`, `responsive_creative`, `agent_placement`) MAY carry non-experimental product declarations where the seller's adopter contract is well-tested. Buyer SDKs SHOULD filter products with `experimental: true` from default views and offer an opt-in flag to surface them.
+     *
+     * Replaces the earlier `runtime_status` enum (`stable | preview | declared_only`) — same semantic ('use with caution') without the cognitive overhead of two stability axes.
+     */
+    experimental?: boolean;
+    /**
+     * REQUIRED when `format_kind: "custom"`; otherwise MUST be absent. Recognized global pattern this custom shape is an instance of, drawn from the [format-shape vocabulary registry](/schemas/core/format-shape-vocabulary.json) (`multi_placement_takeover`, `roadblock`, `branded_content`, `cross_screen_sponsorship`, `sponsorship_lockup`, `newsletter_sponsorship`, `ar_lens`, `playable`, `live_event_sponsorship`, …). Non-canonical values valid (validators MAY soft-warn) — adopters CAN ship a shape that isn't yet in the registry. Adding entries is a vocabulary PR. Once a `format_shape` entry sees 2+ adopters with substantively similar `format_schema` content for 90+ days, the working group promotes it to a first-class canonical.
+     */
+    format_shape?: string;
+    /**
+     * Authoritative v2 → v1 link, expressed as an array of one or more v1 `format_id` ({agent_url, id}) values. Each entry asserts that this canonical-formats declaration IS the same underlying format as the referenced v1 named format. Always an array (single-ref is `[{...}]`) so the multi-size case below has a clean wire shape — adopters surveyed in the SDK implementor review pushed for this over the lossy single-ref form.
+     *
+     * The v2 declaration's `params` MUST narrow (be compatible with) each referenced v1 format's `requirements` — see the 'Narrows — formal definition' section in canonical-formats.mdx. SDKs comparing dual-emitted shapes (`Product.format_ids[]` ⊇ entries from `v1_format_ref` AND `Product.format_options[]` carrying this declaration) treat the link as the authoritative pairing and run the narrowing check between this declaration and EACH referenced v1 format file's `requirements`.
+     *
+     * **Multi-size fan-out (normative).** When the declaration carries `params.sizes: [{w,h}, ...]` (multi-size flexible slot), sellers SHOULD carry one `v1_format_ref[]` entry per size, each pointing at the per-size v1 named format in the AAO catalog. Example: a multi-size image declaration with `sizes: [300x250, 728x90, 970x250]` SHOULD carry `v1_format_ref: [{aao, display_300x250_image}, {aao, display_728x90_image}, {aao, display_970x250_image}]`. v1-only buyers then see the product on all three sizes via the `format_ids[]` dual-emission. When `v1_format_ref[]` count < `sizes[]` count, SDKs MUST emit `FORMAT_DECLARATION_V1_LOSSY_MULTI_SIZE` on the response `errors[]` (advisory, alongside the partial-coverage v1 emit — NOT in place of it). SDKs MAY (non-normative) fan out automatically by catalog lookup when `v1_format_ref[]` has length 1 and `sizes[]` has length N — opt-in, requires catalog access; sellers asserting refs is the source of truth.
+     *
+     * Mutually exclusive with `canonical_formats_only: true` — a declaration can EITHER assert no v1 projection (`canonical_formats_only: true`) OR link to v1 named formats (`v1_format_ref[]`), never both. When neither is present, SDKs fall back to the resolution order in `v1-canonical-mapping.json` (seller's explicit `canonical` field on the v1 file → registry glob → structural match → fail-closed).
+     *
+     * This is the v2-side authoritative replacement for the v1-side `canonical_parameters` field on `format.json` (which is deprecated for 3.1, removed at 4.0). Sellers SHOULD prefer authoring v2 declarations with `v1_format_ref[]` over mirroring the v2 shape onto v1 files via `canonical_parameters`; the directional link (v2 declaration → v1 identifiers) is the same fact without the parallel-shape drift surface.
+     *
+     * **AAO-hosted convention (normative).** For IAB-standard formats (image dimensions, VAST/DAAST tags, standard third-party tags, HTML5 banner bundles), sellers SHOULD point each `v1_format_ref[].agent_url` at the AAO-hosted canonical agent URL `https://creative.adcontextprotocol.org` and use the registry-published id (e.g., `display_300x250_image`, `video_vast_30s`, `audio_standard_30s`, `display_300x250_html`, `display_js`). This converges the v1-wire namespace: every seller's IAB MREC points at the same `{agent_url, id}` pair, so v1-only buyers' allowlists work uniformly. Without this convention, every publisher's 300x250 ships with a different `v1_format_ref` (theirs vs nytimes.example vs cnn.example vs …) and the v1 wire fragments into per-publisher namespaces — exactly what canonical-formats was designed to eliminate.
+     *
+     * For platform-specific formats (Meta Reels, TikTok Spark, Snap Spotlight, etc.), each `v1_format_ref[].agent_url` SHOULD point at the platform's own agent_url when the platform has adopted AdCP and publishes its own `adagents.json` with `formats[]`. When the platform has NOT adopted AdCP, sellers SHOULD point at the AAO community-registry mirror — `https://creative.adcontextprotocol.org/translated/<platform>` + `id: <platform-format-name>` (e.g., `https://creative.adcontextprotocol.org/translated/meta` + `id: meta_reels`). This keeps the v1 namespace converged across all sellers selling that platform's inventory until the platform owns its own adagents.json.
+     *
+     * **Platform-adoption cutover (normative).** When a platform adopts AdCP and publishes its own adagents.json, sellers MUST update `v1_format_ref[].agent_url` to the platform's adopted agent_url in the same minor release as the AAO mirror entry's `superseded_by` field goes live (see `static/schemas/source/adagents.json#superseded_by`). The AAO mirror entry SHOULD continue serving for ≥1 minor release after `superseded_by` is set, returning an advisory 'superseded' marker so v1 buyer allowlists keyed on the mirror URL get an explicit signal rather than a silent break. **Identity-confusion note**: the mirror URL is *format-shape namespace*, NOT seller identity. Inventory authorization always flows from `authorized_agents[]` + publisher signing keys; a buyer matching `v1_format_ref[].agent_url` against an allowlist is matching format-shape provenance, not seller identity.
+     *
+     * **Mirror domain migration (3.1).** Earlier drafts used `https://mirror.adcontextprotocol.org/translated/<platform>`. As of this release, the convention is `https://creative.adcontextprotocol.org/translated/<platform>` — sibling content under the AAO catalog domain we already host. Adopters who hardcoded the earlier mirror URL MUST migrate to the new path; the canonical-formats.mdx migration section documents the move. No transitional redirect is currently published (the earlier subdomain was never provisioned).
+     *
+     * For seller-bespoke formats (a publisher's `acme_homepage_takeover` that doesn't fit IAB conventions), each `v1_format_ref[].agent_url` is the seller's own agent_url and the id is seller-namespaced. These won't appear in `v1-canonical-mapping.json`'s registry; they're seller-asserted only.
+     */
+    v1_format_ref?: FormatReferenceStructuredObject[];
+    format_schema?: PlatformExtensionReference;
+} & (ImageFormatDeclaration | HTML5FormatDeclaration | DisplayTagFormatDeclaration | ImageCarouselFormatDeclaration | HostedVideoFormatDeclaration | VASTVideoFormatDeclaration | HostedAudioFormatDeclaration | DAASTAudioFormatDeclaration | SponsoredPlacementFormatDeclaration | NativeInFeedFormatDeclaration | ResponsiveCreativeFormatDeclaration | AgentPlacementFormatDeclaration | CustomFormatDeclaration);
+
+/**
+ * Identifier for a publisher property. Must be lowercase alphanumeric with underscores only.
+ * @pattern ^[a-z0-9_]+$
+ */
+export type PropertyID = string;
+
+/**
+ * Push notification configuration for async task updates (A2A and REST protocols). Echoed from the request to confirm webhook settings. Specifies URL, authentication scheme (Bearer or HMAC-SHA256), and credentials. MCP uses progress notifications instead of webhooks.
+ */
+export interface PushNotificationConfig {
+    /**
+     * Webhook endpoint URL for task status notifications. The wire contract is unconstrained beyond `format: "uri"` — in particular, publishers SHOULD NOT enforce a destination-port allowlist by default, since buyers legitimately host receivers on non-standard TLS ports (`:9443`, `:4443`, path-routed multi-tenant gateways). The SSRF guard the protocol relies on is the IP-range check + DNS-rebinding-resistant connect pin defined in [Webhook URL validation (SSRF)](/docs/building/by-layer/L1/security#webhook-url-validation-ssrf), not port filtering. Operators who want a hardened destination-port allowlist as defense-in-depth (e.g., locked-down enterprise egress) opt in explicitly — see [Destination port: permissive by default](/docs/building/by-layer/L1/security#destination-port-permissive-by-default).
+     */
+    url: string;
+    /**
+     * Buyer-supplied correlation identifier for the operation that will produce webhooks against this registration. The seller MUST echo this value verbatim into every webhook payload's `operation_id` field (see [`mcp-webhook-payload.json`](/schemas/core/mcp-webhook-payload.json) and [Webhooks — Operation IDs](/docs/building/by-layer/L3/webhooks#operation-ids-and-url-templates)). Buyers SHOULD generate a unique value per task invocation (UUID recommended). This field is the canonical registration channel for `operation_id`; buyers MAY additionally embed the same value in the URL path or query as a routing aid for their own HTTP server, but the URL is opaque to the seller and the wire-level source of truth is this field. Sellers MUST NOT parse the URL to recover `operation_id`. Sellers that receive a webhook registration without `operation_id` MAY reject the task with `INVALID_REQUEST`.
+     * @minLength 1
+     * @maxLength 255
+     * @pattern ^[A-Za-z0-9_.:-]{1,255}$
+     */
+    operation_id?: string;
+    /**
+     * Optional client-provided token for webhook validation. The seller MUST echo this value verbatim in every webhook payload's `token` field (see [`mcp-webhook-payload.json`](/schemas/core/mcp-webhook-payload.json) for the receiver-side validation obligation). Length bounds give receivers a defensive range check on the echoed value; senders SHOULD generate tokens with at least 128 bits of entropy (≥22 base64url characters). This is a complementary authenticity mechanism that can layer on top of the RFC 9421 webhook signature — unlike the `authentication` block below, it is not on the 4.0 removal track. Receivers that registered both a signing key (RFC 9421) and a `token` MUST NOT treat a valid token echo as authorization to skip signature verification; both checks remain independent obligations.
+     * @minLength 16
+     * @maxLength 4096
+     */
+    token?: string;
+    /**
+     * Legacy authentication configuration (A2A-compatible). Opts the seller into Bearer or HMAC-SHA256 signing instead of the default RFC 9421 webhook profile. Deprecated; removed in AdCP 4.0. **Precedence is a switch, not a fallback:** presence of this block selects the legacy scheme; absence selects 9421. A seller MUST NOT sign the same webhook both ways, and a buyer MUST NOT attempt 'try 9421 first, fall back to HMAC' verification — signature mode is determined solely by whether this block was present at registration time. The seller's baseline 9421 webhook-signing key published at its brand.json `agents[]` `jwks_uri` does not override this selector; it is always discoverable but only used when `authentication` is omitted. See docs/building/implementation/security.mdx#webhook-callbacks for the full precedence and downgrade-resistance rules (including the `webhook_mode_mismatch` rejection a buyer MUST apply when a received webhook's signing mode does not match the registered mode).
+     */
+    authentication?: {
+        /**
+         * Array of authentication schemes. Supported: ['Bearer'] for simple token auth, ['HMAC-SHA256'] for legacy shared-secret signing. Both are deprecated; new integrations SHOULD omit `authentication` and use the RFC 9421 webhook profile.
+         */
+        schemes: AuthenticationScheme[];
+        /**
+         * Credentials for the legacy scheme. For Bearer: token sent in Authorization header. For HMAC-SHA256: shared secret used to generate signature. Minimum 32 characters. Exchanged out-of-band during onboarding.
+         * @minLength 32
+         */
+        credentials: string;
+    };
+}
+
+/**
+ * Repeatable asset group (for carousels, slideshows, playlists, etc.)
+ */
+export interface RepeatableGroupAsset {
+    /**
+     * Discriminator indicating this is a repeatable asset group
+     */
+    item_type: 'repeatable_group';
+    /**
+     * Identifier for this asset group (e.g., 'product', 'slide', 'card')
+     */
+    asset_group_id: string;
+    /**
+     * Whether this asset group is required. If true, at least min_count repetitions must be provided.
+     */
+    required: boolean;
+    /**
+     * Minimum number of repetitions required (if group is required) or allowed (if optional)
+     * @minimum 0
+     */
+    min_count: number;
+    /**
+     * Maximum number of repetitions allowed
+     * @minimum 1
+     */
+    max_count: number;
+    /**
+     * How the platform uses repetitions of this group. 'sequential' means all items display in order (carousels, playlists). 'optimize' means the platform selects the best-performing combination from alternatives (asset group optimization like Meta Advantage+ or Google Pmax).
+     */
+    selection_mode?: 'sequential' | 'optimize';
+    /**
+     * Assets within each repetition of this group
+     */
+    assets: GroupAssetSlot[];
+}
+
+export type Responsive = {
+    [k: string]: unknown | undefined;
+};
+
+export interface ResponsiveCreativeFormatDeclaration {
+    format_kind: 'responsive_creative';
+    params: CanonicalFormatResponsiveCreative;
+}
+
+/**
+ * Video scan method. Modern digital delivery requires progressive scan; interlaced is retained for broadcast legacy content.
+ */
+export type ScanType = 'progressive' | 'interlaced';
+
+/**
+ * Exactly one of: (a) fixed (`width` + `height` both set), (b) multi-size (`sizes` set), (c) responsive (any of `min_width`/`max_width`/`min_height`/`max_height` set), (d) none (no size constraint declared — accepts any dimensions). Combining modes (e.g., `width` + `sizes`) is rejected at schema layer; same rule on `html5` and `display_tag` canonicals.
+ */
+export type SizeModeMutex = Fixed | MultiSize | Responsive | None;
+
+export interface SponsoredPlacementFormatDeclaration {
+    format_kind: 'sponsored_placement';
+    params: CanonicalFormatSponsoredPlacementRetailMediaCatalogDriven;
+}
+
+/**
+ * Current task execution state. Indicates whether the task is completed, in progress (working), submitted for async processing, failed, or requires user input. REQUIRED on every task response envelope. Synchronous tasks (including read-only metadata calls like `get_adcp_capabilities`) MUST emit `status: "completed"`; async tasks emit `submitted`, `working`, `input-required`, etc. per their lifecycle. Agents MUST NOT emit the legacy task_status or response_status fields alongside this field — the status field is the single authoritative task state.
+ */
+export type TaskStatus = 'submitted' | 'working' | 'input-required' | 'completed' | 'canceled' | 'failed' | 'rejected' | 'auth-required' | 'unknown';
+
+/**
+ * Requirements for text creative assets such as headlines, body copy, and CTAs.
+ */
+export interface TextAssetRequirements {
+    /**
+     * Minimum character length
+     * @minimum 0
+     */
+    min_length?: number;
+    /**
+     * Maximum character length
+     * @minimum 1
+     */
+    max_length?: number;
+    /**
+     * Minimum number of lines
+     * @minimum 1
+     */
+    min_lines?: number;
+    /**
+     * Maximum number of lines
+     * @minimum 1
+     */
+    max_lines?: number;
+    /**
+     * Regex pattern defining allowed characters (e.g., '^[a-zA-Z0-9 .,!?-]+$')
+     */
+    character_pattern?: string;
+    /**
+     * List of prohibited words or phrases
+     */
+    prohibited_terms?: string[];
+    /**
+     * Closed set of permitted string values for this text slot. When present, a conformant implementation MUST reject any submitted content not in this list with `CREATIVE_VALUE_NOT_ALLOWED` (echoing the offending field path in `error.field` and the allowed list in `error.details.allowed_values`). Matching is case-sensitive; producers MUST supply exact casing. If the submitted value contains unresolved template tokens (e.g., {{product_name}}), validation against allowed_values MUST be deferred until interpolation is complete. All declared constraints (allowed_values, character_pattern, max_length, etc.) are conjunctive — submitted content must satisfy every applicable constraint simultaneously.
+     */
+    allowed_values?: string[];
+}
+
+/**
+ * Requirements for URL assets such as click-through URLs, tracking pixels, and landing pages.
+ */
+export interface URLAssetRequirements {
+    /**
+     * Purpose this URL slot serves in the format — distinct from `url_type` on the manifest-side asset (which declares the receiver's invocation mechanism). A slot can be `click_tracker` (purpose) and accept a `tracker_pixel` (mechanism) URL, or `clickthrough` (purpose) and accept a `clickthrough` (mechanism) URL. Complements `asset_role` (human-readable label) by providing a machine-readable enum and serves as the receiver's fallback signal when a manifest URL asset omits `url_type`.
+     */
+    role?: 'clickthrough' | 'landing_page' | 'impression_tracker' | 'click_tracker' | 'viewability_tracker' | 'third_party_tracker';
+    /**
+     * Allowed URL protocols. HTTPS is recommended for all ad URLs.
+     */
+    protocols?: ('https' | 'http')[];
+    /**
+     * List of allowed domains for the URL
+     */
+    allowed_domains?: string[];
+    /**
+     * Maximum URL length in characters
+     * @minimum 1
+     */
+    max_length?: number;
+    /**
+     * Whether the URL supports macro substitution (e.g., ${CACHEBUSTER})
+     */
+    macro_support?: boolean;
+}
+
+/**
+ * Standardized macro placeholders for dynamic value substitution in creative tracking URLs. Macros are replaced with actual values at impression time. See docs/creative/universal-macros.mdx for detailed documentation.
+ */
+export type UniversalMacro = 'MEDIA_BUY_ID' | 'PACKAGE_ID' | 'CREATIVE_ID' | 'CACHEBUSTER' | 'TIMESTAMP' | 'CLICK_URL' | 'GDPR' | 'GDPR_CONSENT' | 'US_PRIVACY' | 'GPP_STRING' | 'GPP_SID' | 'IP_ADDRESS' | 'LIMIT_AD_TRACKING' | 'DEVICE_TYPE' | 'OS' | 'OS_VERSION' | 'DEVICE_MAKE' | 'DEVICE_MODEL' | 'USER_AGENT' | 'APP_BUNDLE' | 'APP_NAME' | 'COUNTRY' | 'REGION' | 'CITY' | 'ZIP' | 'DMA' | 'LAT' | 'LONG' | 'DEVICE_ID' | 'DEVICE_ID_TYPE' | 'DOMAIN' | 'PAGE_URL' | 'REFERRER' | 'KEYWORDS' | 'PLACEMENT_ID' | 'FOLD_POSITION' | 'AD_WIDTH' | 'AD_HEIGHT' | 'VIDEO_ID' | 'VIDEO_TITLE' | 'VIDEO_DURATION' | 'VIDEO_CATEGORY' | 'CONTENT_GENRE' | 'CONTENT_RATING' | 'PLAYER_WIDTH' | 'PLAYER_HEIGHT' | 'POD_POSITION' | 'POD_SIZE' | 'AD_BREAK_ID' | 'STATION_ID' | 'COLLECTION_NAME' | 'INSTALLMENT_ID' | 'AUDIO_DURATION' | 'TMPX' | 'AXEM' | 'CATALOG_ID' | 'SKU' | 'GTIN' | 'OFFERING_ID' | 'JOB_ID' | 'HOTEL_ID' | 'FLIGHT_ID' | 'VEHICLE_ID' | 'LISTING_ID' | 'STORE_ID' | 'PROGRAM_ID' | 'DESTINATION_ID' | 'CREATIVE_VARIANT_ID' | 'APP_ITEM_ID';
+
+/**
+ * Requirements for VAST (Video Ad Serving Template) creative assets.
+ */
+export interface VASTAssetRequirements {
+    /**
+     * Required VAST version
+     */
+    vast_version?: '2.0' | '3.0' | '4.0' | '4.1' | '4.2';
+}
+
+export interface VASTVideoFormatDeclaration {
+    format_kind: 'video_vast';
+    params: CanonicalFormatVASTVideo;
+}
+
+/**
+ * Pricing model for a vendor service. Discriminated by model: 'cpm' (fixed CPM), 'percent_of_media' (percentage of spend with optional CPM cap), 'flat_fee' (fixed charge per reporting period), 'per_unit' (fixed price per unit of work), or 'custom' (escape hatch for models not covered by the enumerated forms — requires a description and structured metadata).
+ */
+export type VendorPricing = CpmPricing | PercentOfMediaPricing | FlatFeePricing | PerUnitPricing | CustomPricing;
+
+/**
+ * A pricing option offered by a vendor agent (signals, creative, governance). Combines pricing_option_id with the pricing model fields. Pass pricing_option_id in report_usage for billing verification. All vendor discovery responses return pricing_options as an array — vendors may offer multiple options (volume tiers, context-specific rates, different models per product line).
+ */
+export type VendorPricingOption = {
+    /**
+     * Opaque identifier for this pricing option, unique within the vendor agent. Pass this in report_usage to identify which pricing option was applied.
+     */
+    pricing_option_id: string;
+} & VendorPricing;
+
+/**
+ * Requirements for video creative assets. These define the technical constraints for video files.
+ */
+export interface VideoAssetRequirements {
+    /**
+     * Minimum width in pixels
+     * @minimum 1
+     */
+    min_width?: number;
+    /**
+     * Maximum width in pixels
+     * @minimum 1
+     */
+    max_width?: number;
+    /**
+     * Minimum height in pixels
+     * @minimum 1
+     */
+    min_height?: number;
+    /**
+     * Maximum height in pixels
+     * @minimum 1
+     */
+    max_height?: number;
+    /**
+     * Required aspect ratio (e.g., '16:9', '9:16')
+     * @pattern ^\d+:\d+$
+     */
+    aspect_ratio?: string;
+    /**
+     * Minimum duration in milliseconds
+     * @minimum 1
+     */
+    min_duration_ms?: number;
+    /**
+     * Maximum duration in milliseconds
+     * @minimum 1
+     */
+    max_duration_ms?: number;
+    /**
+     * Accepted video container formats
+     */
+    containers?: ('mp4' | 'webm' | 'mov' | 'avi' | 'mkv')[];
+    /**
+     * Accepted video codecs
+     */
+    codecs?: ('h264' | 'h265' | 'vp8' | 'vp9' | 'av1' | 'prores')[];
+    /**
+     * Maximum file size in kilobytes
+     * @minimum 1
+     */
+    max_file_size_kb?: number;
+    /**
+     * Minimum video bitrate in kilobits per second
+     * @minimum 1
+     */
+    min_bitrate_kbps?: number;
+    /**
+     * Maximum video bitrate in kilobits per second
+     * @minimum 1
+     */
+    max_bitrate_kbps?: number;
+    /**
+     * Accepted frame rates in frames per second (e.g., [24, 30, 60])
+     */
+    frame_rates?: number[];
+    /**
+     * Whether the video must include an audio track
+     */
+    audio_required?: boolean;
+    frame_rate_type?: FrameRateType;
+    scan_type?: ScanType;
+    gop_type?: GOPType;
+    /**
+     * Minimum keyframe interval in seconds
+     * @minimum 0
+     */
+    min_gop_interval_seconds?: number;
+    /**
+     * Maximum keyframe interval in seconds. SSAI typically requires 1-2 second intervals.
+     * @minimum 0
+     */
+    max_gop_interval_seconds?: number;
+    moov_atom_position?: MoovAtomPosition;
+    /**
+     * Accepted audio codecs (e.g., ['aac', 'pcm', 'ac3'])
+     */
+    audio_codecs?: ('aac' | 'pcm' | 'ac3' | 'eac3' | 'mp3' | 'opus' | 'vorbis' | 'flac')[];
+    /**
+     * Accepted audio sample rates in Hz (e.g., [44100, 48000])
+     */
+    audio_sample_rates?: number[];
+    /**
+     * Accepted audio channel configurations
+     */
+    audio_channels?: AudioChannelLayout[];
+    /**
+     * Target integrated loudness in LUFS (e.g., -24 for broadcast, -16 for streaming)
+     */
+    loudness_lufs?: number;
+    /**
+     * Acceptable deviation from loudness_lufs target in dB (e.g., 2 means -22 to -26 LUFS for a -24 target)
+     * @minimum 0
+     */
+    loudness_tolerance_db?: number;
+    /**
+     * Maximum true peak level in dBFS (e.g., -2 for broadcast)
+     */
+    true_peak_dbfs?: number;
+}
+
+/**
+ * Filter to formats that meet at least this WCAG conformance level (A < AA < AAA)
+ */
+export type WCAGLevel = 'A' | 'AA' | 'AAA';
+
+/**
+ * Requirements for webhook creative assets.
+ */
+export interface WebhookAssetRequirements {
+    /**
+     * Allowed HTTP methods
+     */
+    methods?: ('GET' | 'POST')[];
+}