@adcp/sdk 7.11.0 → 7.11.1

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

@@ -0,0 +1,428 @@
+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"