@adcp/sdk 13.1.2 → 13.1.4

package/compliance/cache/{3.1.24 → 3.1.30}/universal/stale-response-advisory.yaml

@@ -30,7 +30,7 @@ narrative: |
 
   The stale-cache forcing phases require comply_test_controller with the
   force_upstream_unavailable scenario. Steps requiring the controller grade not_applicable for
-  agents that do not advertise it. The non-emission guard (Phase 3) runs for all agents.
+  agents that do not advertise it. The healthy non-emission guard runs before outage forcing.
 
 agent:
   interaction_model: media_buy_seller
@@ -45,8 +45,8 @@ caller:
 
 prerequisites:
   description: |
-    Phase 2 (stale-cache forcing) requires comply_test_controller with
-    force_upstream_unavailable support. Phase 3 (non-emission guard) runs for all agents.
+    The stale-cache forcing phase requires comply_test_controller with
+    force_upstream_unavailable support. The healthy non-emission guard runs before outage forcing.
   test_kit: "test-kits/acme-outdoor.yaml"
 
 phases:
@@ -87,7 +87,67 @@ phases:
             value: "stale_response_advisory--get_capabilities"
             description: "Context correlation_id returned unchanged"
 
+  - id: non_emission_guard
+    title: "No STALE_RESPONSE on healthy upstream response"
+    narrative: |
+      STALE_RESPONSE MUST NOT be emitted when the upstream is healthy. Per the normative
+      error-code description, sellers MUST NOT emit STALE_RESPONSE when the cache hit is
+      within freshness target or when no cached payload exists — the correct code for a
+      completely unavailable upstream with no cache is SERVICE_UNAVAILABLE.
+
+      Run this healthy request before forcing any outage. It also warms the cache for
+      the same brief and account used by the subsequent stale-cache probe.
+
+    steps:
+      - id: no_stale_on_healthy_upstream
+        title: "STALE_RESPONSE absent on healthy upstream response"
+        narrative: |
+          A normal get_products request against a healthy upstream MUST NOT emit
+          STALE_RESPONSE. Sellers that unconditionally emit STALE_RESPONSE on every
+          get_products response are non-conformant — the code is only valid when a
+          specific cache-fallback condition is active.
+
+          NOTE: No machine-enforced absence check for STALE_RESPONSE exists today — the
+          `field_absent` primitive rejects errors[] entirely, but other error codes are
+          valid. The schema and correlation_id checks below prove conformance for
+          non-STALE_RESPONSE flows; a dedicated `error_code_absent` check kind would
+          close this gap. TODO: add check primitive when runner contract supports it.
+        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: stale_response_non_emission
+        stateful: false
+        expected: |
+          Return products normally. errors[] may be absent or present with codes other
+          than STALE_RESPONSE. STALE_RESPONSE MUST NOT appear unless the seller is
+          actively serving from a stale cache entry past its freshness target.
+
+        sample_request:
+          buying_mode: "brief"
+          brief: "Display advertising"
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+            sandbox: true
+          context:
+            correlation_id: "stale_response_advisory--no_stale_on_healthy"
+        validations:
+          - check: response_schema
+            description: "Response matches get-products-response.json schema on healthy upstream"
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "stale_response_advisory--no_stale_on_healthy"
+            description: "Context correlation_id returned unchanged"
+
   - id: stale_response_forcing
+    requires_capability:
+      path: compliance_testing.scenarios
+      contains: force_upstream_unavailable
     title: "Force stale-cache condition and verify advisory-success wire placement"
     narrative: |
       The test controller forces an upstream dependency unavailable while a stale cache entry
@@ -127,6 +187,9 @@ phases:
             tool: "get_products"
             upstream_name: "inventory-service"
           account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
             sandbox: true
           context:
             correlation_id: "stale_response_advisory--force_upstream_unavailable"
@@ -184,6 +247,7 @@ phases:
             brand:
               domain: "acmeoutdoor.example"
             operator: "pinnacle-agency.example"
+            sandbox: true
           context:
             correlation_id: "stale_response_advisory--stale_response_wire_placement"
         validations:
@@ -191,105 +255,49 @@ phases:
             description: "Response matches get-products-response.json schema even under stale cache"
             severity: advisory
             permanent_advisory:
-              reason: "Gated on force_upstream_unavailable runner support. Promote to required when widely adopted — remove permanent_advisory and severity fields. See issue #4934."
+              reason: "Gated on force_upstream_unavailable being advertised in the seller's comply_test_controller scenarios. Promote to required when widely adopted — remove permanent_advisory and severity fields. See issue #4934."
           - check: field_present
             path: "errors"
             description: "errors[] is present on a stale-cache response"
             severity: advisory
             permanent_advisory:
