@adcp/sdk 7.11.1 → 7.11.2

package/compliance/cache/{3.1.0-rc.2 → 3.0.18.previous}/universal/idempotency.yaml

@@ -38,7 +38,7 @@ narrative: |
 
   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
@@ -86,6 +86,12 @@ narrative: |
   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
   capabilities:
@@ -99,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
@@ -166,6 +188,10 @@ phases:
         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"
@@ -212,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
@@ -251,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
@@ -278,29 +301,19 @@ phases:
           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:
@@ -334,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"
@@ -345,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:
@@ -400,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: |
@@ -456,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"
@@ -476,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
@@ -539,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
@@ -665,8 +613,8 @@ phases:
             operator: "pinnacle-agency.example"
           brand:
             domain: "acmeoutdoor.example"
-          start_time: "2026-07-01T00:00:00Z"
-          end_time: "2026-07-31T23:59:59Z"
+          start_time: "asap"
+          end_time: "2099-07-31T23:59:59Z"
           packages:
             - product_id: "test-product"
               budget: 5000
@@ -829,8 +777,8 @@ phases:
               operator: "pinnacle-agency.example"
             brand:
               domain: "acmeoutdoor.example"
-            start_time: "2026-07-01T00:00:00Z"
-            end_time: "2026-07-31T23:59:59Z"
+            start_time: "asap"
+            end_time: "2099-07-31T23:59:59Z"
             packages:
               - product_id: "test-product"
                 budget: 5000

package/compliance/cache/{3.1.0-rc.2 → 3.0.18.previous}/universal/schema-validation.yaml

@@ -32,8 +32,26 @@ caller:
 
 prerequisites:
   description: |
-    The caller needs a brand identity for product discovery requests.
+    The caller needs a brand identity for product discovery requests. The runner
+    also seeds the product and pricing option referenced by the temporal
+    create_media_buy requests so date validation is isolated from catalog
+    availability.
   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
@@ -353,8 +371,8 @@ phases:
               domain: "acmeoutdoor.example"
             operator: "pinnacle-agency.example"
           idempotency_key: "$generate:uuid_v4#schema-validation-reversed-dates"
-          start_time: "2026-12-31T00:00:00Z"
-          end_time: "2026-01-01T00:00:00Z"
+          start_time: "2099-12-31T00:00:00Z"
+          end_time: "2099-01-01T00:00:00Z"
           packages:
             - product_id: "test-product"
               budget: 10000
@@ -407,7 +425,7 @@ phases:
         expect_error: true
         negative_path: payload_well_formed
         stateful: false
-        contributes: true
+        contributes_to: past_start_handled
         expected: |
           Reject the request with:
           - Error code: INVALID_REQUEST
@@ -421,7 +439,7 @@ phases:
               domain: "acmeoutdoor.example"
             operator: "pinnacle-agency.example"
           start_time: "2020-01-01T00:00:00Z"
-          end_time: "2026-12-31T23:59:59Z"
+          end_time: "2099-12-31T23:59:59Z"
           packages:
             - product_id: "test-product"
               budget: 10000
@@ -474,7 +492,7 @@ phases:
         doc_ref: "/media-buy/task-reference/create_media_buy"
         comply_scenario: temporal_validation
         stateful: false
-        contributes: true
+        contributes_to: past_start_handled
         expected: |
           Accept the request with auto-adjusted dates:
           - Response matches create-media-buy-response.json schema
@@ -489,7 +507,7 @@ phases:
               domain: "acmeoutdoor.example"
             operator: "pinnacle-agency.example"
           start_time: "2020-01-01T00:00:00Z"
-          end_time: "2026-12-31T23:59:59Z"
+          end_time: "2099-12-31T23:59:59Z"
           packages:
             - product_id: "test-product"
               budget: 10000
@@ -535,7 +553,6 @@ phases:
           Synthetic assertion over accumulated flags from the two optional
           phases. Fails only if neither path contributed past_start_handled.
         task: assert_contribution
