@adcp/sdk 15.8.1 → 16.0.0-beta.1

package/compliance/cache/3.2.4/protocols/media-buy/index.yaml

@@ -0,0 +1,865 @@
+id: media_buy_seller
+version: "1.0.1"
+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
+requires:
+  - controller
+
+required_tools:
+  - get_products
+  - create_media_buy
+requires_scenarios:
+  - media_buy_seller/get_products_rejected
+  - media_buy_seller/refine_products
+  - media_buy_seller/delivery_reporting
+  - media_buy_seller/advanced_delivery_reporting
+  - media_buy_seller/audience_activation_discovery
+  - media_buy_seller/external_audience_source_binding
+  - media_buy_seller/measurement_terms_rejected
+  - media_buy_seller/measurement_terms_accepted
+  - 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/demographic_targeting
+  - media_buy_seller/product_filter_behavior
+  - media_buy_seller/read_filter_behavior
+  - media_buy_seller/list_creatives_filter_behavior
+  - media_buy_seller/account_change_feed
+  - media_buy_seller/targeting_aware_discovery
+  - media_buy_seller/geo_place_targeting
+  - media_buy_seller/geo_region_all_values_support
+  - media_buy_seller/geo_region_exclusion_support
+  - media_buy_seller/geo_region_targeting
+  - media_buy_seller/available_actions
+  - media_buy_seller/change_rights_state_projection
+  - media_buy_seller/acceptance_policy_discovery
+  - media_buy_seller/governance_agent_binding_acceptance
+  - media_buy_seller/invalid_transitions
+  - media_buy_seller/creative_fate_after_cancellation
+  - media_buy_seller/inline_creatives_without_sync
+  - media_buy_seller/create_media_buy_async
+  - media_buy_seller/create_media_buy_async_lifecycle
+  - media_buy_seller/dependency_impairment
+  - media_buy_seller/dependency_impairment_audience
+  - media_buy_seller/dependency_impairment_cardinality
+  - media_buy_seller/seller_optimized_budget
+  - media_buy_seller/seller_optimized_proposal_package_pacing
+  - media_buy_seller/seller_optimized_min_spend_target_exceeds_package_cap
+  - media_buy_seller/total_budget_redistribution
+  - media_buy_seller/bidding_policy_placement
+  - media_buy_seller/bidding_cost_binding
+  - media_buy_seller/package_automatic_bidding
+  - media_buy_seller/typed_proposal_negotiation
+  - media_buy_seller/portfolio_routing_scope
+  - media_buy_seller/catalog_item_availability_updates
+  - media_buy_seller/account_timezone_seller_fixed
+  - media_buy_seller/account_timezone_buyer_selected
+  - media_buy_seller/account_timezone_seller_assigned
+  - media_buy_seller/budget_cap_timezone_account
+  - media_buy_seller/budget_cap_timezone_fixed
+  - media_buy_seller/budget_cap_timezone_override
+  - media_buy_seller/budget_cap_timezone_override_rejected
+  - media_buy_seller/owner_sold_channel_carriage
+  - media_buy_seller/collection_selection
+  - media_buy_seller/outcome_target_list_products_inert
+
+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, and monitor delivery. When your platform advertises a creative library,
+  the required creative scenarios also validate creative sync and library behavior.
+
+  This storyboard walks through the core media buy flow: account setup, product discovery,
+  buy creation, and delivery monitoring.
+
+  Creative sync, governance integration, product refinement, and proposal finalization
+  are tested by capability-gated 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
+
+# The base media-buy lifecycle exercises the universal NON-GUARANTEED
+# (auction-based) path so that every media-buy seller can run it — including
+# sellers that declare only `specialisms: ["sales-non-guaranteed"]`. A
+# non-guaranteed-only seller correctly rejects a guaranteed buy with
+# DELIVERY_MODE_NOT_SUPPORTED, so guaranteed-only fixtures here failed the whole
+# base flow (create_buy + the dependent steps) for that entire seller class. The
+# guaranteed lifecycle (human IO approval, proposal_finalize) is covered by the
+# `sales-guaranteed` specialism bundle, which carries its own guaranteed fixtures.
+fixtures:
+  products:
+    - product_id: "sports_preroll_q2"
+      delivery_type: "non_guaranteed"
+      channels: ["olv"]
+      format_options:
+        - format_option_id: "video_30s"
+          format_kind: "video_hosted"
+          params:
+            duration_ms_exact: 30000
+    - product_id: "lifestyle_display_q2"
+      delivery_type: "non_guaranteed"
+      channels: ["display"]
+      format_options:
+        - format_option_id: "display_300x250"
+          format_kind: "image"
+          params:
+            width: 300
+            height: 250
+  pricing_options:
+    - product_id: "sports_preroll_q2"
+      pricing_option_id: "cpm_non_guaranteed"
+      pricing_model: "cpm"
+      currency: "USD"
+      floor_price: 22.0
+    - product_id: "lifestyle_display_q2"
+      pricing_option_id: "cpm_standard"
+      pricing_model: "cpm"
+      currency: "USD"
+      floor_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"
+    depends_on: []
+    requires_capability:
+      path: account.timezone.supported_timezones
+      present: false
+    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, when the seller echoes one during provisioning
+          - 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: "media-buy-lifecycle.pinnacle-agency.example"
+              sandbox: true
+              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_value
+            path: "accounts[0].action"
+            allowed_values: ["created", "updated", "unchanged"]
+            description: "Account setup succeeds instead of returning a per-account failure"
+          - 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: buyer_selected_account_setup
+    title: "Buyer-selected timezone account setup"
+    depends_on: []
+    requires_capability:
+      path: account.timezone.account_selection
+      equals: buyer_selected
+    narrative: |
+      Buyer-selected account-fixed sellers require one advertised timezone in
+      the provisioning natural key. The buyer discovers that allowlist before
+      establishing the account, resolves the new account through its complete
+      natural key, and carries that complete natural key through the rest of
+      this lifecycle.
+    steps:
+      - id: discover_buyer_selected_timezone
+        title: "Choose an advertised account timezone"
+        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"
+        stateful: false
+        sample_request: {}
+        context_outputs:
+          - name: account_timezone
+            path: "account.timezone.supported_timezones[0]"
+        validations:
+          - check: response_schema
+            description: "Capability response matches the canonical schema"
+          - check: field_present
+            path: "account.timezone.supported_timezones[0]"
+            description: "Buyer has at least one valid provisioning timezone"
+
+      - id: sync_accounts_buyer_selected_timezone
+        title: "Establish the timezone-bound account relationship"
+        task: sync_accounts
+        schema_ref: "account/sync-accounts-request.json"
+        response_schema_ref: "account/sync-accounts-response.json"
+        doc_ref: "/accounts/tasks/sync_accounts"
+        stateful: true
+        sample_request:
+          accounts:
+            - brand:
+                domain: "acmeoutdoor.example"
+              operator: "media-buy-lifecycle.pinnacle-agency.example"
+              timezone: "$context.account_timezone"
+              billing: "operator"
+              payment_terms: "net_30"
+              sandbox: true
+          idempotency_key: "$generate:uuid_v4#media_buy_seller_buyer_selected_account_setup"
+          context:
+            correlation_id: "media_buy_seller--sync_accounts_buyer_selected"
+        validations:
+          - check: response_schema
+            description: "Response matches sync-accounts-response.json schema"
+          - check: field_value
+            path: "accounts[0].action"
+            allowed_values: ["created", "updated", "unchanged"]
+            description: "Timezone-bound account setup succeeds"
+          - check: field_equals_context
+            path: "accounts[0].timezone"
+            context_key: "account_timezone"
+            description: "Seller echoes the chosen immutable timezone"
+
+  - id: product_discovery
+    title: "Product discovery"
+    depends_on: [account_setup]
+    requires_capability:
+      path: account.timezone.supported_timezones
+      present: false
+    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
+          - format_options: canonical creative contracts this product accepts
+          - 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:
+          idempotency_key: "$generate:uuid_v4#media_buy_seller_product_discovery_get_products_brief"
+          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: "media-buy-lifecycle.pinnacle-agency.example"
+            sandbox: true
+          context:
+            correlation_id: "media_buy_seller--get_products_brief"
+
+        context_outputs:
+          - name: product_format_kind
+            path: 'products[0].format_options[0].format_kind'
+          - 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_options"
+            description: "Products include canonical format_options for creative requirements"
+          - check: field_present
+            path: "products[0].format_options[0].format_kind"
+            description: "Every canonical product option declares format_kind"
+          - 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: create_buy
+    title: "Create the media buy"
+    depends_on: [product_discovery]
+    requires_capability:
+      path: account.timezone.supported_timezones
+      present: false
+    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.
+
+      Governance-aware creation is covered by the dedicated, capability-gated
+      governance scenarios. The base lifecycle leaves the test account ungoverned so
+      every media-buy seller can exercise this universal flow without an undeclared
+      governance_context commitment.
+
+    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
+          - 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: AdCP handle the buyer passes to get_task_status or receives webhooks on; it is not the A2A Task id
+          - 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: "media-buy-lifecycle.pinnacle-agency.example"
+            sandbox: true
+          start_time: "asap"
+          end_time: "2099-06-30T23:59:59Z"
+          packages:
+            - product_id: "sports_preroll_q2"
+              budget: 25000
+              pricing_option_id: "cpm_non_guaranteed"
+              bid_price: 25
+            - product_id: "lifestyle_display_q2"
+              budget: 15000
+              pricing_option_id: "cpm_standard"
+              bid_price: 10
+          push_notification_config:
+            url: "https://buyer.example/webhooks/adcp"
+            operation_id: "op_media_buy_seller_create"
+            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
+          invokes get_task_status 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: "media-buy-lifecycle.pinnacle-agency.example"
+            sandbox: true
+          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: delivery_monitoring
+    title: "Delivery and reporting"
+    depends_on: [create_buy]
+    requires_capability:
+      path: account.timezone.supported_timezones
+      present: false
+    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: "media-buy-lifecycle.pinnacle-agency.example"
+            sandbox: true
+          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"
+
+  # The buyer-selected branch repeats the lifecycle with the complete
+  # timezone-bearing natural AccountRef. The request bodies are explicit so
+  # authored-storyboard consumers do not need YAML merge-key support.
+  - id: buyer_selected_product_discovery
+    title: "Buyer-selected timezone product discovery"
+    depends_on: [buyer_selected_account_setup]
+    requires_capability:
+      path: account.timezone.account_selection
+      equals: buyer_selected
+    steps:
+      - id: get_products_brief_buyer_selected_timezone
+        title: "Send a brief for the timezone-bound account"
+        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
+        sample_request:
+          idempotency_key: "$generate:uuid_v4#media_buy_seller_buyer_timezone_get_products"
+          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: "media-buy-lifecycle.pinnacle-agency.example"
+            timezone: "$context.account_timezone"
+            sandbox: true
+          context:
+            correlation_id: "media_buy_seller--get_products_brief"
+        context_outputs:
+          - name: product_format_kind
+            path: 'products[0].format_options[0].format_kind'
+          - 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_options"
+            description: "Products include canonical format_options for creative requirements"
+          - check: field_present
+            path: "products[0].format_options[0].format_kind"
+            description: "Every canonical product option declares format_kind"
+          - 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: buyer_selected_create_buy
+    title: "Buyer-selected timezone media buy"
+    depends_on: [buyer_selected_product_discovery]
+    requires_capability:
+      path: account.timezone.account_selection
+      equals: buyer_selected
+    steps:
+      - id: create_media_buy_buyer_selected_timezone
+        title: "Create a buy for the timezone-bound account"
+        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
+        sample_request:
+          brand:
+            domain: "acmeoutdoor.example"
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "media-buy-lifecycle.pinnacle-agency.example"
+            timezone: "$context.account_timezone"
+            sandbox: true
+          start_time: "asap"
+          end_time: "2099-06-30T23:59:59Z"
+          packages:
+            - product_id: "sports_preroll_q2"
+              budget: 25000
+              pricing_option_id: "cpm_non_guaranteed"
+              bid_price: 25
+            - product_id: "lifestyle_display_q2"
+              budget: 15000
+              pricing_option_id: "cpm_standard"
+              bid_price: 10
+          push_notification_config:
+            url: "https://buyer.example/webhooks/adcp"
+            operation_id: "op_media_buy_seller_timezone"
+            authentication:
+              schemes:
+                - "HMAC-SHA256"
+              credentials: "media-buy-seller-webhook-secret-token"
+          idempotency_key: "$generate:uuid_v4#media_buy_seller_buyer_timezone_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_buyer_selected_timezone
+        title: "Check the timezone-bound media buy"
+        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
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "media-buy-lifecycle.pinnacle-agency.example"
+            timezone: "$context.account_timezone"
+            sandbox: true
+          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: buyer_selected_delivery_monitoring
+    title: "Buyer-selected timezone delivery and reporting"
+    depends_on: [buyer_selected_create_buy]
+    requires_capability:
+      path: account.timezone.account_selection
+      equals: buyer_selected
+    steps:
+      - id: get_delivery_buyer_selected_timezone
+        title: "Check delivery for the timezone-bound account"
+        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
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "media-buy-lifecycle.pinnacle-agency.example"
+            timezone: "$context.account_timezone"
+            sandbox: true
+          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"