@adcp/sdk 7.10.2 → 7.11.1

package/compliance/cache/3.1.0-rc.2/universal/pagination-integrity-creative-formats.yaml

@@ -0,0 +1,265 @@
+id: pagination_integrity_creative_formats
+version: "1.0.0"
+title: "Pagination cursor integrity — list_creative_formats"
+category: schema_validation
+summary: "Validates the cursor↔has_more invariant on list_creative_formats by seeding two formats and walking pages with max_results=1."
+track: core
+required_tools:
+  - list_creative_formats
+
+narrative: |
+  Pagination is cursor-based across AdCP. Every response carrying a
+  `pagination` block satisfies one invariant: when `has_more` is true the
+  `cursor` MUST be present; when `has_more` is false the `cursor` MUST be
+  absent. This storyboard exercises both sides of the invariant on
+  `list_creative_formats`, mirroring the approach used by
+  `pagination-integrity.yaml` for `list_creatives`.
+
+  The runner seeds two creative formats into the agent's session ahead of
+  time so the result set has a knowable size at storyboard-author time. A
+  request filtered to those seeded names with `max_results=1` MUST trigger a
+  continuation page on the first call (`has_more=true` with a cursor).
+  Following that cursor MUST produce a terminal page (`has_more=false` with
+  no cursor). The unique name prefix narrows the result set to the seeded
+  fixtures so production catalogs are not swept during the pagination check.
+
+  The `list-creative-formats-response.json` schema does not define a
+  `query_summary` field, so this storyboard only asserts the
+  `pagination` block fields (`has_more`, `cursor`, `total_count`).
+
+agent:
+  interaction_model: stateful_preloaded
+  capabilities:
+    - has_creative_formats
+  examples:
+    - "Any AdCP agent that exposes a paginated list_creative_formats"
+
+caller:
+  role: buyer_agent
+  example: "Compliance test harness"
+
+prerequisites:
+  description: |
+    The runner seeds two creative formats ahead of time so a max_results=1
+    request reliably triggers a continuation page on the first call.
+  test_kit: "test-kits/acme-outdoor.yaml"
+  controller_seeding: true
+
+fixtures:
+  creative_formats:
+    - format_id: "pagination_integrity_format_1"
+      fixture:
+        name: "Pagination Integrity Format A"
+        type: "display"
+    - format_id: "pagination_integrity_format_2"
+      fixture:
+        name: "Pagination Integrity Format B"
+        type: "display"
+
+phases:
+  - id: capability_discovery
+    title: "Capability discovery"
+    narrative: |
+      Confirm the agent supports list_creative_formats before exercising
+      pagination.
+    steps:
+      - id: get_capabilities
+        title: "Check agent capabilities"
+        narrative: |
+          Verify that the agent declares creative in supported_protocols
+          before driving paginated list_creative_formats.
+        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 declaring creative in supported_protocols.
+
+        sample_request:
+          context:
+            correlation_id: "pagination_integrity_creative_formats--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_creative_formats--get_capabilities"
+            description: "Context correlation_id returned unchanged"
+
+  - id: seed_formats
+    title: "Seed two creative formats"
+    narrative: |
+      Pre-populate exactly two creative formats via comply_test_controller
+      so the result set has a knowable size for the pagination walk.
+    steps:
+      - id: seed_format_1
+        title: "Seed first format fixture"
+        task: comply_test_controller
+        schema_ref: "compliance/comply-test-controller-request.json"
+        response_schema_ref: "compliance/comply-test-controller-response.json"
+        comply_scenario: seed_creative_format
+        stateful: true
+        expected: |
+          Return success: true.
+        sample_request:
+          account:
+            sandbox: true
+            account_id: "acct_pagination_integrity_formats"
+          scenario: "seed_creative_format"
+          params:
+            format_id: "pagination_integrity_format_1"
+            fixture:
+              name: "Pagination Integrity Format A"
+              type: "display"
+          context:
+            correlation_id: "pagination_integrity_creative_formats--seed_1"
+        validations:
+          - check: field_value
+            path: "success"
+            value: true
+            description: "Seed acknowledged"
+
+      - id: seed_format_2
+        title: "Seed second format fixture"
+        task: comply_test_controller
+        schema_ref: "compliance/comply-test-controller-request.json"
+        response_schema_ref: "compliance/comply-test-controller-response.json"
+        comply_scenario: seed_creative_format
+        stateful: true
+        expected: |
+          Return success: true.
+        sample_request:
+          account:
+            sandbox: true
+            account_id: "acct_pagination_integrity_formats"
+          scenario: "seed_creative_format"
+          params:
+            format_id: "pagination_integrity_format_2"
+            fixture:
+              name: "Pagination Integrity Format B"
+              type: "display"
+          context:
+            correlation_id: "pagination_integrity_creative_formats--seed_2"
+        validations:
+          - check: field_value
+            path: "success"
+            value: true
+            description: "Seed acknowledged"
+
+  - id: pagination_walk
+    title: "Walk pages with max_results=1"
+    narrative: |
+      With two matching seeded formats and `max_results: 1`, 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 a terminal
+      page (has_more=false with no cursor).
+
+    steps:
+      - id: first_page
+        title: "Request the first page with max_results=1"
+        narrative: |
+          The buyer asks for one matching test format at a time. The agent has
+          two seeded formats matching the name search, so the first page is
+          non-terminal. The runner captures `pagination.cursor` for the
+          follow-up step.
+        task: list_creative_formats
+        schema_ref: "creative/list-creative-formats-request.json"
+        response_schema_ref: "creative/list-creative-formats-response.json"
+        doc_ref: "/creative/task-reference/list_creative_formats"
+        comply_scenario: pagination_integrity
+        stateful: true
+        context_outputs:
+          - name: next_cursor
+            path: "pagination.cursor"
+        expected: |
+          Return one format with:
+          - pagination.has_more = true
+          - pagination.cursor present (an opaque continuation token)
+
+        sample_request:
+          account:
+            account_id: "acct_pagination_integrity_formats"
+          name_search: "Pagination Integrity Format"
+          pagination:
+            max_results: 1
+          context:
+            correlation_id: "pagination_integrity_creative_formats--first_page"
+        validations:
+          - check: response_schema
+            description: "Response matches list-creative-formats-response.json schema"
+          - check: field_value
+            path: "pagination.has_more"
+            value: true
+            description: "Two formats seeded with max_results=1 → 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: [2]
+            description: "If volunteered, total_count MUST equal the seeded set size of two"
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "pagination_integrity_creative_formats--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 one format remaining
+          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_creative_formats
+        schema_ref: "creative/list-creative-formats-request.json"
+        response_schema_ref: "creative/list-creative-formats-response.json"
+        doc_ref: "/creative/task-reference/list_creative_formats"
+        comply_scenario: pagination_integrity
+        stateful: true
+        expected: |
+          Return the remaining format with:
+          - pagination.has_more = false
+          - pagination.cursor absent
+
+        sample_request:
+          account:
+            account_id: "acct_pagination_integrity_formats"
+          name_search: "Pagination Integrity Format"
+          pagination:
+            cursor: "$context.next_cursor"
+            max_results: 1
+          context:
+            correlation_id: "pagination_integrity_creative_formats--terminal_page"
+        validations:
+          - check: response_schema
+            description: "Response matches list-creative-formats-response.json schema"
+          - check: field_value
+            path: "pagination.has_more"
+            value: false
+            description: "After two pages of one item 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: [2]
+            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_creative_formats--terminal_page"
+            description: "Context correlation_id returned unchanged"

