@adcp/sdk 7.11.0 → 7.11.1

package/compliance/cache/3.1.0-rc.2/universal/v3-envelope-integrity.yaml

@@ -0,0 +1,117 @@
+id: v3_envelope_integrity
+version: "1.0.0"
+title: "v3 envelope integrity — no legacy status fields"
+category: schema_validation
+summary: "v3 protocol envelopes MUST NOT carry task_status or response_status — v2 legacy field names that have no semantics in v3."
+track: core
+required_tools: []  # protocol-level: get_adcp_capabilities is mandatory for all agents
+
+narrative: |
+  AdCP 3.0 normalises all task lifecycle state onto a single `status` field (values
+  defined in the task-status enum). The v2 `task_status` and `response_status` field
+  names have no semantics in v3 — carrying them on a v3 envelope is a normative
+  MUST NOT per the migration guide, task-lifecycle.mdx, and the protocol-envelope
+  schema. See docs/reference/migration/index.mdx and
+  docs/building/implementation/task-lifecycle.mdx.
+
+  This storyboard documents the machine-check assertion and asserts the canonical v3
+  `status` field is present using the `envelope_field_present` check type, which
+  walks the protocol envelope rather than the inner response schema. The explicit
+  envelope-root field-absence checks assert that task_status and response_status are
+  absent using `envelope_field_absent`; protocol-envelope.json carries the matching
+  top-level `not: { anyOf: [{ required: [task_status] }, { required:
+  [response_status] }] }` schema constraint.
+
+  Scope: envelope top-level only. Domain data inside `payload` (e.g., a reporting
+  row carrying a field named task_status) is outside this prohibition and is not
+  checked here.
+
+agent:
+  interaction_model: "*"  # applies to every agent regardless of protocol or specialism
+  examples:
+    - "Any AdCP agent (seller, signals, creative, retail media, SI, governance)"
+
+caller:
+  role: buyer_agent
+  example: "Compliance test harness"
+
+prerequisites:
+  description: |
+    No test-kit credentials required. get_adcp_capabilities is a public operation
+    that every AdCP agent must expose without authentication.
+
+phases:
+  - id: envelope_integrity_check
+    title: "v3 envelope must not carry legacy v2 status field names"
+    narrative: |
+      Call get_adcp_capabilities and verify the response envelope carries the
+      canonical v3 status field and omits the legacy v2 field names
+      task_status and response_status.
+
+    steps:
+      - id: no_legacy_status_fields
+        title: "Envelope carries canonical v3 status; no legacy v2 status field names"
+        narrative: |
+          get_adcp_capabilities is the lightest call every agent supports and
+          requires no credentials. The response envelope must carry the canonical
+          v3 `status` field and must not carry task_status or response_status.
+          The protocol-envelope.json schema's top-level `not: { anyOf: [...] }`
+          constraint forbids either field, making this constraint detectable by
+          any schema-aware validator without runner-specific primitives.
+
+          MCP transport note: the `status` field must appear at the top level of
+          `structuredContent` (or the first parseable `content[].text` JSON object
+          for older MCP servers) — it is NOT a JSON-RPC result-level field. The extracted AdCP
+          response IS the protocol envelope: `status` lives alongside task-specific
+          payload fields in the same flat object. The `get-adcp-capabilities-response.json`
+          schema validates only the task-specific fields (capabilities, context echo,
+          etc.) and does not cover protocol envelope fields like `status` — an agent
+          whose MCP response passes response_schema validation but omits `status` is
+          still non-conformant. See docs/building/implementation/mcp-response-extraction
+          for the normative MCP extraction algorithm and the expected structuredContent
+          shape, including the required `status` field at the top level.
+        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: envelope_integrity
+        stateful: false
+        expected: |
+          Response envelope (all transports):
+          - MUST contain status (the v3 canonical field)
+          - MUST NOT contain task_status (v2 legacy, no v3 semantics)
+          - MUST NOT contain response_status (v2 legacy, no v3 semantics)
+          Both forbidden fields are blocked by the top-level `not: { anyOf: [...] }`
+          constraint in protocol-envelope.json, so any schema-aware validator that
+          validates the full protocol envelope will detect violations.
+
+          For MCP agents specifically: `status` MUST be present at the top level of
+          structuredContent (or the first parseable content[].text JSON object). It is not a JSON-RPC sibling
+          field — it lives inside the content payload, at the same level as the
+          task-specific response fields. An agent returning only the task payload
+          without `status` fails this check regardless of whether the payload itself
+          validates against the task response schema.
+
+        sample_request:
+          context:
+            correlation_id: "v3_envelope_integrity--no_legacy_status"
+
+        validations:
+          - check: response_schema
+            description: "Response matches get-adcp-capabilities-response.json schema"
+          - check: envelope_field_present
+            path: "status"
+            description: "Envelope carries the canonical v3 status field"
+          - check: envelope_field_absent
+            path: "task_status"
+            description: "Envelope root MUST NOT carry task_status (v2 legacy; no v3 semantics)"
+          - check: envelope_field_absent
+            path: "response_status"
+            description: "Envelope root MUST NOT carry response_status (v2 legacy; no v3 semantics)"
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "v3_envelope_integrity--no_legacy_status"
+            description: "Context correlation_id returned unchanged"