-              reason: "Gated on force_upstream_unavailable runner support. Promote to required when widely adopted. See issue #4934."
+              reason: "Gated on force_upstream_unavailable being advertised in the seller's comply_test_controller scenarios. Promote to required when widely adopted. See issue #4934."
           - check: field_value
             path: "errors[0].code"
             value: "STALE_RESPONSE"
             description: "First errors[] entry carries STALE_RESPONSE code"
             severity: advisory
             permanent_advisory:
-              reason: "Gated on force_upstream_unavailable runner support. Promote to required when widely adopted. See issue #4934."
+              reason: "Gated on force_upstream_unavailable being advertised in the seller's comply_test_controller scenarios. Promote to required when widely adopted. See issue #4934."
           - check: field_value
             path: "errors[0].details.served_from_cache"
             value: true
             description: "details.served_from_cache is true per error-details/stale-response.json"
             severity: advisory
             permanent_advisory:
-              reason: "Gated on force_upstream_unavailable runner support. Promote to required when widely adopted. See issue #4934."
+              reason: "Gated on force_upstream_unavailable being advertised in the seller's comply_test_controller scenarios. Promote to required when widely adopted. See issue #4934."
           - check: field_present
             path: "errors[0].details.cache_age_seconds"
             description: "details.cache_age_seconds is present (required details field)"
             severity: advisory
             permanent_advisory:
-              reason: "Gated on force_upstream_unavailable runner support. Promote to required when widely adopted. See issue #4934."
+              reason: "Gated on force_upstream_unavailable being advertised in the seller's comply_test_controller scenarios. Promote to required when widely adopted. See issue #4934."
           - check: field_present
             path: "context"
             description: "Response echoes back the context object on stale-cache advisory"
             severity: advisory
             permanent_advisory:
-              reason: "Gated on force_upstream_unavailable runner support. Promote to required when widely adopted. See issue #4934."
+              reason: "Gated on force_upstream_unavailable being advertised in the seller's comply_test_controller scenarios. Promote to required when widely adopted. See issue #4934."
           - check: field_value
             path: "context.correlation_id"
             value: "stale_response_advisory--stale_response_wire_placement"
             description: "Context correlation_id returned unchanged"
             severity: advisory
             permanent_advisory:
-              reason: "Gated on force_upstream_unavailable runner support. Promote to required when widely adopted. See issue #4934."
+              reason: "Gated on force_upstream_unavailable being advertised in the seller's comply_test_controller scenarios. Promote to required when widely adopted. See issue #4934."
           - check: field_present
             path: "products[0]"
             description: "Response payload is non-empty (products[] has at least one entry from stale cache)"
             severity: advisory
             permanent_advisory:
-              reason: "Gated on force_upstream_unavailable runner support. Promote to required when widely adopted. See issue #4934."
-
-  - id: non_emission_guard
-    title: "No STALE_RESPONSE on healthy upstream response"
-    narrative: |
-      STALE_RESPONSE MUST NOT be emitted when the upstream is healthy. Per the normative
-      error-code description, sellers MUST NOT emit STALE_RESPONSE when the cache hit is
-      within freshness target or when no cached payload exists — the correct code for a
-      completely unavailable upstream with no cache is SERVICE_UNAVAILABLE.
-
-      This phase sends a normal get_products request and verifies no STALE_RESPONSE appears.
-      Runs for all agents — no controller required.
-
-    steps:
-      - id: no_stale_on_healthy_upstream
-        title: "STALE_RESPONSE absent on healthy upstream response"
-        narrative: |
-          A normal get_products request against a healthy upstream MUST NOT emit
-          STALE_RESPONSE. Sellers that unconditionally emit STALE_RESPONSE on every
-          get_products response are non-conformant — the code is only valid when a
-          specific cache-fallback condition is active.
-
-          NOTE: No machine-enforced absence check for STALE_RESPONSE exists today — the
-          `field_absent` primitive rejects errors[] entirely, but other error codes are
-          valid. The schema and correlation_id checks below prove conformance for
-          non-STALE_RESPONSE flows; a dedicated `error_code_absent` check kind would
-          close this gap. TODO: add check primitive when runner contract supports it.
-        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: stale_response_non_emission
-        stateful: false
-        expected: |
-          Return products normally. errors[] may be absent or present with codes other
-          than STALE_RESPONSE. STALE_RESPONSE MUST NOT appear unless the seller is
-          actively serving from a stale cache entry past its freshness target.
-
-        sample_request:
-          buying_mode: "brief"
-          brief: "Display advertising for outdoor lifestyle campaign"
-          account:
-            brand:
-              domain: "acmeoutdoor.example"
-            operator: "pinnacle-agency.example"
-          context:
-            correlation_id: "stale_response_advisory--no_stale_on_healthy"
-        validations:
-          - check: response_schema
-            description: "Response matches get-products-response.json schema on healthy upstream"
-          - check: field_present
-            path: "context"
-            description: "Response echoes back the context object"
-          - check: field_value
-            path: "context.correlation_id"
-            value: "stale_response_advisory--no_stale_on_healthy"
-            description: "Context correlation_id returned unchanged"
+              reason: "Gated on force_upstream_unavailable being advertised in the seller's comply_test_controller scenarios. Promote to required when widely adopted. See issue #4934."

