@adcp/sdk 7.10.2 → 7.11.1

package/compliance/cache/3.1.0-rc.2/domains/media-buy/scenarios/proposal_not_found_errors.yaml

@@ -0,0 +1,257 @@
+id: media_buy_seller/proposal_not_found_errors
+version: "1.0.0"
+title: "Seller returns canonical proposal error codes"
+category: media_buy_seller
+summary: "Validates that the seller returns PROPOSAL_NOT_FOUND (and PROPOSAL_EXPIRED) rather than generic NOT_FOUND or INVALID_REQUEST when the buyer references proposal IDs that do not exist or have expired."
+track: media_buy
+required_tools:
+  - get_products
+  - create_media_buy
+
+requires_capability:
+  path: media_buy.supports_proposals
+  equals: true
+
+narrative: |
+  Error-code coverage is the most common compliance gap. This scenario forces
+  PROPOSAL_NOT_FOUND on two distinct paths — get_products refine mode and
+  create_media_buy — using fabricated proposal IDs the seller cannot resolve.
+  A separate phase forces PROPOSAL_EXPIRED using a sentinel ID that represents
+  a known-but-expired proposal hold window.
+
+  All three probes use schema-valid requests (negative_path: payload_well_formed)
+  so the error is semantic, not a JSON-schema validation rejection. Hard
+  check: error_code assertions ensure sellers cannot pass by returning generic
+  NOT_FOUND or INVALID_REQUEST.
+
+  Background: PROPOSAL_NOT_FOUND and PROPOSAL_EXPIRED were added to the canonical
+  error catalog in #4043. Without storyboard coverage, sellers can keep returning
+  generic codes on the negative proposal paths and still pass the happy-path
+  proposal storyboards.
+
+agent:
+  interaction_model: media_buy_seller
+  capabilities:
+    - sells_media
+    - accepts_briefs
+    - generates_proposals
+  examples:
+    - "Full-service publisher with proposal engine"
+    - "Retail media network with curated packages"
+
+caller:
+  role: buyer_agent
+  example: "Pinnacle Agency (buyer)"
+
+prerequisites:
+  description: |
+    The seller must support proposals (media_buy.supports_proposals: true).
+
+    Sentinel IDs used in this storyboard:
+    - does-not-exist-proposal-not-found-v1: a proposal_id the seller can never resolve
+      (never created, wrong tenant, evicted). Triggers PROPOSAL_NOT_FOUND.
+    - expired-proposal-sentinel-v1: a proposal_id the seller treats as known-but-expired
+      (expires_at in the past). Triggers PROPOSAL_EXPIRED. Sellers that cannot distinguish
+      expired from never-existed MAY return PROPOSAL_NOT_FOUND for this probe; the
+      validation uses allowed_values to accept both.
+  test_kit: "test-kits/acme-outdoor.yaml"
+
+phases:
+  - id: setup
+    title: "Account setup"
+    steps:
+      - id: sync_accounts
+        title: "Establish account"
+        task: sync_accounts
+        schema_ref: "account/sync-accounts-request.json"
+        response_schema_ref: "account/sync-accounts-response.json"
+        doc_ref: "/accounts/tasks/sync_accounts"
+        stateful: true
+        expected: |
+          Return the account with account_id and status active.
+
+        sample_request:
+          accounts:
+            - brand:
+                domain: "acmeoutdoor.example"
+              operator: "pinnacle-agency.example"
+              billing: "operator"
+              payment_terms: "net_30"
+
+          idempotency_key: "$generate:uuid_v4#media_buy_seller_proposal_not_found_errors_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: unknown_proposal_refine
+    title: "Refine an unknown proposal_id"
+    narrative: |
+      The buyer sends get_products in refine mode with a proposal_id the seller cannot
+      resolve. The seller must return PROPOSAL_NOT_FOUND — not NOT_FOUND, not
+      INVALID_REQUEST, not a 500. The request is schema-valid; the error is semantic.
+
+    steps:
+      - id: get_products_refine_unknown_proposal
+        title: "get_products refine with bogus proposal_id"
+        task: get_products
+        schema_ref: "media-buy/get-products-request.json"
+        response_schema_ref: "media-buy/get-products-response.json"
+        doc_ref: "/media-buy/task-reference/get_products"
+        comply_scenario: full_sales_flow
+        expect_error: true
+        negative_path: payload_well_formed
+        stateful: false
+        expected: |
+          Reject with:
+          - code: PROPOSAL_NOT_FOUND
+          - recovery: correctable
+          - error.field pointing at the proposal reference (if available)
+          - context echoed unchanged
+
+        sample_request:
+          buying_mode: "refine"
+          refine:
+            - scope: "proposal"
+              proposal_id: "does-not-exist-proposal-not-found-v1"
+              ask: "Shift 60% of budget to CTV."
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          context:
+            correlation_id: "proposal_not_found_errors--get_products_refine"
+        validations:
+          - check: error_code
+            value: "PROPOSAL_NOT_FOUND"
+            description: "Error code is PROPOSAL_NOT_FOUND"
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object even on errors"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "proposal_not_found_errors--get_products_refine"
+            description: "Context correlation_id returned unchanged"
+
+  - id: unknown_proposal_create
+    title: "create_media_buy from an unknown proposal_id"
+    narrative: |
+      The buyer sends create_media_buy referencing a proposal_id the seller cannot resolve.
+      The seller must return PROPOSAL_NOT_FOUND with correctable recovery — the buyer should
+      re-issue get_products with buying_mode: refine + action: finalize to obtain a valid
+      committed proposal_id before retrying create_media_buy.
+
+    steps:
+      - id: create_media_buy_unknown_proposal
+        title: "create_media_buy with bogus proposal_id"
+        task: create_media_buy
+        schema_ref: "media-buy/create-media-buy-request.json"
+        response_schema_ref: "media-buy/create-media-buy-response.json"
+        doc_ref: "/media-buy/task-reference/create_media_buy"
+        comply_scenario: create_media_buy
+        expect_error: true
+        negative_path: payload_well_formed
+        stateful: false
+        expected: |
+          Reject with:
+          - code: PROPOSAL_NOT_FOUND
+          - recovery: correctable
+          - error.field pointing at proposal_id (if available)
+          - context echoed unchanged
+
+        sample_request:
+          brand:
+            domain: "acmeoutdoor.example"
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          proposal_id: "does-not-exist-proposal-not-found-v1"
+          total_budget:
+            amount: 50000
+            currency: "USD"
+          start_time: "2026-04-01T00:00:00Z"
+          end_time: "2026-06-30T23:59:59Z"
+          idempotency_key: "$generate:uuid_v4#media_buy_seller_proposal_not_found_errors_unknown_proposal_create_create_media_buy_unknown_proposal"
+          context:
+            correlation_id: "proposal_not_found_errors--create_media_buy_unknown"
+        validations:
+          - check: error_code
+            value: "PROPOSAL_NOT_FOUND"
+            description: "Error code is PROPOSAL_NOT_FOUND"
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object even on errors"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "proposal_not_found_errors--create_media_buy_unknown"
+            description: "Context correlation_id returned unchanged"
+
+  - id: expired_proposal_create
+    title: "create_media_buy from an expired proposal"
+    narrative: |
+      The buyer sends create_media_buy referencing a proposal_id whose expires_at hold
+      window has passed. The seller must return PROPOSAL_EXPIRED — distinct from
+      PROPOSAL_NOT_FOUND because the proposal was known but its inventory hold has lapsed.
+      Recovery is correctable: re-issue get_products with buying_mode: refine +
+      action: finalize to obtain a fresh committed proposal before retrying.
+
+      Sellers that cannot distinguish a known-but-expired proposal from a never-existed
+      proposal MAY return PROPOSAL_NOT_FOUND for this probe; the validation uses
+      allowed_values to accept both codes. Per-code precision is preferred for
+      buyer-agent recovery clarity (expired = re-finalize the same proposal;
+      not-found = restart discovery from scratch).
+
+      Trigger convention: the test kit configures 'expired-proposal-sentinel-v1' as a
+      seller-side known-but-expired proposal_id. Sellers that cannot configure a
+      sentinel should document their test-kit approach in their compliance notes.
+
+    steps:
+      - id: create_media_buy_expired_proposal
+        title: "create_media_buy with expired proposal_id"
+        task: create_media_buy
+        schema_ref: "media-buy/create-media-buy-request.json"
+        response_schema_ref: "media-buy/create-media-buy-response.json"
+        doc_ref: "/media-buy/task-reference/create_media_buy"
+        comply_scenario: create_media_buy
+        expect_error: true
+        negative_path: payload_well_formed
+        stateful: false
+        expected: |
+          Reject with:
+          - code: PROPOSAL_EXPIRED (preferred) or PROPOSAL_NOT_FOUND (acceptable if seller
+            cannot distinguish known-but-expired from never-existed)
+          - recovery: correctable
+          - context echoed unchanged
+
+        sample_request:
+          brand:
+            domain: "acmeoutdoor.example"
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          proposal_id: "expired-proposal-sentinel-v1"
+          total_budget:
+            amount: 50000
+            currency: "USD"
+          start_time: "2026-04-01T00:00:00Z"
+          end_time: "2026-06-30T23:59:59Z"
+          idempotency_key: "$generate:uuid_v4#media_buy_seller_proposal_not_found_errors_expired_proposal_create_create_media_buy_expired_proposal"
+          context:
+            correlation_id: "proposal_not_found_errors--create_media_buy_expired"
+        validations:
+          - check: error_code
+            allowed_values:
+              - "PROPOSAL_EXPIRED"
+              - "PROPOSAL_NOT_FOUND"
+            description: "Error code is PROPOSAL_EXPIRED (preferred) or PROPOSAL_NOT_FOUND (acceptable when seller cannot distinguish known-but-expired from never-existed)"
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object even on errors"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "proposal_not_found_errors--create_media_buy_expired"
+            description: "Context correlation_id returned unchanged"

