@adcp/sdk 7.11.0 → 7.11.1

package/compliance/cache/3.1.0-rc.2/test-kits/rate-limit-trip-runner.yaml

@@ -0,0 +1,172 @@
+# Rate Limit Trip Runner — Harness Contract Test Kit
+#
+# Applies to:
+#   - universal/idempotency.yaml (rate_limit_replay_invariant phase — verifies
+#     that a RATE_LIMITED response on idempotency-cache insert MUST NOT be
+#     cached as the canonical replay for that key, per
+#     L1/security.mdx#idempotency bullet 8 + rule 3 ("Only successful
+#     responses are cached")).
+#   - Any future storyboard that needs to drive a fresh-key burst until a
+#     RATE_LIMITED response appears, then verify a downstream invariant.
+#
+# Storyboards are sequential by default and the storyboard YAML has no
+# loop primitive. This test-kit defines the coordination contract between
+# a runner that can drive a sequential burst of fresh-idempotency-key
+# requests and a storyboard step that needs that capability.
+#
+# The runner's burst happens at the @adcp/client layer (or its Python/Go
+# equivalents) using the SDK's request primitive in a tight sequential
+# loop with a configurable max-attempts ceiling. The storyboard author
+# MUST NOT try to express the burst via separate YAML steps.
+
+id: rate_limit_trip_runner
+applies_to:
+  universals:
+    - idempotency
+
+description: |
+  Coordination contract between a runner that can drive a fresh-key burst
+  until a `RATE_LIMITED` response is observed and a storyboard step that
+  needs to verify the replay invariant on the rate-limited key. The runner
+  fires up to `max_attempts` sequential requests with fresh
+  `idempotency_key` values and otherwise-identical canonical payloads. On
+  the first `RATE_LIMITED` response it captures the request's idempotency
+  key, sleeps `error.details.retry_after` seconds, and then re-submits the
+  same key with the same payload. The cross-step assertion compares the
+  replay response against the rate-limit response and fails if the replay
+  returned the cached `RATE_LIMITED`.
+
+endpoint_scope: sandbox
+# Driving a burst against production would consume rate-limit budget that
+# legitimate traffic relies on and may produce real downstream commitments
+# if any of the sequential requests succeed before the limiter trips.
+# Graders MUST target a sandbox/staging endpoint. Agents claiming the
+# universal SHOULD expose a dedicated grading endpoint whose limiter is
+# configured at the same ceiling as production but whose downstream side
+# effects are sandboxed.
+
+harness_mode: black_box
+
+# --- Trip mechanism ---
+#
+# The runner fires requests sequentially against a single mutating-op
+# target named by the storyboard step. Each request carries a fresh
+# UUID v4 idempotency_key and an otherwise-identical canonical payload.
+# The runner observes each response and stops when one of:
+#
+#   1. A response with envelope error_code = RATE_LIMITED is observed.
+#      The runner captures the request's idempotency_key into the
+#      step's context as `rate_limited_key`, captures the response's
+#      `error.details.retry_after` as `retry_after_seconds`, captures
+#      the rate-limit response body for the replay assertion, and
+#      proceeds to the wait + replay phase.
+#
+#   2. `max_attempts` requests complete without producing RATE_LIMITED.
+#      The runner grades the step as `not_applicable` with reason
+#      `rate_limit_not_triggered` — sellers may legitimately configure
+#      a sandbox limiter at a higher ceiling than this contract's
+#      max_attempts. The remainder of the storyboard is unaffected.
+#
+# Pacing. The runner fires requests as fast as the transport will accept
+# without artificial throttling — the goal is to exceed the seller's
+# configured insert-rate ceiling within max_attempts. Runners MAY use the
+# SDK's connection pooling but MUST NOT batch via parallel_dispatch (that
+# changes the cross-key timing and risks IDEMPOTENCY_IN_FLIGHT noise on
+# parallel paths). Sequential is the simpler shape and matches what
+# attacker-burst traffic would look like.
+
+burst_step_contract:
+  required_step_fields:
+    - rate_limit_trip.trip_target_task
+    - rate_limit_trip.trip_target_sample_request
+    - rate_limit_trip.max_attempts
+  optional_step_fields:
+    - rate_limit_trip.replay_max_wait_seconds
+  max_attempts_min: 50
+  max_attempts_max: 500
+  # 50 ≤ max_attempts ≤ 500. Below 50 won't reliably trip a 60/sec-sustained
+  # limiter even with HTTP/2 multiplexing; above 500 inflates runtime
+  # materially without improving signal. Storyboards SHOULD start at 200
+  # and adjust per observed trip rates in CI.
+
+# --- Wait + replay mechanism ---
+#
+# When a RATE_LIMITED is observed the runner reads
+# `error.details.retry_after` (seconds), waits that long (capped by
+# `rate_limit_trip.replay_max_wait_seconds`, default 30), then re-submits
+# the rate-limited request:
+#
+#   - Same idempotency_key (the one captured at trip time).
+#   - Same canonical payload (the trip_target_sample_request, with the
+#     same `$generate:uuid_v4#alias` resolutions as the trip request).
+#   - A distinct correlation_id so the replay's response is traceable in
+#     runner output.
+#
+# Sellers returning `retry_after` greater than `replay_max_wait_seconds`
+# fail the step on `replay_wait_exceeded` rather than the replay invariant
+# itself — `retry_after` values larger than the runner's wait budget are
+# either a seller-side bug or a production-tuning mismatch with the
+# conformance budget, and either way prevent the invariant from being
+# verified.
+#
+# Sellers returning a `RATE_LIMITED` response without
+# `error.details.retry_after` (or with retry_after = 0) fail with
+# `missing_retry_after` — the retry hint is required to make rate-limit
+# responses actionable, per L1/security.mdx error semantics.
+
+# --- Cross-step assertion ---
+#
+# The runner emits a single structured result with three response objects
+# the storyboard validations[] can target:
+#
+#   trip_response.<path>       The first RATE_LIMITED response observed
+#                              during the burst.
+#   replay_response.<path>     The response to the replay request issued
+#                              after the retry_after wait.
+#   rate_limited_request.idempotency_key
+#                              The key captured at trip time, for traceability.
+#
+# The step's validations declare the invariant against `replay_response`.
+# The minimum required assertion is the not-cached check below; storyboards
+# MAY add further assertions on `replay_response.media_buy_id` (success
+# path) or other handler outputs.
+
+replay_invariant_check_kinds:
+  - replay_not_cached_rate_limit
+
+# `replay_not_cached_rate_limit` semantics: the runner compares
+# `trip_response.error.code` against `replay_response.error.code` (when
+# the replay carries an error envelope) or against the absence of error
+# (when the replay carries a success envelope). If both responses carry
+# error_code = RATE_LIMITED, the replay was served from the idempotency
+# cache and the invariant fails. Any other replay response shape passes
+# the invariant — either the handler succeeded (RATE_LIMITED was not
+# cached, the seller correctly re-executed), or the handler returned a
+# different error (the seller correctly re-executed and a state-dependent
+# error fired).
+
+# --- What the contract does NOT cover ---
+#
+# Burst-volume attestation of the 60/300 req/sec ceiling itself. The
+# contract observes whether the limiter exists and behaves correctly under
+# the replay invariant; it does NOT measure the threshold at which the
+# limiter activates. Threshold attestation is structurally non-deterministic
+# in CI environments (runner CPU, network jitter, agent cold-start) and is
+# better evaluated via operator-side load testing or self-attestation.
+#
+# Cross-scope rate-limit leakage. The contract dispatches all requests
+# within a single (authenticated_agent, account) scope. Storyboards needing
+# to verify that one agent's rate-limit budget does not affect another
+# agent's traffic require a separate contract.
+#
+# RATE_LIMITED on read paths. The contract drives mutating-op traffic
+# (where idempotency caching applies). Sellers MAY also rate-limit read
+# operations, but the replay invariant doesn't apply there — reads are
+# inherently safe to retry.
+
+# --- Reviewer checks ---
+
+reviewer_checks:
+  - "Confirm the seller's idempotency-cache implementation explicitly excludes RATE_LIMITED (and other transient-error) responses from the cached-replay path. Review the storage layer or runbook describing which response classes are persisted under idempotency_key."
+  - "Confirm the seller's rate-limit response carries a usable retry_after value (seconds, integer, > 0, ≤ a documented ceiling). A seller that returns retry_after values larger than buyers' realistic retry windows produces unusable rate-limit signaling."
+  - "Confirm the seller's rate-limit budget is scoped per (authenticated_agent, account) tuple — not shared across all agents or accounts globally — so one agent's burst cannot exhaust another's budget."

