@adcp/sdk 17.0.0-beta.8 → 17.0.0-beta.9

package/compliance/cache/3.1.31/protocols/media-buy/scenarios/vendor_metric_accountability.yaml

@@ -0,0 +1,400 @@
+id: media_buy_seller/vendor_metric_accountability
+version: 1.0.1
+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: Wholesale native discovery must expose a non-guaranteed CPM display product declaring
+    attentionvendor.example attention_units before the synthetic vendor-metric fixture is seeded.
+    Valid no-match is an explicit fixture_unsatisfied coverage gap. This 3.1 scenario validates
+    declaration, filtering and emission; it does not add later per-package snapshot or post-flight
+    timing requirements.
+  test_kit: test-kits/acme-outdoor.yaml
+  controller_seeding: true
+fixtures:
+  accounts:
+    - account_id: acct_vendor_metric_accountability_sandbox
+      fixture:
+        brand:
+          domain: acmeoutdoor.example
+        operator: vendor-metric-accountability.pinnacle-agency.example
+        sandbox: true
+        billing: operator
+        status: active
+  products:
+    - product_id: native_vendor_metric_reporting_support
+phases:
+  - id: seed_supported_reporting_fixture
+    title: Prepare reporting fixtures only after native vendor support
+    steps:
+      - id: seed_reporting_product
+        title: Prepare seed_product after native vendor support
+        task: comply_test_controller
+        schema_ref: compliance/comply-test-controller-request.json
+        response_schema_ref: compliance/comply-test-controller-response.json
+        doc_ref: /building/by-layer/L3/comply-test-controller
+        stateful: true
+        sample_request:
+          account:
+            brand:
+              domain: acmeoutdoor.example
+            operator: vendor-metric-accountability.pinnacle-agency.example
+            sandbox: true
+          scenario: seed_product
+          params:
+            product_id: display_premium_vendor_metrics
+            fixture:
+              delivery_type: non_guaranteed
+              channels:
+                - display
+              format_ids:
+                - id: display_300x250
+                  agent_url: https://creative.adcontextprotocol.org/
+              reporting_capabilities:
+                available_metrics:
+                  - impressions
+                  - clicks
+                  - spend
+                vendor_metrics:
+                  - vendor:
+                      domain: attentionvendor.example
+                    metric_id: attention_units
+        validations:
+          - check: field_value
+            path: success
+            value: true
+            description: The controller accepts the supported vendor-reporting fixture
+      - id: seed_reporting_price
+        title: Prepare seed_pricing_option after native vendor support
+        task: comply_test_controller
+        schema_ref: compliance/comply-test-controller-request.json
+        response_schema_ref: compliance/comply-test-controller-response.json
+        doc_ref: /building/by-layer/L3/comply-test-controller
+        stateful: true
+        sample_request:
+          account:
+            brand:
+              domain: acmeoutdoor.example
+            operator: vendor-metric-accountability.pinnacle-agency.example
+            sandbox: true
+          scenario: seed_pricing_option
+          params:
+            product_id: display_premium_vendor_metrics
+            pricing_option_id: cpm_standard_vendor
+            fixture:
+              pricing_model: cpm
+              currency: USD
+              floor_price: 12
+        validations:
+          - check: field_value
+            path: success
+            value: true
+            description: The controller accepts the supported vendor-reporting fixture
+  - 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: vendor-metric-accountability.pinnacle-agency.example
+              billing: operator
+              payment_terms: net_30
+              sandbox: true
+          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
+            required_vendor_metrics:
+              - vendor:
+                  domain: attentionvendor.example
+          account:
+            brand:
+              domain: acmeoutdoor.example
+            operator: vendor-metric-accountability.pinnacle-agency.example
+            sandbox: true
+        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].pricing_option_id
+            description: The captured price is selectable with fixed or auction pricing
+          - check: field_contains
+            path: products[0].reporting_capabilities.vendor_metrics[*]
+            value:
+              vendor:
+                domain: attentionvendor.example
+              metric_id: attention_units
+            description: The selected product actually declares the required vendor metric on one entry
+  - 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: vendor-metric-accountability.pinnacle-agency.example
+            sandbox: true
+          start_time: asap
+          end_time: "2099-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:
+            brand:
+              domain: acmeoutdoor.example
+            operator: vendor-metric-accountability.pinnacle-agency.example
+            sandbox: true
+          scenario: simulate_delivery
+          params:
+            media_buy_id: $context.media_buy_id
+            impressions: 80000
+            reported_spend:
+              amount: 960
+              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: vendor-metric-accountability.pinnacle-agency.example
+            sandbox: true
+          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
+requires:
+  - controller
+requires_all_capabilities:
+  - path: media_buy.buying_modes
+    contains: wholesale
+  - path: compliance_testing.scenarios
+    contains: seed_product
+  - path: compliance_testing.scenarios
+    contains: seed_pricing_option
+context:
+  account:
+    brand:
+      domain: acmeoutdoor.example
+    operator: vendor-metric-accountability.pinnacle-agency.example
+    sandbox: true
+fixture_resolution:
+  products:
+    - handle: native_vendor_metric_reporting_support
+      strategies:
+        - discover
+      match:
+        - path: /delivery_type
+          operator: equals
+          value: non_guaranteed
+        - path: /channels
+          operator: contains_all
+          value:
+            - display
+        - path: /pricing_options
+          operator: any_match
+          where:
+            - path: /pricing_model
+              operator: equals
+              value: cpm
+        - path: /reporting_capabilities/vendor_metrics
+          operator: any_match
+          where:
+            - path: /vendor
+              operator: equals
+              value:
+                domain: attentionvendor.example
+            - path: /metric_id
+              operator: equals
+              value: attention_units

