@adcp/sdk 7.11.0 → 7.11.2

package/compliance/cache/{3.0.12.previous → 3.0.18}/universal/idempotency.yaml

@@ -2,7 +2,7 @@ id: idempotency
 version: "1.0.0"
 title: "Idempotency enforcement"
 category: core
-summary: "Validates that mutating requests enforce idempotency_key — replays return cached responses, key reuse with a different payload returns IDEMPOTENCY_CONFLICT, and fresh keys create new resources."
+summary: "Validates that mutating requests enforce idempotency_key — replays return cached responses, key reuse with a different payload returns IDEMPOTENCY_CONFLICT, fresh keys create new resources, and concurrent retries with the same key produce exactly one resource (first-insert-wins under rule 9)."
 track: core
 
 # Cross-step assertions (adcontextprotocol/adcp#2639). These convert two
@@ -33,12 +33,12 @@ invariants:
 
 narrative: |
   Every mutating request in AdCP carries an idempotency_key so buyers can safely retry
-  after network errors without double-booking. This storyboard walks through the four
+  after network errors without double-booking. This storyboard walks through the
   observable behaviors a seller MUST implement:
 
   1. First call with a fresh key is processed normally and returns the canonical response.
   2. Replay with the same key and an equivalent payload returns the cached response
-     without re-executing side effects (same media_buy_id, no new webhooks fired).
+     without re-executing resource mutations (same media_buy_id).
   3. Replay with the same key but a materially different payload is rejected with
      IDEMPOTENCY_CONFLICT. The buyer has clearly reused a key by mistake.
   4. A request with a different key is treated as a new request, even if the payload