package/compliance/cache/3.1.0-rc.2/test-kits/signed-requests-runner.yaml

@@ -0,0 +1,155 @@
+# Signed-Requests Runner — Harness Contract Test Kit
+#
+# Applies to: universal/signed-requests.yaml (gated on
+# `request_signing.supported: true` in get_adcp_capabilities).
+#
+# The signed-requests storyboard grades an agent's RFC 9421 verifier against 28
+# conformance vectors at /compliance/{version}/test-vectors/request-signing/.
+# Most vectors are pure black-box: the runner constructs a signed HTTP request,
+# sends it, and checks the response. Three negative vectors assert behavior that
+# depends on verifier state the runner cannot set from the outside:
+#
+#   016-replayed-nonce   — replay cache must already contain (keyid, nonce)
+#   017-key-revoked      — keyid must already be in the revocation list
+#   020-rate-abuse       — per-keyid replay cache must be at its configured cap
+#
+# This test-kit defines the coordination contract between a black-box runner and
+# a request-signing agent under test. Agents advertising
+# `request_signing.supported: true` MUST pre-configure their verifier per this
+# contract before the negative phase runs. The runner reads this file to know
+# (a) the keyids it will sign with, (b) how to provoke each stateful negative
+# vector, and (c) the grading-time cap values it will target (which are NOT
+# production recommendations — see each field). See `scope` below for what the
+# contract does NOT specify.
+
+id: signed_requests_runner
+applies_to:
+  universal_storyboard: signed-requests
+
+description: |
+  Coordination contract between a black-box runner and a request-signing agent
+  under test. The runner signs vectors dynamically using the keypairs published
+  in keys.json. The agent pre-configures its verifier — accepted JWKS, pre-revoked
+  keyid, replay TTL, per-keyid cap — so that the three stateful negative vectors
+  produce their expected error codes without the runner injecting verifier state.
+
+  Vectors requiring coordination declare `requires_contract` in their fixture;
+  the runner gates those vectors on this contract being in scope.
+
+endpoint_scope: sandbox
+# The replay-window contract sends a live, validly-signed mutating request as
+# its first step (the second copy is what the grader expects to be rejected).
+# Running this against a production endpoint would create a real media buy.
+# Graders MUST target a sandbox/staging endpoint or an idempotency-keyed
+# sacrificial path the agent discards post-grading. Agents advertising
+# `request_signing.supported: true` SHOULD expose a dedicated grading endpoint
+# rather than grading in prod.
+
+harness_mode: black_box
+# Agents participating in a white-box test harness (e.g., SDK internal tests
+# against the reference verifier) MAY satisfy the stateful vectors via direct
+# state injection using the vector's `test_harness_state` block, and declare
+# `harness_mode: white_box` in their own runner configuration. AdCP Verified
+# grading runs in black_box mode only.
+
+runner_signing_keys:
+  # Runner signs every non-negative-key vector with one of these keypairs. The
+  # agent's verifier MUST treat these keyids as a registered test counterparty
+  # whose JWKS contains the corresponding public keys with
+  # adcp_use: "request-signing". Private keys for signing live in keys.json
+  # under `_private_d_for_test_only`.
+  - keyid: test-ed25519-2026
+    alg: ed25519
+    jwks_source: /compliance/{version}/test-vectors/request-signing/keys.json
+  - keyid: test-es256-2026
+    alg: ecdsa-p256-sha256
+    jwks_source: /compliance/{version}/test-vectors/request-signing/keys.json
+
+stateful_vector_contract:
+  replay_window:
+    # Vector 016-replayed-nonce.
+    #
+    # The runner provokes the replay rejection by sending the same signed
+    # request twice in sequence. The agent MUST accept the first submission
+    # (standard positive path) and reject the second with
+    # request_signature_replayed at checklist step 12.
+    #
+    # The agent's replay-cache TTL for this test counterparty MUST be at least
+    # `min_replay_ttl_seconds`, which is strictly greater than
+    # `max_interval_seconds` to absorb clock skew between runner and agent and
+    # scheduler jitter on either side. Otherwise the cache entry for the first
+    # request may evict before the second arrives and the vector will pass
+    # spuriously (i.e., both requests accepted = no replay rejection). The
+    # runner's own interval between the two submissions MUST NOT exceed
+    # `max_interval_seconds`.
+    #
+    # This supersedes vector 016's `test_harness_state.replay_cache_entries`
+    # for black-box mode. In white-box mode, the harness MAY inject the cache
+    # entry directly and skip the first request.
+    vector_id: 016-replayed-nonce
+    black_box_behavior: repeat_request
+    max_interval_seconds: 5
+    min_replay_ttl_seconds: 10
+
+  revocation:
+    # Vector 017-key-revoked.
+    #
+    # The runner cannot revoke a key on the agent's side. The agent MUST
+    # pre-configure its revocation list with `test-revoked-2026` before the
+    # negative phase runs. The runner signs vector 017 with this keyid and
+    # expects request_signature_key_revoked at checklist step 9.
+    #
+    # A dedicated revoked keypair (rather than reusing a runner signing key)
+    # keeps positive vectors and vector 017 independent: the positive phase
+    # remains runnable after vector 017 is graded.
+    vector_id: 017-key-revoked
+    pre_revoked_keyid: test-revoked-2026
+
+  rate_abuse:
+    # Vector 020-rate-abuse (checklist step 9a).
+    #
+    # The runner sends N+1 distinct-nonce requests signed by the same keyid
+    # within the window. The agent MUST reject the (N+1)th with
+    # request_signature_rate_abuse once the per-keyid cap is hit.
+    #
+    # `grading_target_per_keyid_cap_requests` is the cap the runner will
+    # target during grading — NOT a production recommendation. Agents MAY
+    # configure a lower cap for the test-kit counterparty only so grading
+    # finishes in a reasonable time. Production caps MUST follow the spec
+    # recommendation at docs/building/implementation/security.mdx
+    # §per-keyid cap (at least 1,000,000 entries per keyid). Implementers
+    # copying a value from this file into production code SHOULD use
+    # `production_min_per_keyid_cap_requests` below as the floor, not
+    # `grading_target_per_keyid_cap_requests`.
+    vector_id: 020-rate-abuse
+    grading_target_per_keyid_cap_requests: 100
+    production_min_per_keyid_cap_requests: 1000000
+    window_seconds: 60
+
+scope:
+  in_scope: |
+    - Keyids the runner will sign with and their JWKS source.
+    - Agent-side preconditions for each stateful negative vector.
+    - Grading-time cap the runner will target for rate-abuse grading (NOT a
+      production recommendation; see rate_abuse block).
+    - Minimum replay-cache TTL so the replay-window contract is reliable.
+    - Black-box vs. white-box harness mode selection.
+    - Endpoint scope (sandbox only — see endpoint_scope).
+  out_of_scope: |
+    - Specific error-code strings — those live in each vector's
+      expected_outcome.error_code and are graded byte-for-byte.
+    - Checklist step numbers — informational only; grading is on the error
+      code, not the step.
+    - Pre-signed Signature bytes in the vectors — unchanged by this contract.
+      Black-box runners re-sign dynamically; pre-signed bytes remain valid
+      for white-box cross-SDK byte-equivalence checks.
+    - The agent's internal replay TTL or cap storage mechanism — the contract
+      specifies observable behavior, not implementation.
+    - Production verifier configuration — this contract configures a test
+      counterparty only.
+
+references:
+  universal_storyboard: static/compliance/source/universal/signed-requests.yaml
+  test_vectors: /compliance/{version}/test-vectors/request-signing/
+  verifier_checklist: /docs/building/by-layer/L1/security.mdx#verifier-checklist-requests
+  runner_implementation: https://github.com/adcontextprotocol/adcp-client/issues/585

