@adcp/sdk 7.10.2 → 7.11.1

package/compliance/cache/3.1.0-rc.2/universal/capability-discovery.yaml

@@ -0,0 +1,125 @@
+id: capability_discovery
+version: "1.0.0"
+title: "Capability discovery"
+category: capability_discovery
+summary: "Buyer calls get_adcp_capabilities to discover what an agent supports before making any buying or creative decisions."
+track: core
+
+narrative: |
+  Before doing anything else, a buyer agent calls get_adcp_capabilities to learn what your
+  platform supports. This is the first call in any new relationship — the buyer needs to know
+  your protocol version, supported domains (media buy, creative, governance, signals, SI),
+  pricing models, targeting capabilities, and creative specs.
+
+  The response shapes every subsequent call. If you declare media_buy support, the buyer knows
+  it can send briefs and create media buys. If you declare creative support, the buyer knows
+  it can sync or build creatives. The buyer uses this to decide which storyboards apply to your
+  agent and what flows to attempt.
+
+agent:
+  interaction_model: media_buy_seller
+  capabilities:
+    - sells_media
+  examples:
+    - "Any AdCP-compliant agent"
+    - "Publisher platforms"
+    - "Creative ad servers"
+    - "DSPs"
+
+caller:
+  role: buyer_agent
+  example: "Scope3 (DSP)"
+
+prerequisites:
+  description: |
+    No prerequisites. This is the very first call a buyer makes to any agent.
+    The test kit provides brand context but it is not required for this storyboard.
+  test_kit: "test-kits/acme-outdoor.yaml"
+
+phases:
+  - id: protocol_discovery
+    title: "Protocol and capability discovery"
+    narrative: |
+      The buyer calls get_adcp_capabilities to learn what your agent supports. This call
+      takes no required arguments — it is a read-only introspection of the agent's
+      capabilities. The buyer may optionally filter by protocol domain or major version.
+
+    steps:
+      - id: get_capabilities
+        title: "Discover agent capabilities"
+        narrative: |
+          The buyer calls get_adcp_capabilities with no arguments. Your agent returns its
+          full capability declaration: protocol version, supported domains, pricing models,
+          targeting options, creative specs, and any extensions.
+
+          This response is the source of truth for what the buyer can do with your agent.
+          Every field the buyer reads here determines which tasks it will call next.
+        task: get_adcp_capabilities
+        schema_ref: "protocol/get-adcp-capabilities-request.json"
+        response_schema_ref: "protocol/get-adcp-capabilities-response.json"
+        doc_ref: "/protocol/get_adcp_capabilities"
+        comply_scenario: capability_discovery
+        stateful: false
+        expected: |
+          Return your agent's full capability declaration:
+          - adcp.major_versions: which protocol versions you support (e.g., [3])
+          - supported_protocols: which domains are available (media_buy, creative, governance, signals, sponsored_intelligence)
+          - media_buy: pricing models, delivery types, targeting, reporting features
+          - creative: library support, generation, transformation capabilities
+          - governance: property and creative features the governance agent can evaluate
+          - account: auth model, billing support, sandbox mode
+
+        sample_request:
+          context:
+            correlation_id: "capability_discovery--get_capabilities"
+
+        validations:
+          - check: response_schema
+            description: "Response matches get-adcp-capabilities-response.json schema"
+          - check: field_present
+            path: "adcp.major_versions"
+            description: "Agent declares supported protocol versions"
+          - check: field_present
+            path: "supported_protocols"
+            description: "Agent declares which protocol domains it supports"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "capability_discovery--get_capabilities"
+            description: "Context correlation_id returned unchanged"
+      - id: get_capabilities_filtered
+        title: "Discover capabilities filtered by protocol"
+        narrative: |
+          The buyer calls get_adcp_capabilities again, this time filtering for a specific
+          protocol domain. This is useful when the buyer already knows what it wants and
+          only needs details for one domain (e.g., just media_buy capabilities).
+        task: get_adcp_capabilities
+        schema_ref: "protocol/get-adcp-capabilities-request.json"
+        response_schema_ref: "protocol/get-adcp-capabilities-response.json"
+        doc_ref: "/protocol/get_adcp_capabilities"
+        comply_scenario: capability_discovery
+        stateful: false
+        expected: |
+          Return capabilities filtered to the requested protocol domain. The response
+          should include the same structure but only the requested domain details.
+
+        sample_request:
+          protocols:
+            - "media_buy"
+
+          context:
+            correlation_id: "capability_discovery--get_capabilities_filtered"
+        validations:
+          - check: response_schema
+            description: "Response matches get-adcp-capabilities-response.json schema"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "capability_discovery--get_capabilities_filtered"
+            description: "Context correlation_id returned unchanged"