@@ -55,6 +55,12 @@ narrative: |
      key_reuse_conflict. An end-to-end phase that drives a deterministic terminal
      error and replays the key is deferred pending a generic force-error controller
      verb (see adcontextprotocol/adcp#2760).
+  6. Concurrent retries with the same key produce exactly one resource. The seller
+     MAY wait-and-replay or return IDEMPOTENCY_IN_FLIGHT — both are conformant under
+     security.mdx#idempotency rule 9 (first-insert-wins) as long as the resolved
+     response set converges on a single media_buy_id. Graded via the
+     parallel_dispatch_runner contract; runners without parallel-dispatch skip
+     this phase with a stable not_applicable marker.
 
   Missing idempotency_key on any mutating request MUST be rejected with INVALID_REQUEST.
   Sellers MUST declare adcp.idempotency on get_adcp_capabilities — either
@@ -63,16 +69,28 @@ narrative: |
   validates the supported: true behavior; sellers declaring supported: false
   MUST skip this storyboard (they have no replay window to test).
 
-  **Cache-growth defense (MUST, not yet runtime-graded).** Per
+  **Cache-growth defense (partial runtime grading).** Per
   security.mdx bullet 8 on the idempotency section, sellers MUST apply per-agent
   rate limits on idempotency-cache inserts and MUST return RATE_LIMITED when the
   per-agent insert rate exceeds the configured ceiling. The recommended
   first-deployment ceiling is 60 inserts/sec sustained per agent (3,600/min)
   with burst allowance to 300/sec over rolling 10-second windows. This storyboard
-  does not yet drive the high-volume burst that would exercise the ceiling —
-  runtime grading is tracked as a follow-up once a burst-runner test-kit
-  contract is defined. Sellers SHOULD self-attest to this requirement until the
-  runtime phase lands.
+  does NOT attest the threshold itself — burst-volume measurement is
+  structurally non-deterministic in CI (runner CPU, network jitter, agent
+  cold-start) and better evaluated via operator-side load testing. What it
+  DOES attest, via the `rate_limit_replay_invariant` phase below, is the
+  invariant that matters most for client safety: a `RATE_LIMITED` response on
+  insert MUST NOT be cached as the canonical idempotency replay for that
+  key. Otherwise a client retrying past `retry_after` receives the cached
+  rate-limit error forever, defeating the point of `retry_after`. The
+  threshold (60/300 req/sec) remains seller self-attestation pending
+  operator-side tooling.
+
+  **Webhook side effects are graded separately.** A replay MUST NOT duplicate
+  outbound webhook fires, but observing that side effect requires a runner-hosted
+  webhook receiver. The webhook-specific replay assertion lives in
+  universal/webhook-emission.yaml so this core idempotency storyboard remains
+  runnable by agents and runners that do not host receiver URLs.
 
 agent:
   interaction_model: media_buy_seller
@@ -87,10 +105,26 @@ caller:
 
 prerequisites:
   description: |
-    No special prerequisites. The storyboard uses create_media_buy as the canonical
-    mutating request. Sellers that do not support create_media_buy SHOULD still pass
-    idempotency compliance on whichever mutating task they do implement.
+    The runner seeds the product and pricing option referenced by the
+    create_media_buy payloads below. The storyboard uses create_media_buy as the
+    canonical mutating request. Sellers that do not support create_media_buy SHOULD
+    still pass idempotency compliance on whichever mutating task they do implement.
   test_kit: "test-kits/acme-outdoor.yaml"
+  controller_seeding: true
+
+fixtures:
+  products:
+    - product_id: "test-product"
+      delivery_type: "non_guaranteed"
+      channels: ["display"]
+      format_ids:
+        - id: "display_300x250"
+  pricing_options:
+    - product_id: "test-product"
+      pricing_option_id: "test-pricing"
+      pricing_model: "cpm"
+      currency: "USD"
+      floor_price: 1.0
 
 phases:
   - id: capability_discovery
@@ -106,8 +140,11 @@ phases:
           Call get_adcp_capabilities and verify adcp.idempotency is declared with
           supported: true and a replay_ttl_seconds value. The block is REQUIRED —
           clients MUST NOT fall back to an assumed default, and a seller that omits
-          it is non-compliant. Sellers running this storyboard must declare
-          supported: true; supported: false sellers skip this storyboard entirely.
+          it is non-compliant. Sellers running this storyboard should declare
+          supported: true; sellers declaring supported: false pass this step with
+          advisory findings and cascade-skip the remaining idempotency phases (they
+          have no replay window to test). The full storyboard-level skip gate is
+          pending runner support for a precondition mechanism (adcontextprotocol/adcp#3919).
         task: get_adcp_capabilities
         schema_ref: "protocol/get-adcp-capabilities-request.json"
         response_schema_ref: "protocol/get-adcp-capabilities-response.json"
@@ -130,9 +167,15 @@ phases:
           - check: field_value
             path: "adcp.idempotency.supported"
             value: true
+            severity: advisory
+            permanent_advisory:
+              reason: "supported: false is a valid declaration meaning the agent does not deduplicate retries; these agents are not applicable for this storyboard and must not be failed. The check is advisory so capability_discovery passes cleanly for supported: false agents and downstream phases cascade-skip via missing_tool (not_applicable) rather than prerequisite_failed. Full storyboard-level skip (for agents that implement create_media_buy but declare supported: false) requires runner support for a precondition gate (see adcontextprotocol/adcp#3919)."
             description: "Agent declares supported: true for this storyboard (supported: false sellers skip)"
           - check: field_present
             path: "adcp.idempotency.replay_ttl_seconds"
+            severity: advisory
+            permanent_advisory:
+              reason: "replay_ttl_seconds is only required when adcp.idempotency.supported: true; supported: false agents correctly omit this field and must not be penalised for its absence."
             description: "Agent declares replay window TTL (required when supported: true)"
 
           - check: field_present
@@ -142,6 +185,13 @@ phases:
             path: "context.correlation_id"
             value: "idempotency--get_capabilities"
             description: "Context correlation_id returned unchanged"
+        context_outputs:
+          - name: idempotency_supported
+            path: "adcp.idempotency.supported"
+          - name: replay_key
+            generate: uuid_v4
+          - name: fresh_key
+            generate: uuid_v4
 
   - id: missing_key
     title: "Reject requests without idempotency_key"
@@ -188,8 +238,8 @@ phases:
             operator: "pinnacle-agency.example"
           brand:
             domain: "acmeoutdoor.example"
-          start_time: "2026-05-01T00:00:00Z"
-          end_time: "2026-05-31T23:59:59Z"
+          start_time: "asap"
+          end_time: "2099-09-30T23:59:59Z"
           packages:
             - product_id: "test-product"
               budget: 5000
@@ -227,12 +277,9 @@ phases:
          payload would break the at-most-once guarantee; silently returning the old
          response would hide a real bug in the buyer's retry logic.
 
-      Both branches share a single `$generate:uuid_v4#replay_key` placeholder. They
-      live in the same phase so the alias resolves to one UUID across all four steps
-      — the seller sees one cached idempotency entry that the conflict step probes
-      with a different body. Splitting these into separate phases would reset the
-      alias cache at the phase boundary (adcp-client#1657) and mint a fresh UUID for
-      the conflict step, defeating the test.
+      Both branches share the generated `$context.replay_key` value captured
+      during capability discovery. The seller sees one cached idempotency entry
+      that the conflict step probes with a different body.
 
     steps:
       - id: create_media_buy_initial
@@ -249,36 +296,24 @@ phases:
         context_outputs:
           - name: initial_media_buy_id
             path: "media_buy_id"
-          - name: idempotency_key_a
-            path: "idempotency_key"
         expected: |
           Create a new media buy and return a media_buy_id. This establishes the
           canonical response that subsequent replays must match.
 
         sample_request:
-          idempotency_key: "$generate:uuid_v4#replay_key"
+          idempotency_key: "$context.replay_key"
           account:
             brand:
               domain: "acmeoutdoor.example"
             operator: "pinnacle-agency.example"
           brand:
             domain: "acmeoutdoor.example"
-          start_time: "2026-06-01T00:00:00Z"
-          end_time: "2026-06-30T23:59:59Z"
+          start_time: "asap"
+          end_time: "2099-07-31T23:59:59Z"
           packages:
             - product_id: "test-product"
               budget: 5000
               pricing_option_id: "test-pricing"
-          # Both the initial call and the replay below use the SAME webhook URL
-          # so the canonical payload hash matches across the two calls. A
-          # different URL between the two requests would hash differently and
-          # trip IDEMPOTENCY_CONFLICT instead of exercising replay. The URL
-          # template resolves against the runner's ephemeral webhook receiver
-          # (webhook_receiver_runner contract); runners without a receiver
-          # grade `no_duplicate_webhooks_on_replay` as not_applicable.
-          push_notification_config:
-            url: "{{runner.webhook_url:create_media_buy_initial}}"
-
           context:
             correlation_id: "idempotency--create_media_buy_initial"
         validations:
@@ -312,8 +347,8 @@ phases:
         narrative: |
           Re-send the exact same create_media_buy request — same idempotency_key,
           same payload, same everything. The seller MUST return the same media_buy_id
-          from the prior step. It MUST NOT create a second media buy or fire a
-          second set of webhooks. This is the whole point of idempotency_key.
+          from the prior step. It MUST NOT create a second media buy. This is
+          the whole point of idempotency_key.
         task: create_media_buy
         schema_ref: "media-buy/create-media-buy-request.json"
         response_schema_ref: "media-buy/create-media-buy-response.json"
@@ -323,36 +358,22 @@ phases:
         expected: |
           Return the cached response from the initial request:
           - media_buy_id: same as $context.initial_media_buy_id
-          - No new side effects (no duplicate webhooks, no new audit log entry)
-
-          Programmatic verification of "no duplicate webhooks" runs in the next step
-          (no_duplicate_webhooks_on_replay) when the storyboard is driven by a runner
-          that implements the webhook_receiver_runner contract. Runners without a
-          webhook receiver grade that step as not_applicable — agents MAY still claim
-          idempotency compliance, but the replay-side-effect invariant is only
-          programmatically graded when the webhook_callbacks specialism is also in
-          scope.
+          - No new side effects (no duplicate audit log entry or resource mutation)
 
         sample_request:
-          idempotency_key: "$generate:uuid_v4#replay_key"
+          idempotency_key: "$context.replay_key"
           account:
             brand:
               domain: "acmeoutdoor.example"
             operator: "pinnacle-agency.example"
           brand:
             domain: "acmeoutdoor.example"
-          start_time: "2026-06-01T00:00:00Z"
-          end_time: "2026-06-30T23:59:59Z"
+          start_time: "asap"
+          end_time: "2099-07-31T23:59:59Z"
           packages:
             - product_id: "test-product"
               budget: 5000
               pricing_option_id: "test-pricing"
-          # Byte-identical to the initial call above — same URL, same step id
-          # token — so the canonical payload hash matches and the request
-          # lands on the replay branch rather than IDEMPOTENCY_CONFLICT.
-          push_notification_config:
-            url: "{{runner.webhook_url:create_media_buy_initial}}"
-
           context:
             correlation_id: "idempotency--create_media_buy_replay"
         validations:
@@ -378,53 +399,6 @@ phases:
             value: "idempotency--create_media_buy_replay"
             description: "Context correlation_id returned unchanged"
 
-      - id: no_duplicate_webhooks_on_replay
-        title: "No duplicate webhooks fired across initial + replay"
-        narrative: |
-          The central invariant of idempotency: replaying with the same key MUST
-          NOT produce duplicate side effects. Webhook emission is the observable
-          side effect most likely to leak if the seller re-executes on replay
-          instead of returning cached state.
-
-          This step requires the storyboard runner to implement the
-          `webhook_receiver_runner` contract at
-          `test-kits/webhook-receiver-runner.yaml`. Runners without a webhook
-          receiver skip this step with a stable not_applicable marker; the
-          replay-side-effect invariant then relies on the next phase's cached-
-          response assertions plus manual audit of the seller's webhook
-          delivery history.
-
-          When the receiver IS in scope, the runner counts webhooks arriving at
-          {{runner.webhook_url:create_media_buy_initial}} across the initial
-          call's window AND the replay call's window. A conformant seller emits
-          webhooks only on the first execution; a non-conformant seller that
-          re-executes on replay emits a second set, catchable only by live
-          observation.
-        task: expect_webhook
-        # `triggered_by` points at the initial call (not the replay) because the
-        # default filter resolves `step_id` + `operation_id` from `stepOperationIds`
-        # for that step — which is populated when the initial sample_request's
-        # `push_notification_config.url` expanded `{{runner.webhook_url:create_media_buy_initial}}`
-        # above. The execution-order wait still spans the replay window: this
-        # step runs after `create_media_buy_replay` in YAML order and `wait_all`
-        # drains the full `timeout_seconds` so any webhook re-fired by the
-        # replay is captured and counted against the cap below. A non-conformant
-        # seller that re-executes on replay would deliver a second webhook with
-        # a fresh idempotency_key and trip `duplicate_webhook_on_replay`.
-        triggered_by: create_media_buy_initial
-        timeout_seconds: 30
-        expect_max_deliveries_per_logical_event: 1
-        requires_contract: webhook_receiver_runner
-        stateful: true
-        expected: |
-          At most one logical webhook event delivered for the create_media_buy
-          operation across both the initial and replay windows. If the runner
-          observes a second webhook delivery tagged with a distinct
-          idempotency_key but the same media_buy_id/operation_id, the seller is
-          re-executing on replay and the step fails with
-          duplicate_webhook_on_replay. Not_applicable when the runner does not
-          host a webhook receiver.
-
       - id: create_media_buy_conflict
         title: "Same key, different payload returns IDEMPOTENCY_CONFLICT"
         narrative: |
@@ -434,12 +408,8 @@ phases:
           IDEMPOTENCY_CONFLICT. CONFLICT is accepted as a fallback for sellers
           that haven't adopted the new error code yet.
 
-          This step shares the `$generate:uuid_v4#replay_key` alias with the
-          initial and replay steps above, so the runner injects the same UUID
-          on the wire. Lives in the same phase as those steps because the
-          runner's alias cache resets at phase boundaries (adcp-client#1657);
-          a separate phase would mint a fresh UUID and the seller would treat
-          the call as a new request rather than a conflicting key reuse.
+          This step shares `$context.replay_key` with the initial and replay
+          steps above, so the runner injects the same UUID on the wire.
         task: create_media_buy
         schema_ref: "media-buy/create-media-buy-request.json"
         response_schema_ref: "media-buy/create-media-buy-response.json"
@@ -454,15 +424,15 @@ phases:
           - recovery: correctable (buyer should use a fresh UUID v4)
 
         sample_request:
-          idempotency_key: "$generate:uuid_v4#replay_key"
+          idempotency_key: "$context.replay_key"
           account:
             brand:
               domain: "acmeoutdoor.example"
             operator: "pinnacle-agency.example"
           brand:
             domain: "acmeoutdoor.example"
-          start_time: "2026-06-01T00:00:00Z"
-          end_time: "2026-09-30T23:59:59Z"
+          start_time: "asap"
+          end_time: "2099-09-30T23:59:59Z"
           packages:
             - product_id: "test-product"
               budget: 25000
@@ -517,15 +487,15 @@ phases:
           This confirms the seller treats the fresh key as a new request.
 
         sample_request:
-          idempotency_key: "$generate:uuid_v4#fresh_key"
+          idempotency_key: "$context.fresh_key"
           account:
             brand:
               domain: "acmeoutdoor.example"
             operator: "pinnacle-agency.example"
           brand:
             domain: "acmeoutdoor.example"
-          start_time: "2026-06-01T00:00:00Z"
-          end_time: "2026-06-30T23:59:59Z"
+          start_time: "asap"
+          end_time: "2099-07-31T23:59:59Z"
           packages:
             - product_id: "test-product"
               budget: 5000
@@ -555,21 +525,139 @@ phases:
             value: "idempotency--create_media_buy_fresh_key"
             description: "Context correlation_id returned unchanged"
 
+  - id: concurrent_retry
+    title: "Concurrent retries with the same key produce exactly one resource"
+    narrative: |
+      A buyer's transport timeout fires before the seller's downstream call
+      returns; the buyer retries with the same idempotency_key while the
+      first request is still executing. Per L1/security.mdx#idempotency
+      rule 9 (first-insert-wins), the seller MUST resolve the race
+      deterministically — exactly one resource is created, and both buyer
+      requests converge on the same media_buy_id.
+
+      The seller picks one of two policies and MUST behave consistently:
+
+      - **Wait-and-replay**: the second request blocks until the first
+        completes, then returns the cached response with `replayed: true`.
+      - **Reject-and-redirect**: the second request returns
+        `IDEMPOTENCY_IN_FLIGHT` immediately with
+        `error.details.retry_after`. The buyer retries with the same key
+        after the hint elapses and receives the cached response.
+
+      This phase exercises both policies via the parallel_dispatch_runner
+      contract: it fires two requests with the same fresh idempotency_key
+      and the same canonical payload, and asserts that the resolved
+      response set contains exactly one distinct media_buy_id. The runner
+      transparently resolves IDEMPOTENCY_IN_FLIGHT responses by retrying
+      with the same key after `retry_after` elapses, so the cross-response
+      check operates on the resolved set regardless of which policy the
+      seller adopted.
+
+      Runners without parallel-dispatch support skip this phase with a
+      stable not_applicable marker. The phase does not regress the
+      sequential idempotency contract — sellers that fail this phase due
+      to runner absence are still gradeable on the rest of the storyboard.
+
+    steps:
+      - id: create_media_buy_concurrent
+        title: "Two parallel create_media_buy calls with same key converge on one resource"
+        narrative: |
+          Fire two create_media_buy requests with the same fresh UUID v4
+          idempotency_key and byte-identical canonical payloads. The
+          runner dispatches them via its parallel-dispatch primitive (SDK
+          batch-call or distributed barrier), observes both responses,
+          resolves any IDEMPOTENCY_IN_FLIGHT to its eventual cached
+          response, and applies the cross-response checks below.
+
+          Programmatic verification of "exactly one resource created" runs
+          via `cross_response_count_distinct` on `media_buy_id`. A seller
+          that ignored rule 9 (re-executed both, two media buys created)
+          would produce cardinality 2 here and fail; a seller that
+          correctly serializes via first-insert-wins produces cardinality
+          1 regardless of which policy (wait-and-replay or
+          reject-and-redirect) it adopted.
+
+          The accompanying `cross_response_field_equal` check is redundant
+          when cardinality is 1, but documents the equivalence intent
+          directly: every dispatch's resolved response carries the same
+          media_buy_id.
+        task: create_media_buy
+        schema_ref: "media-buy/create-media-buy-request.json"
+        response_schema_ref: "media-buy/create-media-buy-response.json"
+        doc_ref: "/media-buy/task-reference/create_media_buy"
+        comply_scenario: idempotency_concurrent
+        stateful: true
+        requires_contract: parallel_dispatch_runner
+        parallel_dispatch:
+          count: 2
+          same_idempotency_key: true
+          barrier_timeout_ms: 5000
+        expected: |
+          After resolving any IDEMPOTENCY_IN_FLIGHT responses to their
+          eventual cached response, both dispatches' responses carry the
+          same media_buy_id. Exactly one media buy was created. The
+          resolved-response set has cardinality 1 on media_buy_id.
+
+          A seller adopting wait-and-replay returns the same response on
+          both dispatches directly. A seller adopting reject-and-redirect
+          returns the cached response on one dispatch and
+          IDEMPOTENCY_IN_FLIGHT on the other; the runner resolves the
+          latter by retrying with the same key after `retry_after` and
+          observes the cached response. Either path is conformant.
+
+        sample_request:
+          idempotency_key: "$generate:uuid_v4#concurrent_key"
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          brand:
+            domain: "acmeoutdoor.example"
+          start_time: "asap"
+          end_time: "2099-07-31T23:59:59Z"
+          packages:
+            - product_id: "test-product"
+              budget: 5000
+              pricing_option_id: "test-pricing"
+
+          context:
+            correlation_id: "idempotency--create_media_buy_concurrent"
+        validations:
+          - check: cross_response_count_distinct
+            path: "media_buy_id"
+            allowed_values: [1]
+            description: "Concurrent retries produced exactly one distinct media_buy_id across both dispatches (rule 9: first-insert-wins)"
+          - check: cross_response_field_equal
+            path: "media_buy_id"
+            description: "Both dispatches' resolved responses carry the same media_buy_id"
+
+        reviewer_checks:
+          - "Confirm the seller's claim-row / unique-constraint implementation backs the observed first-insert-wins behavior, rather than a happy-path race the test happened to avoid (review code or runbook describing the INSERT … ON CONFLICT pattern on the scope tuple)."
+          - "If the seller returned IDEMPOTENCY_IN_FLIGHT on the second dispatch, confirm `error.details.retry_after` was populated with a plausible value (seconds, integer, > 0) and that the cached response was available within the hint window. A seller that consistently overshoots retry_after produces brittle retry timing for buyers."
+          - "Confirm the seller's in-flight detection does NOT leak across (authenticated_agent, account_id) scope boundaries — probe with a stolen key from a different scope and verify the response shape and timing match the never-seen-key path."
+
   - id: verify_media_buy_count
     title: "Verify dedup actually happened"
     narrative: |
-      Call get_media_buys to confirm that only TWO media buys were created across
-      all prior steps — one for the initial + replay pair (same key, deduplicated)
-      and one for the fresh-key request. If the seller ignored the idempotency_key,
-      there would be three or more.
+      Call get_media_buys to confirm the two captured media_buy_ids both exist
+      and are distinct. `initial_media_buy_id` was created on the first
+      `create_media_buy` call and reused on the replay (same key, deduplicated);
+      `fresh_key_media_buy_id` was created on the fresh-key request. The
+      `concurrent_retry` phase (when graded) also exercises first-insert-wins
+      but its resource is not queried here — that phase has its own
+      cross-response cardinality check. If the seller ignored the idempotency_key
+      on the replay branch, `initial_media_buy_id` would not match across the
+      replay step's response.
 
     steps:
       - id: get_media_buys_dedup_check
-        title: "Confirm dedup via get_media_buys"
+        title: "Confirm captured media_buy_ids exist and are distinct"
         narrative: |
-          Query the two media_buy_ids captured from prior steps. Both should exist
-          and be distinct. This is an end-to-end verification that the replay did
-          not create a duplicate row.
+          Query the two captured media_buy_ids from prior steps. Both should
+          exist (proving fresh-key and initial calls each created a real
+          resource) and be distinct (proving the fresh-key call was treated as
+          a new request, not deduplicated against the initial). This is an
+          end-to-end verification that the replay did not create a duplicate row.
         task: get_media_buys
         schema_ref: "media-buy/get-media-buys-request.json"
         response_schema_ref: "media-buy/get-media-buys-response.json"
@@ -577,7 +665,7 @@ phases:
         comply_scenario: idempotency_verify
         stateful: true
         expected: |
-          Return exactly two media buys with the two captured IDs. Not three.
+          Return both captured media buys with the two captured IDs, distinct.
 
         sample_request:
           account:
@@ -604,3 +692,118 @@ phases:
             path: "context.correlation_id"
             value: "idempotency--get_media_buys_dedup_check"
             description: "Context correlation_id returned unchanged"
+
+  - id: rate_limit_replay_invariant
+    title: "RATE_LIMITED responses are not cached as idempotency replays"
+    narrative: |
+      Per L1/security.mdx#idempotency rule 3 ("Only successful responses
+      are cached") and bullet 8 (insert-rate ceiling): when the seller's
+      idempotency-cache insert-rate limiter trips and a request receives
+      `RATE_LIMITED`, the response MUST NOT be cached as the canonical
+      replay for that idempotency_key. A buyer retrying with the same key
+      after `error.details.retry_after` elapses MUST observe the real
+      handler result (success or a state-dependent error) — not a cached
+      rate-limit response that would persist for the entire replay TTL.
+
+      Without this invariant, `retry_after` is a meaningless signal: a
+      buyer who hits the limiter once would receive the cached
+      `RATE_LIMITED` on every subsequent retry until the replay window
+      expires, regardless of when the limiter actually cleared. The
+      invariant collapses a real client-safety regression into a
+      cross-response check.
+
+      This phase runs the `expect_rate_limit_not_replayed` task via the
+      `rate_limit_trip_runner` contract. The runner drives a sequential
+      fresh-key burst against `create_media_buy` until one request receives
+      `RATE_LIMITED`, captures that request's `idempotency_key`, waits the
+      response's `retry_after` seconds, then re-submits the captured key
+      with the same payload. The cross-response check
+      `replay_not_cached_rate_limit` fails if the replay response carries
+      `error.code = RATE_LIMITED` (i.e., the cached rate-limit was served
+      as the replay).
+
+      Runners without `rate_limit_trip_runner` skip this phase with a
+      stable `not_applicable` marker. Runners with the contract that
+      exhaust `max_attempts` without observing `RATE_LIMITED` also grade
+      `not_applicable` (reason: `rate_limit_not_triggered`) — a sandbox
+      limiter sitting above the contract's burst ceiling is not a seller
+      conformance fault, only a configuration choice that prevents the
+      invariant from being verified end-to-end.
+
+      The 60/300 req/sec ceiling itself is NOT attested here. Burst-volume
+      measurement is structurally non-deterministic in CI environments and
+      remains seller self-attestation per the cache-growth-defense note
+      above.
+
+    steps:
+      - id: expect_rate_limit_not_replayed
+        title: "Trip the limiter, replay the key after retry_after, assert the cached response is not RATE_LIMITED"
+        narrative: |
+          The runner fires up to `max_attempts` sequential `create_media_buy`
+          requests with fresh UUID v4 idempotency_keys and otherwise-identical
+          canonical payloads. On the first response with envelope error_code
+          = `RATE_LIMITED`, the runner captures the request's
+          `idempotency_key` and the response's `error.details.retry_after`,
+          waits that long (capped by `replay_max_wait_seconds`), and
+          re-submits the captured key with the same payload but a distinct
+          `context.correlation_id` for traceability.
+
+          The cross-response `replay_not_cached_rate_limit` check 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). The check
+          fails iff both responses carry `error.code = RATE_LIMITED` — that
+          is the cached-replay regression. Any other replay response shape
+          passes the invariant: either the handler succeeded (the seller
+          correctly re-executed against the cleared budget), or the handler
+          returned a different error (the seller correctly re-executed and
+          a state-dependent error fired).
+
+          The `trip_target_sample_request` below intentionally uses a
+          minimal `create_media_buy` payload — the goal of the burst is to
+          generate insert-rate pressure on the idempotency cache, not to
+          exercise the create flow itself. The replay payload is byte-
+          identical to the trip request to keep the canonical hash stable.
+        task: expect_rate_limit_not_replayed
+        requires_contract: rate_limit_trip_runner
+        rate_limit_trip:
+          trip_target_task: create_media_buy
+          max_attempts: 200
+          replay_max_wait_seconds: 30
+          trip_target_sample_request:
+            account:
+              brand:
+                domain: "acmeoutdoor.example"
+              operator: "pinnacle-agency.example"
+            brand:
+              domain: "acmeoutdoor.example"
+            start_time: "asap"
+            end_time: "2099-07-31T23:59:59Z"
+            packages:
+              - product_id: "test-product"
+                budget: 5000
+                pricing_option_id: "test-pricing"
+            context:
+              correlation_id: "idempotency--rate_limit_trip_request"
+        expected: |
+          One of two outcomes:
+
+          - At least one burst request returns `RATE_LIMITED`. The runner
+            captures the request's idempotency_key, waits the response's
+            retry_after, replays the captured key, and the replay response
+            does NOT carry `error.code = RATE_LIMITED`. The
+            `replay_not_cached_rate_limit` check passes.
+
+          - All `max_attempts` requests complete without producing
+            `RATE_LIMITED`. The step grades `not_applicable` with reason
+            `rate_limit_not_triggered`. The rest of the storyboard is
+            unaffected.
+
+        validations:
+          - check: replay_not_cached_rate_limit
+            description: "RATE_LIMITED response on rate-limit trip was not cached as the idempotency replay for the same key"
+
+        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_LIMITED 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."