@adcp/sdk 5.23.0 → 5.24.0

package/compliance/cache/3.0.0/protocols/media-buy/scenarios/governance_denied_recovery.yaml

@@ -1,243 +0,0 @@
-id: media_buy_seller/governance_denied_recovery
-version: "1.0.0"
-title: "Seller accepts corrected buy after governance denial"
-category: media_buy_seller
-summary: "Verifies that a buyer can recover from GOVERNANCE_DENIED by shrinking the buy to within plan limits and retrying."
-track: media_buy
-required_tools:
-  - sync_governance
-  - get_products
-  - create_media_buy
-
-narrative: |
-  GOVERNANCE_DENIED is a correctable error, not a dead end. The buyer must be able to
-  read the denial findings, adjust the media buy, and retry. This scenario exercises the
-  full loop: strict governance plan ($10K), failed $50K buy that is denied, then a
-  corrected $8K buy that fits within the plan and is approved.
-
-  The seller must propagate the governance findings unchanged so the buyer can identify
-  exactly which constraint was violated (budget authority, brand policy, etc.) and
-  correct it.
-
-  By default, the governance agent is the training agent at test-agent.adcontextprotocol.org.
-  Override with --governance-agent-url to use a custom governance agent.
-
-agent:
-  interaction_model: media_buy_seller
-  capabilities:
-    - sells_media
-    - governance_aware
-  examples:
-    - "Any media buy seller with governance support"
-
-caller:
-  role: buyer_agent
-  example: "Pinnacle Agency (buyer)"
-
-prerequisites:
-  description: |
-    A governance agent that supports sync_plans and check_governance.
-  test_kit: "test-kits/acme-outdoor.yaml"
-
-phases:
-  - id: governance_plan_setup
-    title: "Set up strict governance plan"
-    narrative: |
-      Create a governance plan with a $10K budget. The initial $50K buy will exceed this
-      limit; the retry at $8K will fit.
-
-    steps:
-      - id: sync_plans
-        title: "Create strict governance plan"
-        task: sync_plans
-        schema_ref: "governance/sync-plans-request.json"
-        response_schema_ref: "governance/sync-plans-response.json"
-        doc_ref: "/governance/campaign/tasks/sync_plans"
-        stateful: true
-        expected: |
-          The governance agent acknowledges the plan.
-        sample_request:
-          idempotency_key: "comply-gov-recovery-sync-plans-v1"
-          plans:
-            - plan_id: "comply-gov-recovery-plan"
-              brand:
-                domain: "acmeoutdoor.example"
-              objectives: "Strict-budget plan for denial + recovery validation"
-              budget:
-                total: 10000
-                currency: "USD"
-                reallocation_threshold: 5000
-              flight:
-                start: "2026-04-01T00:00:00Z"
-                end: "2026-06-30T23:59:59Z"
-              countries: ["US"]
-        validations:
-          - check: response_schema
-            description: "Response matches sync-plans-response.json schema"
-
-  - id: seller_setup
-    title: "Account and governance registration on seller"
-    steps:
-      - id: sync_accounts
-        title: "Establish account with seller"
-        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 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_governance_denied_recovery_seller_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: sync_governance
-        title: "Register governance agent with seller"
-        task: sync_governance
-        schema_ref: "account/sync-governance-request.json"
-        response_schema_ref: "account/sync-governance-response.json"
-        doc_ref: "/accounts/tasks/sync_governance"
-        stateful: true
-        expected: |
-          Acknowledge the governance agent registration.
-        sample_request:
-          accounts:
-            - account:
-                brand:
-                  domain: "acmeoutdoor.example"
-                operator: "pinnacle-agency.example"
-              governance_agents:
-                - url: "$context.governance_agent_url"
-                  authentication:
-                    schemes: ["Bearer"]
-                    credentials: "gov-token-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
-                  categories: ["budget_authority"]
-          idempotency_key: "$generate:uuid_v4#media_buy_seller_governance_denied_recovery_seller_setup_sync_governance"
-        validations:
-          - check: response_schema
-            description: "Response matches sync-governance-response.json schema"
-
-  - id: buy_denied
-    title: "Initial buy exceeds plan — governance denies"
-    steps:
-      - id: get_products_brief
-        title: "Discover products"
-        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 products matching the brief.
-        sample_request:
-          buying_mode: "brief"
-          brief: "Display inventory on outdoor lifestyle content. Q2 flight."
-          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"
-            description: "Response contains products"
-
-      - id: create_media_buy_denied
-        title: "Attempt $50K buy — denied"
-        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
-        stateful: true
-        expected: |
-          The buy is rejected with GOVERNANCE_DENIED. The response includes findings
-          from the governance agent explaining which constraint was exceeded.
-
-        sample_request:
-          brand:
-            domain: "acmeoutdoor.example"
-          account:
-            brand:
-              domain: "acmeoutdoor.example"
-            operator: "pinnacle-agency.example"
-          idempotency_key: "gov-recovery-initial-denied-v1"
-          start_time: "2026-04-01T00:00:00Z"
-          end_time: "2026-06-30T23:59:59Z"
-          packages:
-            - product_id: "$context.product_id"
-              budget: 50000
-              pricing_option_id: "$context.pricing_option_id"
-          context:
-            correlation_id: "governance_denied_recovery--create_media_buy_denied"
-        validations:
-          - check: error_code
-            value: "GOVERNANCE_DENIED"
-            description: "Error code is GOVERNANCE_DENIED"
-          - check: field_value
-            path: "context.correlation_id"
-            value: "governance_denied_recovery--create_media_buy_denied"
-            description: "Response echoes context.correlation_id verbatim on error responses (echo contract applies to both success and failure)"
-
-  - id: buy_retried
-    title: "Corrected buy within plan — governance approves"
-    narrative: |
-      The buyer reads the denial findings, shrinks the budget to $8K (within the $10K
-      plan), and retries with a fresh idempotency_key. The seller consults governance
-      again, which now approves.
-
-    steps:
-      - id: create_media_buy_retry
-        title: "Retry with $8K — approved"
-        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. Governance approves because $8K fits within the $10K plan
-          budget. The seller returns a media_buy_id.
-
-        sample_request:
-          brand:
-            domain: "acmeoutdoor.example"
-          account:
-            brand:
-              domain: "acmeoutdoor.example"
-            operator: "pinnacle-agency.example"
-          idempotency_key: "gov-recovery-retry-approved-v1"
-          start_time: "2026-04-01T00:00:00Z"
-          end_time: "2026-06-30T23:59:59Z"
-          packages:
-            - product_id: "$context.product_id"
-              budget: 8000
-              pricing_option_id: "$context.pricing_option_id"
-        context_outputs:
-          - name: media_buy_id
-            path: "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 after governance approves"

