@adcp/sdk 7.11.1 → 7.11.2

package/compliance/cache/3.1.0-rc.2/specialisms/sales-guaranteed/index.yaml

@@ -1,601 +0,0 @@
-id: sales_guaranteed
-version: "1.0.0"
-title: "Guaranteed media buy with human IO approval"
-protocol: media-buy
-category: sales_guaranteed
-summary: "Seller agent that requires human-in-the-loop IO signing before guaranteed media buys go live."
-track: media_buy
-required_tools:
-  - sync_governance
-  - 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/invalid_transitions
-  - media_buy_seller/proposal_finalize
-  - media_buy_seller/proposal_finalize_asap_timing
-  - media_buy_seller/proposal_not_found_errors
-  - governance_aware_seller/governance_multi_agent_rejected
-
-# Cross-step assertion (adcp#2664). status.monotonic rejects resource
-# status transitions observed across steps that aren't on the spec
-# lifecycle graph — e.g. active → pending_creatives on a media_buy.
-invariants:
-  - status.monotonic
-
-context:
-  governance_agent_url: "https://test-agent.adcontextprotocol.org"
-
-narrative: |
-  You run a sell-side platform that requires human approval before guaranteed media buys go
-  live. When a buyer creates a guaranteed buy, your platform returns an A2A task in the
-  submitted state with a task_id — no media_buy_id is issued yet because IO signing may fail.
-  A human reviewer on your side reviews the deal terms and signs the IO through your own
-  internal workflow.
-
-  The buyer either polls tasks/get with the task_id or configures a push_notification_config
-  webhook to receive a callback when IO signing completes. Only on task completion does your
-  platform issue a media_buy_id and the final CreateMediaBuy result; the buyer then calls
-  get_media_buys to confirm the buy is active and sync creatives.
-
-  This storyboard isolates the guaranteed approval path — the async handshake between agent
-  automation and human decision-making that makes guaranteed buys work in practice. IO review
-  is modelled entirely at the A2A task layer; there is no interim "pending_approval" media buy
-  status (that value only exists on Account.status, not MediaBuy.status).
-
-  Proposal-driven workflows are part of guaranteed selling: most guaranteed deals start with
-  an RFP/brief, generate a proposal with curated bundles and rationale, refine, finalize to
-  committed status with firm pricing and an inventory hold, and then the buyer accepts via
-  create_media_buy. The `media_buy_seller/proposal_finalize` scenario covers that flow and is
-  capability-gated on `media_buy.supports_proposals` — sellers that declare `false` (or omit
-  the field, since the schema default is false) skip it with skip_result.reason: not_applicable;
-  sellers that explicitly declare `true` are graded against it. Direct-buy guaranteed sellers
-  (auction PG, retail SKU, quoted-rate) declare `supports_proposals: false`; full-service
-  guaranteed sellers declare `true`.
-
-  The requires_io_approval capability is scoped to creates that reference products with
-  delivery_type: guaranteed (those in this storyboard's primary fixtures). Four of the
-  general seller scenarios included via requires_scenarios — measurement_terms_rejected,
-  pending_creatives_to_start, inventory_list_targeting, and invalid_transitions — use
-  open-ended product briefs and must complete creates synchronously, returning a media_buy_id
-  directly rather than a task envelope. This storyboard seeds non-guaranteed fixture products
-  so those four scenarios have a synchronous-create path available. A seller whose catalog
-  contains only guaranteed products will fail those four shared scenarios.
-
-agent:
-  interaction_model: media_buy_seller
-  capabilities:
-    - sells_media
-    - supports_guaranteed
-    - requires_io_approval
-  examples:
-    - "Premium publisher with IO requirements"
-    - "Retail media network with sales approval"
-    - "CTV platform with guaranteed deals"
-
-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 guaranteed approval flow.
-  test_kit: "test-kits/acme-outdoor.yaml"
-  controller_seeding: true
-
-fixtures:
-  products:
-    # Non-guaranteed products listed first so open-brief get_products calls (used by
-    # requires_scenarios) resolve to products[0] as a non-guaranteed product, enabling
-    # synchronous creates. The four shared scenarios (measurement_terms_rejected,
-    # pending_creatives_to_start, inventory_list_targeting, invalid_transitions) capture
-    # products[0].product_id and must get a non-guaranteed ID to complete synchronously.
-    - product_id: "display_outdoor_non_guaranteed"
-      delivery_type: "non_guaranteed"
-      channels: ["display"]
-      format_ids:
-        - id: "display_300x250"
-    - product_id: "video_outdoor_non_guaranteed"
-      delivery_type: "non_guaranteed"
-      channels: ["video"]
-      format_ids:
-        - id: "video_30s"
-    # Guaranteed products used by the main storyboard phases (hardcoded in sample_requests).
-    - product_id: "sports_preroll_q2_guaranteed"
-      delivery_type: "guaranteed"
-      channels: ["video"]
-      format_ids:
-        - id: "video_30s"
-    - product_id: "outdoor_ctv_q2_guaranteed"
-      delivery_type: "guaranteed"
-      channels: ["ctv"]
-      format_ids:
-        - id: "video_30s"
-  pricing_options:
-    - product_id: "display_outdoor_non_guaranteed"
-      pricing_option_id: "cpm_display_non_guaranteed"
-      pricing_model: "cpm"
-      currency: "USD"
-      floor_price: 5.0
-    - product_id: "video_outdoor_non_guaranteed"
-      pricing_option_id: "cpm_video_non_guaranteed"
-      pricing_model: "cpm"
-      currency: "USD"
-      floor_price: 12.0
-    - product_id: "sports_preroll_q2_guaranteed"
-      pricing_option_id: "cpm_guaranteed_fixed"
-      pricing_model: "cpm"
-      currency: "USD"
-      fixed_price: 35.0
-    - product_id: "outdoor_ctv_q2_guaranteed"
-      pricing_option_id: "cpm_guaranteed_fixed"
-      pricing_model: "cpm"
-      currency: "USD"
-      fixed_price: 45.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: "sales_guaranteed--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: "sales_guaranteed--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.
-
-    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.
-        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
-        expected: |
-          Return the account with:
-          - account_id: your platform's identifier for this relationship
-          - action: created or updated
-          - status: active or pending_approval
-          - account_scope: operator, brand, operator_brand, or agent
-          - setup: URL and message if pending_approval
-          - 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#sales_guaranteed_account_setup_sync_accounts"
-          context:
-            correlation_id: "sales_guaranteed--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: "sales_guaranteed--sync_accounts"
-            description: "Context correlation_id returned unchanged"
-      - id: sync_governance
-        title: "Register governance agent"
-        narrative: |
-          The buyer registers the configured governance agent on the account before
-          accepting a guaranteed media buy.
-        task: sync_governance
-        schema_ref: "account/sync-governance-request.json"
-        response_schema_ref: "account/sync-governance-response.json"
-        doc_ref: "/accounts/tasks/sync_governance"
-        stateful: true
-        expected: |
-          Acknowledge governance registration for the account:
-          - status: synced
-          - governance_agents[0].url echoes the configured governance agent
-
-        sample_request:
-          accounts:
-            - account:
-                brand:
-                  domain: "acmeoutdoor.example"
-                operator: "pinnacle-agency.example"
-              governance_agents:
-                - url: "$context.governance_agent_url"
-                  authentication:
-                    schemes: ["Bearer"]
-                    credentials: "gov-token-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
-
-          idempotency_key: "$generate:uuid_v4#sales_guaranteed_account_setup_sync_governance"
-          context:
-            correlation_id: "sales_guaranteed--sync_governance"
-        validations:
-          - check: response_schema
-            description: "Response matches sync-governance-response.json schema"
-          - check: field_value
-            path: "accounts[0].status"
-            value: "synced"
-            description: "Governance agent is registered on the account"
-          - check: field_present
-            path: "context"
-            description: "Response echoes back the context object"
-          - check: field_value
-            path: "context.correlation_id"
-            value: "sales_guaranteed--sync_governance"
-            description: "Context correlation_id returned unchanged"
-  - id: product_discovery
-    title: "Discover guaranteed products"
-    narrative: |
-      The buyer sends a brief to discover your guaranteed inventory. The emphasis
-      here is on products with delivery_type: guaranteed — fixed-price, reserved
-      inventory that requires an IO commitment. Your platform returns products with
-      pricing, delivery forecasts, and SLA commitments.
-
-    steps:
-      - id: get_products_brief
-        title: "Send a brief targeting guaranteed inventory"
-        narrative: |
-          The buyer describes what they want, emphasizing guaranteed delivery. Your
-          platform returns products with delivery_type: guaranteed, including SLA
-          commitments, minimum spend requirements, and IO terms.
-        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 guaranteed products matching the brief. Each product should include:
-          - product_id: unique identifier
-          - name and description
-          - delivery_type: guaranteed
-          - pricing_models: fixed CPM or flat-rate pricing
-          - forecast: committed impressions with SLA guarantees
-          - creative_format_ids: required creative formats
-          - minimum_spend or commitment terms if applicable
-
-        sample_request:
-          buying_mode: "brief"
-          brief: "Guaranteed premium video on sports and outdoor lifestyle publishers. Q2 flight, $50K budget. Adults 25-54, US only. Need completion rate SLA."
-          account:
-            brand:
-              domain: "acmeoutdoor.example"
-            operator: "pinnacle-agency.example"
-
-          context:
-            correlation_id: "sales_guaranteed--get_products_brief"
-        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 delivery_type: guaranteed"
-
-          - check: field_present
-            path: "context"
-            description: "Response echoes back the context object"
-          - check: field_value
-            path: "context.correlation_id"
-            value: "sales_guaranteed--get_products_brief"
-            description: "Context correlation_id returned unchanged"
-          - 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"
-  - id: create_buy_submitted
-    title: "Create guaranteed buy (task submitted for approval)"
-    narrative: |
-      The buyer creates a guaranteed media buy. Because your platform requires human
-      IO signing, the A2A task transitions to submitted rather than completed. The
-      buyer gets back a task_id and configures a webhook (or polls tasks/get) to be
-      notified when IO review finishes.
-
-    steps:
-      - id: create_media_buy
-        title: "Create a guaranteed media buy"
-        narrative: |
-          The buyer commits to guaranteed products with budgets and flight dates. Your
-          platform accepts the request but does not create the media buy yet. Instead,
-          the A2A task enters the submitted state — no media_buy_id is issued because
-          IO signing may fail. The buyer receives a task_id to watch.
-
-          The buyer includes push_notification_config so your platform can call back
-          when the IO is signed (completed) or rejected (failed).
-        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: |
-          Return an A2A task envelope in submitted state:
-          - status: submitted (task-level — the CreateMediaBuy success artifact is not yet produced)
-          - task_id / taskId: the handle the buyer polls or receives webhooks on
-          - message (optional): human-readable explanation (e.g., "Awaiting IO signature from sales team; typical turnaround 2–4 hours")
-
-          Do NOT return media_buy_id or packages yet — those land on the task's final artifact
-          when the task transitions to completed. Do NOT return completed status for guaranteed
-          buys that require IO signing. Do NOT use a "pending_approval" media buy status; that
-          value is not in MediaBuy.status — IO review is modelled at the task layer only.
-
-        sample_request:
-          brand:
-            domain: "acmeoutdoor.example"
-          account:
-            brand:
-              domain: "acmeoutdoor.example"
-            operator: "pinnacle-agency.example"
-          start_time: "2026-04-01T00:00:00Z"
-          end_time: "2026-06-30T23:59:59Z"
-          packages:
-            - product_id: "sports_preroll_q2_guaranteed"
-              budget: 30000
-              pricing_option_id: "cpm_guaranteed_fixed"
-              creative_assignments:
-                - creative_id: "video_30s_trail_pro"
-            - product_id: "outdoor_ctv_q2_guaranteed"
-              budget: 20000
-              pricing_option_id: "cpm_guaranteed_fixed"
-          push_notification_config:
-            url: "https://buyer.example/webhooks/adcp"
-            authentication:
-              schemes:
-                - "HMAC-SHA256"
-              credentials: "sales-guaranteed-webhook-secret-token"
-
-          idempotency_key: "$generate:uuid_v4#sales_guaranteed_create_buy_submitted_create_media_buy"
-          context:
-            correlation_id: "sales_guaranteed--create_media_buy"
-        context_outputs:
-          - name: media_buy_id
-            path: "task_completion.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: "sales_guaranteed--create_media_buy"
-            description: "Context correlation_id returned unchanged"
-  - id: confirm_active
-    title: "Confirm active after IO signing"
-    narrative: |
-      The human on your side reviews and signs the IO through your internal workflow.
-      Your platform then transitions the A2A task to completed and emits the final
-      CreateMediaBuy result — including the newly-issued media_buy_id — to the buyer's
-      push_notification webhook (or to the next tasks/get poll). The buyer now calls
-      get_media_buys with that media_buy_id and sees the buy active. There is no
-      intermediate "pending_approval" media buy status in this flow; the buy does not
-      exist as a queryable MediaBuy until the task completes.
-
-    steps:
-      - id: get_media_buys_active
-        title: "Check media buy status (active)"
-        narrative: |
-          After the task completes and your platform issues a media_buy_id, the buyer
-          calls get_media_buys to confirm the buy is live. Your platform returns active
-          (or pending_creatives when creatives are still outstanding), indicating the
-          buy is approved and inventory is reserved.
-        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 media buy in active status:
-          - media_buy_id: matches the buy created earlier
-          - status: active (IO has been signed)
-          - confirmed_at: timestamp when the IO was signed
-          - packages: line items with reserved inventory
-          - valid_actions: updated for active state (creative sync, pause, etc.)
-
-        sample_request:
-          account:
-            brand:
-              domain: "acmeoutdoor.example"
-            operator: "pinnacle-agency.example"
-          media_buy_ids:
-            - "$context.media_buy_id"
-
-          context:
-            correlation_id: "sales_guaranteed--get_media_buys_active"
-        validations:
-          - check: response_schema
-            description: "Response matches get-media-buys-response.json schema"
-          - check: field_present
-            path: "media_buys[0].status"
-            description: "Media buy status is active"
-          - check: field_present
-            path: "media_buys[0].confirmed_at"
-            description: "Active buy includes a confirmed_at timestamp"
-
-          - check: field_present
-            path: "context"
-            description: "Response echoes back the context object"
-          - check: field_value
-            path: "context.correlation_id"
-            value: "sales_guaranteed--get_media_buys_active"
-            description: "Context correlation_id returned unchanged"
-  - id: creative_sync
-    title: "Creative sync"
-    narrative: |
-      With the IO signed and the media buy active, the buyer syncs creative assets
-      to your platform. Each package has creative format requirements that the buyer
-      discovered during product discovery.
-
-    steps:
-      - id: sync_creatives
-        title: "Push creative assets"
-        narrative: |
-          The buyer uploads creative assets for the confirmed packages. Your platform
-          validates each creative against the format specs 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
-
-        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:
-                agent_url: "https://your-platform.example.com"
-                id: "ssai_30s"
-              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"
-
-          idempotency_key: "$generate:uuid_v4#sales_guaranteed_creative_sync_sync_creatives"
-          context:
-            correlation_id: "sales_guaranteed--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: "sales_guaranteed--sync_creatives"
-            description: "Context correlation_id returned unchanged"
-  - id: delivery_monitoring
-    title: "Delivery and reporting"
-    narrative: |
-      The campaign is live with guaranteed delivery commitments. The buyer monitors
-      delivery to ensure the seller is meeting the SLA guarantees from the IO.
-
-    steps:
-      - id: get_delivery
-        title: "Check delivery metrics"
-        narrative: |
-          The buyer requests delivery data for the active guaranteed media buy. Your
-          platform returns performance metrics with pacing against the guaranteed
-          commitment.
-        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 guaranteed media buy:
-          - Per-package delivery: impressions, clicks, spend, completion rates
-          - Pacing against guaranteed commitment: on track, ahead, behind
-          - Budget utilization: spent vs. committed
-          - SLA compliance: completion rate vs. guaranteed threshold
-
-        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: "sales_guaranteed--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: "sales_guaranteed--get_delivery"
-            description: "Context correlation_id returned unchanged"