From 867213c5981694c35223c8b15703ce7a61a48e48 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 30 Apr 2026 02:10:32 +0000 Subject: [PATCH] docs(aao-verified): pre-3.1 framing consistency sweep (#3564) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Rename "Two marks: AdCP Conformant vs AAO Verified" section in aao-verified.mdx to "Naming history" — cold readers see the current single-mark framing, not a confusing two-marks heading - Fix malformed 3-column table row in the same section - Replace ⊆ containment notation in conformance.mdx with the independence-first phrasing established in #3536 - Update salty-wasps-cheat.md: remove "Spec is a prerequisite for measuring Live" (directly contradicts #3536 orthogonal-axes fix) - Update account-authorization-and-rbac-errors.md: qualify attestation_verifier as binding to the AAO Verified (Live) qualifier Item 4 of the sweep (attestation_verifier doc check conditional on #3561) remains open on the parent issue. Refs #3564 https://claude.ai/code/session_013WywfzRTvdv2kWUZdp7aBz --- .changeset/aao-verified-framing-sweep.md | 13 +++++++++++++ .changeset/account-authorization-and-rbac-errors.md | 2 +- .changeset/salty-wasps-cheat.md | 2 +- docs/building/aao-verified.mdx | 4 ++-- docs/building/conformance.mdx | 2 +- 5 files changed, 18 insertions(+), 5 deletions(-) create mode 100644 .changeset/aao-verified-framing-sweep.md diff --git a/.changeset/aao-verified-framing-sweep.md b/.changeset/aao-verified-framing-sweep.md new file mode 100644 index 0000000000..25453da8e8 --- /dev/null +++ b/.changeset/aao-verified-framing-sweep.md @@ -0,0 +1,13 @@ +--- +--- + +docs(aao-verified): pre-3.1 framing consistency sweep + +Reconciles AAO Verified (Spec)/(Live) framing across docs and queued changeset entries: + +- Renames the "Two marks: AdCP Conformant vs AAO Verified" section in `aao-verified.mdx` to "Naming history" so cold readers see the current single-mark framing rather than a confusing two-marks heading; fixes a broken three-column table row in the same section. +- Replaces `⊆` containment notation in `conformance.mdx` with plain-English phrasing that makes the independent-axes framing explicit. +- Updates `.changeset/salty-wasps-cheat.md` to remove "Spec is a prerequisite for measuring Live" — that sentence directly contradicts the orthogonal-axes correction landed in #3536. +- Updates `.changeset/account-authorization-and-rbac-errors.md` to qualify `attestation_verifier` as binding to the "AAO Verified (Live) qualifier" rather than the unqualified "AAO Verified mark", since the scope specifically enables (Live) axis observability. + +Refs #3564. Item 4 (attestation_verifier doc sweep conditional on #3561) remains open on the parent issue. diff --git a/.changeset/account-authorization-and-rbac-errors.md b/.changeset/account-authorization-and-rbac-errors.md index ce20554f0f..04e9404f14 100644 --- a/.changeset/account-authorization-and-rbac-errors.md +++ b/.changeset/account-authorization-and-rbac-errors.md @@ -6,7 +6,7 @@ spec(accounts): caller-scope introspection via per-account `authorization` on sy Caller-scope authorization model for AdCP. Vendor agents (media-buy, signals, governance, creative, brand) attach an optional `authorization` object to each per-account entry in `sync_accounts` and `list_accounts` responses — describing `allowed_tasks`, per-task `field_scopes`, an optional standard `scope_name`, and an optional `read_only` flag. Absence means the vendor agent does not advertise introspectable scope; callers MUST NOT infer access from absence. Conceptually analogous to RFC 7662 OAuth 2.0 Token Introspection, specialized for AdCP's task-and-field authorization model and folded into existing account discovery rather than split into a new task. -Standard named scope `attestation_verifier` is spec-mandated (binds to the AAO Verified mark, a Media Buy Protocol flow). Other scope names are vendor-specific and MUST use the `custom:` prefix so a typo of the standard value fails schema validation. Three new error codes surface RBAC decisions that previously had no standard code: `SCOPE_INSUFFICIENT`, `READ_ONLY_SCOPE`, `FIELD_NOT_PERMITTED`. `FIELD_NOT_PERMITTED` MUST populate `error.field`; `SCOPE_INSUFFICIENT` SHOULD carry an `introspection_hint` pointing at where to re-read scope. All four authz codes classify as `correctable` but are NOT agent-autonomous (scope broadening requires operator intervention) — agents SHOULD surface rather than auto-retry. +Standard named scope `attestation_verifier` is spec-mandated (binds to the AAO Verified (Live) qualifier; Media Buy Protocol). Other scope names are vendor-specific and MUST use the `custom:` prefix so a typo of the standard value fails schema validation. Three new error codes surface RBAC decisions that previously had no standard code: `SCOPE_INSUFFICIENT`, `READ_ONLY_SCOPE`, `FIELD_NOT_PERMITTED`. `FIELD_NOT_PERMITTED` MUST populate `error.field`; `SCOPE_INSUFFICIENT` SHOULD carry an `introspection_hint` pointing at where to re-read scope. All four authz codes classify as `correctable` but are NOT agent-autonomous (scope broadening requires operator intervention) — agents SHOULD surface rather than auto-retry. Identity binding, refresh cadence, and consistency are normative: the authorization object is scoped to `(caller identity, account_id)` at read time; vendor agents MUST resolve identity from the authenticated request (not client-supplied fields) and reflect operator-initiated scope changes within 300 seconds. Sequential reads within the refresh window MUST return identical authorization objects (modulo operator-initiated changes) — flicker from load-balanced or eventually-consistent backends is non-conformant. diff --git a/.changeset/salty-wasps-cheat.md b/.changeset/salty-wasps-cheat.md index f7ad6d8a04..17f5440253 100644 --- a/.changeset/salty-wasps-cheat.md +++ b/.changeset/salty-wasps-cheat.md @@ -1,7 +1,7 @@ --- --- -AAO Verified agent badge — implementation. Agents that declare `specialisms` in `get_adcp_capabilities` and pass the matching storyboards earn a per-protocol badge. Implements the trust-mark spec from #3001 (which introduced `AdCP Conformant` and `AAO Verified` as separate marks) under a single brand name with composable axis qualifiers — `AAO Verified Media Buy Agent (Spec)`, `(Live)`, or `(Spec + Live)`. Same containment relationship as #3001 (Spec is a prerequisite for measuring Live); single brand word for cleaner buyer messaging. +AAO Verified agent badge — implementation. Agents that declare `specialisms` in `get_adcp_capabilities` and pass the matching storyboards earn a per-protocol badge. Implements the trust-mark spec from #3001 (which introduced `AdCP Conformant` and `AAO Verified` as separate marks) under a single brand name with composable axis qualifiers — `AAO Verified Media Buy Agent (Spec)`, `(Live)`, or `(Spec + Live)`. The two axes are orthogonal — neither is a prerequisite for the other (#3536); single brand word for cleaner buyer messaging. Badges are issued by AAO's compliance heartbeat to agents whose organization holds an active API-access membership tier, and revoked when membership lapses or specialisms start failing (48-hour grace). Preview-status specialisms are tested but do not contribute to stable badge issuance. diff --git a/docs/building/aao-verified.mdx b/docs/building/aao-verified.mdx index dc48c72f2a..61d74cc664 100644 --- a/docs/building/aao-verified.mdx +++ b/docs/building/aao-verified.mdx @@ -51,7 +51,7 @@ The two axes are related but answer different questions, and the badge surfaces The (Live) axis is the strongest signal a buyer can rely on: AAO is the active counterparty, not just an attesting body. If something breaks in the production code path, the compliance engine sees it within days and the qualifier expires. -## Two marks: AdCP Conformant vs AAO Verified, or one mark with two qualifiers? +## Naming history Earlier drafts (#3001) proposed "AdCP Conformant" and "AAO Verified" as two distinct mark names — one per axis. This page uses a **single brand mark with axis qualifiers in parens** instead. Same shape, different naming convention: @@ -59,7 +59,7 @@ Earlier drafts (#3001) proposed "AdCP Conformant" and "AAO Verified" as two dist |---|---| | AdCP Conformant | AAO Verified (Spec) | | AAO Verified | AAO Verified (Live) | -| Both held | AdCP Conformant + AAO Verified | AAO Verified (Spec + Live) | +| AdCP Conformant + AAO Verified | AAO Verified (Spec + Live) | The reasoning behind the rename: a single brand word ("Verified") with composable qualifiers is cleaner for buyer messaging. Buyers don't have to learn two distinct marks; they read the qualifier inline. Test agents earning **Verified (Spec)** is a complete, dignified claim — they're test agents, that's the whole point — rather than a "junior" Conformant tier. The wire format reflects this: a single `verification_modes: string[]` array in the JWT and registry API, where an agent might have `["spec"]` or `["spec", "live"]`. One badge URL per agent + role; the qualifier evolves as axes are earned, embedded badges automatically reflect the current state. diff --git a/docs/building/conformance.mdx b/docs/building/conformance.mdx index 3db7a08a9e..212738eafc 100644 --- a/docs/building/conformance.mdx +++ b/docs/building/conformance.mdx @@ -20,7 +20,7 @@ Put differently: - Conformance is a property of the agent's wire behavior. - Verification is a time-bounded third-party attestation. **(Spec)** verifies conformance via simulation; **(Live)** verifies the underlying production capability via real-traffic observation. Each independently demonstrates conformance through different evidence. -- Verified (Spec) ⊆ Conformant via storyboards. Verified (Live) ⊆ Conformant via the eight observability checks (which exercise wire format, filters, lifecycle, and scope through real traffic). The two axes are independent: a seller without a test-mode endpoint can earn (Live) directly, and a test agent that can never serve real impressions earns (Spec) as a complete claim. +- The two axes are independent: a seller without a test-mode endpoint can earn **(Live)** directly, and a test agent that can never serve real impressions earns **(Spec)** as a complete claim. ## Storyboard conformance vs. AAO Verified