package/compliance/cache/3.1.0-rc.2/universal/version-negotiation.yaml

@@ -0,0 +1,130 @@
+id: version_negotiation
+version: "1.0.0"
+title: "Release-precision version negotiation"
+category: version_negotiation
+summary: "Sellers advertise supported releases on capabilities and echo the served release on every response."
+track: core
+required_tools: []  # protocol-level: get_adcp_capabilities is mandatory for all agents
+
+narrative: |
+  AdCP 3.1 introduces release-precision (VERSION.RELEASE, e.g. "3.1") version
+  negotiation alongside the legacy major-precision (`adcp_major_version` integer)
+  carried since 3.0. Both directions of the negotiation are SHOULD-level through
+  3.x and graduate to MUST at 4.0 — this storyboard exercises both halves so
+  sellers can discover gaps before the 3.2 grader cutover flips advisory results
+  to blocking failures.
+
+  Two checks ride on a single get_adcp_capabilities call:
+
+  1. **Seller advertises** `adcp.supported_versions` — an array of release-precision
+     strings the seller speaks. Authoritative for buyer-side pinning; the legacy
+     `adcp.major_versions` integer array remains required through 3.x for
+     backwards compatibility.
+
+  2. **Seller echoes** `adcp_version` at the envelope root — the release the seller
+     actually served. Buyers SHOULD validate the response against the echoed
+     release's schema, not against their own pin. Legacy 3.0 sellers that don't
+     read the field omit the echo (`additionalProperties: true` makes the field
+     invisible to them) — buyers fall back to their constructor pin.
+
+  Per the [migration table](/docs/reference/versioning#migration-timeline), both
+  surfaces are advisory at 3.1 and become blocking failure at 3.2. The advisory
+  marker on each validation makes that promotion a single-PR change at 3.2 cut
+  rather than a per-adopter compliance break at the boundary.
+
+  Scope: protocol envelope and capabilities advertisement only. The
+  `VERSION_UNSUPPORTED` error path (buyer pins a release outside the seller's
+  `supported_versions`) is exercised separately by error_compliance — running it
+  here requires the runner to send a deliberately-mismatched pin and is left to
+  follow-up.
+
+agent:
+  interaction_model: "*"  # applies to every agent regardless of protocol or specialism
+  examples:
+    - "Any AdCP agent (seller, signals, creative, retail media, SI, governance)"
+
+caller:
+  role: buyer_agent
+  example: "Compliance test harness"
+
+prerequisites:
+  description: |
+    No test-kit credentials required. get_adcp_capabilities is a public operation
+    that every AdCP agent must expose without authentication.
+
+phases:
+  - id: capabilities_advertise_and_echo
+    title: "Capabilities advertise supported_versions; response echoes adcp_version"
+    narrative: |
+      Call get_adcp_capabilities. The single response carries both halves of the
+      negotiation contract — `adcp.supported_versions` in the body (seller's
+      advertisement) and `adcp_version` on the envelope (seller's echo of what
+      it served). Sellers SHOULD populate both at 3.1; the grader reports
+      missing entries as advisory findings without failing certification.
+
+    steps:
+      - id: get_capabilities_with_version
+        title: "Verify seller advertises supported_versions and echoes adcp_version"
+        narrative: |
+          The runner emits `adcp_version` on the request envelope based on its
+          configured pin (the SDK's release-precision constructor option). The
+          seller honors the pin within the resolution algorithm in
+          docs/reference/versioning.mdx, echoes the served release on the response
+          envelope, and lists every release it speaks under
+          `adcp.supported_versions` in the response body.
+
+          A seller serving only 3.0 (no awareness of the new fields) passes the
+          request schema unchanged — `adcp_version` rides on the envelope and is
+          invisible to readers that don't look for it. The advisory checks below
+          will report missing `supported_versions` advertisement and missing
+          envelope echo without failing the step.
+        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: version_negotiation
+        stateful: false
+        expected: |
+          Response carries both halves of the negotiation contract:
+          - Body: adcp.supported_versions (array of release-precision strings, e.g.
+            ["3.0", "3.1"]) declaring every release the seller speaks. Authoritative
+            for buyer-side pinning. SHOULD at 3.1, MUST at 4.0.
+          - Envelope: adcp_version (release-precision string) echoing the release
+            the seller actually served. SHOULD at 3.1, MUST at 4.0. Buyers SHOULD
+            validate the response against the echoed release's schema.
+
+          Legacy `adcp.major_versions` (integer array) remains required through 3.x.
+
+        sample_request:
+          context:
+            correlation_id: "version_negotiation--get_capabilities_with_version"
+
+        validations:
+          - check: response_schema
+            description: "Response matches get-adcp-capabilities-response.json schema"
+
+          - check: field_present
+            path: "adcp.major_versions"
+            description: "Legacy major-precision advertisement present (required through 3.x)"
+
+          - check: field_present
+            path: "adcp.supported_versions"
+            severity: advisory
+            permanent_advisory:
+              reason: "Per docs/reference/versioning.mdx > Migration timeline, sellers SHOULD declare supported_versions at 3.1 and the compliance grader reports presence as advisory. At 3.2 the storyboard cut promotes this validation to required (manual flip — not gated on runner_capability_version because the 3.2 boundary is a protocol-spec cutover, not a runner-capability cutover). 4.0 promotes to MUST per the spec. Marking permanent_advisory here is a deliberate use of the field to defer promotion to the 3.2 storyboard PR rather than relying on the expires_after_version semver gate."
+            description: "Seller advertises release-precision supported_versions (advisory at 3.1, required at 3.2)"
+
+          - check: field_present
+            path: "adcp_version"
+            severity: advisory
+            permanent_advisory:
+              reason: "Per docs/reference/versioning.mdx > Migration timeline, sellers SHOULD echo adcp_version at 3.1 and the compliance grader reports presence as advisory. At 3.2 the storyboard cut promotes this validation to required (manual flip — see the supported_versions check above for the same rationale). 4.0 promotes to MUST per the spec."
+            description: "Seller echoes adcp_version on the response envelope (advisory at 3.1, required at 3.2)"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "version_negotiation--get_capabilities_with_version"
+            description: "Context correlation_id returned unchanged"

package/compliance/cache/3.1.0-rc.2/universal/webhook-emission.yaml

@@ -0,0 +1,411 @@
+id: webhook_emission
+version: "1.0.0"
+title: "Webhook emission — outbound webhook conformance (signing + idempotency)"
+category: core
+summary: "Any agent that emits webhooks MUST carry a stable idempotency_key across retries and — when the buyer has not opted into the deprecated HMAC fallback — MUST sign deliveries under the RFC 9421 webhook profile. Graded by a runner hosting a webhook receiver during storyboard execution."
+track: core
+
+narrative: |
+  Webhook emission is a cross-cutting capability, not a specialism. Sellers emit
+  webhooks on `create_media_buy` status changes. Rights agents emit revocation
+  notifications. Governance agents emit `collection_list_changed` and
+  `property_list_changed`. Content-standards agents emit artifact webhooks.
+  Every agent that accepts `push_notification_config` on any operation is in
+  scope for this universal — no capability flag, no opt-in.
+
+  Two load-bearing conformance requirements apply to every outbound webhook:
+
+  1. **`idempotency_key` is present on every payload and stable across retries.**
+     Required by adcontextprotocol/adcp#2417. Receivers dedupe on this field;
+     a sender that regenerates the key on retry breaks at-least-once delivery
+     semantics and creates duplicate side effects downstream.
+
+  2. **RFC 9421 webhook signing is baseline in 3.0** unless the buyer opts into
+     the deprecated HMAC fallback via `push_notification_config.authentication`.
+     Required by adcontextprotocol/adcp#2423. Signatures carry
+     `tag="adcp/webhook-signing/v1"`, cover `content-digest`, and verify
+     against the seller's brand.json-published JWKS.
+
+  Grading is observable-behavior only. The runner hosts a webhook receiver per
+  the contract at `test-kits/webhook-receiver-runner.yaml`, drives storyboards
+  that trigger webhooks from whatever operations the agent advertises, and
+  asserts on what the agent sends back.
+
+  This universal grades not_applicable when the runner does not host a webhook
+  receiver (e.g., lint-only runs against an agent that has no webhook-emitting
+  operations, or runs where the operator has not configured the receiver
+  contract).
+
+  **9421 is the on-ramp.** Any agent advertising webhook-emitting operations
+  MUST publish a `webhook-signing` JWKS at its `brand.json` `agents[].jwks_uri`
+  and MUST emit valid 9421 signatures when triggered with no `authentication`
+  block on `push_notification_config`. Agents without published signing keys
+  fail the `signing_keys_published` precheck before the signature phase runs;
+  agents with keys but invalid signatures fail `signature_validity`. The
+  deprecated HMAC fallback remains a buyer-side registration option in 3.x
+  (`push_notification_config.authentication`), but it is not a path that
+  exempts the agent from publishing 9421 keys — the runner registers as a
+  9421-default buyer, and the agent is graded on what it does in that mode.
+  This closes the on-ramp loophole that previously let agents self-declare
+  themselves out of the signing phase via `webhook_auth_mode == 'hmac_legacy'`.
+
+  **Clean seam**: the runner does NOT reimplement signature verification or
+  idempotency dedup. It delegates to `@adcp/client` primitives —
+  `AsyncHandlerConfig.webhookDedup`, `WebhookMetadata.idempotency_key`, and
+  the 9421 webhook verifier once that lands in the client library. The same
+  code that production receivers rely on is what the conformance runner
+  exercises; a single bug fix in the library covers both surfaces.
+
+agent:
+  interaction_model: webhook_emitter
+  capabilities:
+    - emits_webhooks
+  examples:
+    - "Any AdCP seller that accepts push_notification_config on create_media_buy, update_media_buy, or equivalent async operations"
+    - "Rights agents that post revocation notifications"
+    - "Governance agents that emit collection_list_changed or property_list_changed webhooks"
+    - "Content-standards agents that emit artifact webhooks"
+
+caller:
+  role: compliance_runner
+  example: "AdCP Verified runner with webhook receiver capability"
+
+prerequisites:
+  description: |
+    The runner MUST be configured with a webhook receiver per the contract at
+    `test-kits/webhook-receiver-runner.yaml`. The receiver operates in one of
+    two modes: `loopback_mock` (intercepts at the `@adcp/client` AsyncHandler
+    layer — zero network deps, used for lint runs) or `proxy_url` (operator-
+    supplied HTTPS URL routing into the runner — used for AdCP Verified
+    grading). Runners without a receiver grade this universal as
+    not_applicable.
+
+    The agent under test MUST advertise the operations it supports in
+    `get_adcp_capabilities`. The runner drives whichever webhook-emitting
+    operations are advertised; operations the agent does not support are
+    skipped cleanly, not graded as failures.
+
+    Agents advertising webhook-emitting operations MUST publish a JWKS at the
+    `jwks_uri` on their brand.json `agents[]` entry containing a key with
+    `adcp_use: "webhook-signing"`. The `signing_keys_published` precheck
+    asserts this directly; agents without published signing keys fail
+    `webhook_signing_keys_unpublished` before the signature phase runs.
+  test_kit: "test-kits/webhook-receiver-runner.yaml"
+
+phases:
+  - id: capability_discovery
+    title: "Capability discovery"
+    narrative: |
+      Discover which async operations the agent supports so the runner knows
+      which to drive for webhook emission.
+
+    steps:
+      - id: get_capabilities
+        title: "Discover webhook-emitting operations"
+        narrative: |
+          The runner calls `get_adcp_capabilities` and inspects which async
+          operations the agent supports. If the agent advertises none that
+          accept `push_notification_config`, this universal does not apply
+          and grading returns not_applicable (not a failure).
+        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 a capabilities block including supported_protocols. Webhook-
+          emitting operations are discovered via the transport handshake
+          (MCP tools/list, A2A skills), not the capabilities body; grading
+          returns a stable not_applicable marker downstream when no webhook-
+          emitting operation resolves through
+          $test_kit.operations.primary_webhook_emitter.
+        sample_request:
+          context:
+            correlation_id: "webhook_emission--get_capabilities"
+        validations:
+          - check: field_present
+            path: "supported_protocols"
+            description: "Agent declares its supported AdCP protocols"
+
+  - id: idempotency_key_presence
+    title: "Every webhook payload carries idempotency_key"
+    narrative: |
+      The runner triggers a webhook-emitting operation with a
+      push_notification_config pointed at the runner's per-step receiver. The
+      first inbound webhook MUST carry an `idempotency_key` matching the
+      required pattern (`^[A-Za-z0-9_.:-]{16,255}$`). Absence of the field or
+      a pattern mismatch fails the phase.
+
+      This is the baseline conformance with adcontextprotocol/adcp#2417 —
+      receivers cannot dedupe without it, so "I forgot to emit the field" is
+      the single highest-impact publisher bug the universal catches.
+
+    steps:
+      - id: trigger_webhook_operation
+        title: "Trigger an operation that emits a webhook"
+        narrative: |
+          Runner calls the first operation the capability block advertises as
+          webhook-emitting (typically `create_media_buy` for sales agents,
+          `acquire_rights` for rights agents, etc.), passing
+          `push_notification_config.url = {{runner.webhook_url:trigger_webhook_operation}}`
+          — no `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"
+        doc_ref: "/building/implementation/webhooks"
+        comply_scenario: webhook_trigger
+        stateful: false
+        sample_request:
+          push_notification_config:
+            url: "{{runner.webhook_url:trigger_webhook_operation}}"
+          idempotency_key: "$generate:uuid_v4#webhook_emission_trigger"
+          context:
+            correlation_id: "webhook_emission--trigger_webhook_operation"
+        expected: |
+          Agent accepts the request and begins async execution. Response either
+          returns an immediate terminal status (no webhook needed) or an
+          interim status indicating async processing (webhook will follow).
+
+      - id: expect_webhook_presence
+        title: "Assert inbound webhook carries a valid idempotency_key"
+        narrative: |
+          Wait for a webhook at the per-step URL. When it arrives, validate
+          the payload against the webhook schema and assert the
+          idempotency_key is present and matches the required pattern.
+        task: expect_webhook
+        triggered_by: trigger_webhook_operation
+        filter:
+          operation_id: "{{prior_step.trigger_webhook_operation.operation_id}}"
+        timeout_seconds: 30
+        expect_idempotency_key: true
+        webhook_payload_schema_ref: "core/mcp-webhook-payload.json"
+        stateful: true
+        expected: |
+          Webhook arrives within 30 seconds. Payload validates against
+          mcp-webhook-payload.json. idempotency_key is present and matches
+          the pattern `^[A-Za-z0-9_.:-]{16,255}$`. Any other status fails the
+          phase with a specific error code: no_webhook_received,
+          schema_violation, missing_idempotency_key, or
+          invalid_idempotency_key_format.
+
+  - id: idempotency_key_stability
+    title: "idempotency_key is byte-identical across retries of the same event"
+    narrative: |
+      The runner's receiver deterministically returns HTTP 503 for the first
+      `count` deliveries, then 200. The runner records the idempotency_key on
+      every delivery and asserts all recorded keys are byte-identical. A
+      sender that regenerates the key on retry breaks at-least-once semantics
+      and fails the phase.
+
+      This is the conformance test that cannot be replaced by schema
+      validation — schema validation catches "no key at all" but not "wrong
+      key on retry." Only a live observation catches publisher-side retry
+      bugs.
+
+    steps:
+      - id: trigger_retry_scenario
+        title: "Trigger a webhook that will be retried via 5xx response"
+        narrative: |
+          Runner calls a webhook-emitting operation with
+          push_notification_config.url = {{runner.webhook_url:trigger_retry_scenario}}.
+          The runner's receiver at that URL returns 503 for the first 3
+          deliveries and 200 afterwards. Any conformant at-least-once sender
+          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"
+        doc_ref: "/building/implementation/webhooks"
+        comply_scenario: webhook_retry_trigger
+        stateful: false
+        sample_request:
+          push_notification_config:
+            url: "{{runner.webhook_url:trigger_retry_scenario}}"
+          idempotency_key: "$generate:uuid_v4#webhook_emission_retry_trigger"
+          context:
+            correlation_id: "webhook_emission--trigger_retry_scenario"
+        expected: |
+          Agent accepts the request and begins async execution. The webhook
+          it emits will be rejected with 503 by the runner and retried.
+
+      - id: expect_key_stable_across_retries
+        title: "Assert idempotency_key byte-identical across all deliveries"
+        narrative: |
+          Runner records every delivery and asserts all recorded keys are
+          byte-identical. Requires at least 2 deliveries observed within the
+          timeout window — a sender that doesn't retry at all cannot be
+          graded on retry stability.
+        task: expect_webhook_retry_keys_stable
+        triggered_by: trigger_retry_scenario
+        filter:
+          operation_id: "{{prior_step.trigger_retry_scenario.operation_id}}"
+        retry_trigger:
+          count: 3
+          http_status: 503
+        timeout_seconds: 90
+        expect_min_deliveries: 2
+        stateful: true
+        expected: |
+          At least 2 deliveries of the same logical event observed within
+          90 seconds; all deliveries carry byte-identical idempotency_key.
+          Fails with insufficient_retries if fewer than 2 deliveries arrive,
+          idempotency_key_rotated if the key changes across deliveries, or
+          idempotency_key_format_changed if a later delivery carries a
+          different-shaped value.
+
+  - id: signing_keys_published
+    title: "Agent publishes a webhook-signing JWKS at brand.json"
+    narrative: |
+      Precheck: any agent advertising webhook-emitting operations MUST publish
+      a JWKS at the `jwks_uri` on its `brand.json` `agents[]` entry containing
+      at least one key with `adcp_use: "webhook-signing"`. This is the on-ramp
+      gate — an agent that has only ever signed HMAC and never published a
+      9421 signing key fails here, before the signature phase even runs.
+
+      The runner resolves the agent's `brand.json` from its
+      `get_adcp_capabilities` advertisement (or, for agents not yet member-
+      registered, from operator configuration), fetches the JWKS at
+      `agents[].jwks_uri`, and asserts at least one key has
+      `adcp_use: "webhook-signing"` and a non-revoked status. Absent or
+      malformed JWKS produces `webhook_signing_keys_unpublished`; JWKS present
+      but with no webhook-signing key produces
+      `webhook_signing_keys_wrong_purpose`.
+
+      This phase is observable-only and stateless — no traffic flows. It runs
+      before the signature phase so an operator debugging "why did signing
+      fail" gets a specific keys-vs-signing diagnostic instead of a generic
+      `signature_key_unknown` deep in the verifier checklist.
+
+    steps:
+      - id: fetch_brand_json
+        title: "Fetch brand.json and resolve jwks_uri"
+        narrative: |
+          Runner fetches the agent's `brand.json` (resolved from
+          `get_adcp_capabilities` or operator configuration), iterates the
+          `agents[]` array, and asserts at least one entry exposes a
+          `jwks_uri` reachable at HTTP 200.
+        task: fetch_brand_jwks
+        stateful: false
+        expected: |
+          brand.json reachable and parseable; at least one `agents[]` entry
+          has a `jwks_uri` returning a valid JWKS document. Fails with
+          `brand_json_unreachable`, `brand_json_malformed`, or
+          `agents_jwks_uri_missing`.
+
+      - id: assert_webhook_signing_key_present
+        title: "Assert JWKS contains a webhook-signing key"
+        narrative: |
+          Runner inspects the JWKS and asserts at least one key has
+          `adcp_use: "webhook-signing"`. Keys advertising other purposes
+          (`request-signing`, `webhook-receipts`, etc.) do not satisfy this
+          check — purpose-separation is enforced per the `adcp_use` rule
+          (one cryptoKeyVersion per signing purpose; receivers enforce
+          purpose at JWK `adcp_use`, not RFC 9421 tag).
+        task: assert_jwks_purpose
+        stateful: false
+        expected: |
+          At least one JWK in the agent's published JWKS carries
+          `adcp_use: "webhook-signing"` and is not marked revoked. Fails
+          with `webhook_signing_keys_unpublished` (no JWKS or empty JWKS),
+          `webhook_signing_keys_wrong_purpose` (JWKS present but no key
+          with the webhook-signing purpose), or
+          `webhook_signing_keys_all_revoked` (all webhook-signing keys
+          revoked).
+
+  - id: signature_validity
+    title: "Webhook signatures validate under the 9421 profile"
+    narrative: |
+      Every outbound webhook MUST verify under the 14-step webhook verifier
+      checklist per
+      docs/building/implementation/security.mdx#verifier-checklist-for-webhooks.
+      The runner registers the trigger as a 9421-default buyer (no
+      `authentication` block on `push_notification_config`); the agent is
+      graded on the signatures it emits in that mode.
+
+      Verification is delegated to the `@adcp/client` 9421 webhook verifier
+      (see test-kits/webhook-receiver-runner.yaml client_primitives section).
+      Until the client verifier lands in a published release, this phase
+      grades as `not_applicable` rather than skipping silently — operators
+      get an explicit "verifier not yet available" signal instead of a
+      false-pass.
+
+      Negative conformance — signatures that MUST be rejected with a specific
+      webhook_signature_* error code — is tested via static conformance
+      vectors at `/compliance/{version}/test-vectors/webhook-signing/`
+      (follow-up), not by this phase. This phase only grades positive-path
+      agents emitting conformant signatures on live traffic.
+
+    steps:
+      - id: trigger_signed_webhook
+        title: "Trigger a webhook the agent will sign"
+        narrative: |
+          Runner calls a webhook-emitting operation with no `authentication`
+          block on push_notification_config, 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"
+        doc_ref: "/building/implementation/webhooks"
+        comply_scenario: webhook_signed_trigger
+        stateful: false
+        sample_request:
+          push_notification_config:
+            url: "{{runner.webhook_url:trigger_signed_webhook}}"
+          idempotency_key: "$generate:uuid_v4#webhook_emission_signed_trigger"
+          context:
+            correlation_id: "webhook_emission--trigger_signed_webhook"
+        expected: |
+          Agent accepts the request; the webhook it emits will carry
+          Signature-Input, Signature, and Content-Digest headers per the
+          9421 webhook profile.
+
+      - id: expect_signature_valid
+        title: "Assert webhook signature verifies under the 9421 profile"
+        narrative: |
+          Runner delegates to the @adcp/client 9421 webhook verifier (14-step
+          checklist). A passing signature means: covered components include
+          `@method`, `@target-uri`, `@authority`, `content-type`,
+          `content-digest`; `tag` is `adcp/webhook-signing/v1`; `alg` is
+          allowlisted; `keyid` resolves via the agent's brand.json
+          `agents[]` jwks_uri; content-digest recomputes cleanly; nonce is
+          not replayed.
+        task: expect_webhook_signature_valid
+        triggered_by: trigger_signed_webhook
+        filter:
+          operation_id: "{{prior_step.trigger_signed_webhook.operation_id}}"
+        timeout_seconds: 30
+        require_tag: "adcp/webhook-signing/v1"
+        stateful: true
+        expected: |
+          Signature verifies under the 9421 webhook profile. Fails with the
+          specific webhook_signature_* error code on any checklist failure
+          (e.g., signature_invalid, signature_expired, signature_key_unknown,
+          signature_digest_mismatch, signature_tag_invalid). Not_applicable
+          if the client library doesn't yet implement 9421 webhook
+          verification.
+
+grading:
+  pass_criteria: |
+    Phases idempotency_key_presence, idempotency_key_stability,
+    signing_keys_published, and signature_validity MUST pass when the agent
+    advertises any webhook-emitting operation and the runner hosts a webhook
+    receiver. Agents without a published webhook-signing JWKS fail
+    signing_keys_published — there is no exemption for "HMAC legacy mode."
+    Agents that advertise no webhook-emitting operations grade the entire
+    universal as not_applicable. Runners without a webhook receiver grade the
+    entire universal as not_applicable. signature_validity may grade
+    not_applicable if the runner's `@adcp/client` 9421 webhook verifier is
+    not yet available; this is an explicit operator signal, not a silent
+    skip.
+  report_format: |
+    Per-phase pass/fail/not_applicable, with per-step error codes on failure.
+    Retry-stability failures include a diff of the observed keys across
+    deliveries so operators can debug sender-side retry bugs without re-running
+    the full suite. signing_keys_published failures cite the specific gap —
+    `webhook_signing_keys_unpublished`, `webhook_signing_keys_wrong_purpose`,
+    or `webhook_signing_keys_all_revoked` — so operators distinguish "never
+    set up keys" from "set up keys with the wrong purpose label" without
+    reading the JWKS by hand.