package/compliance/cache/3.0.0/protocols/media-buy/scenarios/invalid_transitions.yaml

@@ -1,279 +0,0 @@
-id: media_buy_seller/invalid_transitions
-version: "1.0.0"
-title: "Seller rejects illegal state transitions and unknown references"
-category: media_buy_seller
-summary: "Validates that the seller returns structured AdCP errors (MEDIA_BUY_NOT_FOUND, PACKAGE_NOT_FOUND, NOT_CANCELLABLE) rather than 500s or undefined behavior when the buyer references missing entities or attempts forbidden state transitions."
-track: media_buy
-required_tools:
-  - get_products
-  - create_media_buy
-  - update_media_buy
-
-narrative: |
-  Error-code coverage is the most common compliance gap: sellers accept malformed input
-  silently or return generic 500s rather than the specific AdCP codes the spec defines.
-  This scenario forces three of the most-referenced media_buy error codes with
-  deterministic input:
-
-  - MEDIA_BUY_NOT_FOUND — buyer references a media_buy_id that does not exist.
-  - PACKAGE_NOT_FOUND — media_buy_id is valid but package_id inside it is not.
-  - NOT_CANCELLABLE — buyer cancels the same media buy twice; the second cancel must
-    be rejected because canceled is terminal.
-
-  All three probes use hard `check: error_code` assertions so a seller that returns
-  a 500 or swallows the error fails the scenario outright. Recovery hints, correlation
-  echo, and context preservation are also checked on every error response.
-
-agent:
-  interaction_model: media_buy_seller
-  capabilities:
-    - sells_media
-  examples:
-    - "Any media buy seller"
-
-caller:
-  role: buyer_agent
-  example: "Pinnacle Agency (buyer)"
-
-prerequisites:
-  description: |
-    Seller supports create_media_buy and update_media_buy with cancellation via
-    the canceled field.
-  test_kit: "test-kits/acme-outdoor.yaml"
-
-phases:
-  - id: unknown_media_buy
-    title: "Reference an unknown media_buy_id"
-    narrative: |
-      Before any state is set up, call update_media_buy with a fabricated media_buy_id.
-      The seller must return MEDIA_BUY_NOT_FOUND with a correctable recovery hint — not
-      a 500 and not a silent success.
-
-    steps:
-      - id: update_unknown_media_buy
-        title: "update_media_buy with bogus media_buy_id"
-        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
-        expect_error: true
-        stateful: false
-        expected: |
-          Reject with:
-          - code: MEDIA_BUY_NOT_FOUND
-          - recovery: correctable
-          - context echoed unchanged
-
-        sample_request:
-          account:
-            brand:
-              domain: "acmeoutdoor.example"
-            operator: "pinnacle-agency.example"
-          media_buy_id: "does-not-exist-invalid-transitions-v1"
-          paused: true
-          context:
-            correlation_id: "invalid_transitions--update_unknown_media_buy"
-        validations:
-          - check: error_code
-            value: "MEDIA_BUY_NOT_FOUND"
-            description: "Error code is MEDIA_BUY_NOT_FOUND"
-          - check: field_present
-            path: "context"
-            description: "Response echoes back the context object even on errors"
-          - check: field_value
-            path: "context.correlation_id"
-            value: "invalid_transitions--update_unknown_media_buy"
-            description: "Context correlation_id returned unchanged"
-
-  - id: setup
-    title: "Create a real media buy for follow-up probes"
-    narrative: |
-      The remaining probes need a real media_buy_id and package_id. Discover a product
-      and create a plain buy — no targeting tricks, no governance — so we have known-good
-      IDs for the error cases.
-
-    steps:
-      - id: get_products_brief
-        title: "Discover a 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 with pricing.
-        sample_request:
-          buying_mode: "brief"
-          brief: "Display inventory on outdoor lifestyle content. Q3 flight."
-          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"
-
-      - id: create_buy
-        title: "Create a buy for the error probes"
-        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: |
-          Media buy created with media_buy_id and at least one package.
-
-        sample_request:
-          brand:
-            domain: "acmeoutdoor.example"
-          account:
-            brand:
-              domain: "acmeoutdoor.example"
-            operator: "pinnacle-agency.example"
-          idempotency_key: "invalid-transitions-setup-v1"
-          start_time: "2026-08-01T00:00:00Z"
-          end_time: "2026-08-31T23:59:59Z"
-          packages:
-            - product_id: "$context.product_id"
-              budget: 5000
-              pricing_option_id: "$context.pricing_option_id"
-          context:
-            correlation_id: "invalid_transitions--create_buy"
-        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 returns media_buy_id"
-
-  - id: unknown_package
-    title: "Reference an unknown package_id on a real buy"
-    narrative: |
-      The media_buy_id is real, but the package_id is fabricated. The seller must
-      return PACKAGE_NOT_FOUND — distinct from MEDIA_BUY_NOT_FOUND — because the
-      lookup succeeds at the buy level and only fails at the package lookup.
-
-    steps:
-      - id: update_unknown_package
-        title: "update_media_buy with bogus package_id"
-        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
-        expect_error: true
-        stateful: true
-        expected: |
-          Reject with:
-          - code: PACKAGE_NOT_FOUND
-          - recovery: correctable
-          - context echoed unchanged
-
-        sample_request:
-          account:
-            brand:
-              domain: "acmeoutdoor.example"
-            operator: "pinnacle-agency.example"
-          media_buy_id: "$context.media_buy_id"
-          packages:
-            - package_id: "does-not-exist-package-invalid-transitions-v1"
-              paused: true
-          context:
-            correlation_id: "invalid_transitions--update_unknown_package"
-        validations:
-          - check: error_code
-            value: "PACKAGE_NOT_FOUND"
-            description: "Error code is PACKAGE_NOT_FOUND"
-          - check: field_present
-            path: "context"
-            description: "Response echoes back the context object even on errors"
-          - check: field_value
-            path: "context.correlation_id"
-            value: "invalid_transitions--update_unknown_package"
-            description: "Context correlation_id returned unchanged"
-
-  - id: double_cancel
-    title: "Cancel twice — second cancel is not valid"
-    narrative: |
-      Cancel the buy (success), then try to cancel the same buy again. canceled is
-      terminal per the AdCP spec, so the second cancel cannot succeed. The seller
-      must return NOT_CANCELLABLE — the schema specifically reserves this code for
-      "media buy cannot be canceled in its current state."
-
-    steps:
-      - id: first_cancel
-        title: "Cancel the media buy"
-        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: |
-          Seller acknowledges the cancellation and transitions the buy to canceled.
-
-        sample_request:
-          account:
-            brand:
-              domain: "acmeoutdoor.example"
-            operator: "pinnacle-agency.example"
-          media_buy_id: "$context.media_buy_id"
-          canceled: true
-          cancellation_reason: "Testing NOT_CANCELLABLE on re-cancel"
-          idempotency_key: "$generate:uuid_v4#media_buy_seller_invalid_transitions_double_cancel_first_cancel"
-          context:
-            correlation_id: "invalid_transitions--first_cancel"
-        validations:
-          - check: response_schema
-            description: "Response matches update-media-buy-response.json schema"
-
-      - id: second_cancel
-        title: "Re-cancel the canceled buy"
-        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
-        expect_error: true
-        stateful: true
-        expected: |
-          Reject with:
-          - code: NOT_CANCELLABLE
-          - recovery: correctable
-          - context echoed unchanged
-
-        sample_request:
-          account:
-            brand:
-              domain: "acmeoutdoor.example"
-            operator: "pinnacle-agency.example"
-          media_buy_id: "$context.media_buy_id"
-          canceled: true
-          cancellation_reason: "Deliberate re-cancel to force NOT_CANCELLABLE"
-          idempotency_key: "$generate:uuid_v4#media_buy_seller_invalid_transitions_double_cancel_second_cancel"
-          context:
-            correlation_id: "invalid_transitions--second_cancel"
-        validations:
-          - check: error_code
-            value: "NOT_CANCELLABLE"
-            description: "Error code is NOT_CANCELLABLE on re-cancel of canceled buy"
-          - check: field_present
-            path: "context"
-            description: "Response echoes back the context object even on errors"
-          - check: field_value
-            path: "context.correlation_id"
-            value: "invalid_transitions--second_cancel"
-            description: "Context correlation_id returned unchanged"

