@adcp/sdk 14.0.0-rc.38 → 14.0.0-rc.39

package/compliance/cache/3.1.0-beta.7/specialisms/sales-catalog-driven/index.yaml

@@ -1,840 +0,0 @@
-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"