@adcp/sdk 7.11.0 → 7.11.1

package/compliance/cache/3.1.0-rc.2/domains/media-buy/index.yaml

@@ -0,0 +1,789 @@
+id: media_buy_seller
+version: "1.0.0"
+title: "Media buy seller agent"
+category: media_buy_seller
+summary: "Seller agent that receives briefs, returns products, accepts media buys, and reports delivery."
+track: media_buy
+required_tools:
+  - get_products
+  - create_media_buy
+requires_scenarios:
+  - media_buy_seller/refine_products
+  - media_buy_seller/delivery_reporting
+  - media_buy_seller/measurement_terms_rejected
+  - media_buy_seller/pending_creatives_to_start
+  - media_buy_seller/inventory_list_targeting
+  - media_buy_seller/inventory_list_no_match
+  - media_buy_seller/product_signal_targeting
+  - media_buy_seller/available_actions
+  - media_buy_seller/invalid_transitions
+  - media_buy_seller/creative_fate_after_cancellation
+  - media_buy_seller/create_media_buy_async
+  - media_buy_seller/dependency_impairment
+  - media_buy_seller/dependency_impairment_cardinality
+
+narrative: |
+  You run a sell-side platform — a publisher, SSP, retail media network, or any system that
+  sells advertising inventory. A buyer agent connects to discover your products, create
+  media buys, sync creatives, and monitor delivery. Your agent handles the full lifecycle
+  from brief to reporting.
+
+  This storyboard walks through the core media buy flow: account setup, product discovery,
+  buy creation, creative sync, and delivery monitoring.
+
+  Governance integration, product refinement, and proposal finalization are tested by
+  required scenarios that run alongside this storyboard. See requires_scenarios for the
+  full set of seller behaviors validated.
+
+agent:
+  interaction_model: media_buy_seller
+  capabilities:
+    - sells_media
+    - accepts_briefs
+    - supports_guaranteed
+    - supports_non_guaranteed
+  examples:
+    - "Yahoo"
+    - "Retail media networks"
+    - "Publisher platforms"
+    - "SSPs"
+
+caller:
+  role: buyer_agent
+  example: "Scope3 (DSP)"
+
+prerequisites:
+  description: |
+    The caller needs a brand identity and operator credentials for account setup.
+    The test kit provides a sample brand (Acme Outdoor) with campaign parameters
+    suitable for testing the full media buy flow.
+  test_kit: "test-kits/acme-outdoor.yaml"
+  controller_seeding: true
+
+fixtures:
+  products:
+    - product_id: "sports_preroll_q2"
+      delivery_type: "guaranteed"
+      channels: ["video"]
+      format_ids:
+        - id: "video_30s"
+    - product_id: "lifestyle_display_q2"
+      delivery_type: "guaranteed"
+      channels: ["display"]
+      format_ids:
+        - id: "display_300x250"
+  pricing_options:
+    - product_id: "sports_preroll_q2"
+      pricing_option_id: "cpm_guaranteed"
+      pricing_model: "cpm"
+      currency: "USD"
+      fixed_price: 22.0
+    - product_id: "lifestyle_display_q2"
+      pricing_option_id: "cpm_standard"
+      pricing_model: "cpm"
+      currency: "USD"
+      fixed_price: 8.0
+
+phases:
+  - id: capability_discovery
+    title: "Capability discovery"
+    narrative: |
+      The buyer calls get_adcp_capabilities to confirm the agent supports media buying before sending briefs or creating buys.
+
+    steps:
+      - id: get_capabilities
+        title: "Check agent capabilities"
+        narrative: |
+          Verify that the agent declares the expected protocol support before
+          proceeding with domain-specific operations.
+        task: get_adcp_capabilities
+        schema_ref: "protocol/get-adcp-capabilities-request.json"
+        response_schema_ref: "protocol/get-adcp-capabilities-response.json"
+        doc_ref: "/protocol/get_adcp_capabilities"
+        comply_scenario: capability_discovery
+        stateful: false
+        expected: |
+          Return capabilities declaring media_buy in supported_protocols, confirming the agent sells media.
+        sample_request:
+          context:
+            correlation_id: "media_buy_seller--get_capabilities"
+        validations:
+          - check: response_schema
+            description: "Response matches get-adcp-capabilities-response.json schema"
+          - check: field_present
+            path: "supported_protocols"
+            description: "Agent declares supported protocols"
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "media_buy_seller--get_capabilities"
+            description: "Context correlation_id returned unchanged"
+
+  - id: account_setup
+    title: "Account setup"
+    narrative: |
+      Before buying anything, the buyer establishes an account relationship with
+      your platform. This is the handshake: the buyer tells you which brand and
+      agency (operator) they represent, and you return an account ID, status, and
+      any setup requirements.
+
+      Some platforms approve accounts instantly. Others require human review — the
+      buyer gets back a pending_approval status and a URL to complete setup. The
+      buyer polls or waits for a webhook until the account is active.
+
+    steps:
+      - id: sync_accounts
+        title: "Establish account relationship"
+        narrative: |
+          The buyer registers their brand and operator with your platform. This is
+          the first call in any new relationship. Your platform validates the request,
+          provisions the account, and returns its status.
+
+          If your platform requires manual approval (credit checks, sales team review),
+          return the account with status pending_approval and account.setup.url populated.
+          The buyer directs the human to that URL to complete setup, then polls list_accounts
+          until the account status changes to active.
+        task: sync_accounts
+        schema_ref: "account/sync-accounts-request.json"
+        response_schema_ref: "account/sync-accounts-response.json"
+        doc_ref: "/accounts/tasks/sync_accounts"
+        # No TestScenario exists for account setup
+        stateful: true
+        expected: |
+          Return the account with:
+          - account_id: your platform's identifier for this relationship
+          - action: created or updated
+          - status: active (instant approval) or pending_approval (requires human review)
+          - account_scope: operator, brand, operator_brand, or agent
+          - setup.url and setup.message: populated on the account when status is pending_approval (where the human completes onboarding)
+          - rate_card: pricing tiers if applicable
+          - payment_terms: net_30, prepay, etc.
+
+        sample_request:
+          accounts:
+            - brand:
+                domain: "acmeoutdoor.example"
+              operator: "pinnacle-agency.example"
+              billing: "operator"
+              payment_terms: "net_30"
+          idempotency_key: "$generate:uuid_v4#media_buy_seller_account_setup_sync_accounts"
+          context:
+            correlation_id: "media_buy_seller--sync_accounts"
+
+        validations:
+          - check: response_schema
+            description: "Response matches sync-accounts-response.json schema"
+          - check: field_present
+            path: "accounts[0].account_id"
+            description: "Account has a platform-assigned ID"
+          - check: field_present
+            path: "accounts[0].status"
+            description: "Account has a status (active or pending_approval)"
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "media_buy_seller--sync_accounts"
+            description: "Context correlation_id returned unchanged"
+
+  - id: governance_setup
+    title: "Governance agent registration"
+    narrative: |
+      The buyer registers their governance agent with your platform. This tells your
+      platform where to call check_governance before confirming media buys.
+
+    steps:
+      - id: sync_governance
+        title: "Register governance agents"
+        narrative: |
+          The buyer tells your platform: "Before you confirm any media buy for this
+          account, call this governance agent to validate it."
+        task: sync_governance
+        schema_ref: "account/sync-governance-request.json"
+        response_schema_ref: "account/sync-governance-response.json"
+        doc_ref: "/accounts/tasks/sync_governance"
+        requires_tool: sync_governance
+        stateful: true
+        expected: |
+          Acknowledge the governance agents. Your platform should:
+          - Store the governance agent URLs for the specified accounts
+          - Return confirmation that agents were registered
+
+        sample_request:
+          accounts:
+            - account:
+                brand:
+                  domain: "acmeoutdoor.example"
+                operator: "pinnacle-agency.example"
+              governance_agents:
+                - url: "https://governance.pinnacle-agency.example"
+                  authentication:
+                    schemes: ["Bearer"]
+                    credentials: "gov-token-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+          idempotency_key: "$generate:uuid_v4#media_buy_seller_governance_setup_sync_governance"
+          context:
+            correlation_id: "media_buy_seller--sync_governance"
+          ext:
+            test_platform:
+              governance_tier: "standard"
+
+        validations:
+          - check: response_schema
+            description: "Response matches sync-governance-response.json schema"
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "media_buy_seller--sync_governance"
+            description: "Context correlation_id returned unchanged"
+
+  - id: product_discovery
+    title: "Product discovery"
+    narrative: |
+      The buyer sends a natural-language brief describing what they want to buy.
+      Your platform interprets the brief against your inventory and returns products —
+      structured representations of what you can sell, with pricing, delivery forecasts,
+      targeting options, and creative requirements.
+
+      This is where seller differentiation happens. The same brief sent to three sellers
+      produces three different product sets. Your AI interprets "premium video on sports
+      and outdoor lifestyle" against your specific inventory, audiences, and pricing.
+
+    steps:
+      - id: get_products_brief
+        title: "Send a brief"
+        narrative: |
+          The buyer describes what they want in natural language. Your platform returns
+          up to five representative products that match the brief, including pricing
+          options, delivery forecasts, and creative format requirements. Exhaustive
+          catalog enumeration is not required for this compliance step.
+
+          This call may take up to 60 seconds — your platform is running AI inference
+          against your inventory catalog. If the brief is ambiguous, you can return
+          input-required to ask clarifying questions before producing results.
+        task: get_products
+        schema_ref: "media-buy/get-products-request.json"
+        response_schema_ref: "media-buy/get-products-response.json"
+        doc_ref: "/media-buy/task-reference/get_products"
+        comply_scenario: full_sales_flow
+        stateful: false
+        expected: |
+          Return up to five products matching the brief. Each product should include:
+          - product_id: unique identifier
+          - name and description
+          - delivery_type: guaranteed or non_guaranteed
+          - pricing_models: available pricing options (CPM, CPC, etc.)
+          - forecast: estimated impressions, reach
+          - creative_format_ids: what creative formats this product requires
+          - targeting: what audiences or contexts this product reaches
+
+          Optionally return proposals — curated media plans that bundle products
+          with budget allocations the buyer can accept or refine.
+
+          If the brief is unclear, return input-required with clarifying questions.
+
+        sample_request:
+          buying_mode: "brief"
+          brief: "Premium video inventory on sports and outdoor lifestyle publishers. Q2 flight, $50K budget. Adults 25-54, US and Canada."
+          pagination:
+            max_results: 5
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          context:
+            correlation_id: "media_buy_seller--get_products_brief"
+
+        context_outputs:
+          - name: product_format_id
+            path: 'products[0].format_ids[0]'
+          - name: product_id
+            path: 'products[0].product_id'
+          - name: pricing_option_id
+            path: 'products[0].pricing_options[0].pricing_option_id'
+        validations:
+          - check: response_schema
+            description: "Response matches get-products-response.json schema"
+          - check: field_present
+            path: "products"
+            description: "Response contains a products array"
+          - check: field_present
+            path: "products[0].product_id"
+            description: "Each product has a product_id"
+          - check: field_present
+            path: "products[0].delivery_type"
+            description: "Each product declares guaranteed or non_guaranteed delivery"
+          - check: field_present
+            path: "products[0].format_ids"
+            description: "Products include format_ids for creative requirements"
+          - check: field_present
+            path: "products[0].format_ids[0].agent_url"
+            description: "Format IDs include agent_url — must match this agent's URL"
+          - check: field_present
+            path: "products[0].format_ids[0].id"
+            description: "Format IDs include id — must be accepted back in sync_creatives"
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "media_buy_seller--get_products_brief"
+            description: "Context correlation_id returned unchanged"
+
+          - check: field_present
+            path: "products[0].publisher_properties"
+            description: "Products include publisher_properties"
+      - id: list_formats_integrity
+        title: "Verify format_ids on products resolve to real formats"
+        narrative: |
+          The buyer asks the sales agent to filter `list_creative_formats` by
+          `products[0].format_ids[0]`. The sales agent MUST return the format
+          it advertised on its own product — whether it hosts that format
+          directly or proxies to the creative agent named in
+          `format_ids[0].agent_url`. An empty `formats[]` means the sales
+          agent's product catalog references a format that does not resolve —
+          a stale or typo'd entry that would have failed silently at
+          `sync_creatives` after the media buy was already committed.
+        task: list_creative_formats
+        schema_ref: "creative/list-creative-formats-request.json"
+        response_schema_ref: "creative/list-creative-formats-response.json"
+        doc_ref: "/creative/task-reference/list_creative_formats"
+        comply_scenario: creative_lifecycle
+        stateful: false
+        expected: |
+          The sales agent resolves `products[0].format_ids[0]` and returns
+          the matching format entry:
+          - formats[] contains at least one entry
+          - formats[0].format_id matches the id captured from get_products
+
+          An empty formats[] means the sales agent's product catalog references
+          a format that does not resolve — a common production failure mode
+          when creative agents deprecate formats without sellers updating
+          their product catalog.
+        sample_request:
+          format_ids:
+            - "$context.product_format_id"
+          context:
+            correlation_id: "media_buy_seller--list_formats_integrity"
+        # The @adcp/client `list_creative_formats` request builder up
+        # through 5.10.0 (the currently-published release) returns `{}`,
+        # and the runner's post-builder merge only forwards envelope
+        # fields (context / ext / idempotency_key /
+        # push_notification_config) from sample_request — so `format_ids`
+        # above never reaches the wire and the seller answers with its
+        # full format catalog. `context_inputs` is applied after the
+        # builder runs, so this injects the captured `product_format_id`
+        # (the `{agent_url, id}` object from `products[0].format_ids[0]`)
+        # at `format_ids[0]` and lets the round-trip invariant actually
+        # grade. Drop once we bump past the @adcp/client release that
+        # ships adcontextprotocol/adcp-client#789.
+        context_inputs:
+          - key: product_format_id
+            inject_at: "format_ids[0]"
+        validations:
+          - check: response_schema
+            description: "Response matches list-creative-formats-response.json schema"
+          - check: field_present
+            path: "formats[0]"
+            description: "Sales agent resolves the format_id — products[0].format_ids[0] exists in the catalog"
+          - check: field_value
+            path: "formats[0].format_id"
+            value: "$context.product_format_id"
+            description: "Returned format_id round-trips verbatim — the agent cannot substitute a different format in response to the filter"
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "media_buy_seller--list_formats_integrity"
+            description: "Context correlation_id returned unchanged"
+  - id: create_buy
+    title: "Create the media buy"
+    narrative: |
+      The buyer is satisfied with the products and creates a media buy. This is the
+      equivalent of signing an IO — the buyer commits to specific products, budgets,
+      and flight dates.
+
+      This operation may be synchronous (completed immediately), short-async (working
+      while your platform processes), or long-async (task stays submitted while a human
+      signs the IO internally; task completion delivers the final media_buy_id). There
+      is no "pending_approval" media buy status — IO review is modelled at the task
+      layer, not as a MediaBuy.status value.
+
+      If the buyer registered governance agents in Phase 2, your platform calls
+      check_governance before confirming the buy. The governance agent validates budget
+      authority, brand safety, and compliance. If governance denies the buy, return the
+      denial — don't override it.
+
+    steps:
+      - id: create_media_buy
+        title: "Create a media buy"
+        narrative: |
+          The buyer commits to specific products with budgets and flight dates. Your
+          platform validates the request, optionally calls governance, and either confirms
+          the buy or sends it through an approval workflow.
+
+          Two creation modes:
+          - Manual: buyer specifies packages array with explicit product selections
+          - Proposal: buyer passes a proposal_id from get_products to execute a proposal
+
+          The response status tells the buyer what happens next:
+          - completed: buy is active and live
+          - working: your platform is processing (poll or wait for webhook)
+          - submitted: long-running async — approval workflow, IO signing, etc.
+          - input-required: need more information (budget clarification, approval)
+        task: create_media_buy
+        schema_ref: "media-buy/create-media-buy-request.json"
+        response_schema_ref: "media-buy/create-media-buy-response.json"
+        doc_ref: "/media-buy/task-reference/create_media_buy"
+        comply_scenario: create_media_buy
+        stateful: true
+        expected: |
+          Process the media buy request and return one of:
+
+          Synchronous (completed):
+          - media_buy_id: your platform's identifier
+          - media_buy_status: active, pending_start, or pending_creatives (deprecated top-level status may mirror this during the 3.1 migration window)
+          - packages: line items with pricing
+          - confirmed_at: seller commitment timestamp, or null only for a provisional buy that already exists and is retrievable
+          - revision: optimistic concurrency token
+          - valid_actions: what the buyer can do next
+
+          Asynchronous (working):
+          - percentage: 0-100 completion
+          - current_step: what's happening ("Validating inventory", "Checking governance")
+
+          Async with human approval (submitted):
+          - task_id / taskId: handle the buyer polls or receives webhooks on
+          - message (optional): explanation of what the seller is waiting on (e.g., "Awaiting IO signature from sales team; typical turnaround 2–4 hours")
+          - No media_buy_id yet — it is issued on task completion. If you allocate media_buy_id before commitment, return synchronous success with confirmed_at: null instead, and make the provisional buy retrievable via get_media_buys.
+          - Seller-side IO signing is modelled here (task stays submitted until signed). Do not emit a "pending_approval" media buy status — that value is not in MediaBuy.status
+
+          Needs input (input-required):
+          - reason: APPROVAL_REQUIRED, BUDGET_EXCEEDS_LIMIT, CLARIFICATION_NEEDED
+          - errors: what needs to be resolved
+          - Used only when the seller needs the buyer to respond (e.g., confirm a budget). If the blocker is account-level (credit application, funding), the resolution path is list_accounts / sync_accounts, where account.setup.url surfaces on the pending_approval account
+
+        sample_request:
+          brand:
+            domain: "acmeoutdoor.example"
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+            sandbox: true
+          start_time: "2026-04-01T00:00:00Z"
+          end_time: "2026-06-30T23:59:59Z"
+          packages:
+            - product_id: "sports_preroll_q2"
+              budget: 25000
+              pricing_option_id: "cpm_guaranteed"
+              creative_assignments:
+                - creative_id: "video_30s_trail_pro"
+            - product_id: "lifestyle_display_q2"
+              budget: 15000
+              pricing_option_id: "cpm_standard"
+          push_notification_config:
+            url: "https://buyer.example/webhooks/adcp"
+            authentication:
+              schemes:
+                - "HMAC-SHA256"
+              credentials: "media-buy-seller-webhook-secret-token"
+          idempotency_key: "$generate:uuid_v4#media_buy_seller_create_buy_create_media_buy"
+          context:
+            correlation_id: "media_buy_seller--create_media_buy"
+
+        context_outputs:
+          - name: media_buy_id
+            path: 'media_buy_id'
+        validations:
+          - check: response_schema
+            description: "Response matches create-media-buy-response.json schema"
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "media_buy_seller--create_media_buy"
+            description: "Context correlation_id returned unchanged"
+
+      - id: check_buy_status
+        title: "Check media buy status"
+        narrative: |
+          Once create_media_buy has completed and a media_buy_id is issued, the buyer
+          calls get_media_buys to read current state — pending_creatives, pending_start,
+          active, paused, completed, rejected, or canceled.
+
+          While the create_media_buy task is still submitted (e.g., waiting on internal
+          IO signing), the media buy does not exist as a queryable MediaBuy yet. IO
+          review is tracked at the task layer, not as a MediaBuy.status value. The buyer
+          polls tasks/get or waits on the webhook until the task completes and a
+          media_buy_id is delivered.
+        task: get_media_buys
+        schema_ref: "media-buy/get-media-buys-request.json"
+        response_schema_ref: "media-buy/get-media-buys-response.json"
+        doc_ref: "/media-buy/task-reference/get_media_buys"
+        comply_scenario: media_buy_lifecycle
+        stateful: true
+        expected: |
+          Return the current state of the media buy:
+          - media_buy_id: matches what was returned from create_media_buy
+          - status: pending_creatives, pending_start, active, paused, completed, rejected, canceled
+          - packages: line items with current delivery status
+          - valid_actions: what operations are available in this state
+
+          If pending_creatives:
+          - Include message explaining what creatives are needed
+          - valid_actions should include sync_creatives
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          media_buy_ids:
+            - "$context.media_buy_id"
+          context:
+            correlation_id: "media_buy_seller--check_buy_status"
+
+        validations:
+          - check: response_schema
+            description: "Response matches get-media-buys-response.json schema"
+          - check: field_present
+            path: "media_buys[0].status"
+            description: "Each media buy has a status"
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "media_buy_seller--check_buy_status"
+            description: "Context correlation_id returned unchanged"
+          - check: field_equals_context
+            path: "media_buys[0].media_buy_id"
+            context_key: "media_buy_id"
+            description: "get_media_buys returns the media_buy_id created earlier"
+          - check: field_value
+            path: "media_buys[0].context.correlation_id"
+            value: "media_buy_seller--create_media_buy"
+            description: "get_media_buys includes persisted media-buy context from create_media_buy"
+
+  - id: creative_sync
+    title: "Creative sync"
+    narrative: |
+      With the media buy confirmed, the buyer syncs creative assets to your platform.
+      Each package in the buy has creative format requirements — the buyer discovered
+      these during product discovery and now pushes matching assets.
+
+      The format_ids used in sync_creatives must match those returned by your platform
+      in get_products and list_creative_formats. If your platform returns a format_id
+      in a product but rejects it when the buyer echoes it back in sync_creatives, the
+      buyer cannot fulfill the creative requirements. This is a common compliance failure.
+
+      Your platform validates each creative against the format specs and returns
+      per-creative status. If assets need review or transcoding, the operation may
+      go async.
+
+    steps:
+      - id: list_formats
+        title: "Check creative format requirements"
+        narrative: |
+          The buyer confirms the first creative format referenced by the discovered
+          product. Your platform returns that format spec with asset requirements,
+          dimensions, and constraints. This is a bounded integrity check, not a
+          full format-catalog dump.
+        task: list_creative_formats
+        schema_ref: "creative/list-creative-formats-request.json"
+        response_schema_ref: "creative/list-creative-formats-response.json"
+        doc_ref: "/creative/task-reference/list_creative_formats"
+        comply_scenario: creative_lifecycle
+        stateful: false
+        expected: |
+          Return the creative format referenced by the discovered product. The format should define:
+          - format_id with your agent_url and unique id
+          - Asset requirements (dimensions, file sizes, mime types)
+          - Render dimensions
+
+        sample_request:
+          format_ids:
+            - "$context.product_format_id"
+          pagination:
+            max_results: 1
+          context:
+            correlation_id: "media_buy_seller--list_formats"
+
+        validations:
+          - check: response_schema
+            description: "Response matches list-creative-formats-response.json schema"
+          - check: field_present
+            path: "formats"
+            description: "Response contains formats array"
+          - check: field_present
+            path: "formats[0].format_id.agent_url"
+            description: "Format IDs include agent_url"
+          - check: field_present
+            path: "formats[0].format_id.id"
+            description: "Format IDs include id — must match those in get_products"
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "media_buy_seller--list_formats"
+            description: "Context correlation_id returned unchanged"
+          - check: refs_resolve
+            description: |
+              The captured format_id returned on the first product resolves to a
+              format in this agent's list_creative_formats. Broken references here surface as a
+              grading failure instead of a silent mismatch that only breaks at
+              sync_creatives time, after the buy is committed. Third-party
+              format_ids (agent_url pointing at a different creative agent)
+              can't be verified without calling that agent and are reported as
+              observations rather than failures.
+            source:
+              from: context
+              path: "product_format_id"
+            target:
+              from: current_step
+              path: "formats[*].format_id"
+            match_keys: [agent_url, id]
+            scope:
+              key: agent_url
+              equals: $agent_url
+            on_out_of_scope: warn
+
+      - id: sync_creatives
+        title: "Push creative assets (format_id roundtrip)"
+        narrative: |
+          The buyer uploads creative assets for the confirmed packages. The first
+          creative uses $context.product_format_id — the exact format_id object
+          returned by get_products. This is the roundtrip test: the seller must
+          accept its own format_ids without modification. If the seller's validation
+          rejects a format_id that it returned in products, this step fails.
+
+          Your platform validates each creative against the format specs, transcodes
+          if necessary, and returns per-creative status.
+        task: sync_creatives
+        schema_ref: "creative/sync-creatives-request.json"
+        response_schema_ref: "creative/sync-creatives-response.json"
+        doc_ref: "/creative/task-reference/sync_creatives"
+        comply_scenario: creative_sync
+        stateful: true
+        expected: |
+          Accept and validate creatives:
+          - Per-creative action: created or updated
+          - Per-creative status: accepted, pending_review, or rejected
+          - Validation errors for rejected creatives
+          - Platform-assigned IDs if applicable
+
+          The first creative uses a format_id extracted from get_products.
+          If this is rejected, your format_ids do not roundtrip correctly.
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          creatives:
+            - creative_id: "video_30s_trail_pro"
+              name: "Trail Pro 3000 - 30s CTV Spot"
+              format_id: "$context.product_format_id"
+              assets:
+                video:
+                  asset_type: "video"
+                  url: "https://cdn.pinnacle-agency.example/trail-pro-30s.mp4"
+                  width: 1920
+                  height: 1080
+                  duration_ms: 30000
+                  mime_type: "video/mp4"
+            - creative_id: "display_trail_pro_300x250"
+              name: "Trail Pro 3000 - Display 300x250"
+              format_id:
+                agent_url: "https://your-platform.example.com"
+                id: "display_300x250"
+              assets:
+                image:
+                  asset_type: "image"
+                  url: "https://cdn.pinnacle-agency.example/trail-pro-300x250.png"
+                  width: 300
+                  height: 250
+                  mime_type: "image/png"
+          idempotency_key: "$generate:uuid_v4#media_buy_seller_creative_sync_sync_creatives"
+          context:
+            correlation_id: "media_buy_seller--sync_creatives"
+
+        validations:
+          - check: response_schema
+            description: "Response matches sync-creatives-response.json schema"
+          - check: field_present
+            path: "creatives[0].action"
+            description: "Each creative has an action (created/updated)"
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "media_buy_seller--sync_creatives"
+            description: "Context correlation_id returned unchanged"
+
+  - id: delivery_monitoring
+    title: "Delivery and reporting"
+    narrative: |
+      The campaign is live. The buyer monitors delivery through two tasks:
+      get_media_buys for status and get_media_buy_delivery for performance metrics.
+
+      Your platform reports in a standard format — impressions, clicks, spend,
+      completion rates — so the buyer can compare delivery across multiple sellers
+      in a single view.
+
+    steps:
+      - id: get_delivery
+        title: "Check delivery metrics"
+        narrative: |
+          The buyer requests delivery data for the active media buy. Your platform
+          returns performance metrics — impressions, clicks, spend, completion rates —
+          broken down by package and optionally by day.
+
+          This call may take up to 60 seconds as your platform aggregates reporting
+          data across delivery systems.
+        task: get_media_buy_delivery
+        schema_ref: "media-buy/get-media-buy-delivery-request.json"
+        response_schema_ref: "media-buy/get-media-buy-delivery-response.json"
+        doc_ref: "/media-buy/task-reference/get_media_buy_delivery"
+        comply_scenario: reporting_flow
+        stateful: true
+        expected: |
+          Return delivery metrics for the media buy:
+          - Per-package delivery: impressions, clicks, spend, completion rates
+          - Daily breakdown if requested (include_package_daily_breakdown)
+          - Pacing information: on track, ahead, behind
+          - Budget utilization: spent vs. committed
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          media_buy_ids:
+            - "$context.media_buy_id"
+          include_package_daily_breakdown: true
+          context:
+            correlation_id: "media_buy_seller--get_delivery"
+
+        validations:
+          - check: response_schema
+            description: "Response matches get-media-buy-delivery-response.json schema"
+          - check: field_present
+            path: "media_buy_deliveries"
+            description: "Response contains media buy delivery data"
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "media_buy_seller--get_delivery"
+            description: "Context correlation_id returned unchanged"