From 8da9f3ce6e739934d1d4bbd3e0febe0ab47876cc Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Fri, 24 Apr 2026 19:39:59 -0400 Subject: [PATCH] patch: storyboards = patch by default + deprecate signed-requests preview specialism MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two clarifications, both patches. versioning.mdx: new "Spec changes vs. conformance-suite changes" subsection makes explicit that conformance-suite changes (storyboards, specialism taxonomy, scenario classifications, runner mechanics) version independently of spec and are patch-level by default. Includes a per-change-type table. The release-vs-patch rules apply to wire-level artifacts; storyboards are verification artifacts AAO maintains. signed-requests preview specialism: marked status: deprecated with narrative explaining the reclassification. RFC 9421 verification is a transport-layer concern that applies to every AdCP agent regardless of supported_protocols — classifying it as a media-buy specialism was a taxonomy error. The on-wire seller obligation is unchanged (advertise request_signing.supported: true, implement the verifier per the security profile); only the conformance runner location moves. Tracked at #3047. Both are patch-level: versioning.mdx is policy clarification, no normative wire-level requirement changes. signed-requests is preview with no graded users; the conformance bar itself is unchanged. Full reclassification (file move specialisms/ -> universal/, test-kit refactor, doc cross-reference updates) ships as follow-up patch under #3047. Co-Authored-By: Claude Opus 4.7 (1M context) --- .changeset/storyboards-patch-clarify.md | 16 ++++++++ docs/reference/versioning.mdx | 20 ++++++++++ .../specialisms/signed-requests/index.yaml | 38 ++++++++++++++----- 3 files changed, 65 insertions(+), 9 deletions(-) create mode 100644 .changeset/storyboards-patch-clarify.md diff --git a/.changeset/storyboards-patch-clarify.md b/.changeset/storyboards-patch-clarify.md new file mode 100644 index 0000000000..f87ad9c76f --- /dev/null +++ b/.changeset/storyboards-patch-clarify.md @@ -0,0 +1,16 @@ +--- +--- + +patch: clarify that storyboards/conformance-suite changes version independently of spec; deprecate `signed-requests` preview specialism (taxonomy correction) + +Two patches in one PR, both clarifications: + +**versioning.mdx clarification.** Adds a "Spec changes vs. conformance-suite changes" subsection making explicit that conformance-suite changes (storyboards, specialism taxonomy, scenario classifications, runner mechanics) version independently of spec and are patch-level by default. The release-vs-patch rules in the spec apply to wire-level artifacts under `static/schemas/source/` and normative prose in `docs/`. Storyboards under `static/compliance/source/` and the runner machinery are verification artifacts AAO maintains; they're not the spec. Includes a per-change-type table so authors can size correctly. + +**`signed-requests` preview specialism deprecated.** The `signed-requests` specialism YAML at `static/compliance/source/specialisms/signed-requests/index.yaml` is marked `status: deprecated` with an updated narrative explaining the reclassification. The conformance bar is unchanged; only the location moves. Tracked at #3075 (full reclassification to a universal capability-gated storyboard at `static/compliance/source/universal/signed-requests.yaml`, alongside the `request_signing.supported: true` capability advertisement). + +Why patch: +- The versioning.mdx change is policy clarification — no normative wire-level requirement changes. +- The signed-requests reclassification is `preview` status with no graded users today; the on-wire seller obligation (advertise `request_signing.supported: true`, implement the verifier per the security profile) is unchanged. Only the conformance runner taxonomy moves. + +The full reclassification (file move from `specialisms/` to `universal/`, test-kit refactor at `signed-requests-runner.yaml`, doc cross-reference updates in `release-notes.mdx`, `whats-new-in-v3.mdx`, `prerelease-upgrades.mdx`, `compliance-catalog.mdx`, etc.) ships as a follow-up patch under #3075. diff --git a/docs/reference/versioning.mdx b/docs/reference/versioning.mdx index 89e12b9b5b..1cb0ee044f 100644 --- a/docs/reference/versioning.mdx +++ b/docs/reference/versioning.mdx @@ -74,6 +74,26 @@ Every release with schema changes is called out in the changelog, release notes, [Experimental surfaces](/docs/reference/experimental-status) operate under a separate, faster notice window of 6 weeks. The deprecation policy above applies only to stable surfaces. +### Spec changes vs. conformance-suite changes + +The release-vs-patch rules above apply to **spec-level artifacts** — JSON Schemas under `static/schemas/source/`, normative prose in `docs/`, and protocol task definitions. These are what an agent implements on the wire and what buyers depend on for interop. + +The **conformance suite** — storyboards, specialism taxonomy, scenario classifications, runner mechanics — versions independently and is **patch-level by default**. The conformance suite is a verification artifact AAO maintains; it is not the spec and it is not the docs. Adding, removing, renaming, or reclassifying preview-status specialisms; relocating storyboards between universal/protocol/specialism directories; refactoring scenario coverage; and adjusting runner behavior to match an unchanged spec are all patch changes. + +A conformance-suite change escalates to minor or major only when it would alter what an agent must do on the wire — i.e., when it tightens implicit spec validation, requires sellers to advertise a new capability that didn't exist, or removes a stable specialism that agents are actively claiming (which is breaking, since agents currently advertising it become non-conformant). + +| Change | Tier | +|--------|------| +| Add a new universal storyboard for an existing capability | Patch | +| Move a storyboard between directories (`specialisms/{id}/` → `universal/`, etc.) | Patch | +| Reclassify a preview-status specialism (no graded users) | Patch | +| Add scenarios within an existing storyboard | Patch | +| Add a new stable specialism to the enum | Minor (new claim agents can make) | +| Remove a stable specialism from the enum | Major (breaks agents currently claiming it) | +| Add a new error code or new optional field to a request/response schema | Minor | + +This separation lets the verification machinery evolve quickly without dragging spec-level versioning along with it. + --- ## 3.x stability guarantees diff --git a/static/compliance/source/specialisms/signed-requests/index.yaml b/static/compliance/source/specialisms/signed-requests/index.yaml index f44c8c6423..3215883d58 100644 --- a/static/compliance/source/specialisms/signed-requests/index.yaml +++ b/static/compliance/source/specialisms/signed-requests/index.yaml @@ -2,28 +2,48 @@ id: signed_requests version: "1.0.0" title: "Signed requests — RFC 9421 transport-layer verification" protocol: media-buy -status: preview +status: deprecated category: signed_requests -summary: "Agent verifies RFC 9421 HTTP Signatures on incoming AdCP requests per the transport-layer profile. Graded against conformance vectors covering every checklist step and canonicalization-edge rule." +summary: "DEPRECATED — being reclassified from per-protocol specialism to a universal capability-gated storyboard. Agents that currently advertise `request_signing.supported: true` SHOULD NOT add `signed-requests` to their `specialisms` array; the universal storyboard at `/compliance/{version}/universal/signed-requests.yaml` (when published) covers the same conformance bar regardless of `supported_protocols`. See https://github.com/adcontextprotocol/adcp/issues/3075." track: security_transport required_tools: - get_adcp_capabilities # Additional tool families are exercised transport-layer only — the runner signs # requests targeting any mutating AdCP operation (create_media_buy, update_media_buy, - # acquire_*, activate_signal, sync_creatives) and grades the verifier's response. The - # specialism is preview status pending runner implementation at adcontextprotocol/adcp#2331; - # when the runner ships, required_tools will expand to the concrete list of operations - # exercised. + # acquire_*, activate_signal, sync_creatives) and grades the verifier's response. + # See deprecation note in narrative below — this specialism is being reclassified as + # a universal capability-gated storyboard and will be removed from the specialism + # taxonomy in 4.0. Runner implementation tracked at adcontextprotocol/adcp#2331. narrative: | + **DEPRECATED** — this specialism is being reclassified as a universal capability-gated + storyboard. The signed-requests claim is a transport-layer concern that applies to every + AdCP agent regardless of `supported_protocols` — there is nothing media-buy-specific about + it. Classifying it as a media-buy specialism was a taxonomy error. The conformance bar + itself is unchanged; only the location moves. Tracked at + [#3075](https://github.com/adcontextprotocol/adcp/issues/3075). + + **For agents:** do not add `signed-requests` to your `get_adcp_capabilities.specialisms` + array. Advertise `request_signing.supported: true` in the `request_signing` capability + block instead — that is the on-wire claim. Once the universal storyboard ships at + `/compliance/{version}/universal/signed-requests.yaml`, every agent advertising + `request_signing.supported: true` runs it automatically (same gating model as + `compliance_testing.supported`). + + --- + + *Original specialism description follows for historical reference; the conformance + content (vectors, contracts, runner harness) is unchanged and will move verbatim to + the universal storyboard location:* + The signed-requests specialism certifies that an agent correctly implements the AdCP RFC 9421 request-signing verifier per `docs/building/implementation/security.mdx#signed-requests-transport-layer`. This is a transport-layer claim, not a protocol-specific one. A signed request can target any mutating operation — most commonly `create_media_buy`, `update_media_buy`, `acquire_*`, - `activate_signal`, and `sync_creatives`. The claim is scoped to `media-buy` because that - is where the financial stake is highest, but the verifier behavior is the same across all - mutating operations. + `activate_signal`, and `sync_creatives`. The claim is scoped to `media-buy` in this + preview specialism (a classification error fixed in #3075) — the verifier behavior is + the same across all mutating operations regardless of which protocols the agent supports. The claim is certifiable only when the agent advertises `request_signing.supported: true` in `get_adcp_capabilities`. An agent that does not advertise support is not tested against