@adcp/sdk 7.10.2 → 7.11.1

package/compliance/cache/3.1.0-rc.2/specialisms/brand-rights/scenarios/governance_denied.yaml

@@ -0,0 +1,226 @@
+id: brand_rights/governance_denied
+version: "1.0.0"
+title: "Brand agent rejects rights acquisition when governance denies"
+category: brand_rights
+summary: "Verifies that a brand agent propagates GOVERNANCE_DENIED when the buyer's governance plan denies a rights license."
+track: brand
+required_tools:
+  - sync_governance
+  - get_rights
+  - acquire_rights
+
+narrative: |
+  Acquiring rights is a spending event. The brand agent must consult the buyer's
+  governance agent before issuing a license and deny the acquisition when governance
+  returns denied. This keeps licensing authority consistent with media buy spending
+  authority — a buyer cannot commit to a generative campaign budget that exceeds the
+  plan even when the spending flows to a brand agent instead of a seller.
+
+  This scenario sets up a strict $50 governance plan, registers governance with the
+  brand agent via sync_governance, then attempts to acquire rights whose pricing
+  exceeds the plan. The brand agent must return the canonical denial shape — the
+  `AcquireRightsRejected` arm of the response (`rights_status: "rejected"` + `reason`)
+  — propagating the governance agent's findings in `reason`. Per the wire-placement
+  rule on `GOVERNANCE_DENIED`, when a task response defines a structured rejection arm,
+  the arm IS the canonical denial shape: sellers do NOT additionally emit
+  `GOVERNANCE_DENIED` in `errors[]` or `adcp_error`, and transport-level success
+  markers stay flipped to success. The schema enforces this — `AcquireRightsRejected`
+  declares `not: { required: [errors] }`, so dual-emission is already a schema violation.
+
+  By default, the governance agent is the training agent at test-agent.adcontextprotocol.org.
+  Override by supplying a different `governance_agent_url` in the run's initial context
+  (e.g., via `--context` on `adcp storyboard run` once the CLI supports it).
+
+context:
+  governance_agent_url: "https://test-agent.adcontextprotocol.org"
+
+agent:
+  interaction_model: brand_rights_holder
+  capabilities:
+    - rights_licensing
+    - governance_aware
+  examples:
+    - "Any brand rights agent that honors governance before licensing"
+
+caller:
+  role: buyer_agent
+  example: "Pinnacle Agency (buyer)"
+
+prerequisites:
+  description: |
+    A governance agent that supports sync_plans and check_governance, and a brand
+    agent that supports sync_governance + acquire_rights.
+  test_kit: "test-kits/acme-outdoor.yaml"
+
+phases:
+  - id: governance_plan_setup
+    title: "Set up strict governance plan"
+    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:
+          plans:
+            - plan_id: "comply-rights-gov-denied"
+              brand:
+                domain: "acmeoutdoor.example"
+              objectives: "Restricted plan — rights licensing test"
+              budget:
+                total: 50
+                currency: "USD"
+                reallocation_threshold: 25
+              flight:
+                start: "2026-04-01T00:00:00Z"
+                end: "2026-06-30T23:59:59Z"
+              countries: ["US"]
+          idempotency_key: "$generate:uuid_v4#brand_rights_governance_denied_governance_plan_setup_sync_plans"
+        validations:
+          - check: response_schema
+            description: "Response matches sync-plans-response.json schema"
+
+  - id: brand_agent_setup
+    title: "Register account and governance with the brand agent"
+    steps:
+      - id: sync_accounts
+        title: "Establish account with brand agent"
+        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: |
+          Brand agent returns 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#brand_rights_governance_denied_brand_agent_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 brand agent"
+        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: |
+          Brand agent acknowledges governance 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"
+          idempotency_key: "$generate:uuid_v4#brand_rights_governance_denied_brand_agent_setup_sync_governance"
+        validations:
+          - check: response_schema
+            description: "Response matches sync-governance-response.json schema"
+
+  - id: rights_denied
+    title: "Attempt rights acquisition — governance denies"
+    steps:
+      - id: get_rights_catalog
+        title: "Discover rights to license"
+        task: get_rights
+        schema_ref: "brand/get-rights-request.json"
+        response_schema_ref: "brand/get-rights-response.json"
+        doc_ref: "/brand-protocol/tasks/get_rights"
+        stateful: false
+        expected: |
+          Return rights available for licensing, each with pricing_options.
+        sample_request:
+          buyer:
+            domain: "pinnacle-agency.example"
+          query: "licensed commercial rights for a regional outdoor retail campaign"
+          uses:
+            - "commercial"
+            - "endorsement"
+        context_outputs:
+          - path: "rights[0].rights_id"
+            key: "rights_id"
+          - path: "rights[0].pricing_options[0].pricing_option_id"
+            key: "pricing_option_id"
+        validations:
+          - check: response_schema
+            description: "Response matches get-rights-response.json schema"
+
+      - id: acquire_rights_denied
+        title: "acquire_rights — governance denies via rejection arm"
+        task: acquire_rights
+        schema_ref: "brand/acquire-rights-request.json"
+        response_schema_ref: "brand/acquire-rights-response.json"
+        doc_ref: "/brand-protocol/tasks/acquire_rights"
+        expected_arm: "rejected"
+        stateful: true
+        expected: |
+          Brand agent returns the canonical denial shape for a task with a structured rejection arm:
+          AcquireRightsRejected (`rights_status: "rejected"` + `reason`, with `suggestions` optional). Per the
+          wire-placement rule on `GOVERNANCE_DENIED`, the spec-correct denial response carries no error
+          code on the wire — the rejection arm enforces `not: { required: [errors] }` at the schema layer,
+          so emitting `errors[]` alongside the rejection arm is already a schema violation. Transport-level
+          success markers MUST NOT be flipped (HTTP 200, MCP `isError: false`, A2A `succeeded`) — the task
+          ran successfully and produced a structured response.
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          rights_id: "$context.rights_id"
+          pricing_option_id: "$context.pricing_option_id"
+          buyer:
+            domain: "pinnacle-agency.example"
+          campaign:
+            description: "Governance-denied rights acquisition probe"
+            uses:
+              - "likeness"
+              - "commercial"
+            start_date: "2026-04-01"
+            end_date: "2026-06-30"
+          revocation_webhook:
+            url: "https://pinnacle-agency.example/webhooks/revocation"
+            authentication:
+              schemes:
+                - "Bearer"
+              credentials: "pinnacle-revocation-webhook-secret-token"
+          idempotency_key: "$generate:uuid_v4#brand_rights_governance_denied_acquire_rights_denied"
+
+          context:
+            correlation_id: "brand_rights--governance_denied--acquire"
+        validations:
+          - check: response_schema
+            description: "Response matches acquire-rights-response.json (rejection arm validates against AcquireRightsRejected; the schema's `not: { required: [errors] }` rule rejects dual-emission)"
+          - check: field_value
+            path: "rights_status"
+            value: "rejected"
+            description: "Discriminator on the rejection arm — rights_status must be 'rejected'"
+          - check: field_present
+            path: "reason"
+            description: "Rejection arm carries the operator-readable reason (governance findings propagated verbatim per wire-placement guidance)"
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object on the rejection arm"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "brand_rights--governance_denied--acquire"
+            description: "Context correlation_id returned unchanged"