-        requires_tool: create_media_buy
         comply_scenario: temporal_validation
         stateful: false
         expected: |

package/compliance/cache/{3.1.0-rc.2 → 3.0.18.previous}/universal/security.yaml

@@ -36,6 +36,15 @@ narrative: |
   fail any required phase, or advertise no working auth mechanism, are
   non-conformant.
 
+  Positive static-credential probes MUST run through the normal protocol
+  session lifecycle. For MCP, that means the runner authenticates the
+  Streamable HTTP session with the test-kit credential, performs `initialize`,
+  and then calls the protected probe task on that initialized session. A server
+  that rejects a direct, unauthenticated-session `tools/call` carrying only an
+  `Authorization: Bearer ...` header is not failing this phase; the raw direct
+  path is reserved for unauthenticated and deliberately invalid-credential
+  rejection probes.
+
   **Static-credential agents (no OAuth).** An agent with no OAuth issuer -
   sandbox, staging, or any production deployment that chose Bearer or Basic auth
   - does NOT need to advertise RFC 9728 protected-resource metadata. Declare
@@ -71,10 +80,12 @@ prerequisites:
     return 200 without credentials by design.
 
     The test kit MAY also provide an API key at `auth.api_key` or HTTP Basic
-    credentials at `auth.basic`. If both are absent, the static-credential phases
-    are skipped and the OAuth discovery phase MUST succeed instead. OAuth discovery
-    probes the well-known endpoint directly and does not require any test-kit
-    input.
+    credentials at `auth.basic`. Positive static-credential probes use those
+    credentials as the runner's normal transport authentication, including the
+    protocol initialization handshake before the protected task call. If both
+    are absent, the static-credential phases are skipped and the OAuth discovery
+    phase MUST succeed instead. OAuth discovery probes the well-known endpoint
+    directly and does not require any test-kit input.
 
     Agent URLs MUST use `https://` in production compliance runs. The runner rejects
     `http://` agent URLs outright unless invoked with `--allow-http` for local dev.
@@ -159,30 +170,25 @@ phases:
       - id: probe_api_key
         title: "Call the protected probe task with the provided API key"
         narrative: |
-          Authenticate with the API key supplied by the test kit (as a Bearer token
-          in the Authorization header) and expect a normal 200 response on the
-          declared protected task. This confirms the static-credential path works
-          end to end.
+          Authenticate the protocol session with the API key supplied by the
+          test kit (as a Bearer token in the Authorization header), perform the
+          normal transport initialization handshake, and call the declared
+          protected task. This confirms the static-credential path works end
+          to end for a real buyer session.
         task: "$test_kit.auth.probe_task"
         task_default: list_creatives
         doc_ref: "/protocol/authentication"
         comply_scenario: security_api_key
         stateful: false
-        auth:
-          type: api_key
-          from_test_kit: true
         expected: |
-          The agent accepts the API key and returns a well-formed response with
-          http_status 200.
+          The initialized session accepts the API key and returns a well-formed
+          successful response.
 
         sample_request:
           context:
             correlation_id: "security_baseline--probe_api_key"
 
         validations:
-          - check: http_status
-            value: 200
-            description: "Agent accepts the provided API key on the protected probe task"
           - check: field_present
             path: "context"
             description: "Response echoes back the context object"
@@ -260,30 +266,25 @@ phases:
       - id: probe_basic
         title: "Call the protected probe task with the provided Basic credential"
         narrative: |
-          Authenticate with the Basic credential supplied by the test kit (as an
-          `Authorization: Basic ...` header) and expect a normal 200 response on
-          the declared protected task. This confirms the Basic credential path
-          works end to end.
+          Authenticate the protocol session with the Basic credential supplied
+          by the test kit (as an `Authorization: Basic ...` header), perform
+          the normal transport initialization handshake, and call the declared
+          protected task. This confirms the Basic credential path works end to
+          end for a real buyer session.
         task: "$test_kit.auth.probe_task"
         task_default: list_creatives
         doc_ref: "/protocol/authentication"
         comply_scenario: security_basic
         stateful: false
