@adcp/sdk 6.8.0 → 6.10.0

package/compliance/cache/3.0.6/universal/pagination-integrity-creative-formats.yaml

@@ -0,0 +1,258 @@
+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 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 `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:
+            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:
+            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 formats seeded 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 format at a time. The agent has two seeded
+          formats, 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"
+          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"
+          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.0.6/universal/pagination-integrity-list-accounts.yaml

@@ -0,0 +1,262 @@
+id: pagination_integrity_list_accounts
+version: "1.0.0"
+title: "Pagination cursor integrity — list_accounts"
+category: schema_validation
+summary: "Validates the cursor↔has_more invariant by walking a paginated list_accounts response from a continuation page to a terminal page."
+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 both
+  sides of the invariant on `list_accounts` in a single run.
+
+  The runner bootstraps three accounts via `sync_accounts`, then lists them
+  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; the next page returns the remaining account and MUST
+  signal `has_more=false` with no cursor. An agent that hides the third
+  account 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 account count of three.
+
+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 a
+      deterministic set of three 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 three accounts 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 accounts. The agent has 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 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:
+          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: "Three accounts 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 — under-reporting hides accounts the same way a dishonest has_more does"
+
+          - 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: terminal_page
+        title: "Follow the cursor to the terminal page"
+        narrative: |
+          The buyer follows the captured cursor. With at most one remaining
+          account 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_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 remaining account(s) with:
+          - pagination.has_more = false
+          - pagination.cursor absent (a stale cursor on a terminal page is a
+            dishonest pagination signal)
+
+        sample_request:
+          pagination:
+            cursor: "$context.next_cursor"
+            max_results: 2
+
+          context:
+            correlation_id: "pagination_integrity_list_accounts--terminal_page"
+        validations:
+          - check: response_schema
+            description: "Response matches list-accounts-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_list_accounts--terminal_page"
+            description: "Context correlation_id returned unchanged"