package/compliance/cache/3.1.0-rc.2/specialisms/collection-lists/index.yaml

@@ -0,0 +1,359 @@
+id: collection_lists
+version: "1.0.0"
+title: "Collection lists"
+protocol: governance
+category: collection_lists
+summary: "Curated collection lists for program-level brand safety and content targeting — create, query, update, and delete lists of content programs (shows, series, podcasts)."
+track: governance
+required_tools:
+  - create_collection_list
+
+# Cross-step assertion (adcp#2664). status.monotonic rejects resource
+# status transitions observed across steps that aren't on the spec
+# lifecycle graph. Silent on collection-list-only runs (no tracked
+# lifecycle resource), but wired so phases that touch media_buy /
+# account status are automatically gated.
+invariants:
+  - status.monotonic
+
+narrative: |
+  You run a governance agent that manages collection lists for brand safety. Unlike
+  property lists which operate on technical surfaces (domains, apps), collection lists
+  operate on content programs (shows, series, podcasts) identified by platform-independent
+  IDs like IMDb, Gracenote, or EIDR.
+
+  Buyers create inclusion and exclusion lists that define which programs their ads can
+  and cannot appear against. Your agent resolves the base collections and filters into a
+  concrete list of program identifiers that sellers can cache and enforce at bid time.
+
+  Collection lists are setup-time resources: the governance agent resolves them once and
+  sellers cache the result. Unlike property lists, there is no post-delivery validation
+  task yet — enforcement happens at serve time via the cached list, not via after-the-fact
+  compliance checks. This storyboard therefore exercises the full CRUD lifecycle (create,
+  query, update, delete) but does not test delivery validation.
+
+agent:
+  interaction_model: governance_agent
+  capabilities:
+    - collection_lists
+    - brand_safety
+  examples:
+    - "IAS"
+    - "DoubleVerify"
+    - "GARM-aligned platforms"
+    - "Brand safety services"
+
+caller:
+  role: buyer_agent
+  example: "Nova Motors (buyer)"
+
+prerequisites:
+  description: |
+    The caller needs a brand identity and content-program knowledge (distribution IDs,
+    publisher identifiers, or genre taxonomies). The test kit provides a sample brand
+    with campaign context.
+  test_kit: "test-kits/nova-motors.yaml"
+
+phases:
+  - id: capability_discovery
+    title: "Capability discovery"
+    narrative: |
+      The buyer calls get_adcp_capabilities to confirm the agent supports governance
+      before creating or fetching collection lists.
+
+    steps:
+      - id: get_capabilities
+        title: "Check agent capabilities"
+        narrative: |
+          Verify that the agent declares the expected protocol support before
+          proceeding with domain-specific operations.
+        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 governance in supported_protocols, confirming
+          the agent provides governance services.
+        sample_request:
+          context:
+            correlation_id: "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: "collection_lists--get_capabilities"
+            description: "Context correlation_id returned unchanged"
+
+  - id: create_list
+    title: "Create collection lists"
+    narrative: |
+      The buyer creates an inclusion collection list for the campaign. The list defines
+      which content programs the brand is willing to advertise against, selected by
+      platform-independent distribution identifiers.
+
+    steps:
+      - id: create_inclusion_list
+        title: "Create an inclusion collection list"
+        narrative: |
+          The buyer creates an inclusion list of programs the brand considers safe to
+          advertise against, referenced by distribution IDs (e.g. IMDb) so the selection
+          is portable across publishers.
+        task: create_collection_list
+        schema_ref: "collection/create-collection-list-request.json"
+        response_schema_ref: "collection/create-collection-list-response.json"
+        doc_ref: "/governance/collection/tasks/collection_lists"
+        comply_scenario: governance_collection_lists
+        stateful: true
+        expected: |
+          Return the created collection list:
+          - list_id: platform-assigned identifier
+          - collection_count reflecting the resolved programs
+          - auth_token issued for sellers to fetch the list
+          - Timestamps populated
+
+        sample_request:
+          account:
+            brand:
+              domain: "novamotors.example"
+            operator: "pinnacle-agency.example"
+          brand:
+            domain: "novamotors.example"
+          name: "Nova Motors approved programs"
+          base_collections:
+            - selection_type: "distribution_ids"
+              identifiers:
+                - type: "imdb_id"
+                  value: "tt9999901"
+                - type: "imdb_id"
+                  value: "tt9999902"
+                - type: "imdb_id"
+                  value: "tt9999903"
+          filters:
+            kinds: ["series"]
+
+          idempotency_key: "$generate:uuid_v4#collection_lists_create_list_create_inclusion_list"
+          context:
+            correlation_id: "collection_lists--create_inclusion_list"
+        context_outputs:
+          - path: "list.list_id"
+            key: "collection_list_id"
+
+        validations:
+          - check: response_schema
+            description: "Response matches create-collection-list-response.json schema"
+          - check: field_present
+            path: "list.list_id"
+            description: "Governance agent assigns list_id — must be echoed in get/update/delete"
+          - check: field_present
+            path: "auth_token"
+            description: "Agent issues an auth_token at creation time for seller fetches"
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "collection_lists--create_inclusion_list"
+            description: "Context correlation_id returned unchanged"
+
+  - id: list_and_get
+    title: "Query collection lists"
+    narrative: |
+      The buyer lists all collection lists for the brand and retrieves a specific list
+      with resolved collections.
+
+    steps:
+      - id: list_collection_lists
+        title: "List all collection lists"
+        narrative: |
+          The buyer lists all collection lists for the brand. The response includes
+          list metadata without full resolved collection details.
+        task: list_collection_lists
+        schema_ref: "collection/list-collection-lists-request.json"
+        response_schema_ref: "collection/list-collection-lists-response.json"
+        doc_ref: "/governance/collection/tasks/collection_lists"
+        comply_scenario: governance_collection_lists
+        stateful: true
+        expected: |
+          Return collection list summaries:
+          - Array of lists with list_id, name, collection_count
+          - Includes the list created in the prior phase
+
+        sample_request:
+          account:
+            brand:
+              domain: "novamotors.example"
+            operator: "pinnacle-agency.example"
+          name_contains: "Nova Motors"
+
+          context:
+            correlation_id: "collection_lists--list_collection_lists"
+        validations:
+          - check: response_schema
+            description: "Response matches list-collection-lists-response.json schema"
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "collection_lists--list_collection_lists"
+            description: "Context correlation_id returned unchanged"
+
+      - id: get_collection_list
+        title: "Get a specific collection list with resolved collections"
+        narrative: |
+          The buyer retrieves a specific collection list with resolve:true to confirm
+          the agent can materialize the programs the list references.
+        task: get_collection_list
+        schema_ref: "collection/get-collection-list-request.json"
+        response_schema_ref: "collection/get-collection-list-response.json"
+        doc_ref: "/governance/collection/tasks/collection_lists"
+        comply_scenario: governance_collection_lists
+        stateful: true
+        expected: |
+          Return the full collection list:
+          - list_id, name, collection_count
+          - Resolved collections with distribution_ids, content_rating, genre
+          - cache_valid_until timestamp for seller caching
+
+        sample_request:
+          list_id: "$context.collection_list_id"
+          resolve: true
+          account:
+            brand:
+              domain: "novamotors.example"
+            operator: "pinnacle-agency.example"
+
+          context:
+            correlation_id: "collection_lists--get_collection_list"
+        validations:
+          - check: response_schema
+            description: "Response matches get-collection-list-response.json schema"
+          - check: field_present
+            path: "list.list_id"
+            description: "List id returned"
+          - check: field_present
+            path: "collections"
+            description: "Resolved collections returned when resolve:true"
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "collection_lists--get_collection_list"
+            description: "Context correlation_id returned unchanged"
+
+  - id: update_list
+    title: "Update collection lists"
+    narrative: |
+      The buyer modifies an existing collection list — replacing the base collections
+      as the campaign's content preferences evolve.
+
+    steps:
+      - id: update_collection_list
+        title: "Update a collection list"
+        narrative: |
+          The buyer replaces the base collections on an existing list with a new set
+          of distribution identifiers.
+        task: update_collection_list
+        schema_ref: "collection/update-collection-list-request.json"
+        response_schema_ref: "collection/update-collection-list-response.json"
+        doc_ref: "/governance/collection/tasks/collection_lists"
+        comply_scenario: governance_collection_lists
+        stateful: true
+        expected: |
+          Return the updated collection list:
+          - Same list_id
+          - Updated collection_count reflecting the replaced base collections
+          - Updated updated_at timestamp
+
+        sample_request:
+          list_id: "$context.collection_list_id"
+          account:
+            brand:
+              domain: "novamotors.example"
+            operator: "pinnacle-agency.example"
+          base_collections:
+            - selection_type: "distribution_ids"
+              identifiers:
+                - type: "imdb_id"
+                  value: "tt9999901"
+                - type: "imdb_id"
+                  value: "tt9999904"
+                - type: "imdb_id"
+                  value: "tt9999905"
+                - type: "imdb_id"
+                  value: "tt9999906"
+
+          idempotency_key: "$generate:uuid_v4#collection_lists_update_list_update_collection_list"
+          context:
+            correlation_id: "collection_lists--update_collection_list"
+        validations:
+          - check: response_schema
+            description: "Response matches update-collection-list-response.json schema"
+          - check: field_present
+            path: "list.list_id"
+            description: "Updated list retains its list_id"
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "collection_lists--update_collection_list"
+            description: "Context correlation_id returned unchanged"
+
+  - id: delete_list
+    title: "Delete a collection list"
+    narrative: |
+      The buyer removes a collection list that is no longer needed. Deleting a list
+      revokes the associated auth_token.
+
+    steps:
+      - id: delete_collection_list
+        title: "Delete a collection list"
+        narrative: |
+          The buyer deletes a collection list. The governance agent removes the list
+          and returns confirmation.
+        task: delete_collection_list
+        schema_ref: "collection/delete-collection-list-request.json"
+        response_schema_ref: "collection/delete-collection-list-response.json"
+        doc_ref: "/governance/collection/tasks/collection_lists"
+        comply_scenario: governance_collection_lists
+        stateful: true
+        expected: |
+          Confirm deletion:
+          - deleted: true
+          - list_id: the deleted list
+
+        sample_request:
+          list_id: "$context.collection_list_id"
+          account:
+            brand:
+              domain: "novamotors.example"
+            operator: "pinnacle-agency.example"
+
+          idempotency_key: "$generate:uuid_v4#collection_lists_delete_list_delete_collection_list"
+          context:
+            correlation_id: "collection_lists--delete_collection_list"
+        validations:
+          - check: response_schema
+            description: "Response matches delete-collection-list-response.json schema"
+          - check: field_value
+            path: "deleted"
+            value: true
+            description: "Delete returns deleted: true"
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "collection_lists--delete_collection_list"
+            description: "Context correlation_id returned unchanged"