@adcp/sdk 14.0.0-rc.37 → 14.0.0-rc.39

package/compliance/cache/3.1.0-beta.7/protocols/media-buy/scenarios/performance_buy_flow.yaml

@@ -1,428 +0,0 @@
-id: media_buy_seller/performance_buy_flow
-version: "1.0.0"
-title: "Seller fulfills a performance (event-kind goal) media buy with a CPA target"
-category: media_buy_seller
-summary: "Verifies that a seller advertising conversion_tracking can bind an event source, accept a media buy with an event-kind optimization_goal targeting CPA, reject malformed performance briefs, ingest conversion events, and report conversion-attributed delivery including per-creative breakdown. ROAS / maximize_value goals are out of scope — see media_buy_seller/performance_buy_flow_roas (separate scenario, gated on the supported_target_kinds capability bit from #4639)."
-track: media_buy
-
-# Gate: scenario runs only when the seller declares conversion_tracking.
-# Sellers without it (pure brand/audience sellers — broadcast TV, signal-only)
-# grade `not_applicable`, not failing. Requires runner support for the
-# `present:` matcher (adcp-client >= 7.6.0).
-requires_capability:
-  path: media_buy.conversion_tracking
-  present: true
-
-required_tools:
-  - get_products
-  - sync_event_sources
-  - create_media_buy
-  - log_event
-  - get_media_buy_delivery
-  - comply_test_controller
-
-invariants:
-  - status.monotonic
-
-narrative: |
-  A "performance buy" is a media buy whose optimization_goal is event-kind: the
-  buyer commits to a target_cpa and binds the buy to one or more conversion
-  event sources registered via sync_event_sources. The seller owns optimization
-  toward the goal; the buyer feeds back conversions via log_event and reads
-  attributed delivery via get_media_buy_delivery.
-
-  This scenario is a buy-mode contract test, not a parent specialism. A DSP or
-  social platform may run audience buys AND performance buys against the same
-  agent; this scenario certifies that the performance path connects end-to-end
-  when the seller advertises conversion_tracking.
-
-  Discriminating behaviors this scenario verifies:
-  1. sync_event_sources returns an event_source_id that is then valid as the
-     binding target on optimization_goals[].event_sources[].event_source_id.
-  2. create_media_buy with an event-kind goal (CPA target) pointing at the
-     registered source is accepted.
-  3. create_media_buy with an event-kind goal pointing at an unregistered
-     source is rejected (INVALID_REQUEST with error.field set to the goal's
-     event_source_id path) — silent acceptance would mean the seller cannot
-     actually optimize against that source.
-  4. log_event flows conversions back, scoped to the registered event_source_id.
-  5. get_media_buy_delivery returns first-class conversion metrics —
-     conversions and cost_per_acquisition — at the buy level. Per-creative
-     conversion attribution is deliberately deferred to a follow-up scenario
-     (gated on a separate sub-capability bit) because real adopters report
-     attribution at differing granularities (per-creative, per-line,
-     per-campaign, per-placement); requiring per-creative here would fail
-     honest retail-media / MMP-mediated / broadcast-CTV implementations.
-
-  ROAS (target.kind = per_ad_spend) and value-max (target.kind = maximize_value)
-  are deliberately NOT asserted here. Many sellers — broadcast TV, upper-funnel
-  video, signal-only — declare conversion_tracking honestly but don't compute
-  return-on-ad-spend. Gating the CPA path on conversion_tracking presence is
-  safe; gating ROAS the same way would over-claim. ROAS gets its own scenario
-  (performance_buy_flow_roas) gated on the supported_target_kinds capability
-  bit proposed in #4639.
-
-agent:
-  interaction_model: media_buy_seller
-  capabilities:
-    - sells_media
-    - supports_non_guaranteed
-    - conversion_tracking
-  examples:
-    - "Performance-mode DSPs (open web + social)"
-    - "Meta / TikTok / Snap performance buying surfaces"
-    - "Retail-media performance products"
-    - "Agentic optimizers wrapping multiple buying surfaces"
-
-caller:
-  role: buyer_agent
-  example: "Pinnacle Agency (buyer)"
-
-prerequisites:
-  description: |
-    The seller must implement comply_test_controller with simulate_delivery
-    (already required for delivery_reporting). simulate_delivery's `conversions`
-    param injects attributed conversion counts so get_media_buy_delivery has
-    something to return.
-
-    The buyer fixture supplies a brand, an operator, a conversion event source
-    definition, and a small creative set sufficient to exercise per-creative
-    breakdown.
-  test_kit: "test-kits/acme-outdoor.yaml"
-  controller_seeding: true
-
-fixtures:
-  products:
-    - product_id: "performance_native_q2"
-      delivery_type: "non_guaranteed"
-      channels: ["display", "native"]
-      format_ids:
-        - id: "native_feed_1x1"
-        - id: "display_300x250"
-  pricing_options:
-    - product_id: "performance_native_q2"
-      pricing_option_id: "auction_cpm"
-      pricing_model: "cpm"
-      currency: "USD"
-      floor_price: 1.50
-
-phases:
-
-  - id: setup
-    title: "Establish account and discover products"
-    steps:
-      - id: sync_accounts
-        title: "Establish account"
-        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 and status active.
-        sample_request:
-          accounts:
-            - brand:
-                domain: "acmeoutdoor.example"
-              operator: "pinnacle-agency.example"
-              billing: "operator"
-          idempotency_key: "$generate:uuid_v4#performance_buy_flow_setup_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"
-
-      - id: get_products_for_performance
-        title: "Discover products that support performance optimization"
-        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"
-        stateful: false
-        expected: |
-          Return at least one product whose conversion_tracking capabilities
-          indicate event-kind goals are accepted.
-        sample_request:
-          buying_mode: "brief"
-          brief: "Performance native + display, US, adults 25-54. Target CPA $35 on purchase events from acmeoutdoor.example."
-          required_capabilities:
-            - "conversion_tracking"
-          account:
-            brand:
-              domain: "acmeoutdoor.example"
-            operator: "pinnacle-agency.example"
-        validations:
-          - check: response_schema
-            description: "Response matches get-products-response.json schema"
-          - check: field_present
-            path: "products"
-            description: "Response contains products"
-
-  - id: event_source_binding
-    title: "Register the conversion event source"
-    narrative: |
-      The performance buy cannot be created without a registered event source.
-      This phase exercises the binding — sync_event_sources returns an
-      event_source_id that subsequent create_media_buy calls reference.
-
-    steps:
-      - id: sync_event_sources
-        title: "Register a website conversion source"
-        task: sync_event_sources
-        schema_ref: "media-buy/sync-event-sources-request.json"
-        response_schema_ref: "media-buy/sync-event-sources-response.json"
-        doc_ref: "/media-buy/task-reference/sync_event_sources"
-        stateful: true
-        expected: |
-          Return event_sources with event_source_id, setup.snippet,
-          and action: created. The id is captured for the create_media_buy phase.
-        sample_request:
-          account:
-            brand:
-              domain: "acmeoutdoor.example"
-            operator: "pinnacle-agency.example"
-          event_sources:
-            - event_source_id: "acmeoutdoor_website"
-              name: "Acme Outdoor Website"
-              event_types: ["purchase", "add_to_cart"]
-              allowed_domains: ["acmeoutdoor.example"]
-          idempotency_key: "$generate:uuid_v4#performance_buy_flow_event_source_binding_sync_event_sources"
-        validations:
-          - check: response_schema
-            description: "Response matches sync-event-sources-response.json schema"
-          - check: field_present
-            path: "event_sources[0].event_source_id"
-            description: "Event source has a platform-assigned ID"
-          - check: field_present
-            path: "event_sources[0].setup.snippet"
-            description: "Event source returns integration code"
-
-  - id: create_performance_buy_cpa
-    title: "Create a performance buy with a CPA goal"
-    narrative: |
-      The buyer creates a media buy whose package carries an event-kind
-      optimization_goal binding to the registered event source. The target
-      is target_cpa $35 on purchase events.
-
-    steps:
-      - id: create_media_buy_cpa
-        title: "Create media buy with event-kind goal (CPA)"
-        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"
-        stateful: true
-        expected: |
-          Create the media buy. Response carries a media_buy_id used for
-          subsequent log_event and get_media_buy_delivery calls.
-        sample_request:
-          brand:
-            domain: "acmeoutdoor.example"
-          account:
-            brand:
-              domain: "acmeoutdoor.example"
-            operator: "pinnacle-agency.example"
-          start_time: "2026-06-01T00:00:00Z"
-          end_time: "2026-06-30T23:59:59Z"
-          packages:
-            - product_id: "performance_native_q2"
-              budget: 25000
-              pricing_option_id: "auction_cpm"
-              optimization_goals:
-                - kind: "event"
-                  event_sources:
-                    - event_source_id: "acmeoutdoor_website"
-                      event_type: "purchase"
-                      value_field: "order_total"
-                  target:
-                    kind: "cost_per"
-                    value: 35.00
-                  priority: 1
-          idempotency_key: "$generate:uuid_v4#performance_buy_flow_create_performance_buy_cpa_create_media_buy"
-        validations:
-          - check: response_schema
-            description: "Response matches create-media-buy-response.json schema"
-          - check: field_present
-            path: "media_buy_id"
-            description: "Media buy has a platform-assigned ID"
-
-  - id: rejection_unbound_event_source
-    title: "Reject a buy referencing an unregistered event source"
-    narrative: |
-      Silent acceptance of an unregistered event_source_id is a façade — the
-      seller cannot optimize against a source it doesn't know about. The
-      seller MUST reject with INVALID_REQUEST and set error.field to the
-      offending event_source_id path.
-
-    steps:
-      - id: create_media_buy_with_phantom_source
-        title: "Submit a buy whose goal references a non-existent event_source_id"
-        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"
-        expect_error: true
-        negative_path: payload_well_formed
-        stateful: false
-        expected: |
-          Reject with INVALID_REQUEST. error.field points at the goal's
-          event_sources[].event_source_id path. media_buy_id is not allocated.
-        sample_request:
-          brand:
-            domain: "acmeoutdoor.example"
-          account:
-            brand:
-              domain: "acmeoutdoor.example"
-            operator: "pinnacle-agency.example"
-          start_time: "2026-06-01T00:00:00Z"
-          end_time: "2026-06-30T23:59:59Z"
-          packages:
-            - product_id: "performance_native_q2"
-              budget: 5000
-              pricing_option_id: "auction_cpm"
-              optimization_goals:
-                - kind: "event"
-                  event_sources:
-                    - event_source_id: "does_not_exist_phantom_source"
-                      event_type: "purchase"
-                  target:
-                    kind: "cost_per"
-                    value: 35.00
-          idempotency_key: "$generate:uuid_v4#performance_buy_flow_rejection_unbound_event_source"
-        validations:
-          - check: error_code
-            allowed_values: ["INVALID_REQUEST"]
-            description: "Seller rejects the unbound event_source_id with INVALID_REQUEST"
-          - check: field_value
-            path: "errors[0].field"
-            value: "packages[0].optimization_goals[0].event_sources[0].event_source_id"
-            description: "Error.field points at the offending event_source_id path (core/error.json defines field as deterministic JSONPath-lite — literal equality)"
-
-  - id: conversion_event_logging
-    title: "Log conversion events against the bound source"
-    narrative: |
-      The buyer logs purchase events tied to the registered event_source_id.
-      These flow into the seller's attribution pipeline and surface in
-      delivery reporting in the next phase.
-
-    steps:
-      - id: log_purchase_event
-        title: "Log a purchase event with value"
-        task: log_event
-        schema_ref: "media-buy/log-event-request.json"
-        response_schema_ref: "media-buy/log-event-response.json"
-        doc_ref: "/media-buy/task-reference/log_event"
-        stateful: true
-        expected: |
-          Acknowledge the event with accepted status.
-        sample_request:
-          account:
-            brand:
-              domain: "acmeoutdoor.example"
-            operator: "pinnacle-agency.example"
-          event_source_id: "acmeoutdoor_website"
-          events:
-            - event_type: "purchase"
-              event_id: "evt_perf_buy_flow_001"
-              event_time: "2026-06-05T14:30:00Z"
-              user_match:
-                hashed_email: "a000000000000000000000000000000000000000000000000000000000000001"
-              custom_data:
-                order_total: 149.99
-                currency: "USD"
-          idempotency_key: "$generate:uuid_v4#performance_buy_flow_conversion_event_logging_log_event"
-        validations:
-          - check: response_schema
-            description: "Response matches log-event-response.json schema"
-          - check: upstream_traffic
-            description: "log_event forwards the event to the seller's upstream conversion endpoint"
-            min_count: 1
-            endpoint_pattern: "POST *"
-            identifier_paths:
-              - "events[*].user_match.hashed_email"
-
-  - id: attributed_delivery_reporting
-    title: "Delivery reporting carries conversion-attributed metrics and per-creative breakdown"
-    narrative: |
-      The discriminating assertion of the performance buy mode: delivery
-      reporting MUST surface conversion metrics, not just impressions.
-      The runner injects simulated impressions + conversions via the test
-      controller, then verifies get_media_buy_delivery returns conversions,
-      cost_per_acquisition, and a per-creative breakdown whose entries
-      carry conversion attribution.
-
-      Optional metrics (conversion_value, roas) are validated against schema
-      shape when present but not required — sellers that don't compute
-      return-on-ad-spend simply omit them.
-
-    steps:
-      - id: simulate_performance_delivery
-        title: "Inject impressions + conversions + spend"
-        task: comply_test_controller
-        requires_tool: comply_test_controller
-        stateful: true
-        expected: |
-          The test controller acknowledges the simulated delivery.
-        sample_request:
-          account:
-            sandbox: true
-          scenario: "simulate_delivery"
-          params:
-            media_buy_id: "$context.media_buy_id"
-            impressions: 200000
-            clicks: 4500
-            conversions: 90
-            reported_spend:
-              amount: 3000.00
-              currency: "USD"
-        validations:
-          - check: field_value
-            path: "success"
-            allowed_values: [true]
-            description: "Delivery simulation succeeds"
-
-      - id: get_attributed_delivery
-        title: "Get delivery and verify conversion-attributed metrics"
-        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"
-        stateful: true
-        expected: |
-          Delivery response includes:
-          - conversions (>= simulated)
-          - cost_per_acquisition (effective CPA — required for this scenario)
-
-          Per-creative conversion attribution (by_package[].by_creative[].conversions)
-          is intentionally NOT asserted here. Honest implementations vary widely:
-          social platforms surface per-ad attribution natively, retail-media
-          networks (Criteo, Amazon Ads) often expose conversions at the line
-          level with creative rotation opaque, MMP-mediated mobile (post-iOS-14)
-          attributes at the campaign/ad-set level, and broadcast/CTV performance
-          products attribute at the placement. Per-creative attribution will
-          land as its own gated scenario behind a sub-capability bit in a
-          follow-up.
-
-          Optional but validated-if-present (sellers that compute ROAS will
-          carry these; sellers that don't simply omit them):
-          - conversion_value
-          - roas
-        sample_request:
-          account:
-            brand:
-              domain: "acmeoutdoor.example"
-            operator: "pinnacle-agency.example"
-          media_buy_ids:
-            - "$context.media_buy_id"
-          include_package_daily_breakdown: true
-        validations:
-          - check: response_schema
-            description: "Response matches get-media-buy-delivery-response.json schema"
-          - check: field_present
-            path: "media_buy_deliveries[0].totals.conversions"
-            description: "Conversion count surfaced at the buy level"
-          - check: field_present
-            path: "media_buy_deliveries[0].totals.cost_per_acquisition"
-            description: "Effective CPA computed and returned"