@adcp/sdk 7.11.0 → 7.11.1

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

@@ -0,0 +1,840 @@
+id: sales_catalog_driven
+version: "1.0.0"
+title: "Catalog-driven creative and conversion tracking"
+protocol: media-buy
+category: sales_catalog_driven
+summary: "Seller that renders dynamic ads from product catalogs, tracks conversions, and optimizes delivery based on performance feedback."
+track: media_buy
+required_tools:
+  - sync_governance
+  - get_products
+  - create_media_buy
+requires_scenarios:
+  - media_buy_seller/refine_products
+  - media_buy_seller/delivery_reporting
+  - media_buy_seller/pending_creatives_to_start
+  - media_buy_seller/invalid_transitions
+  - 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. active → pending_creatives on a media_buy or
+# approved → pending on a catalog_item.
+#
+# Cross-resource assertion (adcp#2859). impairment.coherence verifies that
+# catalog_item.withdrawn transitions propagate to any non-terminal media buy
+# that references the item: the buy's impairments[] MUST list an entry for
+# the withdrawn catalog item, and the buy's health MUST be `impaired`.
+# Inverse direction is also enforced — a buy reporting an impairment whose
+# referenced catalog_item is no longer offline fails the check. Out of
+# scope: terminal-status buys MAY remain unreported; materiality
+# (package_ids minItems:1) is enforced at the schema layer (#2855), not
+# here. Grades not_applicable until the storyboard exercises both a
+# catalog-item transition AND a media-buy snapshot read (#2860).
+invariants:
+  - status.monotonic
+  - impairment.coherence
+
+narrative: |
+  You run a platform that supports catalog-driven advertising — think Snap Dynamic Ads,
+  Meta Product Catalogs, or retail media product listing ads. The buyer pushes a product
+  catalog (menu items, retail products, hotel listings), and your platform renders ads
+  dynamically from that feed. When a user converts, events are logged back and attributed
+  to catalog items, closing the optimization loop.
+
+  This storyboard walks through the full catalog-to-conversion flow: account setup,
+  catalog sync, creative formats for catalog items, media buy with catalog packages,
+  event source configuration, conversion logging, and performance feedback.
+
+  The key difference from the standard media buy flow is that creatives are catalog-driven —
+  the buyer doesn't build individual ads. They push a feed, and your platform renders
+  the right item to the right user at the right time.
+
+context:
+  governance_agent_url: "https://test-agent.adcontextprotocol.org"
+
+agent:
+  interaction_model: media_buy_seller
+  capabilities:
+    - sells_media
+    - accepts_catalogs
+    - supports_conversion_tracking
+    - catalog_driven_creative
+  examples:
+    - "Snap (Dynamic Ads)"
+    - "Retail media networks"
+    - "Travel platforms"
+    - "Local commerce platforms"
+
+caller:
+  role: buyer_agent
+  example: "Scope3 (DSP)"
+
+prerequisites:
+  description: |
+    The caller needs a product catalog (feed URL or inline items) and an event source
+    for conversion tracking. The test kit provides a sample brand with catalog-compatible
+    assets.
+  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 sending briefs or creating buys.
+
+    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_catalog_driven--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_catalog_driven--get_capabilities"
+            description: "Context correlation_id returned unchanged"
+  - id: account_setup
+    title: "Account setup"
+    narrative: |
+      The buyer establishes an account relationship with your platform. For catalog-driven
+      campaigns, the account must be active before any catalog sync can happen.
+
+    steps:
+      - id: sync_accounts
+        title: "Establish account"
+        narrative: |
+          The buyer registers their brand and operator. Sandbox accounts are provisioned
+          instantly for testing catalog flows.
+        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, status (active for sandbox), and billing terms.
+
+        sample_request:
+          accounts:
+            - brand:
+                domain: "amsterdam-steakhouse.example"
+              operator: "pinnacle-agency.example"
+              billing: "operator"
+              sandbox: true
+
+          idempotency_key: "$generate:uuid_v4#sales_catalog_driven_account_setup_sync_accounts"
+          context:
+            correlation_id: "sales_catalog_driven--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_catalog_driven--sync_accounts"
+            description: "Context correlation_id returned unchanged"
+      - id: sync_governance
+        title: "Register governance agent"
+        narrative: |
+          The buyer registers the configured governance agent on the account before
+          catalog sync and catalog-driven media-buy creation.
+        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: "amsterdam-steakhouse.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_catalog_driven_account_setup_sync_governance"
+          context:
+            correlation_id: "sales_catalog_driven--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 account"
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "sales_catalog_driven--sync_governance"
+            description: "Context correlation_id returned unchanged"
+  - id: catalog_sync
+    title: "Product catalog sync"
+    narrative: |
+      The buyer pushes their product catalog to your platform. This is the foundation of
+      catalog-driven advertising — every ad your platform renders comes from this feed.
+
+      For a restaurant, this is the menu. For retail, it is the product feed. For travel,
+      it is hotel or flight listings. Your platform validates each item against your
+      format requirements (image dimensions, required fields, pricing format) and returns
+      per-item approval status.
+
+      Large feeds may go async — the buyer gets back a submitted status and waits for
+      your platform to finish processing. Small feeds (inline items) are processed
+      synchronously.
+
+    steps:
+      - id: discover_catalog_formats
+        title: "Check catalog format requirements"
+        narrative: |
+          Before pushing catalog items, the buyer checks what creative formats your
+          platform supports for catalog-driven ads. This tells the buyer what image
+          dimensions, text lengths, and required fields each catalog item needs.
+        task: list_creative_formats
+        schema_ref: "creative/list-creative-formats-request.json"
+        response_schema_ref: "creative/list-creative-formats-response.json"
+        doc_ref: "/creative/task-reference/list_creative_formats"
+        comply_scenario: creative_lifecycle
+        stateful: false
+        expected: |
+          Return creative formats that accept catalog assets. Look for formats with
+          catalog-specific asset slots (product_image, product_title, price, description).
+
+        sample_request:
+          channels: ["display", "native"]
+
+          context:
+            correlation_id: "sales_catalog_driven--discover_catalog_formats"
+        validations:
+          - check: response_schema
+            description: "Response matches list-creative-formats-response.json schema"
+          - check: field_present
+            path: "formats"
+            description: "Response contains formats array"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "sales_catalog_driven--discover_catalog_formats"
+            description: "Context correlation_id returned unchanged"
+          - check: field_present
+            path: "formats[0].format_id.agent_url"
+            description: "Format IDs include agent_url"
+          - check: field_present
+            path: "formats[0].format_id.id"
+            description: "Format IDs include id — must match those in get_products"
+      - id: sync_catalogs
+        title: "Push product catalog"
+        narrative: |
+          The buyer pushes their product feed. This can be a URL to an existing feed
+          (your platform fetches and re-fetches on a schedule) or inline items for
+          small catalogs.
+
+          Your platform validates each item: images meet minimum dimensions, required
+          fields are present, prices are formatted correctly. Items that fail validation
+          are rejected with specific reasons. Items that pass are approved and available
+          for dynamic creative rendering.
+        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 and action (created/updated)
+          - item_count, items_approved, items_pending, items_rejected
+          - item_issues for rejected items with specific reasons
+          - next_fetch_at for URL-based feeds
+
+        sample_request:
+          account:
+            brand:
+              domain: "amsterdam-steakhouse.example"
+            operator: "pinnacle-agency.example"
+          catalogs:
+            - catalog_id: "menu_spring_2026"
+              type: "product"
+              name: "Spring 2026 Menu"
+              items:
+                - item_id: "ribeye_36oz"
+                  title: "36oz Tomahawk Ribeye"
+                  description: "Dry-aged 45 days, served with truffle butter and roasted bone marrow"
+                  url: "https://amsterdam-steakhouse.example/menu/ribeye-36oz"
+                  image_url: "https://cdn.amsterdam-steakhouse.example/menu/ribeye-36oz-hero.jpg"
+                  price:
+                    amount: 89.00
+                    currency: "USD"
+                - item_id: "seafood_tower"
+                  title: "Grand Seafood Tower"
+                  description: "Oysters, king crab, lobster tail, shrimp cocktail, tuna tartare"
+                  url: "https://amsterdam-steakhouse.example/menu/seafood-tower"
+                  image_url: "https://cdn.amsterdam-steakhouse.example/menu/seafood-tower-hero.jpg"
+                  price:
+                    amount: 145.00
+                    currency: "USD"
+                - item_id: "wagyu_flight"
+                  title: "A5 Wagyu Tasting Flight"
+                  description: "Three cuts of Japanese A5 Wagyu — striploin, ribeye cap, tenderloin"
+                  url: "https://amsterdam-steakhouse.example/menu/wagyu-flight"
+                  image_url: "https://cdn.amsterdam-steakhouse.example/menu/wagyu-flight-hero.jpg"
+                  price:
+                    amount: 195.00
+                    currency: "USD"
+
+          idempotency_key: "$generate:uuid_v4#sales_catalog_driven_catalog_sync_sync_catalogs"
+          context:
+            correlation_id: "sales_catalog_driven--sync_catalogs"
+        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: "catalogs[0].items_approved"
+            description: "Catalog reports approved item count"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "sales_catalog_driven--sync_catalogs"
+            description: "Context correlation_id returned unchanged"
+  - id: 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 with three attacker-shaped catalog values
+      drawn from the unit-test fixture at `static/test-vectors/catalog-macro-substitution.json`:
+      reserved-char breakout, nested-expansion preservation, and non-ASCII
+      UTF-8. The remaining canonical vectors (CRLF injection, bidi-override,
+      mixed path/query, url-scheme injection) are exercised at the unit-test
+      layer and, where a specialism's template shape supports them, in
+      specialism-specific substitution-safety phases (see
+      `creative-generative/index.yaml` for CRLF + bidi coverage).
+
+      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_attacker_shaped_catalog` and `build_catalog_aware_creative` steps
+      still run (they exercise the catalog-acceptance and build paths), but
+      the substituted-URL assertion is skipped.
+
+    steps:
+      - id: sync_attacker_shaped_catalog
+        title: "Push a catalog with attacker-shaped values"
+        narrative: |
+          Push a small catalog whose fields contain the six canonical
+          attacker-shaped values from the substitution-safety fixture. The
+          seller MUST accept the payload at sync_catalogs (the rule applies at
+          substitution time, not at ingest — the seller is free to pass values
+          through, then encode them at serve time).
+        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 item_ids
+          for downstream assertion binding.
+
+        sample_request:
+          account:
+            brand:
+              domain: "amsterdam-steakhouse.example"
+            operator: "pinnacle-agency.example"
+          catalogs:
+            - catalog_id: "substitution_safety_probe_v1"
+              type: "product"
+              content_id_type: "sku"
+              name: "Substitution safety probe"
+              items:
+                # item_id is the vector name; the `sku` field carries the
+                # attacker-shaped value that substitution must encode.
+                - item_id: "reserved_char_breakout"
+                  sku: "00013&cmd=drop"
+                  title: "Reserved-char breakout probe"
+                  url: "https://amsterdam-steakhouse.example/probe/reserved"
+                  image_url: "https://cdn.amsterdam-steakhouse.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://amsterdam-steakhouse.example/probe/nested"
+                  image_url: "https://cdn.amsterdam-steakhouse.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://amsterdam-steakhouse.example/probe/non-ascii"
+                  image_url: "https://cdn.amsterdam-steakhouse.example/probe/non-ascii.jpg"
+                  price: { amount: 1.00, currency: "USD" }
+
+          idempotency_key: "$generate:uuid_v4#sales_catalog_driven_substitution_safety_sync_attacker_shaped_catalog"
+          context:
+            correlation_id: "sales_catalog_driven--sync_attacker_shaped_catalog"
+        validations:
+          - check: response_schema
+            description: "Response matches sync-catalogs-response.json schema"
+          - check: field_present
+            path: "catalogs[0].catalog_id"
+            description: "Catalog accepted"
+
+      - id: build_catalog_aware_creative
+        title: "Build a creative with catalog-item macros in tracker URLs"
+        narrative: |
+          Build a creative whose impression and click trackers include
+          catalog-item macros bound to the `sku` field of the attacker-shaped
+          catalog items above. Request `include_preview: true` so the
+          substitution-observer runner has a preview surface to inspect.
+        task: build_creative
+        schema_ref: "media-buy/build-creative-request.json"
+        response_schema_ref: "media-buy/build-creative-response.json"
+        doc_ref: "/creative/task-reference/build_creative"
+        comply_scenario: creative_flow
+        stateful: true
+        expected: |
+          Creative manifest returned with preview_html or preview_url populated.
+
+        sample_request:
+          message: "Build a catalog-driven display ad for the substitution_safety_probe_v1 catalog. Use {SKU} in impression and click tracker URLs."
+          target_format_id:
+            agent_url: "https://your-agent.example.com"
+            id: "display_300x250_catalog"
+          account:
+            brand:
+              domain: "amsterdam-steakhouse.example"
+            operator: "pinnacle-agency.example"
+          quality: "draft"
+          include_preview: true
+
+          idempotency_key: "$generate:uuid_v4#sales_catalog_driven_substitution_safety_build_catalog_aware_creative"
+          context:
+            correlation_id: "sales_catalog_driven--build_catalog_aware_creative"
+        validations:
+          - check: response_schema
+            description: "Response matches build-creative-response.json schema"
+          - check: field_present
+            path: "creative_manifest.format_id"
+            description: "Creative manifest returned"
+
+      - id: expect_substitution_safe
+        title: "Assert substituted tracker URLs percent-encode attacker shapes"
+        narrative: |
+          The runner inspects the preview artifact from the previous step,
+          extracts tracker URLs that bind `{SKU}` to a catalog item from the
+          attacker-shaped catalog, and asserts each value is percent-encoded
+          per RFC 3986 (unreserved-whitelist). Raw-byte leakage fails. Every
+          declared binding MUST be observed — a seller 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: "/creative_manifest/preview_html"
+        macro_template: "https://track.example/imp?sku={SKU}"
+        require_every_binding_observed: true
+        catalog_bindings:
+          # Each binding: `catalog_item_id` is the item_id in the synced
+          # catalog; `vector_name` is the fixture entry whose raw_value and
+          # expected_encoded the runner loads from
+          # static/test-vectors/catalog-macro-substitution.json.
+          - 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"
+  - id: create_buy
+    title: "Create catalog-driven media buy"
+    narrative: |
+      The buyer creates a media buy with catalog-driven packages. Instead of assigning
+      individual creatives, the buyer references the synced catalog. Your platform
+      renders the right catalog items dynamically based on user context, intent signals,
+      and inventory availability.
+
+      The key schema difference: packages include a catalogs[] array instead of (or
+      alongside) creative_assignments[].
+
+    steps:
+      - id: get_products
+        title: "Discover catalog-compatible products"
+        narrative: |
+          The buyer finds products that support catalog-driven delivery. These products
+          accept catalog references and render dynamic ads from the feed.
+        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
+        stateful: false
+        expected: |
+          Return products that support catalog-driven creative. Products should indicate
+          catalog compatibility in their format requirements.
+
+        sample_request:
+          buying_mode: "brief"
+          brief: "Dynamic product ads for a high-end steakhouse. Geo-targeted to 10 miles around Amsterdam location. Drive reservations and foot traffic."
+          account:
+            brand:
+              domain: "amsterdam-steakhouse.example"
+            operator: "pinnacle-agency.example"
+
+          context:
+            correlation_id: "sales_catalog_driven--get_products"
+        validations:
+          - check: response_schema
+            description: "Response matches get-products-response.json schema"
+          - check: field_present
+            path: "products"
+            description: "Response contains products"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "sales_catalog_driven--get_products"
+            description: "Context correlation_id returned unchanged"
+          - check: field_present
+            path: "products[0].format_ids"
+            description: "Products include format_ids for creative requirements"
+          - check: field_present
+            path: "products[0].format_ids[0].agent_url"
+            description: "Format IDs include agent_url — must match this agent's URL"
+          - check: field_present
+            path: "products[0].format_ids[0].id"
+            description: "Format IDs include id — must be accepted back in sync_creatives"
+      - id: create_media_buy
+        title: "Create media buy with catalog packages"
+        narrative: |
+          The buyer creates the media buy with packages that reference the synced catalog.
+          Each package has a catalogs[] array specifying which catalog feeds drive the
+          dynamic creative for that line item.
+
+          Your platform optimizes across catalog items within each package's budget
+          envelope — showing the ribeye to steak lovers and the seafood tower to
+          seafood enthusiasts.
+        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
+        stateful: true
+        expected: |
+          Create the media buy with catalog-driven packages. Return:
+          - media_buy_id
+          - status: active
+          - packages with catalog references preserved
+
+        sample_request:
+          brand:
+            domain: "amsterdam-steakhouse.example"
+          account:
+            brand:
+              domain: "amsterdam-steakhouse.example"
+            operator: "pinnacle-agency.example"
+          start_time: "2026-04-07T00:00:00Z"
+          end_time: "2026-06-30T23:59:59Z"
+          packages:
+            - product_id: "local_display_dynamic"
+              pricing_option_id: "cpm_standard"
+              budget: 5000
+              catalogs:
+                - catalog_id: "menu_spring_2026"
+                  type: "product"
+
+          idempotency_key: "$generate:uuid_v4#sales_catalog_driven_create_buy_create_media_buy"
+          context:
+            correlation_id: "sales_catalog_driven--create_media_buy"
+        context_outputs:
+          - name: media_buy_id
+            path: "media_buy_id"
+        validations:
+          - check: response_schema
+            description: "Response matches create-media-buy-response.json schema"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "sales_catalog_driven--create_media_buy"
+            description: "Context correlation_id returned unchanged"
+  - id: event_setup
+    title: "Conversion tracking setup"
+    narrative: |
+      The buyer configures event sources so your platform can attribute conversions to
+      catalog items. For a restaurant, the events are reservations and walk-ins. For
+      retail, they are purchases and add-to-carts.
+
+      Your platform returns setup snippets (pixel code, SDK instructions) that the
+      buyer installs on their conversion surfaces.
+
+    steps:
+      - id: sync_event_sources
+        title: "Configure event sources"
+        narrative: |
+          The buyer tells your platform where conversion events will come from —
+          a website pixel, a mobile SDK, or a server-to-server integration. Your
+          platform returns the integration code.
+        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: "amsterdam-steakhouse.example"
+            operator: "pinnacle-agency.example"
+          event_sources:
+            - event_source_id: "amsterdam_website"
+              name: "Amsterdam Steakhouse Website"
+              event_types: ["purchase", "add_to_cart", "page_view", "lead"]
+              allowed_domains: ["amsterdam-steakhouse.example", "book.amsterdam-steakhouse.example"]
+
+          idempotency_key: "$generate:uuid_v4#sales_catalog_driven_event_setup_sync_event_sources"
+          context:
+            correlation_id: "sales_catalog_driven--sync_event_sources"
+          ext:
+            test_platform:
+              test_run: true
+        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_catalog_driven--sync_event_sources"
+            description: "Context correlation_id returned unchanged"
+  - id: conversion_tracking
+    title: "Log conversions"
+    narrative: |
+      The campaign is running and customers are converting. The buyer logs conversion
+      events back to your platform, attributing them to catalog items via content_ids.
+
+      When someone books a reservation after seeing the ribeye ad, the event includes
+      content_ids: ["ribeye_36oz"] — linking the conversion to the catalog item that
+      drove it. Your platform uses this signal to optimize which items to show.
+
+    steps:
+      - id: log_events
+        title: "Send conversion events"
+        narrative: |
+          The buyer sends a batch of conversion events. Each event includes the event
+          type, value, and content_ids linking to catalog items. Your platform processes
+          these for attribution and 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: |
+          Process the events and return:
+          - events_received and events_processed counts
+          - partial_failures for events that failed validation
+          - match_quality: how well events matched to ad exposures (0.0-1.0)
+
+        sample_request:
+          account:
+            brand:
+              domain: "amsterdam-steakhouse.example"
+            operator: "pinnacle-agency.example"
+          event_source_id: "amsterdam_website"
+          events:
+            - event_id: "evt_001"
+              event_type: "purchase"
+              event_time: "2026-04-15T19:30:00Z"
+              content_ids: ["ribeye_36oz"]
+              value: 89.00
+              currency: "USD"
+            - event_id: "evt_002"
+              event_type: "lead"
+              event_time: "2026-04-15T20:15:00Z"
+              content_ids: ["wagyu_flight"]
+              value: 195.00
+              currency: "USD"
+            - event_id: "evt_003"
+              event_type: "page_view"
+              event_time: "2026-04-15T20:45:00Z"
+              content_ids: ["seafood_tower"]
+
+          idempotency_key: "$generate:uuid_v4#sales_catalog_driven_conversion_tracking_log_events"
+          context:
+            correlation_id: "sales_catalog_driven--log_events"
+        validations:
+          - check: response_schema
+            description: "Response matches log-event-response.json schema"
+          - check: field_present
+            path: "events_received"
+            description: "Response reports events received"
+          - check: field_present
+            path: "match_quality"
+            description: "Response includes match quality score"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "sales_catalog_driven--log_events"
+            description: "Context correlation_id returned unchanged"
+  - id: optimization_loop
+    title: "Performance feedback and optimization"
+    narrative: |
+      The buyer closes the optimization loop by telling your platform how the campaign
+      is performing against their goals. A performance_index above 1.0 means the
+      campaign is exceeding expectations — your platform should maintain or increase
+      delivery. Below 1.0 means underperforming — your platform should adjust targeting,
+      item selection, or pacing.
+
+    steps:
+      - id: provide_feedback
+        title: "Submit performance feedback"
+        narrative: |
+          The buyer reports that the campaign is driving 1.4x the expected reservation
+          rate. Your platform uses this signal to optimize delivery — showing more of
+          the high-performing catalog items and adjusting bid strategies.
+        task: provide_performance_feedback
+        schema_ref: "media-buy/provide-performance-feedback-request.json"
+        response_schema_ref: "media-buy/provide-performance-feedback-response.json"
+        doc_ref: "/media-buy/task-reference/provide_performance_feedback"
+        stateful: true
+        expected: |
+          Acknowledge the feedback. The seller should adjust delivery optimization
+          based on the performance_index signal.
+
+        sample_request:
+          account:
+            brand:
+              domain: "amsterdam-steakhouse.example"
+            operator: "pinnacle-agency.example"
+          media_buy_id: "$context.media_buy_id"
+          measurement_period:
+            start: "2026-04-07T00:00:00Z"
+            end: "2026-04-14T23:59:59Z"
+          performance_index: 1.4
+          metric_type: "conversion_rate"
+          feedback_source: "buyer_attribution"
+
+          idempotency_key: "$generate:uuid_v4#sales_catalog_driven_optimization_loop_provide_feedback"
+          context:
+            correlation_id: "sales_catalog_driven--provide_feedback"
+          ext:
+            test_platform:
+              test_run: true
+        validations:
+          - check: response_schema
+            description: "Response matches provide-performance-feedback-response.json schema"
+          - check: field_value
+            path: "success"
+            value: true
+            description: "Feedback accepted"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "sales_catalog_driven--provide_feedback"
+            description: "Context correlation_id returned unchanged"
+      - id: check_delivery
+        title: "Monitor delivery with catalog attribution"
+        narrative: |
+          The buyer checks delivery metrics to see which catalog items are driving
+          performance and how spend is allocated across the product feed.
+        task: get_media_buy_delivery
+        schema_ref: "media-buy/get-media-buy-delivery-request.json"
+        response_schema_ref: "media-buy/get-media-buy-delivery-response.json"
+        doc_ref: "/media-buy/task-reference/get_media_buy_delivery"
+        comply_scenario: reporting_flow
+        stateful: true
+        expected: |
+          Return delivery metrics including impressions, clicks, spend, and
+          conversion data attributed to catalog items.
+
+        sample_request:
+          account:
+            brand:
+              domain: "amsterdam-steakhouse.example"
+            operator: "pinnacle-agency.example"
+          media_buy_ids:
+            - "$context.media_buy_id"
+          include_package_daily_breakdown: true
+
+          context:
+            correlation_id: "sales_catalog_driven--check_delivery"
+        validations:
+          - check: response_schema
+            description: "Response matches get-media-buy-delivery-response.json schema"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "sales_catalog_driven--check_delivery"
+            description: "Context correlation_id returned unchanged"