@adcp/sdk 7.10.2 → 7.11.1

package/compliance/cache/3.1.0-rc.2/protocols/media-buy/scenarios/inventory_list_targeting.yaml

@@ -0,0 +1,276 @@
+id: media_buy_seller/inventory_list_targeting
+version: "1.0.0"
+title: "Seller honors property_list and collection_list targeting on create and update"
+category: media_buy_seller
+summary: "Verifies that a seller accepts PropertyListReference and CollectionListReference in package targeting on create_media_buy AND update_media_buy, with parity between both paths."
+track: media_buy
+required_tools:
+  - get_products
+  - create_media_buy
+  - update_media_buy
+
+narrative: |
+  AdCP 3.0 targets inventory through agent-hosted reference lists rather than inline
+  property arrays. Buyers point a package's targeting at a `PropertyListReference`
+  and/or `CollectionListReference`; the seller resolves the list against its own
+  inventory at serve time.
+
+  A common integration regression is create/update parity: a seller accepts list
+  references on create_media_buy but silently drops them on update_media_buy, so a
+  buyer who edits a live buy loses their list targeting. This scenario writes both
+  list types on create, then swaps both on update, and finally reads the buy back
+  to confirm the updated references are what the seller persisted.
+
+  The buyer references pre-populated inventory lists from the test kit — one for
+  matching properties and one for matching collections — so the seller's test
+  engine can resolve them without needing a live governance/inventory agent.
+
+agent:
+  interaction_model: media_buy_seller
+  capabilities:
+    - sells_media
+    - supports_property_list_targeting
+    - supports_collection_list_targeting
+  examples:
+    - "Sellers that accept PropertyListReference / CollectionListReference in package targeting"
+
+caller:
+  role: buyer_agent
+  example: "Pinnacle Agency (buyer)"
+
+prerequisites:
+  description: |
+    The seller must accept PropertyListReference and CollectionListReference in
+    package targeting on both create_media_buy and update_media_buy. List contents
+    come from test-kits/acme-outdoor.yaml → inventory_targets.
+  test_kit: "test-kits/acme-outdoor.yaml"
+
+phases:
+  - id: discover_product
+    title: "Discover a product that supports list targeting"
+    steps:
+      - id: get_products_brief
+        title: "Discover product"
+        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 at least one product whose targeting supports property_list and
+          collection_list references.
+
+        sample_request:
+          buying_mode: "brief"
+          brief: "Video inventory on outdoor lifestyle programming. Q3 flight, $30K budget."
+          filters:
+            is_fixed_price: true
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+            sandbox: true
+
+          context:
+            correlation_id: "inventory_list_targeting--get_products_brief"
+        context_outputs:
+          - path: "products[0].product_id"
+            key: "product_id"
+          - path: "products[0].pricing_options[0].pricing_option_id"
+            key: "pricing_option_id"
+        validations:
+          - check: response_schema
+            description: "Response matches get-products-response.json schema"
+          - check: field_present
+            path: "products[0].product_id"
+            description: "Product has a product_id"
+          - check: field_present
+            path: "products[0].pricing_options[0].fixed_price"
+            description: "The captured pricing option is fixed-price; fixed-price storyboards do not send bid_price"
+
+  - id: create_with_both_lists
+    title: "Create media buy with property_list AND collection_list targeting"
+    narrative: |
+      The buyer references the matching-property list and the matching-collection
+      list from the test kit. The seller accepts both references, creates the buy,
+      and echoes the resolved targeting back on the package.
+
+    steps:
+      - id: create_buy_with_lists
+        title: "create_media_buy with both list references"
+        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: |
+          The seller accepts the list references without error. The response
+          includes a media_buy_id and the package retains both the property_list
+          and collection_list targeting fields so subsequent get / update calls
+          can read them back.
+
+        sample_request:
+          brand:
+            domain: "acmeoutdoor.example"
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+            sandbox: true
+          idempotency_key: "$generate:uuid_v4#inventory_list_targeting_create_buy"
+          start_time: "2026-07-01T00:00:00Z"
+          end_time: "2026-09-30T23:59:59Z"
+          packages:
+            - product_id: "$context.product_id"
+              budget: 20000
+              pricing_option_id: "$context.pricing_option_id"
+              targeting_overlay:
+                property_list:
+                  agent_url: "https://governance.pinnacle-agency.example"
+                  list_id: "acme_outdoor_allowlist_v1"
+                collection_list:
+                  agent_url: "https://governance.pinnacle-agency.example"
+                  list_id: "acme_outdoor_collections_v1"
+
+          context:
+            correlation_id: "inventory_list_targeting--create_buy_with_lists"
+        context_outputs:
+          - path: "media_buy_id"
+            key: "media_buy_id"
+          - path: "packages[0].package_id"
+            key: "package_id"
+        validations:
+          - check: response_schema
+            description: "Response matches create-media-buy-response.json schema"
+          - check: field_present
+            path: "media_buy_id"
+            description: "Seller assigns a media_buy_id"
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+
+  - id: verify_create_persisted
+    title: "Verify list targeting persisted after create"
+    narrative: |
+      Read the buy back to confirm the seller stored both list references — not just
+      echoed them back in the create response. This catches sellers that parse list
+      references on create but never persist them to their internal package model.
+
+    steps:
+      - id: get_after_create
+        title: "get_media_buys after create"
+        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 with packages[0].targeting_overlay.property_list
+          and .collection_list populated with the list_id values sent on create.
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+            sandbox: true
+          media_buy_ids:
+            - "$context.media_buy_id"
+
+          context:
+            correlation_id: "inventory_list_targeting--get_after_create"
+        validations:
+          - check: response_schema
+            description: "Response matches get-media-buys-response.json schema"
+          - check: field_value
+            path: "media_buys[0].packages[0].targeting_overlay.property_list.list_id"
+            value: "acme_outdoor_allowlist_v1"
+            description: "property_list.list_id persisted after create"
+          - check: field_value
+            path: "media_buys[0].packages[0].targeting_overlay.collection_list.list_id"
+            value: "acme_outdoor_collections_v1"
+            description: "collection_list.list_id persisted after create"
+
+  - id: update_swap_lists
+    title: "Swap property_list and collection_list via update_media_buy"
+    narrative: |
+      The buyer swaps both list references. This is the create/update parity check:
+      a seller that accepts list references on create but silently drops them on
+      update would fail to update the persisted targeting. We exercise update
+      explicitly to catch that class of regression.
+
+    steps:
+      - id: update_buy_swap_lists
+        title: "update_media_buy replaces both list references"
+        task: update_media_buy
+        schema_ref: "media-buy/update-media-buy-request.json"
+        response_schema_ref: "media-buy/update-media-buy-response.json"
+        doc_ref: "/media-buy/task-reference/update_media_buy"
+        comply_scenario: media_buy_lifecycle
+        stateful: true
+        expected: |
+          The seller acknowledges the updated targeting. Both property_list and
+          collection_list are replaced (not merged) with the new list_id values.
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+            sandbox: true
+          media_buy_id: "$context.media_buy_id"
+          packages:
+            - package_id: "$context.package_id"
+              targeting_overlay:
+                property_list:
+                  agent_url: "https://governance.pinnacle-agency.example"
+                  list_id: "acme_outdoor_no_match_v1"
+                collection_list:
+                  agent_url: "https://governance.pinnacle-agency.example"
+                  list_id: "acme_outdoor_no_match_collections_v1"
+
+          idempotency_key: "$generate:uuid_v4#media_buy_seller_inventory_list_targeting_update_swap_lists_update_buy_swap_lists"
+          context:
+            correlation_id: "inventory_list_targeting--update_buy_swap_lists"
+        validations:
+          - check: response_schema
+            description: "Response matches update-media-buy-response.json schema"
+
+      - id: get_after_update
+        title: "Confirm swap persisted"
+        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: |
+          The persisted package targeting reflects the new list_id values. This is
+          the create/update parity guarantee: edits through update_media_buy land
+          in persistent state just like fields on create_media_buy.
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+            sandbox: true
+          media_buy_ids:
+            - "$context.media_buy_id"
+
+          context:
+            correlation_id: "inventory_list_targeting--get_after_update"
+        validations:
+          - check: response_schema
+            description: "Response matches get-media-buys-response.json schema"
+          - check: field_value
+            path: "media_buys[0].packages[0].targeting_overlay.property_list.list_id"
+            value: "acme_outdoor_no_match_v1"
+            description: "property_list.list_id updated after update_media_buy"
+          - check: field_value
+            path: "media_buys[0].packages[0].targeting_overlay.collection_list.list_id"
+            value: "acme_outdoor_no_match_collections_v1"
+            description: "collection_list.list_id updated after update_media_buy"