package/compliance/cache/3.0.0/protocols/media-buy/scenarios/inventory_list_no_match.yaml

@@ -1,143 +0,0 @@
-id: media_buy_seller/inventory_list_no_match
-version: "1.0.0"
-title: "Seller handles property_list / collection_list references that match zero inventory"
-category: media_buy_seller
-summary: "Verifies a seller returns a zero-forecast product or a clear error — not a crash — when a buyer references inventory lists that resolve to nothing in the seller's catalog."
-track: media_buy
-required_tools:
-  - get_products
-  - create_media_buy
-
-narrative: |
-  Not every buyer list matches every seller's inventory. A buyer may point at a
-  property_list of domains this seller does not carry, or a collection_list of
-  programs this seller does not syndicate. The seller must handle that gracefully:
-
-  - Return a product with a zero forecast and explain the mismatch, OR
-  - Return an informative error on create_media_buy (INSUFFICIENT_INVENTORY or
-    similar) with findings the buyer can act on.
-
-  What the seller must NOT do: crash, return a misleading non-zero forecast, or
-  silently drop the targeting and deliver against unintended inventory. Each of
-  those is a real failure mode we've seen in adapter integrations.
-
-  This scenario exercises the no-match path using the test kit's pre-populated
-  no_match_properties and no_match_collections lists.
-
-agent:
-  interaction_model: media_buy_seller
-  capabilities:
-    - sells_media
-    - supports_property_list_targeting
-    - supports_collection_list_targeting
-  examples:
-    - "Sellers that validate inventory against buyer-supplied lists"
-
-caller:
-  role: buyer_agent
-  example: "Pinnacle Agency (buyer)"
-
-prerequisites:
-  description: |
-    The seller must resolve PropertyListReference / CollectionListReference against
-    its own inventory and report a truthful outcome when nothing matches.
-  test_kit: "test-kits/acme-outdoor.yaml"
-
-phases:
-  - id: discover
-    title: "Discover products"
-    steps:
-      - id: get_products_brief
-        title: "Discover products"
-        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 products the seller carries.
-        sample_request:
-          buying_mode: "brief"
-          brief: "Video inventory on outdoor lifestyle programming. Q3 flight."
-          account:
-            brand:
-              domain: "acmeoutdoor.example"
-            operator: "pinnacle-agency.example"
-
-          context:
-            correlation_id: "inventory_list_no_match--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"
-
-  - id: no_match_attempt
-    title: "Create buy with lists that match no inventory"
-    narrative: |
-      The buyer references the no-match property list and the no-match collection
-      list. Neither list resolves to anything in the seller's catalog. The seller
-      must either (a) accept the buy and surface a zero-delivery expectation, or
-      (b) reject it with an informative error. Silent success with undefined
-      delivery behaviour is not acceptable.
-
-    steps:
-      - id: create_buy_no_match
-        title: "create_media_buy against empty intersections"
-        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: |
-          One of two acceptable outcomes:
-
-          1. Buy accepted with zero-forecast reporting — status may be
-             pending_creatives/pending_start/active, but the seller returns
-             packages with forecast indicating zero deliverable inventory and
-             a message explaining the list mismatch.
-
-          2. Buy rejected with an informative error — typically
-             INSUFFICIENT_INVENTORY or INVALID_TARGETING — including findings
-             that identify which list(s) matched nothing.
-
-          What is NOT acceptable: a silently-successful buy with normal forecast
-          numbers, or a crash / non-AdCP error shape.
-
-        sample_request:
-          brand:
-            domain: "acmeoutdoor.example"
-          account:
-            brand:
-              domain: "acmeoutdoor.example"
-            operator: "pinnacle-agency.example"
-          idempotency_key: "inventory-list-no-match-v1"
-          start_time: "2026-07-01T00:00:00Z"
-          end_time: "2026-09-30T23:59:59Z"
-          packages:
-            - product_id: "$context.product_id"
-              budget: 10000
-              pricing_option_id: "$context.pricing_option_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"
-
-          context:
-            correlation_id: "inventory_list_no_match--create_buy_no_match"
-        validations:
-          - check: field_present
-            path: "context"
-            description: "Response echoes back the context object (success or error)"
-          - check: field_value
-            path: "context.correlation_id"
-            value: "inventory_list_no_match--create_buy_no_match"
-            description: "Context correlation_id returned unchanged"