package/compliance/cache/3.1.0-rc.2/test-kits/single-side-trust-runner.yaml

@@ -0,0 +1,294 @@
+# Single-Side Trust Runner — Harness Contract Test Kit
+#
+# Applies to:
+#   - protocols/brand/scenarios/single_side_trust_extension.yaml
+#
+# The single-side-trust scenario is a partner-conformance red test. Unlike
+# every other storyboard in the corpus today — which grades an agent serving
+# verify_brand_claim — this scenario grades a CONSUMER of verify_brand_claim.
+# The subject under test is a partner that may extend governance trust (auto-
+# provision a member account, propagate billable seat inclusion, inherit
+# governance posture) based on what verify_brand_claim returns. The red test
+# asserts the asymmetric trust rule from
+# /docs/brand-protocol/tasks/verify_brand_claim §"The trust rule — two calls,
+# not one": a single signed `owned` response is NOT trust-extending.
+#
+# This is a framework extension. The conformance corpus today drives an agent
+# under test and grades its response. Grading a consumer-side trust decision
+# requires:
+#
+#   1. The runner hosts fixture brand-agents (a malicious house signing
+#      `owned` for relationships it does not legitimately have) plus the
+#      static brand.json files that should — under the spec — fail to
+#      reciprocate.
+#
+#   2. The runner exercises the partner under test through whatever surface
+#      that partner exposes for "evaluate a verify_brand_claim response and
+#      decide whether to extend trust" — the partner advertises this surface
+#      via comply_test_controller (scenario name
+#      `evaluate_verify_brand_claim_trust_extension`, defined below). Partners
+#      that do not advertise it grade the scenario `not_applicable`.
+#
+#   3. The runner queries the partner's comply_test_controller
+#      `query_upstream_traffic` to confirm:
+#        - The partner DID call leaf-side reciprocation (positive assertion:
+#          `min_count: 1` against a `GET *.well-known/brand.json` pattern on
+#          the leaf, OR a verify_brand_claim call with `claim_type: "parent"`
+#          on a leaf-side brand-agent — when one exists).
+#        - The partner did NOT extend trust (negative assertion: `min_count: 0`
+#          against governance-trust-extension endpoint patterns the partner
+#          declares via this contract).
+#
+# Runner-side implementation is pending. Until adcp-client lands the consumer-
+# under-test dispatch primitive, scenario steps grade `not_applicable` via
+# their `requires_contract: single_side_trust_runner` declaration. This file
+# documents the contract so the dispatch can be implemented against a stable
+# fixture surface.
+
+id: single_side_trust_runner
+applies_to:
+  protocol_scenarios:
+    - single_side_trust_extension
+
+description: |
+  Coordination contract between a black-box runner and a partner under test
+  whose responsibility is to evaluate verify_brand_claim responses and decide
+  whether to extend governance trust. The runner hosts the malicious-house
+  fixture brand-agent and the non-reciprocating leaf brand.json. The partner
+  receives a `verify_brand_claim` invocation through its comply_test_controller
+  `evaluate_verify_brand_claim_trust_extension` scenario, performs whatever
+  verification the spec mandates, and exposes its outbound HTTP traffic via
+  `query_upstream_traffic` for the runner to assert against.
+
+endpoint_scope: sandbox
+# The partner under test executes a real verify-and-decide pipeline against
+# the runner-hosted fixtures. Partners MUST NOT run this against any
+# production trust-extension surface; the runner's `owned` responses describe
+# fabricated relationships and any partner that auto-provisions on them in
+# production is the bug this test exists to surface.
+
+harness_mode: black_box
+
+# --- Fixture brand-agents and static documents the runner hosts ---
+#
+# The runner stands up three fixture surfaces. All use the IANA-reserved
+# `.example` TLD. The runner is the authoritative origin for every URL below
+# during a test run; partners under test resolve these names against the
+# runner's DNS or hosts override per the operator's harness configuration.
+
+fixtures:
+  malicious_house:
+    # A brand-agent at a runner-controlled domain that signs `owned` for
+    # arbitrary subsidiary / property / trademark claims. The agent's JWKS is
+    # published at the same domain so signature verification succeeds — the
+    # point of the red test is that signature validity does NOT confer
+    # relationship trust without reciprocation.
+    domain: "malicious-house.example"
+    brand_agent_url: "https://malicious-house.example/agents/brand"
+    jwks_uri: "https://malicious-house.example/.well-known/jwks.json"
+    response_signing_keyid: "test-malicious-house-2026"
+    # When the runner asks the malicious house's brand-agent any of the
+    # supported claim types, it returns `owned` with a freshly signed
+    # response. Behavior matrix:
+    response_matrix:
+      - claim_type: subsidiary
+        # Any `claim.subsidiary_domain` returns owned, regardless of whether
+        # the leaf actually claims this house as its parent.
+        status: owned
+        details:
+          brand_id: "fabricated_subsidiary"
+      - claim_type: property
+        # Any `claim.property.identifier` returns owned, regardless of the
+        # real registrant of that property.
+        status: owned
+        details:
+          relationship: "owned"
+      - claim_type: trademark
+        # Returns `licensed_in` claiming a licensor the runner ALSO hosts as
+        # a non-reciprocating fixture (see `non_reciprocating_licensor`
+        # below).
+        status: licensed_in
+        details:
+          matched_registration: "fabricated-mark-001"
+          licensor_domain: "non-reciprocating-licensor.example"
+
+  non_reciprocating_leaf:
+    # A static brand.json hosted at a runner-controlled domain. The brand
+    # declares NO `house_domain` (or declares a different parent). No
+    # brand-agent is advertised at this domain — reciprocation requires a
+    # static crawl. This is the "leaf does not agree" half of the asymmetric
+    # trust model.
+    domain: "independent-leaf.example"
+    brand_json_url: "https://independent-leaf.example/.well-known/brand.json"
+    brand_json_shape:
+      # The leaf is standalone — no `house_domain` field at all. A spec-
+      # conformant consumer that crawls this MUST conclude no relationship
+      # exists with malicious-house.example.
+      brand_id: "independent_leaf"
+      names:
+        - { locale: "en", value: "Independent Leaf" }
+      house_domain: null
+
+  non_reciprocating_licensor:
+    # A static brand.json for the trademark licensed_in variant. The
+    # malicious house claims `licensed_in` from this licensor; the licensor
+    # does NOT publish a matching `licensed_out` for the mark. Per the
+    # trademark trust rule, partners SHOULD treat `licensed_in` as
+    # unverified until the licensor reciprocates.
+    domain: "non-reciprocating-licensor.example"
+    brand_json_url: "https://non-reciprocating-licensor.example/.well-known/brand.json"
+    brand_json_shape:
+      brand_id: "non_reciprocating_licensor"
+      names:
+        - { locale: "en", value: "Non-Reciprocating Licensor" }
+      # No trademarks[] entry naming malicious-house.example as a licensee.
+      trademarks: []
+
+  non_reciprocating_property_owner:
+    # A static brand.json for the property variant. The runner exposes a
+    # property identifier (a website) the malicious house claims `owned`,
+    # but the property's actual owning brand publishes a brand.json that
+    # does NOT include the property in its `properties[]`.
+    domain: "real-property-owner.example"
+    brand_json_url: "https://real-property-owner.example/.well-known/brand.json"
+    property_under_test:
+      type: "website"
+      identifier: "real-property-owner.example"
+    brand_json_shape:
+      brand_id: "real_property_owner"
+      names:
+        - { locale: "en", value: "Real Property Owner" }
+      # The property is listed here under the real owner, NOT under the
+      # malicious house's `owned` claim.
+      properties:
+        - { type: "website", identifier: "real-property-owner.example" }
+
+# --- Consumer-under-test dispatch contract ---
+#
+# The runner drives the partner under test via its comply_test_controller.
+# The partner MUST advertise this scenario in its `list_scenarios` response
+# to participate; partners that do not advertise it grade the scenario
+# `not_applicable` (not failed) — the scenario is opt-in by partner
+# capability, matching the upstream_traffic convention documented in
+# storyboard-schema.yaml > authored_check_kinds.
+#
+# The contract is forward-looking: today no partner implements this
+# controller scenario, and runner support is pending. Partners that want to
+# claim conformance against this red test register support here.
+
+consumer_test_controller_scenario:
+  name: evaluate_verify_brand_claim_trust_extension
+  request_shape:
+    # Variant the runner is exercising.
+    variant: subsidiary | property | trademark_licensed_in
+    # The malicious-house brand-agent URL the partner should call
+    # verify_brand_claim against.
+    brand_agent_url: "<runner-supplied URL from fixtures.malicious_house>"
+    # The claim payload the partner should pass.
+    claim:
+      # Shape varies by variant — matches verify-brand-claim-request.json
+      # discriminator arms.
+      claim_type: subsidiary | property | trademark
+      claim: { ... }
+    # Optional account context. Partners that only auto-provision under
+    # an authenticated account context use this to scope the test to that
+    # path.
+    requesting_account:
+      brand:
+        domain: "<runner-supplied partner-controlled account domain>"
+      operator: "<runner-supplied operator>"
+
+  expected_partner_behavior:
+    # The partner MUST call verify_brand_claim on brand_agent_url.
+    # The partner MUST then EITHER:
+    #   (a) crawl the leaf's static brand.json for reciprocation, OR
+    #   (b) call a leaf-side brand-agent's verify_brand_claim with
+    #       claim_type: "parent" — if the leaf advertises one (in this
+    #       contract's fixtures, none does, forcing path (a)).
+    # The partner MUST NOT extend governance trust on the strength of the
+    # malicious-house's signed `owned` alone.
+
+# --- Upstream-traffic assertions the runner applies ---
+#
+# After dispatching the scenario, the runner queries the partner's
+# comply_test_controller `query_upstream_traffic` and applies these
+# assertions. See storyboard-schema.yaml > `upstream_traffic` for the
+# check primitives.
+
+upstream_traffic_contract:
+  reciprocation_call_observed:
+    # POSITIVE assertion. The partner MUST have called either the leaf's
+    # static brand.json or a leaf-side brand-agent's verify_brand_claim
+    # (claim_type: "parent" / property crawl / licensor reciprocation,
+    # depending on variant).
+    min_count: 1
+    endpoint_pattern_by_variant:
+      subsidiary: "GET *://independent-leaf.example/.well-known/brand.json"
+      property: "GET *://real-property-owner.example/.well-known/brand.json"
+      trademark_licensed_in: "GET *://non-reciprocating-licensor.example/.well-known/brand.json"
+
+  trust_extension_not_taken:
+    # NEGATIVE assertion. The partner MUST NOT have extended governance
+    # trust on the malicious house's response alone. Partners declare the
+    # endpoint patterns that represent trust-extension side effects in
+    # their own conformance config; the runner exercises a closed set:
+    min_count: 0
+    candidate_endpoint_patterns:
+      # The partner is configured (out of band, when registering for this
+      # red test) to surface trust-extension side effects through one of
+      # these well-known patterns OR through a partner-declared list
+      # carried alongside its list_scenarios response. The runner asserts
+      # NONE of these fire during the test window.
+      - "POST */governance/auto-provision"
+      - "POST */accounts/auto-create-member"
+      - "POST */governance/contexts"
+      - "POST */billing/seats/auto-add"
+
+# --- Identifier echo for anti-façade ---
+#
+# To raise the bar against partners that satisfy the controller scenario
+# without actually performing the upstream calls, the runner injects a
+# load-bearing identifier (a per-run nonce) into the malicious-house's
+# response_signing keyid path or the claim payload's `subsidiary_brand_id`
+# field. The reciprocation call MUST carry that identifier verbatim — a
+# façade that fabricates an empty traffic record cannot satisfy the
+# `identifier_paths` echo check.
+
+identifier_echo:
+  nonce_injection_field:
+    subsidiary: "claim.subsidiary_brand_id"
+    property: "claim.property.identifier"
+    trademark_licensed_in: "claim.mark"
+  identifier_paths_in_reciprocation_request:
+    # The runner asserts the leaf-side fetch (whether brand.json crawl or
+    # verify_brand_claim with claim_type: "parent") carries the same
+    # identifier value at the appropriate path.
+    subsidiary: "<HTTP path component containing the leaf domain>"
+    property: "<HTTP path component containing the property identifier>"
+    trademark_licensed_in: "<HTTP path component containing the licensor domain>"
+
+scope:
+  in_scope: |
+    - Fixture brand-agent endpoints (URLs, JWKS, signing keyids).
+    - Fixture static brand.json shapes that fail reciprocation.
+    - The consumer-test-controller scenario name and request shape the
+      runner uses to dispatch the partner under test.
+    - The endpoint patterns the runner asserts on via query_upstream_traffic.
+    - Identifier echo paths for anti-façade verification.
+  out_of_scope: |
+    - The partner's specific trust-extension implementation (account-
+      auto-provisioning, governance-context creation, billable seat
+      inclusion, etc.). The contract names the side-effect patterns it
+      asserts on; how the partner internally wires trust extension is
+      partner-specific.
+    - Runner-side dispatch implementation. Tracked separately when
+      partner adoption reaches a quorum — until then, scenario steps
+      grade not_applicable via `requires_contract`.
+    - Real-world brand domains. Every fixture domain is on the
+      IANA-reserved `.example` TLD.
+
+references:
+  scenario: static/compliance/source/protocols/brand/scenarios/single_side_trust_extension.yaml
+  task_spec: /brand-protocol/tasks/verify_brand_claim
+  trust_model: /brand-protocol/brand-json#agent-augmented-verification
+  source_issue: https://github.com/adcontextprotocol/adcp/issues/4597