package/compliance/cache/{3.1.29 → 3.1.31}/protocols/media-buy/scenarios/vendor_metric_catalog_precondition.yaml

@@ -86,7 +86,7 @@ fixtures:
       pricing_option_id: "cpm_vendor_metric_catalog_precondition"
       pricing_model: "cpm"
       currency: "USD"
-      fixed_price: 14.0
+      floor_price: 14.0
 
 phases:
   - id: account_setup
@@ -201,6 +201,7 @@ phases:
           packages:
             - product_id: "display_vendor_metric_catalog_precondition"
               pricing_option_id: "cpm_vendor_metric_catalog_precondition"
+              bid_price: 21
               budget: 5000
               optimization_goals:
                 - kind: "vendor_metric"
@@ -264,6 +265,7 @@ phases:
           packages:
             - product_id: "display_vendor_metric_catalog_precondition"
               pricing_option_id: "cpm_vendor_metric_catalog_precondition"
+              bid_price: 21
               budget: 5000
               optimization_goals:
                 - kind: "vendor_metric"

package/compliance/cache/{3.1.29/domains → 3.1.31/protocols}/media-buy/scenarios/vendor_metric_optimization_flow.yaml

@@ -121,12 +121,12 @@ fixtures:
       pricing_option_id: "cpm_vendor_opt"
       pricing_model: "cpm"
       currency: "USD"
-      fixed_price: 14.0
+      floor_price: 14.0
     - product_id: "display_vendor_metric_unreportable"
       pricing_option_id: "cpm_vendor_opt_unreportable"
       pricing_model: "cpm"
       currency: "USD"
-      fixed_price: 14.0
+      floor_price: 14.0
 
 phases:
   - id: discover_vendor_metric_optimization
@@ -178,7 +178,6 @@ phases:
           buying_mode: "brief"
           brief: "Display inventory with attention-score optimization from attentionvendor."
           filters:
-            is_fixed_price: true
             channels: ["display"]
           account:
             brand:
@@ -196,8 +195,8 @@ phases:
             path: "products[0].product_id"
             description: "At least one product returned"
           - 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"
+            path: "products[0].pricing_options[0].pricing_option_id"
+            description: "The captured pricing option is selectable with fixed or auction pricing"
           - check: field_present
             path: "products[0].vendor_metric_optimization.supported_metrics"
             description: "Product declares vendor_metric_optimization.supported_metrics[]"
@@ -554,6 +553,7 @@ phases:
           packages:
             - product_id: "display_vendor_metric_unreportable"
               pricing_option_id: "cpm_vendor_opt_unreportable"
+              bid_price: 21
               budget: 5000
               optimization_goals:
                 - kind: "vendor_metric"

package/compliance/cache/{3.1.29 → 3.1.31}/specialisms/creative-generative/generative-seller.yaml

@@ -77,7 +77,7 @@ fixtures:
         - id: "display_300x250"
     - product_id: "outdoor_video_q2"
       delivery_type: "guaranteed"
-      channels: ["video"]
+      channels: ["olv"]
       format_ids:
         - id: "video_15s"
   pricing_options:

package/compliance/cache/{3.1.29 → 3.1.31}/specialisms/governance-delivery-monitor/index.yaml

@@ -60,7 +60,7 @@ fixtures:
         - id: "display_300x250"
     - product_id: "outdoor_video_q2"
       delivery_type: "guaranteed"
-      channels: ["video"]
+      channels: ["olv"]
       format_ids:
         - id: "video_15s"
   pricing_options:

package/compliance/cache/{3.1.29 → 3.1.31}/specialisms/sales-catalog-driven/index.yaml