-        auth:
-          type: basic
-          from_test_kit: "auth.basic"
         expected: |
-          The agent accepts the Basic credential and returns a well-formed response
-          with http_status 200.
+          The initialized session accepts the Basic credential and returns a
+          well-formed successful response.
 
         sample_request:
           context:
             correlation_id: "security_baseline--probe_basic"
 
         validations:
-          - check: http_status
-            value: 200
-            description: "Agent accepts the provided Basic credential on the protected probe task"
           - check: field_present
             path: "context"
             description: "Response echoes back the context object"

package/compliance/cache/{3.0.12.previous → 3.0.18.previous}/universal/storyboard-schema.yaml

@@ -185,8 +185,17 @@
 #     id                 string (short identifier)
 #     auth.api_key       string (`demo-<kit>-v1` pattern; the demo Bearer the
 #                        runner sends on positive api-key probes)
+#       OR
+#     auth.basic         object (the demo HTTP Basic credential the runner sends
+#                        on positive Basic probes). Shape is either:
+#                          username: string
+#                          password: string
+#                        or:
+#                          credentials: string
+#                        where `credentials` is the unencoded `username:password`
+#                        pair used to build the Authorization header.
 #     auth.probe_task    string (the protected read the runner calls under
-#                        `auth: none` and with a random-invalid key)
+#                        `auth: none` and with random-invalid credentials)
 #     brand              object (house + brand_id + names + logos + colors +
 #                        fonts + tone — full brand.json payload)
 #     + optional products, creatives, pricing_options, destinations, etc.
@@ -214,9 +223,10 @@
 #   "no credentials" property is temporal, not structural.
 #
 # Enforcement. `scripts/lint-storyboard-test-kits.cjs` fails the build if a
-# kit under `test-kits/` declares neither `auth.api_key` nor `applies_to` —
-# that's the bimodal partition this section describes. The lint tolerates
-# kits that declare both (the future-branded-runner case above).
+# kit under `test-kits/` declares none of `auth.api_key`, `auth.basic`, or
+# `applies_to` — that's the bimodal partition this section describes. The lint
+# tolerates kits that declare both a credential marker and `applies_to` (the
+# future-branded-runner case above).
 #
 # Composition. Storyboards that need BOTH a brand identity AND a harness
 # contract declare the brand kit in `prerequisites.test_kit` and opt into the
@@ -238,9 +248,9 @@
 # docs).
 #
 # `test_kit=<path>` in the contradiction-lint fingerprint disambiguates the
-# two flavors — `auth=kit_default` resolves to the kit's api_key for brand
-# kits and to no-credential for runner contracts, but the two never collide
-# because the `test_kit=` component separates them.
+# two flavors — `auth=kit_default` resolves to the kit's static credential for
+# brand kits and to no-credential for runner contracts, but the two never
+# collide because the `test_kit=` component separates them.
 #
 # Future: if a storyboard ever needs to compose TWO runner contracts
 # simultaneously (e.g., signed-requests + substitution-observer), the step-
@@ -294,6 +304,10 @@
 #   auth: { type: api_key, value_strategy: random_invalid }
 #                                                         → use a per-run random bogus API key (for invalid-key probes).
 #                                                           Runner generates `invalid-<32 random bytes>` per run.
+#   auth: { type: basic, from_test_kit: "auth.basic" }   → use the Basic credential at `auth.basic` in the test kit
+#   auth: { type: basic, value_strategy: random_invalid }
+#                                                         → use a per-run random bogus Basic credential (for invalid-Basic probes).
+#                                                           Runner generates random username/password bytes per run.
 #   auth: { type: oauth_bearer, value_strategy: random_invalid_jwt }
 #                                                         → use a per-run random JWT-shaped bogus Bearer token.
 #                                                           Runner generates `<base64url random>.<base64url random>.<base64url random>` per run.