package/compliance/cache/{3.1.24 → 3.1.30}/universal/storyboard-schema.yaml

@@ -407,6 +407,14 @@
 #             operator: "buyer.example"
 #             billing: "operator"
 #             sandbox: true
+#       creative_formats:
+#         - format_id: "seller_display_300x250"
+#           fixture:
+#             format_id: { agent_url: "https://formats.seller.example/", id: "seller_display_300x250" }
+#             name: "Seller display 300x250"
+#             type: "display"
+#             assets:
+#               - { item_type: "individual", asset_id: "image", asset_type: "image", required: true }
 #       creatives:
 #         - creative_id: "campaign_hero_video"
 #           status: "approved"
@@ -419,7 +427,15 @@
 #           status: "active"
 #   Each top-level key maps to a seed_* scenario (accounts → seed_account,
 #   products → seed_product, pricing_options → seed_pricing_option,
-#   creatives → seed_creative, plans → seed_plan, media_buys → seed_media_buy).
+#   creative_formats → seed_creative_format, creatives → seed_creative,
+#   plans → seed_plan, media_buys → seed_media_buy).
+#
+#   Declaring ANY fixture key makes its seed_* scenario required: if the agent's
+#   comply_test_controller `list_scenarios` does not advertise it, the runner
+#   skips the WHOLE storyboard as `fixture_seed_unsupported` / not_applicable
+#   rather than seeding partially. Adding a fixture key to an existing
+#   storyboard therefore removes coverage from every agent that does not yet
+#   implement that scenario — weigh that before adding one.
 #   Storyboards that need an
 #   external measurement vendor catalog SHOULD add an explicit
 #   comply_test_controller step with scenario: seed_measurement_catalog. Product
@@ -431,6 +447,7 @@
 #     product ──┬─→ pricing_option
 #               ├─→ plan
 #               └─→ media_buy
+#     creative_format ─→ creative
 #     creative ────→ media_buy
 #     plan ────────→ media_buy
 #
@@ -905,6 +922,13 @@
 #   Omitting `negative_path` when `expect_error: true` behaves as `schema_invalid`
 #   (backwards-compatible default).
 #
+# enrich_request: true (optional — only with expect_error: true and
+#   negative_path: payload_well_formed). Opt this semantic rejection probe into
+#   the normal per-task request enricher, including discovered auction bids.
+#   The default for negative probes preserves the authored request exactly;
+#   intentionally malformed requests MUST NOT set this flag. Explicit fixture
+#   values still win, and governance-authorized payloads remain unmodified.
+#
 # sample_request_skip_schema: boolean (optional — explicit opt-out of schema
 #   validation for a step regardless of `expect_error` / `negative_path`. Use
 #   sparingly; prefer `negative_path: schema_invalid` for intentionally malformed

package/compliance/cache/{3.1.24 → 3.1.30}/universal/webhook-emission.yaml

@@ -1,5 +1,5 @@
 id: webhook_emission
-version: "1.3.0"
+version: "1.3.1"
 title: "Webhook emission — outbound webhook conformance (operation ID + signing + idempotency + sync silence)"
 category: core
 summary: "Any agent that emits webhooks MUST echo the caller-supplied operation_id in every payload, carry a stable idempotency_key across retries, avoid duplicate webhook side effects on request replay, and — when the buyer has not opted into the deprecated HMAC fallback — MUST sign deliveries under the RFC 9421 webhook profile. Sellers MUST NOT emit task webhooks for inline terminal responses; any future sync-completion notification mode would be explicit and capability-advertised. Graded by a runner hosting a webhook receiver during storyboard execution."
@@ -162,6 +162,46 @@ phases:
             path: "supported_protocols"
             description: "Agent declares its supported AdCP protocols"
 