package/compliance/cache/3.1.0-rc.2/universal/collection-lists-pagination-integrity.yaml

@@ -0,0 +1,306 @@
+id: pagination_integrity_collection_lists
+version: "1.0.0"
+title: "Pagination cursor integrity — list_collection_lists"
+category: schema_validation
+summary: "Validates the cursor↔has_more invariant by walking a paginated list_collection_lists response from a continuation page to a terminal page."
+track: core
+required_tools:
+  - list_collection_lists
+
+narrative: |
+  Pagination is cursor-based across AdCP. Every response carrying a
+  `pagination` block satisfies a single invariant: when `has_more` is true the
+  `cursor` MUST be present (callers need it to fetch the next page); when
+  `has_more` is false the `cursor` MUST be absent (a stale token on a terminal
+  page invites callers to follow it into undefined behavior).
+
+  The invariant is documented in prose on
+  `static/schemas/source/core/pagination-response.json` but JSON Schema does
+  not gate the two fields against each other. This storyboard exercises both
+  sides of the invariant on `list_collection_lists` in a single run.
+
+  The runner bootstraps three collection lists via `create_collection_list`,
+  then lists them back with `max_results=2`. The first page MUST cap at two
+  lists and signal continuation with `has_more=true` plus a cursor. The runner
+  then follows that cursor; the second call MUST return the terminal page with
+  `has_more=false` and no cursor. An agent that hides the third list by
+  reporting `has_more=false` on the first page fails the first-page assertion.
+  An agent that carries a stale cursor onto the terminal page fails the
+  second-page assertion.
+
+  The `total_count` field is allowed to be absent (some backends cannot
+  compute it cheaply per the pagination-response schema) but when an agent
+  volunteers it, the value MUST match the seeded count of three.
+
+agent:
+  interaction_model: stateful_preloaded
+  capabilities: []
+  examples:
+    - "Any AdCP agent that exposes a paginated list_collection_lists"
+
+caller:
+  role: buyer_agent
+  example: "Compliance test harness"
+
+prerequisites:
+  description: |
+    The storyboard bootstraps three collection lists in the setup phase via
+    `create_collection_list`. The seed-DAG does not include collection lists,
+    so this storyboard uses the create-then-list pattern to keep itself
+    self-contained without extending the seed taxonomy.
+  test_kit: "test-kits/acme-outdoor.yaml"
+  controller_seeding: false
+
+phases:
+  - id: capability_discovery
+    title: "Capability discovery"
+    narrative: |
+      Confirm the agent responds to get_adcp_capabilities before
+      exercising list_collection_lists.
+    steps:
+      - id: get_capabilities
+        title: "Check agent capabilities"
+        narrative: |
+          Verify that the agent declares supported protocols before
+          driving paginated list_collection_lists.
+        task: get_adcp_capabilities
+        schema_ref: "protocol/get-adcp-capabilities-request.json"
+        response_schema_ref: "protocol/get-adcp-capabilities-response.json"
+        doc_ref: "/protocol/get_adcp_capabilities"
+        comply_scenario: pagination_integrity_collection_lists
+        stateful: false
+        expected: |
+          Return capabilities declaring supported protocols.
+
+        sample_request:
+          context:
+            correlation_id: "pagination_integrity_collection_lists--get_capabilities"
+        validations:
+          - check: response_schema
+            description: "Response matches get-adcp-capabilities-response.json schema"
+          - check: field_present
+            path: "supported_protocols"
+            description: "Agent declares supported protocols"
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "pagination_integrity_collection_lists--get_capabilities"
+            description: "Context correlation_id returned unchanged"
+
+  - id: setup
+    title: "Bootstrap three collection lists"
+    narrative: |
+      Create three collection lists so the pagination walk has a deterministic
+      set of three items to page through with max_results=2.
+    steps:
+      - id: create_list_1
+        title: "Create first collection list"
+        narrative: |
+          Create a collection list for primetime drama programs. The agent MUST
+          accept this and return a list_id.
+        task: create_collection_list
+        schema_ref: "collection/create-collection-list-request.json"
+        response_schema_ref: "collection/create-collection-list-response.json"
+        doc_ref: "/governance/task-reference/create_collection_list"
+        comply_scenario: pagination_integrity_collection_lists
+        stateful: true
+        expected: |
+          Accept the collection list and return a list.list_id.
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          name: "Primetime Drama Allowlist"
+          description: "Collection of approved primetime drama programs."
+          idempotency_key: "$generate:uuid_v4#pagination_integrity_collection_lists_setup_create_list_1"
+          context:
+            correlation_id: "pagination_integrity_collection_lists--setup_1"
+        validations:
+          - check: response_schema
+            description: "Response matches create-collection-list-response.json schema"
+          - check: field_present
+            path: "list.list_id"
+            description: "Response contains list.list_id"
+
+      - id: create_list_2
+        title: "Create second collection list"
+        narrative: |
+          Create a collection list for news programs.
+        task: create_collection_list
+        schema_ref: "collection/create-collection-list-request.json"
+        response_schema_ref: "collection/create-collection-list-response.json"
+        doc_ref: "/governance/task-reference/create_collection_list"
+        comply_scenario: pagination_integrity_collection_lists
+        stateful: true
+        expected: |
+          Accept the collection list and return a list.list_id.
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          name: "News Programs Allowlist"
+          description: "Approved national news broadcast programs."
+          idempotency_key: "$generate:uuid_v4#pagination_integrity_collection_lists_setup_create_list_2"
+          context:
+            correlation_id: "pagination_integrity_collection_lists--setup_2"
+        validations:
+          - check: response_schema
+            description: "Response matches create-collection-list-response.json schema"
+          - check: field_present
+            path: "list.list_id"
+            description: "Response contains list.list_id"
+
+      - id: create_list_3
+        title: "Create third collection list"
+        narrative: |
+          Create a collection list for sports programs.
+        task: create_collection_list
+        schema_ref: "collection/create-collection-list-request.json"
+        response_schema_ref: "collection/create-collection-list-response.json"
+        doc_ref: "/governance/task-reference/create_collection_list"
+        comply_scenario: pagination_integrity_collection_lists
+        stateful: true
+        expected: |
+          Accept the collection list and return a list.list_id.
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          name: "Sports Programs Allowlist"
+          description: "Approved live sports broadcasts."
+          idempotency_key: "$generate:uuid_v4#pagination_integrity_collection_lists_setup_create_list_3"
+          context:
+            correlation_id: "pagination_integrity_collection_lists--setup_3"
+        validations:
+          - check: response_schema
+            description: "Response matches create-collection-list-response.json schema"
+          - check: field_present
+            path: "list.list_id"
+            description: "Response contains list.list_id"
+
+  - id: pagination_walk
+    title: "Walk pages with a small max_results"
+    narrative: |
+      With three collection lists seeded and `max_results: 2`, the first call
+      MUST return a continuation page (has_more=true with a cursor). The runner
+      then follows the cursor; the second call MUST return the terminal page
+      (has_more=false with no cursor).
+
+    steps:
+      - id: first_page
+        title: "Request the first page with max_results=2"
+        narrative: |
+          The buyer asks for up to two collection lists. The agent has three
+          matching lists, so the request is non-terminal: callers expect
+          `has_more=true` and a `cursor` they can follow to retrieve the
+          remaining list.
+
+          The runner captures `pagination.cursor` into `$context.next_cursor`
+          for the follow-up step. If the agent reports `has_more=false` on
+          this page (hiding the seeded third list behind a dishonest terminal
+          signal), the field_value check on `pagination.has_more` fails.
+        task: list_collection_lists
+        schema_ref: "collection/list-collection-lists-request.json"
+        response_schema_ref: "collection/list-collection-lists-response.json"
+        doc_ref: "/governance/task-reference/list_collection_lists"
+        comply_scenario: pagination_integrity_collection_lists
+        stateful: true
+        context_outputs:
+          - name: next_cursor
+            path: "pagination.cursor"
+        expected: |
+          Return up to two collection lists with:
+          - pagination.has_more = true
+          - pagination.cursor present (an opaque continuation token)
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          pagination:
+            max_results: 2
+
+          context:
+            correlation_id: "pagination_integrity_collection_lists--first_page"
+        validations:
+          - check: response_schema
+            description: "Response matches list-collection-lists-response.json schema"
+          - check: field_value
+            path: "pagination.has_more"
+            value: true
+            description: "Three lists seeded with max_results=2 → first page is non-terminal"
+          - check: field_present
+            path: "pagination.cursor"
+            description: "has_more=true requires a cursor — without one the caller cannot continue"
+          - check: field_value_or_absent
+            path: "pagination.total_count"
+            allowed_values: [3]
+            description: "If volunteered, total_count MUST equal the seeded set size"
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "pagination_integrity_collection_lists--first_page"
+            description: "Context correlation_id returned unchanged"
+
+      - id: terminal_page
+        title: "Follow the cursor to the terminal page"
+        narrative: |
+          The buyer follows the captured cursor. With at most one remaining
+          list the agent MUST return a terminal page: `has_more=false` with no
+          `cursor` field. A cursor on `has_more=false` is a stale token that
+          invites callers to follow it past the end of results.
+        task: list_collection_lists
+        schema_ref: "collection/list-collection-lists-request.json"
+        response_schema_ref: "collection/list-collection-lists-response.json"
+        doc_ref: "/governance/task-reference/list_collection_lists"
+        comply_scenario: pagination_integrity_collection_lists
+        stateful: true
+        expected: |
+          Return the remaining list(s) with:
+          - pagination.has_more = false
+          - pagination.cursor absent
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          pagination:
+            cursor: "$context.next_cursor"
+            max_results: 2
+
+          context:
+            correlation_id: "pagination_integrity_collection_lists--terminal_page"
+        validations:
+          - check: response_schema
+            description: "Response matches list-collection-lists-response.json schema"
+          - check: field_value
+            path: "pagination.has_more"
+            value: false
+            description: "After two pages of two items the seeded set is exhausted"
+          - check: field_value_or_absent
+            path: "pagination.cursor"
+            allowed_values: [null]
+            description: "Terminal page MUST omit cursor (null also accepted for clients that explicitly clear the field)"
+          - check: field_value_or_absent
+            path: "pagination.total_count"
+            allowed_values: [3]
+            description: "total_count (when volunteered) MUST stay stable across pages and equal the seeded set size"
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "pagination_integrity_collection_lists--terminal_page"
+            description: "Context correlation_id returned unchanged"