package/compliance/cache/3.1.0-rc.2/universal/pagination-integrity-list-accounts.yaml

@@ -0,0 +1,245 @@
+id: pagination_integrity_list_accounts
+version: "1.0.0"
+title: "Pagination continuation integrity — list_accounts"
+category: schema_validation
+summary: "Validates the has_more=true continuation side of list_accounts pagination by creating sandbox accounts, requesting a small first page, and following its cursor once."
+track: core
+required_tools:
+  - list_accounts
+
+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 the
+  continuation side on `list_accounts`: when `has_more=true`, `cursor` must be
+  present and usable.
+
+  The runner bootstraps three sandbox accounts via `sync_accounts`, then
+  lists sandbox accounts back with `max_results=2`. The first page MUST cap
+  at two accounts and signal continuation with `has_more=true` plus a cursor.
+  The runner then follows that cursor to prove the continuation token is usable.
+  Agents may have pre-existing sandbox accounts, so this storyboard deliberately
+  does not assert that the second observed page is terminal or that
+  `total_count` equals exactly three. The terminal side of the invariant is
+  covered by pagination storyboards with isolated seeded result sets; adding
+  equivalent account seeding with isolated lookup semantics is tracked
+  separately.
+
+agent:
+  interaction_model: stateful_preloaded
+  capabilities: []
+  examples:
+    - "Any AdCP agent that exposes a paginated list_accounts"
+
+caller:
+  role: buyer_agent
+  example: "Compliance test harness"
+
+prerequisites:
+  description: |
+    The storyboard bootstraps three accounts in the setup phase via
+    `sync_accounts`. The seed-DAG documented at
+    `static/compliance/source/universal/storyboard-schema.yaml` does not
+    include accounts (today's seed kinds are products, pricing_options,
+    creatives, plans, media_buys), so this storyboard deliberately
+    departs from the `controller_seeding: true` precedent used by
+    `pagination-integrity.yaml` (list_creatives) and bootstraps via
+    real protocol calls. Adding `seed_account` to the controller is
+    tracked separately; until then the create-then-list pattern keeps
+    the storyboard 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_accounts.
+    steps:
+      - id: get_capabilities
+        title: "Check agent capabilities"
+        narrative: |
+          Verify that the agent declares supported protocols before
+          driving paginated list_accounts.
+        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 declaring supported protocols.
+
+        sample_request:
+          context:
+            correlation_id: "pagination_integrity_list_accounts--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_list_accounts--get_capabilities"
+            description: "Context correlation_id returned unchanged"
+
+  - id: setup
+    title: "Bootstrap three test accounts"
+    narrative: |
+      Sync three sandbox accounts so the pagination walk has at least three
+      sandbox items to page through with max_results=2.
+    steps:
+      - id: sync_three_accounts
+        title: "Sync three sandbox accounts"
+        narrative: |
+          Create three sandbox accounts — Acme c/o Pinnacle, Nova c/o Pinnacle,
+          and Pinnacle Direct. The agent MUST accept all three and respond with
+          account_id values that subsequent list_accounts calls surface.
+        task: sync_accounts
+        schema_ref: "account/sync-accounts-request.json"
+        response_schema_ref: "account/sync-accounts-response.json"
+        doc_ref: "/accounts/task-reference/sync_accounts"
+        comply_scenario: pagination_integrity_list_accounts
+        stateful: true
+        expected: |
+          Accept all three accounts and return account_id for each.
+
+        sample_request:
+          accounts:
+            - brand:
+                domain: acme-corp.com
+              operator: pinnacle-media.com
+              billing: operator
+              sandbox: true
+            - brand:
+                domain: nova-brands.com
+              operator: pinnacle-media.com
+              billing: operator
+              sandbox: true
+            - brand:
+                domain: pinnacle-media.com
+              operator: pinnacle-media.com
+              billing: operator
+              sandbox: true
+
+          idempotency_key: "$generate:uuid_v4#pagination_integrity_list_accounts_setup_sync_three_accounts"
+          context:
+            correlation_id: "pagination_integrity_list_accounts--setup"
+        validations:
+          - check: response_schema
+            description: "Response matches sync-accounts-response.json schema"
+          - check: field_present
+            path: "accounts"
+            description: "Response contains accounts array"
+
+  - id: pagination_walk
+    title: "Walk pages with a small max_results"
+    narrative: |
+      With at least three sandbox accounts and `max_results: 2`, the first call
+      MUST return a continuation page (has_more=true with a cursor). The
+      runner then follows the cursor and validates the next page response shape.
+
+    steps:
+      - id: first_page
+        title: "Request the first page with max_results=2"
+        narrative: |
+          The buyer asks for up to two sandbox accounts. The agent has at least
+          three matching accounts, so the request is non-terminal: callers expect
+          `has_more=true` and a `cursor` they can follow to retrieve the
+          remaining account.
+
+          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 sandbox account behind a dishonest
+          terminal signal), the field_value check on `pagination.has_more`
+          fails — surfacing exactly the bug class this storyboard exists to
+          catch.
+        task: list_accounts
+        schema_ref: "account/list-accounts-request.json"
+        response_schema_ref: "account/list-accounts-response.json"
+        doc_ref: "/accounts/task-reference/list_accounts"
+        comply_scenario: pagination_integrity_list_accounts
+        stateful: true
+        context_outputs:
+          - name: next_cursor
+            path: "pagination.cursor"
+        expected: |
+          Return up to two accounts with:
+          - pagination.has_more = true
+          - pagination.cursor present (an opaque continuation token)
+
+        sample_request:
+          sandbox: true
+          pagination:
+            max_results: 2
+
+          context:
+            correlation_id: "pagination_integrity_list_accounts--first_page"
+        validations:
+          - check: response_schema
+            description: "Response matches list-accounts-response.json schema"
+          - check: field_value
+            path: "pagination.has_more"
+            value: true
+            description: "At least three sandbox accounts exist 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_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "pagination_integrity_list_accounts--first_page"
+            description: "Context correlation_id returned unchanged"
+
+      - id: next_page
+        title: "Follow the cursor to the next page"
+        narrative: |
+          The buyer follows the captured cursor. The response MUST remain
+          schema-valid and echo context. The runner does not require this page
+          to be terminal because sellers may already have more than the three
+          sandbox accounts created during setup.
+        task: list_accounts
+        schema_ref: "account/list-accounts-request.json"
+        response_schema_ref: "account/list-accounts-response.json"
+        doc_ref: "/accounts/task-reference/list_accounts"
+        comply_scenario: pagination_integrity_list_accounts
+        stateful: true
+        expected: |
+          Return the next page of sandbox accounts with a valid pagination block.
+
+        sample_request:
+          sandbox: true
+          pagination:
+            cursor: "$context.next_cursor"
+            max_results: 2
+
+          context:
+            correlation_id: "pagination_integrity_list_accounts--next_page"
+        validations:
+          - check: response_schema
+            description: "Response matches list-accounts-response.json schema"
+          - check: field_present
+            path: "pagination.has_more"
+            description: "Pagination response declares whether more sandbox accounts remain"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "pagination_integrity_list_accounts--next_page"
+            description: "Context correlation_id returned unchanged"