+      - id: get_products_discovery
+        title: "Discover a product for webhook trigger steps"
+        narrative: |
+          Sales-agent triggers need a real catalog product and its pricing option.
+          Capture both before create_media_buy; an empty catalog or missing
+          pricing option fails setup instead of sending placeholder identifiers.
+          Brief discovery may complete inline or asynchronously. The
+          task_completion captures wait for a submitted/working task to finish
+          before binding IDs, and also accept an inline completed response.
+          Retain product metadata so request enrichment can honor auction floors.
+          Agents without get_products skip this sales-specific setup step.
+        task: get_products
+        requires_tool: get_products
+        schema_ref: "media-buy/get-products-request.json"
+        response_schema_ref: "media-buy/get-products-response.json"
+        doc_ref: "/media-buy/task-reference/get_products"
+        stateful: false
+        sample_request:
+          idempotency_key: "$generate:uuid_v4#webhook_emission_get_products_discovery"
+          buying_mode: "brief"
+          brief: "Advertising inventory for Acme Outdoor's outdoor gear campaign."
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+        context_outputs:
+          - path: "task_completion.products"
+            key: "products"
+          - path: "task_completion.products[0].product_id"
+            key: "product_id"
+          - path: "task_completion.products[0].pricing_options[0].pricing_option_id"
+            key: "pricing_option_id"
+        validations:
+          - check: response_schema
+            description: "Discovery response matches get-products-response.json"
+        expected: |
+          Complete discovery with at least one product and pricing option.
+          All sales-agent webhook triggers use the captured product and pricing
+          option IDs only after discovery reaches a successful result.
+
   - id: idempotency_key_presence
     title: "Every webhook payload carries idempotency_key"
     narrative: |
@@ -187,12 +227,25 @@ phases:
           `authentication` block (9421 is the baseline for conformance).
         task: "$test_kit.operations.primary_webhook_emitter"
         task_default: create_media_buy
-        schema_ref: "$test_kit.schemas.primary_request"
-        response_schema_ref: "$test_kit.schemas.primary_response"
+        schema_ref: "media-buy/create-media-buy-request.json"
+        response_schema_ref: "media-buy/create-media-buy-response.json"
         doc_ref: "/building/implementation/webhooks"
         comply_scenario: webhook_trigger
         stateful: false
         sample_request:
+          brand:
+            domain: "acmeoutdoor.example"
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          # The runner rolls elapsed sample dates to a fresh seven-day flight.
+          start_time: "2025-01-01T00:00:00Z"
+          end_time: "2025-01-08T00:00:00Z"
+          packages:
+            - product_id: "$context.product_id"
+              pricing_option_id: "$context.pricing_option_id"
+              budget: 1000
           push_notification_config:
             url: "{{runner.webhook_url:trigger_webhook_operation}}"
             operation_id: "op_webhook_presence_explicit"
@@ -252,12 +305,25 @@ phases:
           payload echo must come from the explicit operation_id field.
         task: "$test_kit.operations.primary_webhook_emitter"
         task_default: create_media_buy
-        schema_ref: "$test_kit.schemas.primary_request"
-        response_schema_ref: "$test_kit.schemas.primary_response"
+        schema_ref: "media-buy/create-media-buy-request.json"
+        response_schema_ref: "media-buy/create-media-buy-response.json"
         doc_ref: "/building/implementation/webhooks"
         comply_scenario: webhook_operation_id_echo_trigger
         stateful: false
         sample_request:
+          brand:
+            domain: "acmeoutdoor.example"
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          # The runner rolls elapsed sample dates to a fresh seven-day flight.
+          start_time: "2025-01-01T00:00:00Z"
+          end_time: "2025-01-08T00:00:00Z"
+          packages:
+            - product_id: "$context.product_id"
+              pricing_option_id: "$context.pricing_option_id"
+              budget: 1000
           push_notification_config:
             url: "{{runner.webhook_url:trigger_operation_id_echo}}"
             operation_id: "op_storyboard_echo_123"
@@ -320,12 +386,25 @@ phases:
           duplicate.
         task: "$test_kit.operations.primary_webhook_emitter"
         task_default: create_media_buy
-        schema_ref: "$test_kit.schemas.primary_request"
-        response_schema_ref: "$test_kit.schemas.primary_response"
+        schema_ref: "media-buy/create-media-buy-request.json"
+        response_schema_ref: "media-buy/create-media-buy-response.json"
         doc_ref: "/building/implementation/webhooks"
         comply_scenario: webhook_idempotency_replay_trigger
         stateful: true
         sample_request:
+          brand:
+            domain: "acmeoutdoor.example"
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          # The runner rolls elapsed sample dates to a fresh seven-day flight.
+          start_time: "2025-01-01T00:00:00Z"
+          end_time: "2025-01-08T00:00:00Z"
+          packages:
+            - product_id: "$context.product_id"
+              pricing_option_id: "$context.pricing_option_id"
+              budget: 1000
           push_notification_config:
             url: "{{runner.webhook_url:trigger_idempotent_webhook_initial}}"
             operation_id: "op_webhook_idempotency_replay"
@@ -345,12 +424,25 @@ phases:
           webhook for the replay.
         task: "$test_kit.operations.primary_webhook_emitter"
         task_default: create_media_buy
-        schema_ref: "$test_kit.schemas.primary_request"
-        response_schema_ref: "$test_kit.schemas.primary_response"
+        schema_ref: "media-buy/create-media-buy-request.json"
+        response_schema_ref: "media-buy/create-media-buy-response.json"
         doc_ref: "/building/implementation/webhooks"
         comply_scenario: webhook_idempotency_replay_trigger
         stateful: true
         sample_request:
+          brand:
+            domain: "acmeoutdoor.example"
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          # The runner rolls elapsed sample dates to a fresh seven-day flight.
+          start_time: "2025-01-01T00:00:00Z"
+          end_time: "2025-01-08T00:00:00Z"
+          packages:
+            - product_id: "$context.product_id"
+              pricing_option_id: "$context.pricing_option_id"
+              budget: 1000
           push_notification_config:
             url: "{{runner.webhook_url:trigger_idempotent_webhook_initial}}"
             operation_id: "op_webhook_idempotency_replay"
@@ -550,12 +642,25 @@ phases:
           will retry on each 5xx and eventually succeed.
         task: "$test_kit.operations.primary_webhook_emitter"
         task_default: create_media_buy
-        schema_ref: "$test_kit.schemas.primary_request"
-        response_schema_ref: "$test_kit.schemas.primary_response"
+        schema_ref: "media-buy/create-media-buy-request.json"
+        response_schema_ref: "media-buy/create-media-buy-response.json"
         doc_ref: "/building/implementation/webhooks"
         comply_scenario: webhook_retry_trigger
         stateful: false
         sample_request:
+          brand:
+            domain: "acmeoutdoor.example"
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          # The runner rolls elapsed sample dates to a fresh seven-day flight.
+          start_time: "2025-01-01T00:00:00Z"
+          end_time: "2025-01-08T00:00:00Z"
+          packages:
+            - product_id: "$context.product_id"
+              pricing_option_id: "$context.pricing_option_id"
+              budget: 1000
           push_notification_config:
             url: "{{runner.webhook_url:trigger_retry_scenario}}"
             operation_id: "op_webhook_retry_explicit"
@@ -687,12 +792,25 @@ phases:
           forcing 9421 signing per the baseline rule.
         task: "$test_kit.operations.primary_webhook_emitter"
         task_default: create_media_buy
-        schema_ref: "$test_kit.schemas.primary_request"
-        response_schema_ref: "$test_kit.schemas.primary_response"
+        schema_ref: "media-buy/create-media-buy-request.json"
+        response_schema_ref: "media-buy/create-media-buy-response.json"
         doc_ref: "/building/implementation/webhooks"
         comply_scenario: webhook_signed_trigger
         stateful: false
         sample_request:
+          brand:
+            domain: "acmeoutdoor.example"
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          # The runner rolls elapsed sample dates to a fresh seven-day flight.
+          start_time: "2025-01-01T00:00:00Z"
+          end_time: "2025-01-08T00:00:00Z"
+          packages:
+            - product_id: "$context.product_id"
+              pricing_option_id: "$context.pricing_option_id"
+              budget: 1000
           push_notification_config:
             url: "{{runner.webhook_url:trigger_signed_webhook}}"
             operation_id: "op_webhook_signed_explicit"

package/dist/lib/schemas-data/3.1/a2ui/bound-value.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "/schemas/3.1.24/a2ui/bound-value.json",
+  "$id": "/schemas/3.1.30/a2ui/bound-value.json",
   "title": "A2UI Bound Value",
   "description": "A value that can be a literal or bound to a path in the data model",
   "oneOf": [

package/dist/lib/schemas-data/3.1/a2ui/component.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "/schemas/3.1.24/a2ui/component.json",
+  "$id": "/schemas/3.1.30/a2ui/component.json",
   "title": "A2UI Component",
   "description": "A component in an A2UI surface",
   "type": "object",