@adcp/sdk 7.11.1 → 7.11.3

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

@@ -1,293 +0,0 @@
-id: media_buy_seller/vendor_metric_accountability
-version: "1.0.0"
-title: "End-to-end vendor-metric accountability: declaration → filter → emission"
-category: media_buy_seller
-summary: "Buyer discovers products that declare a vendor metric, creates a media buy, and verifies vendor-metric values appear in the delivery report."
-track: reporting
-required_tools:
-  - get_products
-  - create_media_buy
-  - get_media_buy_delivery
-  - comply_test_controller
-
-narrative: |
-  Vendor-defined metrics (attention scores, emissions, panel demographics) must
-  flow through the full media buy lifecycle — declared at discovery, carried
-  through the buy, and emitted in delivery reporting. AdCP supports this in
-  three pieces:
-
-    1. `reporting_capabilities.vendor_metrics` on the product — each entry is a
-       pointer `{ vendor, metric_id }` into the vendor's metric catalog (category,
-       methodology, and documentation live at the vendor's `brand.json`).
-
-    2. `filters.required_vendor_metrics` on `get_products` — buyer declares which
-       vendor metric it needs. Sellers MUST silently exclude products that don't
-       match (filter-not-fail; do not return an error). At least one of `vendor`
-       or `metric_id` must be pinned per entry.
-
-    3. `by_package[].vendor_metric_values` on `get_media_buy_delivery` — reported
-       values for each declared vendor metric. One row per `(vendor.domain,
-       vendor.brand_id, metric_id)` per reporting period. Sellers MUST
-       de-duplicate before emission.
-
-  This storyboard exercises that contract end to end. It uses
-  comply_test_controller to seed a product with vendor metrics declared and to
-  inject delivery data with vendor_metric_values, then asserts the schema-level
-  contract on the delivery response.
-
-  Item 3 of the originating issue (#3501) — whether vendor-metric emission
-  failures need a dedicated hint kind — is deferred to a follow-up adcp-client PR.
-
-agent:
-  interaction_model: media_buy_seller
-  capabilities:
-    - sells_media
-  examples:
-    - "Any media buy seller that declares vendor_metrics on its products"
-
-caller:
-  role: buyer_agent
-  example: "Pinnacle Agency (buyer)"
-
-prerequisites:
-  description: |
-    The seller supports comply_test_controller and can seed products with
-    `reporting_capabilities.vendor_metrics`. The seeded product must appear in
-    `get_products` responses when filtered by the declared vendor.
-  test_kit: "test-kits/acme-outdoor.yaml"
-  controller_seeding: true
-
-fixtures:
-  products:
-    - product_id: "display_premium_vendor_metrics"
-      delivery_type: "guaranteed"
-      channels: ["display"]
-      format_ids:
-        - id: "display_300x250"
-      reporting_capabilities:
-        available_metrics:
-          - impressions
-          - clicks
-          - spend
-        vendor_metrics:
-          - vendor:
-              domain: "attentionvendor.example"
-            metric_id: "attention_units"
-  pricing_options:
-    - product_id: "display_premium_vendor_metrics"
-      pricing_option_id: "cpm_standard_vendor"
-      pricing_model: "cpm"
-      currency: "USD"
-      fixed_price: 12.0
-
-phases:
-  - id: discover_with_required_vendor_metrics
-    title: "Discover products that declare an attention vendor metric"
-    narrative: |
-      The buyer needs display inventory that declares attention measurement from
-      a specific vendor. They pass `required_vendor_metrics: [{ vendor: { domain:
-      "attentionvendor.example" } }]` in filters. The seller MUST silently exclude
-      products whose `reporting_capabilities.vendor_metrics` doesn't satisfy the
-      filter — same filter-not-fail convention as `required_metrics`.
-    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_vendor_metric_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_vendor_metrics
-        title: "Discover with required_vendor_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.vendor_metrics
-          includes an entry for vendor domain "attentionvendor.example". Products
-          that don't declare this vendor are silently excluded — the seller does
-          NOT return an error for unmet vendor metric requirements.
-        sample_request:
-          buying_mode: "brief"
-          brief: "Display inventory with attention measurement from attentionvendor."
-          filters:
-            channels: ["display"]
-            is_fixed_price: true
-            required_vendor_metrics:
-              - vendor:
-                  domain: "attentionvendor.example"
-          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_vendor_metrics filter"
-          - check: field_present
-            path: "products[0].reporting_capabilities.vendor_metrics"
-            description: "Matched product declares vendor_metrics in reporting_capabilities"
-          - check: field_present
-            path: "products[0].reporting_capabilities.vendor_metrics[0].vendor.domain"
-            description: "Each declared vendor metric entry carries a vendor domain"
-          - check: field_present
-            path: "products[0].reporting_capabilities.vendor_metrics[0].metric_id"
-            description: "Each declared vendor metric entry carries a metric_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_media_buy
-    title: "Commit the media buy on the matched product"
-    narrative: |
-      The buyer commits a media buy on the vendor-metric-capable product. The
-      product's `vendor_metrics` declaration carries forward as the vendor
-      reporting contract for the resulting buy — no additional field is required
-      on `create_media_buy` itself.
-    steps:
-      - id: create_media_buy
-        title: "Create media buy"
-        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 vendor_metrics declaration carries
-          forward as the vendor reporting contract — no additional field is
-          required on the buy itself.
-        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: 12000
-          idempotency_key: "$generate:uuid_v4#media_buy_seller_vendor_metric_accountability_create"
-        context_outputs:
-          - path: "media_buy_id"
-            key: "media_buy_id"
-        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_vendor_metrics
-    title: "Simulate delivery with vendor-metric values and validate emission"
-    narrative: |
-      Inject simulated delivery via the test controller, including
-      vendor_metric_values, then call get_media_buy_delivery and check that
-      `by_package[].vendor_metric_values` carries the injected entries.
-
-      The semantic uniqueness key for each vendor metric row is
-      `(vendor.domain, vendor.brand_id, metric_id)`. Since brand_id is optional
-      in BrandRef, the operative key for single-brand vendors is
-      `(vendor.domain, metric_id)`. Sellers MUST NOT emit the same
-      `(vendor, metric_id)` pair twice in a single delivery report.
-    steps:
-      - id: simulate_delivery_with_vendor_metrics
-        title: "Inject simulated delivery with vendor_metric_values"
-        task: comply_test_controller
-        requires_tool: comply_test_controller
-        stateful: true
-        expected: |
-          The test controller acknowledges the simulated delivery data including
-          the vendor_metric_values.
-        sample_request:
-          account:
-            sandbox: true
-          scenario: "simulate_delivery"
-          params:
-            media_buy_id: "$context.media_buy_id"
-            impressions: 80000
-            reported_spend:
-              amount: 960.00
-              currency: "USD"
-            vendor_metric_values:
-              - vendor:
-                  domain: "attentionvendor.example"
-                metric_id: "attention_units"
-                value: 4.2
-                unit: "score"
-                measurable_impressions: 72000
-        validations:
-          - check: field_value
-            path: "success"
-            allowed_values: [true]
-            description: "Delivery simulation succeeds"
-
-      - id: get_delivery_with_vendor_metrics
-        title: "Get delivery report and assert vendor_metric_values are present"
-        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 vendor_metric_values populated in
-          by_package[0]. The entry must carry vendor.domain, metric_id, and
-          value matching the injected data. measurable_impressions is the
-          coverage denominator — buyers compute coverage rate as
-          measurable_impressions / impressions.
-        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"
-          - check: field_present
-            path: "media_buy_deliveries[0].by_package[0].vendor_metric_values"
-            description: "by_package[0] includes vendor_metric_values — vendor metric emission contract honored"
-          - check: field_present
-            path: "media_buy_deliveries[0].by_package[0].vendor_metric_values[0].vendor.domain"
-            description: "Each vendor_metric_value entry carries a vendor domain"
-          - check: field_present
-            path: "media_buy_deliveries[0].by_package[0].vendor_metric_values[0].metric_id"
-            description: "Each vendor_metric_value entry carries a metric_id"
-          - check: field_present
-            path: "media_buy_deliveries[0].by_package[0].vendor_metric_values[0].value"
-            description: "Each vendor_metric_value entry carries a value"
-          - check: field_present
-            path: "media_buy_deliveries[0].by_package[0].vendor_metric_values[0].measurable_impressions"
-            description: "Coverage denominator is present — buyers can compute vendor measurement coverage rate"

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

@@ -1,307 +0,0 @@
-id: media_buy_seller/vendor_metric_catalog_precondition
-version: "1.0.0"
-title: "Vendor-metric external catalog precondition"
-category: media_buy_seller
-summary: "Exercises the 3.1 SHOULD-window behavior for vendor_metric goals whose metric_id is absent from a seeded measurement.metrics[] catalog."
-track: media_buy
-introduced_in: "3.1"
-
-# Gate: scenario runs only when the seller declares vendor-metric
-# optimization support. Sellers that do not advertise this optional 3.1
-# capability are not expected to handle vendor_metric optimization goals.
-requires_capability:
-  path: media_buy.vendor_metric_optimization
-  present: true
-
-required_tools:
-  - create_media_buy
-  - sync_accounts
-  - comply_test_controller
-
-narrative: |
-  Vendor-metric optimization goals bind to a measurement vendor's
-  `measurement.metrics[]` catalog. In AdCP 3.1, sellers SHOULD verify that the
-  goal's `(vendor, metric_id)` is present in that vendor-published catalog, but
-  MAY accept catalog misses while measurement vendors finish publishing
-  conformant capability catalogs. The next minor tightens this discovery
-  precondition to MUST.
-
-  This storyboard seeds two facts that intentionally diverge. The seller product
-  can optimize and report `attention_catalog_probe`, satisfying the product
-  capability and reporting-coherence preconditions. The measurement vendor
-  catalog seeded for `attentionvendor.example` publishes only
-  `attention_catalog_baseline`, so `attention_catalog_probe` is a deterministic
-  external catalog miss. The storyboard captures the 3.1 compatibility window:
-  a seller may accept the request, or it may reject with `TERMS_REJECTED`. The
-  3.2 storyboard cut should collapse this branch set to the reject path only.
-
-agent:
-  interaction_model: media_buy_seller
-  capabilities:
-    - sells_media
-    - supports_vendor_metric_optimization
-  examples:
-    - "Premium publishers with attention measurement optimization"
-    - "Sellers integrating vendor-defined measurement into bidding"
-
-caller:
-  role: buyer_agent
-  example: "Pinnacle Agency (buyer)"
-
-prerequisites:
-  description: |
-    The runner seeds a product that can optimize and report the
-    attention_catalog_probe metric, with an attentionvendor.example
-    measurement.metrics[] fixture that deliberately omits that metric_id. The
-    request is therefore valid by product capability and reporting coherence,
-    but is a deterministic external catalog miss.
-  test_kit: "test-kits/acme-outdoor.yaml"
-  controller_seeding: true
-
-fixtures:
-  products:
-    - product_id: "display_vendor_metric_catalog_precondition"
-      delivery_type: "non_guaranteed"
-      channels: ["display"]
-      format_ids:
-        - id: "display_300x250"
-      reporting_capabilities:
-        available_metrics:
-          - impressions
-          - clicks
-          - spend
-        vendor_metrics:
-          - vendor:
-              domain: "attentionvendor.example"
-            metric_id: "attention_catalog_probe"
-      vendor_metric_optimization:
-        supported_metrics:
-          - vendor:
-              domain: "attentionvendor.example"
-            metric_id: "attention_catalog_probe"
-            supported_targets:
-              - threshold_rate
-  pricing_options:
-    - product_id: "display_vendor_metric_catalog_precondition"
-      pricing_option_id: "cpm_vendor_metric_catalog_precondition"
-      pricing_model: "cpm"
-      currency: "USD"
-      fixed_price: 14.0
-
-phases:
-  - id: account_setup
-    title: "Establish account"
-    narrative: |
-      The buyer provisions or resolves an account so subsequent media-buy
-      creation uses the same tenant scope as the seeded product.
-    steps:
-      - id: sync_accounts
-        title: "Establish buyer 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_vendor_metric_catalog_precondition_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: seed_measurement_catalog
-    title: "Seed the measurement vendor catalog"
-    narrative: |
-      The product fixture proves the seller-side vendor_metric capability and
-      reporting contract. This controller step separately seeds the external
-      measurement vendor catalog so the later create_media_buy request is a
-      deterministic catalog miss rather than merely catalog-unproven.
-
-    steps:
-      - id: seed_attention_vendor_catalog
-        title: "Seed attentionvendor.example without the requested metric"
-        task: comply_test_controller
-        requires_tool: comply_test_controller
-        stateful: true
-        expected: |
-          The controller stores attentionvendor.example's measurement.metrics[]
-          catalog for this compliance session.
-        sample_request:
-          account:
-            sandbox: true
-          brand:
-            domain: "acmeoutdoor.example"
-          scenario: "seed_measurement_catalog"
-          params:
-            vendor:
-              domain: "attentionvendor.example"
-            metrics:
-              - metric_id: "attention_catalog_baseline"
-                unit: "score"
-                description: "Baseline attention metric present in the seeded vendor catalog."
-          context:
-            correlation_id: "vendor_metric_catalog_precondition--seed_catalog"
-        validations:
-          - check: field_value
-            path: "success"
-            allowed_values: [true]
-            description: "Measurement catalog seeding succeeds"
-          - check: field_present
-            path: "context"
-            description: "Response echoes back the context object"
-          - check: field_value
-            path: "context.correlation_id"
-            value: "vendor_metric_catalog_precondition--seed_catalog"
-            description: "Context correlation_id returned unchanged"
-
-  - id: catalog_miss_accept_path
-    title: "3.1 catalog-miss metric — accept path"
-    narrative: |
-      The seller may accept the buy during the 3.1 SHOULD window even though
-      attention_catalog_probe is absent from the seeded vendor catalog.
-    optional: true
-    branch_set:
-      id: vendor_metric_catalog_miss_handled
-      semantics: any_of
-    steps:
-      - id: create_media_buy_catalog_miss_accept
-        title: "Accept vendor_metric with catalog miss during 3.1 SHOULD window"
-        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
-        auth:
-          type: api_key
-          from_test_kit: true
-        stateful: false
-        contributes: true
-        expected: |
-          3.1 compatibility behavior: accept the buy even though the metric is
-          absent from the seeded vendor measurement.metrics[] catalog.
-        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: "display_vendor_metric_catalog_precondition"
-              pricing_option_id: "cpm_vendor_metric_catalog_precondition"
-              budget: 5000
-              optimization_goals:
-                - kind: "vendor_metric"
-                  vendor:
-                    domain: "attentionvendor.example"
-                  metric_id: "attention_catalog_probe"
-                  target:
-                    kind: "threshold_rate"
-                    value: 70
-                  priority: 1
-              committed_metrics:
-                - scope: "vendor"
-                  vendor:
-                    domain: "attentionvendor.example"
-                  metric_id: "attention_catalog_probe"
-          idempotency_key: "$generate:uuid_v4#media_buy_seller_vendor_metric_catalog_precondition_accept"
-        validations:
-          - check: response_schema
-            description: "Response matches create-media-buy-response.json schema for the 3.1 catalog-miss accept branch"
-          - check: field_present
-            path: "media_buy_id"
-            description: "Seller returns a media_buy_id during the 3.1 catalog-miss SHOULD window"
-
-  - id: catalog_miss_reject_path
-    title: "3.1 catalog-miss metric — reject path"
-    narrative: |
-      The seller may also reject the same request in 3.1. This is the
-      recommended behavior ahead of the 3.2 MUST boundary.
-    optional: true
-    branch_set:
-      id: vendor_metric_catalog_miss_handled
-      semantics: any_of
-    steps:
-      - id: create_media_buy_catalog_miss_reject
-        title: "Reject vendor_metric with catalog miss using TERMS_REJECTED"
-        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
-        expect_error: true
-        negative_path: payload_well_formed
-        auth:
-          type: api_key
-          from_test_kit: true
-        stateful: false
-        contributes: true
-        expected: |
-          Recommended 3.1 behavior and required 3.2 behavior: reject with
-          TERMS_REJECTED because the metric is absent from the vendor's seeded
-          measurement.metrics[] catalog.
-        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: "display_vendor_metric_catalog_precondition"
-              pricing_option_id: "cpm_vendor_metric_catalog_precondition"
-              budget: 5000
-              optimization_goals:
-                - kind: "vendor_metric"
-                  vendor:
-                    domain: "attentionvendor.example"
-                  metric_id: "attention_catalog_probe"
-                  target:
-                    kind: "threshold_rate"
-                    value: 70
-                  priority: 1
-              committed_metrics:
-                - scope: "vendor"
-                  vendor:
-                    domain: "attentionvendor.example"
-                  metric_id: "attention_catalog_probe"
-          idempotency_key: "$generate:uuid_v4#media_buy_seller_vendor_metric_catalog_precondition_reject"
-        validations:
-          - check: error_code
-            allowed_values: ["TERMS_REJECTED"]
-            description: "Seller may reject catalog-miss vendor metrics with TERMS_REJECTED in 3.1; catalog misses become required rejections at 3.2"
-
-  - id: catalog_miss_assertion
-    title: "Require catalog-miss metric handling"
-    narrative: |
-      Synthetic assertion over the accept and reject branches. In 3.1, either
-      compatibility acceptance or recommended TERMS_REJECTED rejection satisfies
-      the catalog-miss metric behavior. The 3.2 storyboard cut should collapse
-      this branch set to the reject branch only.
-    steps:
-      - id: assert_vendor_metric_catalog_miss_handled
-        title: "Require catalog-miss handling from either branch"
-        task: assert_contribution
-        comply_scenario: create_media_buy
-        stateful: false
-        expected: |
-          At least one of catalog_miss_accept_path or catalog_miss_reject_path
-          contributed vendor_metric_catalog_miss_handled.
-        validations:
-          - check: any_of
-            allowed_values: ["vendor_metric_catalog_miss_handled"]
-            description: "Agent must either accept the catalog-miss metric during the 3.1 SHOULD window or reject it with TERMS_REJECTED."