package/compliance/cache/3.1.0-rc.2/universal/comply-controller-mode-gate.yaml

@@ -0,0 +1,141 @@
+id: comply_controller_mode_gate
+version: '1.0.0'
+title: 'Comply test controller — live-account denial gate'
+category: deterministic_testing
+summary: 'Verifies that a seller exposing comply_test_controller refuses calls from live-mode (non-sandbox) accounts with FORBIDDEN.'
+track: security
+required_tools:
+  - comply_test_controller
+
+requires:
+  - controller
+
+narrative: |
+  Sellers that expose comply_test_controller MUST gate dispatch against the calling
+  account's mode. When a buyer agent authenticates as a live-mode (non-sandbox)
+  account and calls comply_test_controller, the seller MUST refuse with
+  error: FORBIDDEN before dispatching any scenario.
+
+  This storyboard exercises the denial path by sending a well-formed
+  force_creative_status request from a live-mode principal (test-kit:
+  acme-outdoor-live, sandbox: false) and asserting FORBIDDEN is returned.
+
+  The live_account_denial phase is optional for two-deployment sellers whose
+  sandbox endpoint admits all authenticated principals regardless of account mode.
+  Those sellers rely on their production endpoint simply not advertising
+  comply_test_controller. Single-endpoint sellers that expose the controller on
+  their main endpoint MUST implement per-account gating and MUST pass this phase.
+
+  This storyboard is the keystone for the (Sandbox) AAO Verified tier — a seller
+  claiming that badge must prove its compliance infrastructure correctly refuses
+  live-mode callers from the controller surface, confirming the sandbox/production
+  boundary is enforced in both directions.
+
+agent:
+  interaction_model: media_buy_seller
+  capabilities:
+    - sells_media
+    - supports_test_controller
+  examples:
+    - 'Any single-endpoint seller with comply_test_controller'
+
+caller:
+  role: buyer_agent
+  example: 'Comply test harness'
+
+prerequisites:
+  description: |
+    The seller must expose comply_test_controller (verified by requires: [controller]
+    at storyboard load time). The live-mode test kit (acme-outdoor-live, sandbox: false)
+    provides an API key whose associated account resolves as live/production mode.
+    Conformant sellers resolve the account, detect mode: live, and return FORBIDDEN
+    without dispatching the scenario.
+  test_kit: 'test-kits/acme-outdoor-live.yaml'
+
+phases:
+  - id: live_account_denial
+    title: 'Live-account caller is denied'
+    narrative: |
+      A buyer authenticates as the live-mode Acme Outdoor principal (sandbox: false)
+      and calls comply_test_controller with a well-formed force_creative_status request.
+
+      Sellers that implement per-account gating MUST detect mode: live and return
+      ControllerError with error: FORBIDDEN before any scenario dispatch occurs.
+
+      This phase is optional: two-deployment sellers whose sandbox endpoint
+      has no per-account gate will return a successful state transition rather than
+      FORBIDDEN, which would fail this phase. Those sellers correctly prevent
+      live-mode misuse by not advertising the tool on their production endpoint
+      at all, so an optional result here does not indicate non-conformance.
+
+    optional: true
+
+    steps:
+      - id: deny_live_caller
+        title: 'comply_test_controller returns FORBIDDEN for a live-mode account'
+        narrative: |
+          Send a valid force_creative_status request authenticated as the live-mode
+          principal. The creative_id comply-live-mode-probe-000 is a stable probe
+          value that will not exist on any real seller; the scenario is benign —
+          the seller's gate fires before entity lookup, so NOT_FOUND is not a
+          conformant response here.
+
+          The seller MUST resolve the calling account, detect that account.mode
+          is live (not sandbox), and return FORBIDDEN. Returning UNKNOWN_SCENARIO,
+          NOT_FOUND, or a success response are all non-conformant for a
+          single-endpoint seller that implements the gate.
+        task: comply_test_controller
+        schema_ref: 'compliance/comply-test-controller-request.json'
+        response_schema_ref: 'compliance/comply-test-controller-response.json'
+        doc_ref: '/building/implementation/comply-test-controller'
+        comply_scenario: comply_controller_mode_gate
+        stateful: false
+        auth:
+          type: api_key
+          from_test_kit: true
+        expect_error: true
+        negative_path: payload_well_formed
+        expected: |
+          Seller refuses with:
+          - success: false
+          - error: FORBIDDEN
+          - error_detail (optional): human-readable explanation such as
+            "comply_test_controller requires a sandbox account; resolved
+            account is in live mode"
+
+        sample_request:
+          scenario: 'force_creative_status'
+          params:
+            creative_id: 'comply-live-mode-probe-000'
+            status: 'approved'
+          # account.sandbox is a caller-side declaration of intent (schema const: true).
+          # The denial here comes from the seller resolving the auth principal to a
+          # live-mode account in its persisted records — not from the payload claim.
+          # The payload still MUST be schema-valid, otherwise it never reaches the
+          # per-account gate (schema rejection happens first as defense-in-depth).
+          account:
+            sandbox: true
+          context:
+            correlation_id: "comply_controller_mode_gate--deny_live_caller"
+
+        validations:
+          - check: response_schema
+            description: 'Response matches comply-test-controller-response.json schema (ControllerError branch)'
+          - check: field_value
+            path: 'success'
+            allowed_values:
+              - false
+            description: 'Request is rejected — seller refused live-mode controller dispatch'
+          - check: field_value
+            path: 'error'
+            allowed_values:
+              - 'FORBIDDEN'
+            description: 'Error code is FORBIDDEN — seller detected live-mode account and denied dispatch before scenario execution'
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "comply_controller_mode_gate--deny_live_caller"
+            description: "Context correlation_id returned unchanged"