@adcp/sdk 7.11.0 → 7.11.1

package/compliance/cache/3.1.0-rc.2/specialisms/creative-generative/index.yaml

@@ -0,0 +1,758 @@
+id: creative_generative
+version: "1.0.0"
+title: "Generative creative agent"
+protocol: creative
+category: creative_generative
+summary: "Agent that takes a brief and generates finished creatives from scratch — no input assets required."
+required_tools:
+  - build_creative
+# Note: sync_catalogs is NOT in required_tools. The catalog_augmented_generation
+# phase below is additive — brief-only generative agents (pure-prompt DSPs) pass
+# the other phases without claiming catalog support. Agents that do not implement
+# sync_catalogs grade that phase not_applicable rather than fail the specialism.
+
+# 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.
+#
+# Cross-resource assertion (adcp#2859). impairment.coherence verifies that
+# creative.rejected transitions propagate to any non-terminal media buy
+# that references the creative — the buy's impairments[] MUST list an
+# entry for the rejected creative, and `health` MUST track impairments[]
+# non-empty (impaired) ↔ empty (ok). See snapshot-and-log Rule 1 and
+# lifecycle.mdx Compliance for the full forward + inverse rule. Grades
+# not_applicable until #2860 wires the cross-resource exercise. Note:
+# generative-creative storyboards typically don't surface a media-buy
+# snapshot read; this specialism may stay not_applicable more often
+# than its peers even after #2860.
+invariants:
+  - status.monotonic
+  - impairment.coherence
+
+narrative: |
+  You run a generative creative platform — an AI ad network, a generative DSP, or any system
+  that creates ad creatives from a natural-language brief and brand identity. The buyer doesn't
+  push assets to you. Instead, they describe what they want, point you at a brand.json, and
+  your agent produces finished creatives ready for trafficking.
+
+  This is fundamentally different from template-based transformation (Celtra) or library-based
+  retrieval (Innovid). Your agent creates something new. The buyer sends a brief, optionally
+  with seed assets or constraints, and your platform generates creatives — potentially in
+  multiple formats at once.
+
+  This storyboard walks through the generation flow: format discovery, brief-driven generation,
+  multi-format builds, iterative refinement, and quality progression from draft to production.
+
+agent:
+  interaction_model: stateless_generate
+  capabilities:
+    - supports_generation
+  examples:
+    - "OpenAds"
+    - "AI ad networks"
+    - "Generative DSPs"
+
+caller:
+  role: buyer_agent
+  example: "Scope3 (DSP)"
+
+prerequisites:
+  description: |
+    The caller needs a brand identity (brand.json at the brand's domain) for the agent
+    to resolve visual identity — logos, colors, fonts, tone. The test kit provides a
+    sample brand with campaign parameters.
+  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 creative operations before browsing or building 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 creative in supported_protocols, confirming the agent handles creative operations.
+        sample_request:
+          context:
+            correlation_id: "creative_generative--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: "creative_generative--get_capabilities"
+            description: "Context correlation_id returned unchanged"
+  - id: format_discovery
+    title: "Discover generative formats"
+    narrative: |
+      The buyer needs to know what your agent can generate. Unlike a template platform
+      where formats are fixed dimensions, generative formats describe what the agent
+      produces — the output type, constraints, and what inputs it accepts. A generative
+      format might be "display_300x250_generative" that accepts a brief and produces
+      a finished banner, or "social_post_generative" that creates platform-native content.
+
+    steps:
+      - id: discover_formats
+        title: "Discover available generative formats"
+        narrative: |
+          The buyer asks: "What can you generate?" Your platform returns the formats
+          you support. Each format describes the output type, dimensions, and what
+          inputs it needs (brief text, brand reference, seed images, etc.).
+        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_sync
+        stateful: false
+        expected: |
+          Return your generative formats. Each format should include:
+          - format_id with your agent_url and a unique id
+          - Human-readable name and description
+          - Asset slots describing what inputs are accepted (brief text, images, etc.)
+          - Render dimensions for the output
+          - Variables for any dynamic fields the buyer can control
+
+        sample_request:
+          context:
+            correlation_id: "creative_generative--discover_formats"
+
+        validations:
+          - check: response_schema
+            description: "Response matches list-creative-formats-response.json schema"
+          - check: field_present
+            path: "formats"
+            description: "Response contains a formats array"
+          - check: field_present
+            path: "formats[0].format_id.agent_url"
+            description: "Each format has a format_id with agent_url"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "creative_generative--discover_formats"
+            description: "Context correlation_id returned unchanged"
+  - id: generate_from_brief
+    title: "Generate from brief"
+    narrative: |
+      The buyer describes what they want in natural language and your agent generates
+      a creative from scratch. The brief includes the campaign message, target audience
+      context, and a brand reference so your agent can resolve visual identity.
+
+      This is the core generative flow. The buyer doesn't provide finished assets —
+      they provide intent, and your agent creates.
+
+    steps:
+      - id: build_draft
+        title: "Generate a draft creative from brief"
+        narrative: |
+          The buyer sends a brief describing the campaign and a target format. Your
+          agent generates a draft creative — fast, lower-fidelity output the buyer can
+          review before committing to a production build.
+
+          The brief is passed as a message alongside the target format. The brand
+          reference lets your agent resolve brand.json for visual identity.
+        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: false
+        expected: |
+          Return a generated creative manifest:
+          - creative_manifest with the generated assets (images, copy, serving code)
+          - format_id matching the target format
+          - If include_preview is true, include a preview render
+
+          The output should be a coherent creative that reflects the brief and brand
+          identity — not a template with placeholder text.
+
+        sample_request:
+          message: "Create a display banner for a summer outdoor gear sale. Bold, adventurous tone. Headline should emphasize 40% off. Target audience: active adults 25-54."
+          target_format_id:
+            agent_url: "https://your-agent.example.com"
+            id: "display_300x250_generative"
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          quality: "draft"
+          include_preview: true
+
+          idempotency_key: "$generate:uuid_v4#creative_generative_generate_from_brief_build_draft"
+          context:
+            correlation_id: "creative_generative--build_draft"
+        validations:
+          - check: response_schema
+            description: "Response matches build-creative-response.json schema"
+          - check: field_present
+            path: "creative_manifest.assets"
+            description: "Output manifest includes generated assets"
+          - check: field_present
+            path: "creative_manifest.format_id"
+            description: "Output manifest includes format_id"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "creative_generative--build_draft"
+            description: "Context correlation_id returned unchanged"
+  - id: refine
+    title: "Refine the creative"
+    narrative: |
+      The buyer reviews the draft and wants changes. They send the generated manifest
+      back with refinement instructions. Your agent modifies the creative based on the
+      feedback — adjusting copy, swapping imagery, or changing the layout.
+
+      This is iterative: the buyer can refine multiple times until they're satisfied,
+      then request a production-quality build.
+
+    steps:
+      - id: refine_creative
+        title: "Refine with feedback"
+        narrative: |
+          The buyer passes the generated manifest back with a message describing what
+          to change. Your agent applies the refinements and returns an updated creative.
+        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: false
+        expected: |
+          Return a refined creative manifest reflecting the requested changes.
+          The output should preserve what worked in the original while applying
+          the refinements.
+
+        sample_request:
+          message: "Make the headline larger. Replace the mountain imagery with a trail running scene. Add a CTA button that says 'Shop Now'."
+          creative_manifest:
+            format_id:
+              agent_url: "https://your-agent.example.com"
+              id: "display_300x250_generative"
+            assets:
+              generated_image:
+                asset_type: "image"
+                url: "https://your-agent.example.com/generated/abc123.jpg"
+                width: 300
+                height: 250
+              headline:
+                asset_type: "text"
+                content: "Summer Sale — 40% Off All Gear"
+          target_format_id:
+            agent_url: "https://your-agent.example.com"
+            id: "display_300x250_generative"
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          quality: "draft"
+          include_preview: true
+
+          idempotency_key: "$generate:uuid_v4#creative_generative_refine_refine_creative"
+          context:
+            correlation_id: "creative_generative--refine_creative"
+        validations:
+          - check: response_schema
+            description: "Response matches build-creative-response.json schema"
+          - check: field_present
+            path: "creative_manifest.assets"
+            description: "Refined manifest includes assets"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "creative_generative--refine_creative"
+            description: "Context correlation_id returned unchanged"
+  - id: multi_format
+    title: "Multi-format generation"
+    narrative: |
+      The buyer needs the creative in multiple sizes. Instead of generating each
+      format separately, they pass target_format_ids (plural) and your agent produces
+      all formats in a single call. This is where generative agents shine — adapting
+      a concept across formats while maintaining visual coherence.
+
+    steps:
+      - id: build_multi_format
+        title: "Generate for multiple formats"
+        narrative: |
+          The buyer passes the refined manifest with multiple target formats. Your
+          agent generates a creative for each format, adapting layout, copy, and
+          imagery to fit each size while maintaining brand consistency.
+        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: false
+        expected: |
+          Return creative manifests for each requested format in creative_manifests
+          (plural). Each manifest should:
+          - Have a format_id matching one of the target formats
+          - Contain complete, format-appropriate assets
+          - Maintain visual coherence across formats
+
+          If a format cannot be produced, include it with an error — don't fail
+          the entire request.
+
+        sample_request:
+          message: "Generate production-ready versions for all three sizes."
+          creative_manifest:
+            format_id:
+              agent_url: "https://your-agent.example.com"
+              id: "display_300x250_generative"
+            assets:
+              generated_image:
+                asset_type: "image"
+                url: "https://your-agent.example.com/generated/abc123-refined.jpg"
+                width: 300
+                height: 250
+              headline:
+                asset_type: "text"
+                content: "Summer Sale — 40% Off All Gear"
+              cta:
+                asset_type: "text"
+                content: "Shop Now"
+          target_format_ids:
+            - agent_url: "https://your-agent.example.com"
+              id: "display_300x250_generative"
+            - agent_url: "https://your-agent.example.com"
+              id: "display_728x90_generative"
+            - agent_url: "https://your-agent.example.com"
+              id: "display_320x50_generative"
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          quality: "production"
+
+          idempotency_key: "$generate:uuid_v4#creative_generative_multi_format_build_multi_format"
+          context:
+            correlation_id: "creative_generative--build_multi_format"
+        validations:
+          - check: response_schema
+            description: "Response matches build-creative-response.json schema"
+          - check: field_present
+            path: "creative_manifests"
+            description: "Response contains creative_manifests array (plural)"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "creative_generative--build_multi_format"
+            description: "Context correlation_id returned unchanged"
+  - id: production_build
+    title: "Production build"
+    narrative: |
+      The buyer is satisfied with the concept and needs a final, production-quality
+      creative ready for trafficking. They switch quality from draft to production.
+      Your agent generates the finished output with full-fidelity assets.
+
+    steps:
+      - id: build_production
+        title: "Build at production quality"
+        narrative: |
+          The buyer requests a production-quality build of the approved concept. Your
+          agent generates the final creative with full-fidelity rendering, polished
+          assets, and serving code ready for trafficking.
+        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: false
+        expected: |
+          Return a production-quality creative manifest:
+          - Full-fidelity generated assets
+          - Serving code (HTML, JavaScript, or VAST) ready for trafficking
+          - Provenance metadata if AI-generated (digital_source_type, ai_tool)
+
+        sample_request:
+          message: "Final production build. No changes needed."
+          creative_manifest:
+            format_id:
+              agent_url: "https://your-agent.example.com"
+              id: "display_300x250_generative"
+            assets:
+              generated_image:
+                asset_type: "image"
+                url: "https://your-agent.example.com/generated/abc123-refined.jpg"
+                width: 300
+                height: 250
+              headline:
+                asset_type: "text"
+                content: "Summer Sale — 40% Off All Gear"
+              cta:
+                asset_type: "text"
+                content: "Shop Now"
+          target_format_id:
+            agent_url: "https://your-agent.example.com"
+            id: "display_300x250_generative"
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          quality: "production"
+          include_preview: true
+
+          idempotency_key: "$generate:uuid_v4#creative_generative_production_build_build_production"
+          context:
+            correlation_id: "creative_generative--build_production"
+        validations:
+          - check: response_schema
+            description: "Response matches build-creative-response.json schema"
+          - check: field_present
+            path: "creative_manifest.assets"
+            description: "Production manifest includes assets"
+          - check: field_present
+            path: "creative_manifest.format_id"
+            description: "Production manifest includes format_id"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "creative_generative--build_production"
+            description: "Context correlation_id returned unchanged"
+
+  - id: catalog_augmented_generation
+    title: "Catalog-augmented generation"
+    narrative: |
+      Generative platforms routinely hydrate catalog items into the generation context:
+      the buyer pushes a product catalog, and each generated creative references a specific
+      catalog item (via `{SKU}`, `{GTIN}`, or the catalog-item family) in its impression
+      trackers and click trackers. This is how generative DSPs produce per-SKU dynamic
+      creative at scale.
+
+      This phase exercises the catalog-acceptance leg and emits a generative build that
+      includes catalog-item macros in its tracker URL assets. `preview_creative` is the
+      natural observation point for the runtime substitution-safety check tracked in
+      #2638 — when the substitution-observer contract lands, a runner can assert that
+      the previewed HTML contains percent-encoded catalog-item values per
+      `docs/creative/universal-macros#substitution-safety-catalog-item-macros`.
+
+    steps:
+      - id: sync_generation_catalog
+        title: "Push a product catalog for generation"
+        narrative: |
+          The buyer pushes a small inline catalog. Your agent will use these items as the
+          hydration targets for subsequent generated creatives.
+        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_generative_source"
+              type: "product"
+              content_id_type: "sku"
+              name: "Acme Outdoor — Generative source feed"
+              items:
+                - item_id: "peak_jacket_x"
+                  title: "Peak Jacket X"
+                  description: "Goretex 3L shell, seam-taped, 280g."
+                  url: "https://acmeoutdoor.example/gear/peak-jacket-x"
+                  image_url: "https://cdn.acmeoutdoor.example/gear/peak-jacket-x.jpg"
+                  price:
+                    amount: 449.00
+                    currency: "USD"
+
+          idempotency_key: "$generate:uuid_v4#creative_generative_catalog_augmented_generation_sync_generation_catalog"
+          context:
+            correlation_id: "creative_generative--sync_generation_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: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "creative_generative--sync_generation_catalog"
+            description: "Context correlation_id returned unchanged"
+
+      - id: build_catalog_aware_creative
+        title: "Generate a creative bound to a catalog item"
+        narrative: |
+          The buyer asks your agent to build a creative for a specific catalog item.
+          The generated manifest MUST include tracker URLs with catalog-item macros
+          (`{SKU}`, `{GTIN}`) so impression-time substitution renders per-SKU output.
+
+          Per #2620, the substitution step MUST percent-encode catalog-item values
+          against the RFC 3986 unreserved set — but the substitution itself happens at
+          serve time, not in the build_creative response. Runtime observability is
+          tracked in #2638.
+        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: |
+          Return a creative manifest whose tracker assets include catalog-item
+          macros ({SKU} or {GTIN}) and whose format references a catalog-capable
+          format declared by the agent.
+
+        sample_request:
+          message: "Generate a 300x250 display ad for the Peak Jacket X, using our catalog feed for product fields and tracker URLs."
+          target_format_id:
+            agent_url: "https://your-agent.example.com"
+            id: "display_300x250_generative"
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          quality: "draft"
+          include_preview: true
+
+          idempotency_key: "$generate:uuid_v4#creative_generative_catalog_augmented_generation_build_catalog_aware_creative"
+          context:
+            correlation_id: "creative_generative--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: "Generated manifest includes format_id"
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "creative_generative--build_catalog_aware_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 and creative 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 five canonical attacker-shaped
+      catalog values drawn from the fixture at
+      `static/test-vectors/catalog-macro-substitution.json`:
+      reserved-char breakout, nested-expansion preservation, non-ASCII UTF-8,
+      CRLF injection, and bidi-override neutralization. Generative pipelines
+      have a higher risk profile on bidi-override than template pipelines
+      (LLM-generated copy with embedded user text can round-trip bidi
+      controls into attribute contexts), so this phase exercises bidi
+      alongside the baseline vectors. The two remaining fixture vectors —
+      `mixed-path-and-query-contexts` (requires the same macro in two URL
+      positions) and `url-scheme-injection-neutralized` (requires an
+      href-whole-value macro binding) — are unit-test-layer conformance only;
+      runtime observation in a storyboard requires specialism-specific
+      template shapes tracked as follow-ups.
+
+      `build_creative`-with-`include_preview: true` is the natural observation
+      point on a generative specialism — the substitution-observer runner
+      (#2638) parses the returned `preview_html` and asserts each macro
+      position carries the fixture's `expected_encoded` form, not the raw
+      attacker bytes.
+
+      Scope note: this phase validates substitution on the PREVIEW surface
+      only. Sellers with divergent preview vs impression-time substitution
+      paths MAY pass here while failing at serve time; serve-time attestation
+      or log-introspection observability is deferred (#2651, out-of-scope v1
+      per the observer contract).
+
+      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` and `build_substitution_probe_creative`
+      steps still run (exercising the catalog-acceptance and build 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 three of the
+          canonical attacker-shaped values from the substitution-safety
+          fixture. The agent MUST accept the payload at sync_catalogs — the
+          encoding rule applies at substitution time, not at ingest — but
+          subsequent build_creative output must percent-encode each value.
+        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: "creative_generative_substitution_probe_v1"
+              type: "product"
+              content_id_type: "sku"
+              name: "Substitution safety probe"
+              items:
+                # item_id names the vector; 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://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-\u202E1234"
+                  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#creative_generative_catalog_substitution_safety_sync_substitution_probe_catalog"
+          context:
+            correlation_id: "creative_generative--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: build_substitution_probe_creative
+        title: "Generate a creative with catalog-item macros bound to the probe"
+        narrative: |
+          Generate a draft creative that uses `{SKU}` in its impression tracker
+          URL and request `include_preview: true` so the substitution-observer
+          runner has a preview surface to inspect.
+
+          The `message` is a natural-language brief; a generative agent that
+          ignores the `{SKU}` directive (generates its own macro, inlines an
+          encoded value, omits the tracker) fails the downstream
+          `expect_substitution_safe` step with `substitution_binding_missing`.
+          To keep that failure mode diagnostically clear, this step validates
+          the creative_manifest contains `{SKU}` unsubstituted in at least
+          one tracker asset before the observer runs.
+        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 populated. Impression
+          tracker asset includes {SKU} unsubstituted in its template (to be
+          resolved at impression time against catalog items).
+
+        sample_request:
+          message: "Generate a 300x250 display ad for the creative_generative_substitution_probe_v1 catalog. Include the `{SKU}` macro as a literal token in the impression tracker URL — the platform resolves it per-impression against catalog items."
+          target_format_id:
+            agent_url: "https://your-agent.example.com"
+            id: "display_300x250_generative"
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          quality: "draft"
+          include_preview: true
+
+          idempotency_key: "$generate:uuid_v4#creative_generative_catalog_substitution_safety_build_substitution_probe_creative"
+          context:
+            correlation_id: "creative_generative--build_substitution_probe_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_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
+          generative agent 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 probe
+          # catalog; `vector_name` is the fixture entry whose raw_value and
+          # expected_encoded the runner loads from the unit-test fixture.
+          - 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"