package/compliance/cache/3.1.0-rc.2/domains/media-buy/scenarios/provenance_audit_observation.yaml

@@ -0,0 +1,333 @@
+id: media_buy_seller/provenance_audit_observation
+version: "1.0.0"
+title: "Seller accepts a provenance carve-out claim surfaced as an audit observation"
+category: media_buy_seller
+summary: "Buyer submits AI-assisted creatives with human_oversight directed/edited and disclosure.required false. Seller invokes an on-list verifier, records OVERSIGHT_DISCLOSURE_CARVEOUT_CLAIMED audit observations, and accepts the creatives rather than treating the observations as rejections."
+track: creative
+required_tools:
+  - get_products
+  - sync_creatives
+  - comply_test_controller
+
+narrative: |
+  This scenario exercises the non-rejection half of provenance verification.
+  The buyer claims editorial-responsibility carve-outs by submitting AI-
+  assisted creatives with human_oversight: directed/edited and
+  disclosure.required: false. Those combinations are audit-worthy, but they
+  are not contradictions and are not grounds for rejection by themselves.
+
+  The seller should call an on-list governance agent via get_creative_features.
+  The verifier returns audit_observations[] with
+  OVERSIGHT_DISCLOSURE_CARVEOUT_CLAIMED. The seller accepts the creative
+  through the normal lifecycle rather than rejecting solely on that
+  observation. Shared conformance observes the accept result, outbound
+  verifier calls, and a sandbox-only controller query for the recorded
+  observation; public seller responses do not have to expose the seller's
+  internal audit log.
+
+agent:
+  interaction_model: stateful_push
+  capabilities:
+    - has_creative_library
+  examples:
+    - "Publishers and SSPs that run independent provenance review against buyer-declared disclosure claims"
+
+caller:
+  role: buyer_agent
+  example: "Pinnacle Agency (buyer)"
+
+prerequisites:
+  description: |
+    Seller publishes a product with creative_policy.accepted_verifiers
+    pointing at a governance agent that implements get_creative_features and
+    can emit audit_observations[] for oversight/disclosure carve-out claims.
+  test_kit: "test-kits/acme-outdoor.yaml"
+  controller_seeding: true
+
+fixtures:
+  products:
+    - product_id: "test-product-provenance-audit-observation"
+      name: "Provenance Audit Observation Test Product"
+      description: "Sandbox display inventory exercising audit-worthy but non-rejecting provenance carve-out claims"
+      delivery_type: "non_guaranteed"
+      channels: ["display"]
+      creative_policy:
+        co_branding: "optional"
+        landing_page: "any"
+        templates_available: false
+        provenance_required: true
+        accepted_verifiers:
+          - agent_url: "https://governance.encypher.seller.example"
+            feature_id: "ai_generated"
+            providers: ["Encypher"]
+      pricing_options:
+        - pricing_option_id: "test-pricing-cpm"
+          pricing_model: "cpm"
+          rate: 5.00
+          currency: "USD"
+
+phases:
+  - id: discover_verifier
+    title: "Discover the verifier allowlist"
+    narrative: |
+      The buyer reads creative_policy.accepted_verifiers from get_products
+      before submitting the creative, so it can reference an on-list verifier
+      in provenance metadata.
+
+    steps:
+      - id: get_products_with_accepted_verifiers
+        title: "Read accepted_verifiers from creative_policy"
+        task: get_products
+        schema_ref: "media-buy/get-products-request.json"
+        response_schema_ref: "media-buy/get-products-response.json"
+        doc_ref: "/media-buy/task-reference/get_products"
+        stateful: false
+        expected: |
+          Return the seeded product with creative_policy.accepted_verifiers
+          populated. Buyer reads the agent_url for use on its verify_agent
+          reference in the next phase.
+        sample_request:
+          buying_mode: "brief"
+          # Brief intentionally surfaces "Provenance Audit Observation" so
+          # brief-mode keyword scoring places the seeded fixture product at
+          # products[0]. This mirrors the provenance_enforcement coupling; if
+          # the runner supports JSONPath predicates later, switch to wholesale
+          # mode plus product_id predicate matching.
+          brief: "Provenance audit-observation display inventory — verifier surfaces carve-out claims for audit"
+          brand:
+            domain: "acmeoutdoor.example"
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          context:
+            correlation_id: "provenance_audit_observation--get_products"
+        validations:
+          - check: response_schema
+            description: "Response matches get-products-response.json schema"
+          - check: field_present
+            path: "products[0].creative_policy.accepted_verifiers[0].agent_url"
+            description: "Seller publishes at least one accepted verifier"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "provenance_audit_observation--get_products"
+            description: "Context correlation_id returned unchanged"
+
+  - id: accept_carveout_claim
+    title: "Sync creative with audit-worthy carve-out claim"
+    narrative: |
+      The buyer submits AI-assisted creative and declares disclosure.required:
+      false because a human directed or edited the creative process. The seller
+      invokes the on-list verifier. The verifier's audit observation should be
+      retained for review, but the seller should not reject the creative solely because
+      OVERSIGHT_DISCLOSURE_CARVEOUT_CLAIMED is present.
+
+    steps:
+      - id: sync_creatives_carveout_claim
+        title: "Submit creative that carries an audit-worthy carve-out claim"
+        task: sync_creatives
+        schema_ref: "creative/sync-creatives-request.json"
+        response_schema_ref: "creative/sync-creatives-response.json"
+        doc_ref: "/creative/task-reference/sync_creatives"
+        stateful: true
+        expected: |
+          The seller invokes get_creative_features against an on-list verifier,
+          receives the verifier's OVERSIGHT_DISCLOSURE_CARVEOUT_CLAIMED audit
+          observation, and accepts the creative. Per-creative result: action
+          created or updated; no PROVENANCE_CLAIM_CONTRADICTED error.
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          creatives:
+            - creative_id: "acme_provenance_audit_directed_001"
+              name: "Acme provenance audit observation probe — directed"
+              format_id:
+                agent_url: "https://your-platform.example.com"
+                id: "display_300x250"
+              assets:
+                headline:
+                  asset_type: "text"
+                  content: "Outdoor gear designed with expert guidance"
+                image:
+                  asset_type: "image"
+                  url: "https://test-assets.adcontextprotocol.org/acme-outdoor/ai-generated-true.jpg"
+                  width: 300
+                  height: 250
+                click_url:
+                  asset_type: "url"
+                  url: "https://acmeoutdoor.example/spring"
+              provenance:
+                digital_source_type: "composite_with_trained_algorithmic_media"
+                ai_tool:
+                  name: "Acme Creative Assist"
+                  provider: "Acme Outdoor"
+                human_oversight: "directed"
+                declared_by:
+                  role: "agency"
+                disclosure:
+                  required: false
+                embedded_provenance:
+                  - method: "provenance_markers"
+                    provider: "Encypher"
+                    verify_agent:
+                      agent_url: "https://governance.encypher.seller.example"
+                      feature_id: "ai_generated"
+            - creative_id: "acme_provenance_audit_edited_001"
+              name: "Acme provenance audit observation probe — edited"
+              format_id:
+                agent_url: "https://your-platform.example.com"
+                id: "display_300x250"
+              assets:
+                headline:
+                  asset_type: "text"
+                  content: "Outdoor gear refined with expert guidance"
+                image:
+                  asset_type: "image"
+                  url: "https://test-assets.adcontextprotocol.org/acme-outdoor/ai-generated-true.jpg"
+                  width: 300
+                  height: 250
+                click_url:
+                  asset_type: "url"
+                  url: "https://acmeoutdoor.example/spring"
+              provenance:
+                digital_source_type: "composite_with_trained_algorithmic_media"
+                ai_tool:
+                  name: "Acme Creative Assist"
+                  provider: "Acme Outdoor"
+                human_oversight: "edited"
+                declared_by:
+                  role: "agency"
+                disclosure:
+                  required: false
+                embedded_provenance:
+                  - method: "provenance_markers"
+                    provider: "Encypher"
+                    verify_agent:
+                      agent_url: "https://governance.encypher.seller.example"
+                      feature_id: "ai_generated"
+          idempotency_key: "$generate:uuid_v4#provenance_audit_observation_accept_carveout_sync"
+          context:
+            correlation_id: "provenance_audit_observation--accept_carveout"
+        validations:
+          - check: response_schema
+            description: "Response matches sync-creatives-response.json schema"
+          - check: field_value
+            path: "creatives[0].action"
+            allowed_values: ["created", "updated"]
+            description: "Directed per-creative action is created or updated because the audit observation is non-blocking"
+          - check: field_absent
+            path: "creatives[0].errors[0].code"
+            description: "Directed creative has no rejection code solely for the audit-worthy carve-out claim"
+          - check: field_value
+            path: "creatives[1].action"
+            allowed_values: ["created", "updated"]
+            description: "Edited per-creative action is created or updated because the audit observation is non-blocking"
+          - check: field_absent
+            path: "creatives[1].errors[0].code"
+            description: "Edited creative has no rejection code solely for the audit-worthy carve-out claim"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "provenance_audit_observation--accept_carveout"
+            description: "Context correlation_id returned unchanged"
+          - check: upstream_traffic
+            description: "Seller invoked an upstream verifier with the submitted directed carve-out claim"
+            min_count: 1
+            endpoint_pattern: "POST *"
+            payload_must_contain:
+              - path: "creative_manifest.provenance.human_oversight"
+                match: equals
+                value: "directed"
+              - path: "creative_manifest.provenance.disclosure.required"
+                match: equals
+                value: false
+          - check: upstream_traffic
+            description: "Seller invoked an upstream verifier with the submitted edited carve-out claim"
+            min_count: 1
+            endpoint_pattern: "POST *"
+            payload_must_contain:
+              - path: "creative_manifest.provenance.human_oversight"
+                match: equals
+                value: "edited"
+              - path: "creative_manifest.provenance.disclosure.required"
+                match: equals
+                value: false
+
+      - id: query_directed_audit_observation
+        title: "Assert directed carve-out audit observation"
+        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"
+        stateful: true
+        expected: |
+          The sandbox controller returns the audit observation recorded for the
+          accepted directed creative. Public seller responses are not required
+          to expose this internal audit log.
+        sample_request:
+          account:
+            sandbox: true
+          scenario: "query_provenance_audit_observations"
+          params:
+            creative_id: "acme_provenance_audit_directed_001"
+          context:
+            correlation_id: "provenance_audit_observation--query_directed"
+        validations:
+          - check: response_schema
+            description: "Response matches comply-test-controller-response.json schema"
+          - check: field_value
+            path: "success"
+            allowed_values: [true]
+            description: "Controller returned the creative's audit observations"
+          - check: field_value
+            path: "audit_observations[0].code"
+            value: "OVERSIGHT_DISCLOSURE_CARVEOUT_CLAIMED"
+            description: "Directed carve-out claim is surfaced as the standardized audit observation"
+          - check: field_value
+            path: "audit_observations[0].details.claimed_value.human_oversight"
+            value: "directed"
+            description: "Observation records the directed human_oversight claim"
+          - check: field_value
+            path: "audit_observations[0].details.claimed_value.disclosure_required"
+            value: false
+            description: "Observation records the disclosure.required false claim"
+
+      - id: query_edited_audit_observation
+        title: "Assert edited carve-out audit observation"
+        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"
+        stateful: true
+        expected: |
+          The sandbox controller returns the audit observation recorded for the
+          accepted edited creative, exercising the second documented
+          human_oversight value.
+        sample_request:
+          account:
+            sandbox: true
+          scenario: "query_provenance_audit_observations"
+          params:
+            creative_id: "acme_provenance_audit_edited_001"
+          context:
+            correlation_id: "provenance_audit_observation--query_edited"
+        validations:
+          - check: response_schema
+            description: "Response matches comply-test-controller-response.json schema"
+          - check: field_value
+            path: "success"
+            allowed_values: [true]
+            description: "Controller returned the creative's audit observations"
+          - check: field_value
+            path: "audit_observations[0].code"
+            value: "OVERSIGHT_DISCLOSURE_CARVEOUT_CLAIMED"
+            description: "Edited carve-out claim is surfaced as the standardized audit observation"
+          - check: field_value
+            path: "audit_observations[0].details.claimed_value.human_oversight"
+            value: "edited"
+            description: "Observation records the edited human_oversight claim"
+          - check: field_value
+            path: "audit_observations[0].details.claimed_value.disclosure_required"
+            value: false
+            description: "Observation records the disclosure.required false claim"