@@ -196,7 +196,7 @@ phases:
           catalog-specific asset slots (product_image, product_title, price, description).
 
         sample_request:
-          channels: ["display", "native"]
+          channels: ["display"]
 
           context:
             correlation_id: "sales_catalog_driven--discover_catalog_formats"

package/compliance/cache/{3.1.29 → 3.1.31}/specialisms/sales-guaranteed/index.yaml

@@ -101,13 +101,13 @@ fixtures:
         - id: "display_300x250"
     - product_id: "video_outdoor_non_guaranteed"
       delivery_type: "non_guaranteed"
-      channels: ["video"]
+      channels: ["olv"]
       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"]
+      channels: ["olv"]
       format_ids:
         - id: "video_30s"
     - product_id: "outdoor_ctv_q2_guaranteed"

package/compliance/cache/{3.1.29 → 3.1.31}/specialisms/sales-non-guaranteed/index.yaml

@@ -85,7 +85,7 @@ fixtures:
         - id: "display_300x250"
     - product_id: "outdoor_video_auction"
       delivery_type: "non_guaranteed"
-      channels: ["video"]
+      channels: ["olv"]
       format_ids:
         - id: "video_30s"
   pricing_options:

package/compliance/cache/{3.1.29 → 3.1.31}/universal/runner-output-contract.yaml

@@ -26,7 +26,7 @@
 # --- Schema definition ---
 
 id: runner_output_contract
-version: "2.6.0"
+version: "2.14.0"
 title: "Runner output contract"
 summary: "Required failure-detail shape that AdCP storyboard runners MUST emit so implementors can self-diagnose validation failures."
 
@@ -62,6 +62,7 @@ authored_check_kinds:
   - a2a_context_continuity
   - field_less_than
   - field_equals_context
+  - all_fields_in_context_array
   - upstream_traffic
   - canonical_format_satisfaction
 
@@ -97,6 +98,49 @@ cross_response_check_kinds:
 # the storyboard's step.validations array, plus any transport-level check
 # the runner performs (e.g., extraction path).
 
+# Runtime-only collection diagnostic; never a storyboard-authored check.
+product_page_collection_synthesized_check_kinds:
+  - product_page_collection
+
+product_page_collection_output:
+  description: |
+    An opt-in collected wholesale get_products step records a complete logical
+    catalog separately from its physical transport exchanges. A logical aggregate
+    MUST NOT be presented as a response the seller sent in one exchange.
+  fields:
+    complete: boolean
+    page_count: integer
+    restart_count: integer
+    pages: |
+      Bounded array of physical-page observations. Each includes page_index,
+      restart_count, exact redacted request and response records, extraction,
+      and schema_validated. Page schema and enabled invariant checks MUST run
+      before restart/discard or evidence-retention limits can remove a receipt.
+    logical_response: |
+      Optional, separately labelled extracted-domain aggregate available only
+      after stable enumeration completes. Incomplete enumeration MUST NOT
+      publish a partial logical_response or capture values from a partial feed.
+      Products and advisory errors aggregate across the stable enumeration;
+      other envelope metadata represents the first stable page, not a generic
+      merge of every response field.
+  interpretation: |
+    complete means enumeration completed, not that its contents passed checks.
+    A complete catalog with a failed page invariant still fails the step.
+    step.request/response and response_record remain actual first stable-page
+    or failure exchanges. Authored field checks and captures may consume the
+    logical_response; their JSON Pointers MUST be rooted under
+    /product_page_collection/logical_response and extraction.note MUST identify
+    that source. Physical-page failures retain the actual page's request,
+    response, schema identity, and page-local JSON Pointer. Successful and failed
+    physical schema verdicts remain observable as response_schema validations;
+    the runner MUST NOT fabricate an aggregate wire-schema verdict.
+  failure_check: |
+    product_page_collection reports cursor, feed-identity, duplicate, budget,
+    or authoring failures. It is a runtime discriminator, not an authored
+    validation kind. Malformed physical pages use response_schema and failed
+    page invariants retain their assertion results. All existing diagnostic,
+    redaction, account-scope, and coverage-gap requirements continue to apply.
+
 step_result:
   description: |
     Runners MUST emit one step result per executed step. Skipped steps MUST
@@ -119,6 +163,8 @@ step_result:
     - error                   # transport-level error (no validations attempted)
     - request                 # exact request the runner sent (see request block)
     - response                # exact response observed (see response block)
+    - product_page_collection # bounded physical-page receipts and a separately
+                              # labelled complete logical catalog; see above
     - notices                 # array of notice objects attached to this step's
                               # result — informational signals that MUST NOT
                               # change `passed`. See the notice block below for