@@ -315,12 +329,14 @@
 #                         that a later assert_contribution step can require)
 # contributes: boolean (optional — shorthand for `contributes_to: <enclosing phase's branch_set.id>`
 #                       introduced alongside first-class `branch_set:` declarations.
-#                       Legal only inside a phase that declares `branch_set:`; the runner's
-#                       loader resolves `contributes: true` to the phase's branch_set.id
-#                       and raises a storyboard-load error on `contributes: true` outside
+#                       Legal only inside a phase that declares `branch_set:`; current
+#                       SDK runners resolve `contributes: true` to the phase's branch_set.id
+#                       and raise a storyboard-load error on `contributes: true` outside
 #                       a branch_set phase or on a step that also declares `contributes_to`.
-#                       See adcp-client#693 and `lint:storyboard-branch-sets` for the
-#                       full rule set.)
+#                       Use explicit `contributes_to` when a storyboard must remain
+#                       compatible with older runners that grade before loader
+#                       normalization. See adcp-client#693 and
+#                       `lint:storyboard-branch-sets` for the full rule set.)
 # contributes_if: string (optional — runner-evaluated expression gating the contribution)
 #   Supported grammar (single form; not a general-purpose DSL):
 #     "prior_step.<step_id>.passed"   → true if the named prior step in the same storyboard passed
@@ -537,10 +553,11 @@
 #   `@adcp/client` 5.8.0+ also accepts the boolean shorthand
 #   `contributes: true` on a step inside a branch_set phase — the runner's
 #   loader resolves it to the enclosing phase's `branch_set.id`. The two
-#   forms are semantically identical; `contributes: true` is preferred
-#   inside a branch_set phase because it eliminates the typo surface (the
-#   string form must equal `branch_set.id` exactly). Authors may use
-#   either; the lint enforces both.
+#   forms are semantically identical in current SDK runners. Use explicit
+#   `contributes_to: <branch_set.id>` for storyboards that need to run against
+#   older graders that may inspect the field before loader normalization;
+#   use `contributes: true` only when the target runner line is known to
+#   support shorthand normalization. The lint enforces both forms.
 #
 #   New storyboards MUST declare branch-set membership with a `branch_set:`
 #   object. The implicit-detection fallback below exists only so pre-#2633
@@ -556,11 +573,13 @@
 #   Per-step contribution signalling is REQUIRED on each contributing step —
 #   the phase-level `branch_set:` declares membership but does not replace
 #   the step-level flag. Runners accumulate contributions at the step level.
-#   Two equivalent forms:
-#     - `contributes: true` (preferred inside a branch_set phase; resolves
-#       to the enclosing phase's `branch_set.id`)
-#     - `contributes_to: <branch_set.id>` (string form; required outside a
-#       branch_set phase and must equal `branch_set.id` inside one)
+#   Two equivalent forms in current SDK runners:
+#     - `contributes_to: <branch_set.id>` (compatibility-safe string form;
+#       required outside a branch_set phase and must equal `branch_set.id`
+#       inside one)
+#     - `contributes: true` (shorthand inside a branch_set phase; resolves
+#       to the enclosing phase's `branch_set.id` on runners that support
+#       shorthand normalization)
 #
 #   Authoring rules (enforced by `lint:storyboard-branch-sets`):
 #     - A phase with `branch_set:` MUST set `optional: true`. A
@@ -924,8 +943,9 @@
 # for the reference contract (endpoint modes, retry-replay shape, client-primitive
 # hooks). Storyboard authors MUST declare the contract in prerequisites; the
 # webhook-emission universal (universal/webhook-emission.yaml) is the reference
-# consumer, and universal/idempotency.yaml uses it for the "no duplicate webhooks
-# on replay" assertion.
+# consumer, including idempotency replay side-effect assertions that need
+# webhook observation. Keep those assertions on webhook-specific storyboards so
+# core idempotency requests do not depend on runner-only URL templating.
 #
 # --- Substitution variables (webhook-receiver enabled) ---
 #