@adcp/sdk 7.11.0 → 7.11.1

package/compliance/cache/3.1.0-rc.2/specialisms/sales-social/index.yaml

@@ -0,0 +1,919 @@
+id: sales_social
+version: "1.0.0"
+title: "Social platform"
+protocol: media-buy
+category: sales_social
+summary: "Social media platform that accepts audience segments, native creatives, and conversion events from buyer agents."
+track: audiences
+required_tools:
+  - sync_governance
+  - sync_audiences
+  - sync_catalogs
+  - sync_creatives
+  - sync_event_sources
+  - preview_creative
+requires_scenarios:
+  - governance_aware_seller/governance_multi_agent_rejected
+
+# Cross-step assertion (adcp#2664). status.monotonic rejects resource
+# status transitions observed across steps that aren't on the spec
+# lifecycle graph — e.g. approved → processing on a creative asset or
+# active → pending_creatives on a media_buy.
+invariants:
+  - status.monotonic
+
+narrative: |
+  You run a social media platform — Snap, Meta, TikTok, Pinterest, or any walled garden that
+  sells advertising through audience-based targeting and native creative formats. A buyer agent
+  connects to set up an account, push audience segments, sync native creatives, track conversion
+  events, and monitor spend.
+
+  Unlike open-web media buys, social platforms require the buyer to push assets into the
+  platform's environment. Audiences are activated via sync_audiences, creatives are pushed via
+  sync_creatives in platform-native formats, and conversion events flow back via log_event.
+
+  This storyboard covers the social platform integration from the buyer's perspective:
+  account setup, audience activation, native creative push, event tracking, and financial
+  monitoring.
+
+context:
+  governance_agent_url: "https://test-agent.adcontextprotocol.org"
+
+agent:
+  interaction_model: media_buy_seller
+  capabilities:
+    - sells_media
+    - accepts_briefs
+    - supports_non_guaranteed
+  examples:
+    - "Snap"
+    - "Meta"
+    - "TikTok"
+    - "Pinterest"
+
+caller:
+  role: buyer_agent
+  example: "Scope3 (DSP)"
+
+prerequisites:
+  description: |
+    The caller needs a brand identity, operator credentials, audience segment definitions,
+    and native creative assets. The test kit provides a sample brand with creative assets
+    suitable for social formats.
+  test_kit: "test-kits/acme-outdoor.yaml"
+
+phases:
+  - id: capability_discovery
+    title: "Capability discovery"
+    narrative: |
+      The buyer calls get_adcp_capabilities to confirm the agent supports media buying before syncing audiences and native creatives.
+
+    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 media_buy in supported_protocols, confirming the agent sells media.
+        sample_request:
+          context:
+            correlation_id: "sales_social--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: "sales_social--get_capabilities"
+            description: "Context correlation_id returned unchanged"
+  - id: account_setup
+    title: "Account setup"
+    narrative: |
+      The buyer establishes an account with the social platform and verifies its status.
+      Social platforms often require advertiser verification before accepting ad spend.
+
+    steps:
+      - id: sync_accounts
+        title: "Register advertiser account"
+        narrative: |
+          The buyer registers their brand and operator with the social platform. The platform
+          provisions an advertiser account and returns its status. Social platforms may require
+          identity verification before the account goes active.
+        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 advertiser account with:
+          - account_id: platform's identifier
+          - status: active or pending_approval (if verification required)
+          - account_scope: how the platform scopes this relationship
+
+        sample_request:
+          accounts:
+            - brand:
+                domain: "acmeoutdoor.example"
+              operator: "pinnacle-agency.example"
+              billing: "operator"
+
+          idempotency_key: "$generate:uuid_v4#sales_social_account_setup_sync_accounts"
+          context:
+            correlation_id: "sales_social--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"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "sales_social--sync_accounts"
+            description: "Context correlation_id returned unchanged"
+      - id: list_accounts
+        title: "Verify account status"
+        narrative: |
+          The buyer checks which accounts exist on the platform and their current status.
+          This confirms the account is active and shows any pending setup requirements.
+        task: list_accounts
+        schema_ref: "account/list-accounts-request.json"
+        response_schema_ref: "account/list-accounts-response.json"
+        doc_ref: "/accounts/tasks/list_accounts"
+        stateful: true
+        # Explicit-mode social platforms (Snap, Meta, TikTok) pre-provision
+        # advertiser accounts out-of-band — `sync_accounts` is intentionally
+        # missing_tool, with `list_accounts` as the canonical alternative.
+        # Declaring the substitution here lets the runner waive the
+        # downstream missing_tool cascade when list_accounts passes.
+        # See adcontextprotocol/adcp#3734.
+        provides_state_for: sync_accounts
+        expected: |
+          Return accounts matching the query:
+          - accounts array with status, account_id, brand, operator
+          - Active accounts ready for ad operations
+          - Pending accounts with accounts[].setup.url populated if verification is needed
+
+        sample_request:
+          context:
+            correlation_id: "sales_social--list_accounts"
+        validations:
+          - check: response_schema
+            description: "Response matches list-accounts-response.json schema"
+          - check: field_present
+            path: "accounts"
+            description: "Response contains accounts array"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "sales_social--list_accounts"
+            description: "Context correlation_id returned unchanged"
+      - id: sync_governance
+        title: "Register governance agent"
+        narrative: |
+          The buyer registers the configured governance agent on the advertiser
+          account before pushing audiences, creatives, catalogs, or conversion
+          events that can affect spend.
+        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: |
+          Acknowledge governance registration for the account:
+          - status: synced
+          - governance_agents[0].url echoes the configured governance agent
+
+        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#sales_social_account_setup_sync_governance"
+          context:
+            correlation_id: "sales_social--sync_governance"
+        validations:
+          - check: response_schema
+            description: "Response matches sync-governance-response.json schema"
+          - check: field_value
+            path: "accounts[0].status"
+            value: "synced"
+            description: "Governance agent is registered on the advertiser account"
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "sales_social--sync_governance"
+            description: "Context correlation_id returned unchanged"
+  - id: audience_sync
+    title: "Audience activation"
+    narrative: |
+      The buyer pushes audience segments to the platform. Social platforms use these segments
+      for targeting — the buyer defines who to reach, and the platform matches against its
+      user base.
+
+    steps:
+      - id: sync_audiences
+        title: "Push audience segments"
+        narrative: |
+          The buyer syncs audience segment definitions to the platform. Each segment includes
+          targeting criteria that the platform evaluates against its user graph. The platform
+          returns match rates and segment status.
+        task: sync_audiences
+        schema_ref: "media-buy/sync-audiences-request.json"
+        response_schema_ref: "media-buy/sync-audiences-response.json"
+        doc_ref: "/media-buy/task-reference/sync_audiences"
+        comply_scenario: sync_audiences
+        stateful: true
+        expected: |
+          Accept and process audience segments:
+          - Per-segment status: active, processing, or rejected
+          - Match rate estimates where available
+          - Platform-assigned segment IDs
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          audiences:
+            - audience_id: "outdoor_enthusiasts_25_54"
+              name: "Outdoor enthusiasts 25-54"
+              description: "Adults 25-54 interested in hiking, camping, and outdoor gear"
+              # Realistic add[] payload forces adapters to call the upstream
+              # audience-upload endpoint rather than returning shape-valid
+              # responses from an empty-members branch. Hash values are
+              # fictional test vectors distinct from the audience_sync
+              # storyboard's fixtures to avoid cross-storyboard collision.
+              add:
+                - external_id: "acme-user-0001"
+                  hashed_email: "a000000000000000000000000000000000000000000000000000000000000001"
+                - external_id: "acme-user-0002"
+                  hashed_phone: "b000000000000000000000000000000000000000000000000000000000000002"
+
+          idempotency_key: "$generate:uuid_v4#sales_social_audience_sync_sync_audiences"
+          context:
+            correlation_id: "sales_social--sync_audiences"
+        validations:
+          - check: response_schema
+            description: "Response matches sync-audiences-response.json schema"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "sales_social--sync_audiences"
+            description: "Context correlation_id returned unchanged"
+          # Anti-façade: the adapter MUST forward the hashed identifiers to
+          # the upstream platform's audience-upload endpoint. Adopters who
+          # don't advertise query_upstream_traffic in list_scenarios grade
+          # this check not_applicable per the runner's forward-compat rule —
+          # opt-in by adopter capability.
+          - check: upstream_traffic
+            description: "sync_audiences caused upstream traffic carrying the supplied hashed identifiers"
+            min_count: 1
+            endpoint_pattern: "POST *"
+            identifier_paths:
+              - "audiences[*].add[*].hashed_email"
+              - "audiences[*].add[*].external_id"
+  - id: creative_push
+    title: "Native creative sync"
+    narrative: |
+      The buyer pushes native creative assets to the platform. Social platforms render ads
+      in their native format — the buyer provides assets (images, headlines, descriptions)
+      and the platform assembles them into the native ad unit.
+
+    steps:
+      - id: sync_creatives
+        title: "Push native creative assets"
+        narrative: |
+          The buyer syncs creative assets for native ad formats. The platform validates
+          each creative against its format requirements and returns per-creative status.
+        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"
+        comply_scenario: creative_sync
+        stateful: true
+        expected: |
+          Accept and validate native creatives:
+          - Per-creative action: created or updated
+          - Per-creative status: accepted, pending_review, or rejected
+          - Validation errors for rejected creatives
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          creatives:
+            - creative_id: "native_trail_pro"
+              name: "Trail Pro 3000 - Native"
+              format_id:
+                agent_url: "https://social-platform.example.com"
+                id: "native_feed"
+              assets:
+                image:
+                  asset_type: "image"
+                  url: "https://cdn.pinnacle-agency.example/trail-pro-native.png"
+                  width: 1200
+                  height: 628
+                  mime_type: "image/png"
+                headline:
+                  asset_type: "text"
+                  content: "Trail Pro 3000 — Built for the Summit"
+
+          idempotency_key: "$generate:uuid_v4#sales_social_creative_push_sync_creatives"
+          context:
+            correlation_id: "sales_social--sync_creatives"
+        validations:
+          - check: response_schema
+            description: "Response matches sync-creatives-response.json schema"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "sales_social--sync_creatives"
+            description: "Context correlation_id returned unchanged"
+  - id: catalog_driven_dynamic_ads
+    title: "Catalog-driven dynamic product ads"
+    narrative: |
+      Social platforms routinely ship dynamic product ads (Snap Dynamic Ads, Meta DPA,
+      TikTok Dynamic Showcase): the buyer pushes a product catalog and the platform
+      renders per-impression creative pulling product images, titles, and tracker URLs
+      from catalog items. The creative template references catalog-item macros
+      (`{SKU}`, `{GTIN}`) whose values resolve to the specific item shown at
+      impression time.
+
+      This phase exercises the catalog-acceptance leg of that flow: push a small inline
+      product catalog (with `content_id_type: "sku"` declared so macro resolution binds
+      to the right field), then push a DPA creative template using the AdCP-native
+      `product_carousel_3_to_10` format on `creative.adcontextprotocol.org`. Real
+      social-platform formats (Meta `native_carousel`, Snap dynamic ad set, TikTok
+      dynamic showcase) are platform-specific refinements tracked as follow-ups on
+      #2640; the AdCP-native format is the interop baseline.
+
+      Runtime substitution-safety — assertion that emitted tracker URLs percent-encode
+      catalog-item macro values per `docs/creative/universal-macros#substitution-safety-catalog-item-macros` —
+      runs in the separate `catalog_substitution_safety` phase below, gated on the
+      `substitution_observer_runner` test-kit contract.
+
+    steps:
+      - id: sync_product_catalog
+        title: "Push a product catalog"
+        narrative: |
+          The buyer pushes a small inline product catalog — the shape social platforms
+          accept for dynamic product ads. Your platform validates each item and
+          returns per-item approval status.
+        task: sync_catalogs
+        schema_ref: "media-buy/sync-catalogs-request.json"
+        response_schema_ref: "media-buy/sync-catalogs-response.json"
+        doc_ref: "/media-buy/task-reference/sync_catalogs"
+        stateful: true
+        expected: |
+          Return per-catalog results with catalog_id, action, item_count, and
+          items_approved counts.
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          catalogs:
+            - catalog_id: "acme_gear_spring_2026"
+              type: "product"
+              content_id_type: "sku"
+              name: "Acme Outdoor — Spring 2026 Gear"
+              items:
+                - item_id: "trail_pro_3000"
+                  title: "Trail Pro 3000 Backpack"
+                  description: "65L expedition pack with torso-length adjustment."
+                  url: "https://acmeoutdoor.example/gear/trail-pro-3000"
+                  image_url: "https://cdn.acmeoutdoor.example/gear/trail-pro-3000.jpg"
+                  price:
+                    amount: 289.00
+                    currency: "USD"
+                - item_id: "summit_tent_2p"
+                  title: "Summit 2P Ultralight Tent"
+                  description: "2-person four-season tent, 1.8kg packed."
+                  url: "https://acmeoutdoor.example/gear/summit-tent-2p"
+                  image_url: "https://cdn.acmeoutdoor.example/gear/summit-tent-2p.jpg"
+                  price:
+                    amount: 549.00
+                    currency: "USD"
+
+          idempotency_key: "$generate:uuid_v4#sales_social_catalog_driven_dynamic_ads_sync_product_catalog"
+          context:
+            correlation_id: "sales_social--sync_product_catalog"
+        validations:
+          - check: response_schema
+            description: "Response matches sync-catalogs-response.json schema"
+          - check: field_present
+            path: "catalogs[0].catalog_id"
+            description: "Catalog has an ID"
+          - check: field_present
+            path: "catalogs[0].item_count"
+            description: "Catalog reports item count"
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "sales_social--sync_product_catalog"
+            description: "Context correlation_id returned unchanged"
+
+      - id: sync_dpa_creative
+        title: "Push a dynamic product ad creative with catalog-item macros"
+        narrative: |
+          The buyer pushes a creative template whose tracker URLs reference
+          catalog-item macros (`{SKU}`, `{GTIN}`). At impression time, your platform
+          substitutes each catalog item's values into the template to render the
+          per-impression ad.
+
+          The template uses the AdCP-native `product_carousel_3_to_10` format
+          (see `docs/creative/channels/carousels.mdx`). Per #2620, values substituted
+          into URL contexts MUST be percent-encoded such that only RFC 3986 unreserved
+          characters remain unescaped; nested macro expansion is prohibited. This step
+          validates that the template is accepted into the library; runtime
+          substitution validation is tracked under #2638.
+        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"
+        comply_scenario: creative_sync
+        stateful: true
+        expected: |
+          Accept the DPA creative template. Per-creative action: created or updated.
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          creatives:
+            - creative_id: "acme_dpa_spring_2026"
+              name: "Acme Outdoor — Spring DPA template"
+              format_id:
+                agent_url: "https://creative.adcontextprotocol.org"
+                id: "product_carousel_3_to_10"
+              assets:
+                impression_pixel:
+                  asset_type: "url"
+                  url: "https://track.acmeoutdoor.example/imp?sku={SKU}&gtin={GTIN}&mb={MEDIA_BUY_ID}"
+                click_url:
+                  asset_type: "url"
+                  url: "https://track.acmeoutdoor.example/click?sku={SKU}"
+
+          idempotency_key: "$generate:uuid_v4#sales_social_catalog_driven_dynamic_ads_sync_dpa_creative"
+          context:
+            correlation_id: "sales_social--sync_dpa_creative"
+        validations:
+          - check: response_schema
+            description: "Response matches sync-creatives-response.json schema"
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "sales_social--sync_dpa_creative"
+            description: "Context correlation_id returned unchanged"
+  - id: catalog_substitution_safety
+    title: "Catalog-item macro substitution safety"
+    narrative: |
+      Per docs/creative/universal-macros#substitution-safety-catalog-item-macros,
+      sales agents MUST percent-encode catalog-item macro values such that only
+      RFC 3986 `unreserved` characters remain unescaped before substituting them
+      into a URL context. Nested macro expansion is prohibited.
+
+      This phase exercises the rule on the social-platform flow: push a probe
+      catalog whose items carry attacker-shaped `sku` values, push a DPA
+      creative template that binds to that catalog and references `{SKU}` in
+      its tracker URLs, then call `preview_creative` to render the bound
+      preview. The substitution-observer runner inspects `preview_html` from
+      the response and asserts each substituted `{SKU}` value is encoded per
+      the fixture at `static/test-vectors/catalog-macro-substitution.json`.
+
+      Scope note: this phase validates substitution on the PREVIEW surface
+      only. Social platforms with divergent preview vs impression-time
+      substitution paths MAY pass here while failing at serve time; serve-time
+      attestation is a known coverage limitation shared with creative-generative.
+      Real-impression observability for sales-social is deferred to a future
+      revision when platform attestation hooks become standardized.
+
+      The `expect_substitution_safe` step is gated on the
+      `substitution_observer_runner` test-kit contract (see
+      `test-kits/substitution-observer-runner.yaml`). Runners that do not
+      advertise the contract grade the step as `not_applicable` — the earlier
+      `sync_substitution_probe_catalog`, `sync_substitution_probe_creative`,
+      and `preview_substitution_probe_creative` steps still run (exercising
+      the catalog-acceptance, creative-push, and preview paths), but the
+      substituted-URL assertion is skipped.
+
+    steps:
+      - id: sync_substitution_probe_catalog
+        title: "Push a probe catalog with attacker-shaped values"
+        narrative: |
+          Push a small probe catalog whose `sku` fields contain five canonical
+          attacker-shaped values from the substitution-safety fixture. The
+          platform MUST accept the payload — the encoding rule applies at
+          substitution time, not at ingest — but the downstream `preview_creative`
+          output must percent-encode each value into tracker URLs.
+        task: sync_catalogs
+        schema_ref: "media-buy/sync-catalogs-request.json"
+        response_schema_ref: "media-buy/sync-catalogs-response.json"
+        doc_ref: "/media-buy/task-reference/sync_catalogs"
+        stateful: true
+        expected: |
+          Catalog accepted with per-item counts. Runner captures the
+          catalog_id + item_ids for the downstream assertion binding.
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          catalogs:
+            - catalog_id: "sales_social_substitution_probe_v1"
+              type: "product"
+              content_id_type: "sku"
+              name: "Substitution safety probe"
+              items:
+                - item_id: "reserved_char_breakout"
+                  sku: "00013&cmd=drop"
+                  title: "Reserved-char breakout probe"
+                  url: "https://acmeoutdoor.example/probe/reserved"
+                  image_url: "https://cdn.acmeoutdoor.example/probe/reserved.jpg"
+                  price: { amount: 1.00, currency: "USD" }
+                - item_id: "nested_expansion"
+                  sku: "vacancy-{DEVICE_ID}-42"
+                  title: "Nested-expansion probe"
+                  url: "https://acmeoutdoor.example/probe/nested"
+                  image_url: "https://cdn.acmeoutdoor.example/probe/nested.jpg"
+                  price: { amount: 1.00, currency: "USD" }
+                - item_id: "non_ascii"
+                  sku: "café-amsterdam"
+                  title: "Non-ASCII UTF-8 probe"
+                  url: "https://acmeoutdoor.example/probe/non-ascii"
+                  image_url: "https://cdn.acmeoutdoor.example/probe/non-ascii.jpg"
+                  price: { amount: 1.00, currency: "USD" }
+                - item_id: "crlf_injection"
+                  sku: "abc\r\nHost: evil.example"
+                  title: "CRLF injection probe"
+                  url: "https://acmeoutdoor.example/probe/crlf"
+                  image_url: "https://cdn.acmeoutdoor.example/probe/crlf.jpg"
+                  price: { amount: 1.00, currency: "USD" }
+                - item_id: "bidi_override"
+                  sku: "VIN-‮1234"
+                  title: "Bidi-override probe"
+                  url: "https://acmeoutdoor.example/probe/bidi"
+                  image_url: "https://cdn.acmeoutdoor.example/probe/bidi.jpg"
+                  price: { amount: 1.00, currency: "USD" }
+
+          idempotency_key: "$generate:uuid_v4#sales_social_catalog_substitution_safety_sync_substitution_probe_catalog"
+          context:
+            correlation_id: "sales_social--sync_substitution_probe_catalog"
+        validations:
+          - check: response_schema
+            description: "Response matches sync-catalogs-response.json schema"
+          - check: field_present
+            path: "catalogs[0].catalog_id"
+            description: "Probe catalog accepted"
+
+      - id: sync_substitution_probe_creative
+        title: "Push a DPA creative bound to the probe catalog"
+        narrative: |
+          Push a DPA creative template whose `product_catalog` asset binds to
+          the probe catalog from the previous step. Tracker URLs reference
+          `{SKU}` so the platform's substitution path resolves attacker-shaped
+          values into URL contexts at preview time.
+        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"
+        comply_scenario: creative_sync
+        stateful: true
+        expected: |
+          DPA creative template accepted. Per-creative action: created or updated.
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          creatives:
+            - creative_id: "sales_social_substitution_probe_creative_v1"
+              name: "Substitution safety probe DPA"
+              format_id:
+                agent_url: "https://creative.adcontextprotocol.org"
+                id: "product_carousel_3_to_10"
+              assets:
+                product_catalog:
+                  asset_type: "catalog"
+                  type: "product"
+                  catalog_id: "sales_social_substitution_probe_v1"
+                impression_pixel:
+                  asset_type: "url"
+                  url: "https://track.acmeoutdoor.example/imp?sku={SKU}"
+                click_url:
+                  asset_type: "url"
+                  url: "https://track.acmeoutdoor.example/click?sku={SKU}"
+
+          idempotency_key: "$generate:uuid_v4#sales_social_catalog_substitution_safety_sync_substitution_probe_creative"
+          context:
+            correlation_id: "sales_social--sync_substitution_probe_creative"
+        validations:
+          - check: response_schema
+            description: "Response matches sync-creatives-response.json schema"
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+
+      - id: preview_substitution_probe_creative
+        title: "Render a preview against the probe catalog"
+        narrative: |
+          Call `preview_creative` against the probe creative. The platform
+          renders the DPA template by binding `{SKU}` against the probe
+          catalog's items, returning `preview_html` whose tracker URLs carry
+          substituted SKU values. The substitution-observer runner uses this
+          response as its observation source in the next step.
+
+          `format: html` is requested so the response surfaces `preview_html`
+          directly; `item_limit: 5` ensures every probe catalog item is
+          rendered at least once so the observer can match every binding.
+        task: preview_creative
+        schema_ref: "creative/preview-creative-request.json"
+        response_schema_ref: "creative/preview-creative-response.json"
+        doc_ref: "/creative/task-reference/preview_creative"
+        stateful: true
+        expected: |
+          Preview returned with at least one render carrying preview_html
+          containing the substituted tracker URLs.
+
+        sample_request:
+          request_type: "single"
+          format: "html"
+          item_limit: 5
+          creative_manifest:
+            format_id:
+              agent_url: "https://creative.adcontextprotocol.org"
+              id: "product_carousel_3_to_10"
+            assets:
+              product_catalog:
+                asset_type: "catalog"
+                type: "product"
+                catalog_id: "sales_social_substitution_probe_v1"
+              impression_pixel:
+                asset_type: "url"
+                url: "https://track.acmeoutdoor.example/imp?sku={SKU}"
+              click_url:
+                asset_type: "url"
+                url: "https://track.acmeoutdoor.example/click?sku={SKU}"
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+
+          idempotency_key: "$generate:uuid_v4#sales_social_catalog_substitution_safety_preview_substitution_probe_creative"
+          context:
+            correlation_id: "sales_social--preview_substitution_probe_creative"
+        validations:
+          - check: response_schema
+            description: "Response matches preview-creative-response.json schema"
+          - check: field_present
+            path: "previews[0].renders[0].preview_html"
+            description: "Preview render carries preview_html"
+
+      - id: expect_substitution_safe
+        title: "Assert substituted tracker URLs percent-encode attacker shapes"
+        narrative: |
+          The runner inspects the `preview_html` from the previous step,
+          extracts tracker URLs that bind `{SKU}` to a probe catalog item,
+          and asserts each value is percent-encoded per RFC 3986
+          (unreserved-whitelist). Raw-byte leakage fails. Every declared
+          binding MUST be observed — a platform that silently strips `{SKU}`
+          rather than substituting it fails with `substitution_binding_missing`.
+        task: expect_substitution_safe
+        requires_contract: substitution_observer_runner
+        source: html_inline
+        source_path: "/previews/0/renders/0/preview_html"
+        macro_template: "https://track.acmeoutdoor.example/imp?sku={SKU}"
+        require_every_binding_observed: true
+        catalog_bindings:
+          - macro: "{SKU}"
+            catalog_item_id: "reserved_char_breakout"
+            vector_name: "reserved-character-breakout"
+          - macro: "{SKU}"
+            catalog_item_id: "nested_expansion"
+            vector_name: "nested-expansion-preserved-as-literal"
+          - macro: "{SKU}"
+            catalog_item_id: "non_ascii"
+            vector_name: "non-ascii-utf8-percent-encoding"
+          - macro: "{SKU}"
+            catalog_item_id: "crlf_injection"
+            vector_name: "crlf-injection-neutralized"
+          - macro: "{SKU}"
+            catalog_item_id: "bidi_override"
+            vector_name: "bidi-override-neutralized"
+  - id: event_setup
+    title: "Event source setup"
+    narrative: |
+      Before sending conversion events, the buyer registers the event sources the platform
+      should expect events from — a website pixel, a mobile SDK, or a server-to-server feed.
+      The platform returns setup instructions and binds the event_source_id that later
+      log_event calls will reference.
+
+    steps:
+      - id: sync_event_sources
+        title: "Register conversion event sources"
+        narrative: |
+          The buyer tells the platform where conversion events will come from. The
+          platform records each event_source_id, returns integration code, and will
+          accept log_event calls that reference it.
+        task: sync_event_sources
+        schema_ref: "media-buy/sync-event-sources-request.json"
+        response_schema_ref: "media-buy/sync-event-sources-response.json"
+        doc_ref: "/media-buy/task-reference/sync_event_sources"
+        stateful: true
+        expected: |
+          Return event sources with:
+          - event_source_id and seller_id
+          - setup.snippet: integration code (JavaScript pixel, HTML tag, or pixel URL)
+          - setup.instructions: human-readable integration guide
+          - action: created or updated
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          event_sources:
+            - event_source_id: "acmeoutdoor_website"
+              name: "Acme Outdoor Website"
+              event_types: ["purchase", "add_to_cart", "page_view", "lead"]
+              allowed_domains: ["acmeoutdoor.example"]
+
+          idempotency_key: "$generate:uuid_v4#sales_social_event_setup_sync_event_sources"
+          context:
+            correlation_id: "sales_social--sync_event_sources"
+        validations:
+          - check: response_schema
+            description: "Response matches sync-event-sources-response.json schema"
+          - check: field_present
+            path: "event_sources[0].setup.snippet"
+            description: "Event source includes setup snippet"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "sales_social--sync_event_sources"
+            description: "Context correlation_id returned unchanged"
+  - id: event_logging
+    title: "Conversion event tracking"
+    narrative: |
+      The buyer sends conversion events back to the platform for measurement and optimization.
+      Events include purchases, signups, and other post-click actions that the platform uses
+      to optimize delivery and report on campaign performance.
+
+    steps:
+      - id: log_event
+        title: "Send conversion events"
+        narrative: |
+          The buyer logs conversion events that occurred after ad exposure. The platform
+          records these events for attribution, reporting, and delivery optimization.
+        task: log_event
+        schema_ref: "media-buy/log-event-request.json"
+        response_schema_ref: "media-buy/log-event-response.json"
+        doc_ref: "/media-buy/task-reference/log_event"
+        stateful: true
+        expected: |
+          Acknowledge the events:
+          - Per-event status: accepted or rejected
+          - Event IDs for deduplication
+          - Attribution window validation
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          event_source_id: "acmeoutdoor_website"
+          events:
+            - event_type: "purchase"
+              event_id: "evt_trail_pro_001"
+              event_time: "2026-04-05T14:30:00Z"
+              # user_match prevents adapters from injecting synthetic placeholder
+              # identifiers to satisfy the upstream's required-field check.
+              # The hashed_email here matches the sync_audiences add[]
+              # member so an upstream_traffic identifier echo can confirm
+              # values were forwarded, not constants.
+              user_match:
+                hashed_email: "a000000000000000000000000000000000000000000000000000000000000001"
+              # value/currency belong inside custom_data per event-custom-data.json;
+              # additionalProperties: true on the parent silently swallowed them
+              # at the wrong nesting level, meaning real upstreams never saw
+              # the purchase value.
+              custom_data:
+                value: 149.99
+                currency: "USD"
+
+          idempotency_key: "$generate:uuid_v4#sales_social_event_logging_log_event"
+          context:
+            correlation_id: "sales_social--log_event"
+        validations:
+          - check: response_schema
+            description: "Response matches log-event-response.json schema"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "sales_social--log_event"
+            description: "Context correlation_id returned unchanged"
+          # Anti-façade: the adapter MUST forward the conversion event to the
+          # upstream platform's event-tracking endpoint, carrying the supplied
+          # user_match identifier. A façade that injects a constant placeholder
+          # hash to satisfy the upstream's required-field check fails the
+          # identifier_paths echo — the constant won't match the storyboard's
+          # supplied value.
+          - check: upstream_traffic
+            description: "log_event caused upstream traffic carrying the supplied user_match identifier"
+            min_count: 1
+            endpoint_pattern: "POST *"
+            identifier_paths:
+              - "events[*].user_match.hashed_email"
+  - id: financials
+    title: "Account financials"
+    narrative: |
+      The buyer checks account financials — spending, balance, and payment status. This is
+      essential for budget monitoring across multiple social platforms.
+
+    steps:
+      - id: get_account_financials
+        title: "Check account spending and balance"
+        narrative: |
+          The buyer retrieves financial information for the advertiser account. The platform
+          returns current spend, remaining balance, and payment status.
+        task: get_account_financials
+        schema_ref: "account/get-account-financials-request.json"
+        response_schema_ref: "account/get-account-financials-response.json"
+        doc_ref: "/accounts/tasks/get_account_financials"
+        stateful: true
+        expected: |
+          Return account financial data:
+          - Current spend to date
+          - Remaining balance or credit
+          - Payment status and terms
+          - Budget utilization metrics
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+
+          context:
+            correlation_id: "sales_social--get_account_financials"
+        validations:
+          - check: response_schema
+            description: "Response matches get-account-financials-response.json schema"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "sales_social--get_account_financials"
+            description: "Context correlation_id returned unchanged"