package/compliance/cache/3.1.0-rc.2/protocols/media-buy/scenarios/measurement_accountability.yaml

@@ -0,0 +1,244 @@
+id: media_buy_seller/measurement_accountability
+version: "1.0.0"
+title: "End-to-end metric accountability through the media buy lifecycle"
+category: media_buy_seller
+summary: "Buyer requires specific reporting metrics at discovery; seller filters products to those that can deliver; delivery report exposes any gaps via missing_metrics."
+track: reporting
+required_tools:
+  - get_products
+  - create_media_buy
+  - get_media_buy_delivery
+  - comply_test_controller
+
+narrative: |
+  A buyer that needs `completed_views` for a CTV CPCV buy should be able to
+  enforce that requirement at discovery time, carry it through the lifecycle,
+  and verify in delivery reporting that the metric was actually produced.
+  AdCP supports this contract in three pieces:
+
+    1. `filters.required_metrics` on `get_products` — buyer declares the
+       metric vocabulary they need. Sellers MUST exclude products whose
+       `reporting_capabilities.available_metrics` is not a superset
+       (filter-not-fail; do not return an error). Derived ratio metrics
+       like `completion_rate` are satisfied by their underlying scalars.
+
+    2. The product's declared `available_metrics` carries forward as the
+       reporting contract — no additional field is needed on `create_media_buy`.
+
+    3. `by_package[].missing_metrics` on `get_media_buy_delivery` — seller
+       lists any metrics from the product's `available_metrics` that are
+       NOT populated in this report. Empty (or absent) means clean
+       delivery; non-empty signals an accountability breach.
+
+  This storyboard exercises that contract end to end. It uses
+  comply_test_controller to inject delivery so reporting has data to
+  validate, then asserts the schema-level contract on missing_metrics.
+
+agent:
+  interaction_model: media_buy_seller
+  capabilities:
+    - sells_media
+  examples:
+    - "CTV/streaming sellers with completion-rate reporting"
+    - "Any media buy seller that publishes available_metrics"
+
+caller:
+  role: buyer_agent
+  example: "Pinnacle Agency (buyer)"
+
+prerequisites:
+  description: |
+    The seller publishes `reporting_capabilities.available_metrics` on its
+    products and supports comply_test_controller's simulate_delivery
+    scenario for delivery reporting tests.
+  test_kit: "test-kits/acme-outdoor.yaml"
+  controller_seeding: true
+
+fixtures:
+  products:
+    - product_id: "ctv_premium_completed_views"
+      delivery_type: "guaranteed"
+      channels: ["ctv"]
+      format_ids:
+        - id: "video_15s"
+  pricing_options:
+    - product_id: "ctv_premium_completed_views"
+      pricing_option_id: "cpm_standard"
+      pricing_model: "cpm"
+      currency: "USD"
+      fixed_price: 25.0
+
+phases:
+  - id: discover_with_required_metrics
+    title: "Discover products that commit to reporting completed_views"
+    narrative: |
+      The buyer needs CTV inventory with `completed_views` reporting for a
+      CPCV-priced campaign. They pass `required_metrics: ["completed_views"]`
+      in filters. The seller MUST silently exclude products whose
+      `available_metrics` doesn't include `completed_views` — this is a
+      capability filter, not a guarantee threshold.
+    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"
+              payment_terms: "net_30"
+          idempotency_key: "$generate:uuid_v4#media_buy_seller_measurement_accountability_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_required_metrics
+        title: "Discover with required_metrics filter"
+        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 only products whose reporting_capabilities.available_metrics
+          includes "completed_views". Products that don't are silently
+          excluded; the seller does NOT return an error for unmet metrics.
+        sample_request:
+          buying_mode: "brief"
+          brief: "CTV inventory with completed-view reporting for a Q2 CPCV campaign."
+          filters:
+            channels: ["ctv"]
+            is_fixed_price: true
+            required_metrics:
+              - "completed_views"
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+        context_outputs:
+          - path: "products[0].product_id"
+            key: "product_id"
+          - path: "products[0].pricing_options[0].pricing_option_id"
+            key: "pricing_option_id"
+        validations:
+          - check: response_schema
+            description: "Response matches get-products-response.json schema"
+          - check: field_present
+            path: "products[0].product_id"
+            description: "At least one product matched the required metrics"
+          - check: field_present
+            path: "products[0].reporting_capabilities.available_metrics"
+            description: "Matched product declares its available_metrics — schema validation confirms the superset relationship via the closed enum"
+          - check: field_present
+            path: "products[0].pricing_options[0].fixed_price"
+            description: "The captured pricing option is fixed-price; fixed-price storyboards do not send bid_price"
+
+  - id: create_media_buy
+    title: "Commit the media buy"
+    steps:
+      - id: create_media_buy
+        title: "Create media buy on the matched product"
+        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: |
+          The buy succeeds. The product's available_metrics carries forward as
+          the reporting contract — no additional field is required on the buy.
+        sample_request:
+          brand:
+            domain: "acmeoutdoor.example"
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          start_time: "2026-05-01T00:00:00Z"
+          end_time: "2026-05-31T23:59:59Z"
+          packages:
+            - product_id: "$context.product_id"
+              pricing_option_id: "$context.pricing_option_id"
+              budget: 25000
+          idempotency_key: "$generate:uuid_v4#media_buy_seller_measurement_accountability_create"
+        validations:
+          - check: response_schema
+            description: "Response matches create-media-buy-response.json schema"
+          - check: field_present
+            path: "media_buy_id"
+            description: "Seller returns a media_buy_id"
+
+  - id: simulate_and_validate_accountability
+    title: "Simulate delivery and validate missing_metrics contract"
+    narrative: |
+      Inject simulated delivery via the test controller, then call
+      get_media_buy_delivery and check that `by_package[].missing_metrics` is
+      present and shaped correctly. When the seller has populated all metrics
+      it advertised, missing_metrics is empty (or absent). When a metric
+      from the product's available_metrics is not present in this report,
+      it MUST appear in missing_metrics — except for derived ratios
+      (completion_rate, ctr, etc.) which are derivable from scalars and
+      never appear in this list.
+    steps:
+      - id: simulate_delivery
+        title: "Inject simulated delivery metrics"
+        task: comply_test_controller
+        requires_tool: comply_test_controller
+        stateful: true
+        expected: |
+          The test controller acknowledges the simulated delivery data.
+        sample_request:
+          account:
+            sandbox: true
+          scenario: "simulate_delivery"
+          params:
+            media_buy_id: "$context.media_buy_id"
+            impressions: 100000
+            completed_views: 72000
+            reported_spend:
+              amount: 2500.00
+              currency: "USD"
+        validations:
+          - check: field_value
+            path: "success"
+            allowed_values: [true]
+            description: "Delivery simulation succeeds"
+
+      - id: get_delivery_clean
+        title: "Get delivery report and assert clean accountability"
+        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 with completed_views populated. The
+          by_package entry includes `missing_metrics: []` (or omits the
+          field entirely) because every metric the product advertised is
+          present in this report.
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          media_buy_ids:
+            - "$context.media_buy_id"
+        validations:
+          - check: response_schema
+            description: "Response matches get-media-buy-delivery-response.json schema (validates missing_metrics shape when present)"
+          - check: field_value_or_absent
+            path: "media_buy_deliveries[0].by_package[0].missing_metrics"
+            value: []
+            description: "missing_metrics is empty (or absent) — clean delivery against the declared contract, no accountability breach"