Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions .changeset/rc-promotion.json
Original file line number Diff line number Diff line change
Expand Up @@ -42,10 +42,18 @@
"file": "prerelease-pins-anonymous-discovery.md",
"sha256": "10978798514254bdea822bf6453bed2555bd5a0183e3839f916dde19a6031ecc"
},
{
"file": "rc0-docs-reserved-word-enums.md",
"sha256": "4d49677189ada6131bf7037cac23e9ad45b3dd9370c55adee221b60801f2c41f"
},
{
"file": "refresh-3-3-release-docs-rc0.md",
"sha256": "4a24b8c1b6c164ac6bc9402877c7d11c05c4fda20f57d4be69aed83f9e244642"
},
{
"file": "reserved-word-enum-replacements.md",
"sha256": "155587b2d54590e750562b8cc3481f2614ec4b61367018c802261d28b87d57b3"
},
{
"file": "social-distribution-identifiers.md",
"sha256": "c36c8c3b4fe730eddd758effc2d1d9886ce2424c0bdf0dcc348037551f3b7ac1"
Expand Down
5 changes: 5 additions & 0 deletions .changeset/rc0-docs-reserved-word-enums.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"adcontextprotocol": patch
---

Docs: the 3.3 release notes, What's new, the 3.2 to 3.3 migration guide, the prerelease page, and Versions describe the reserved-word-safe enum replacements (#8915) as part of `3.3.0-rc.0`. `pass` becomes `passed`, `global` becomes `all`, and `name` becomes `full_name` in six positions. The originals are deprecated, not removed, and a replacement goes only to a peer served 3.3 or later.
2 changes: 1 addition & 1 deletion docs/reference/3-3-beta.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ GA follows the first release candidate that meets every one of the GA criteria i
| `3.3.0-beta.4` | 2026-11-05 | Reporting-subscription coverage fixes (per-package `added_at`, a reduced grant as a loss of authority) and the probe reset, `replace` that transfers assignment settings, tracker-slot limits only where a format declares slots, `BUDGET_TOO_LOW` details, `creative.supports_provenance`, `opportunity` on explicit-package buys, undefined-property reporting, and the hold, account-request, and reporting-subscription storyboards | The same teams, and SDK maintainers adopting the two coverage rule changes |
| `3.3.0-beta.5` | 2026-11-07 | Experimental match keys for cross-publisher frequency capping, `sales-fixed-rate` promoted to stable, and the bundled Public Suffix List (DR-0037) | Pinned adopters comparing beta.5 with beta.6 and rc.0 |
| `3.3.0-beta.6` | 2026-11-13 | Schemas open by default (DR-0036), the closed-schema triage, the versioning rules for what changes between releases, and every other change merged since beta.5 | SDK maintainers and adopters testing ahead of rc.0 |
| `3.3.0-rc.0` | 2026-11-16 | First release candidate: everything in beta.6, plus the prerelease pins, unpinned discovery, and anonymous capabilities guidance, declared `sync_creatives` assignment operations (#8997), audience targeting without member push (#8996), carousel card `cta_values` (#9001), inline `submitted` branches aligned with their status files (#8934), the `by_package` guidance (#8970), scope and `signing_keys` rules for several matching `authorized_agents` entries (#9011, #9017), three renamed experimental values (#8989), an omitted `human_review_required` accepted by campaign governance (#9007), compliance gates for `audience_buy_flow` and `inline_creatives_without_sync` (#9013, #9005), the public test agent's `3.3-beta.6` preview (#9018), and the Instagram, Facebook, Snapchat and X distribution identifier types (#8995) | Every team that tested a beta, SDK maintainers ingesting the bundle, and raw-wire implementers; this is the checkpoint the docs describe |
| `3.3.0-rc.0` | 2026-11-16 | First release candidate: everything in beta.6, plus the prerelease pins, unpinned discovery, and anonymous capabilities guidance, declared `sync_creatives` assignment operations (#8997), audience targeting without member push (#8996), carousel card `cta_values` (#9001), inline `submitted` branches aligned with their status files (#8934), the `by_package` guidance (#8970), scope and `signing_keys` rules for several matching `authorized_agents` entries (#9011, #9017), three renamed experimental values (#8989), an omitted `human_review_required` accepted by campaign governance (#9007), compliance gates for `audience_buy_flow` and `inline_creatives_without_sync` (#9013, #9005), the public test agent's `3.3-beta.6` preview (#9018), reserved-word-safe replacements for six enum values, with the originals deprecated (#8915), and the Instagram, Facebook, Snapchat and X distribution identifier types (#8995) | Every team that tested a beta, SDK maintainers ingesting the bundle, and raw-wire implementers; this is the checkpoint the docs describe |

Beta.0 did not wait for the SDKs. A checkpoint is SDK-backed only after the matching SDK versions and integration evidence are published. `@adcp/sdk` 17.0.0-beta.11 is the first published SDK that bundles beta.3 ([SDK guidance](#sdk-guidance)). Three features that shipped in the betas are [withdrawn after beta.1](#withdrawn-after-beta-1), and the [closed-schema triage](#closed-schema-triage-before-rc-0) removes further beta fields before rc.0.

Expand Down
18 changes: 17 additions & 1 deletion docs/reference/migration/3-2-to-3-3.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -91,6 +91,7 @@ Everything else is an optional declaration or a clarification. Agent identity (D
| 58 | Sellers that answer `get_media_buy_delivery` | Return at least one `by_package` row per media buy, one per package, and omit a buy you can't report and return an error rather than an empty `by_package` ([#8970](https://github.com/adcontextprotocol/adcp/pull/8970)). `by_package: []` stays valid in 3.x; requiring a row is proposed for 4.0 ([#8973](https://github.com/adcontextprotocol/adcp/issues/8973)). |
| 59 | Sellers, buyers, and SDKs that use `media_buy.execution_readiness`, `creative.live_updates`, or `media_buy.delivery_projection` | Send and accept the renamed values: `input-required` (was `input_required`), `clickthrough` (was `click_through`), and `under_delivery` (was `underdelivery`). There is no alias ([details](#three-experimental-values-renamed)). |
| 60 | Campaign governance agents (`governance.campaign`) | Accept a `sync_plans` plan that omits `human_review_required` and derive the flag from its resolved policies; keep rejecting an explicit `false`. Reject `flight.end` not after `flight.start`, and repeated or colliding policy IDs, with `INVALID_REQUEST` ([#9007](https://github.com/adcontextprotocol/adcp/pull/9007)). |
| 61 | Buyers, sellers, SDKs, and registry and compliance tooling that use `binary-verdict`, `local_verdict`, the compliance `tracks` status, `RATE_LIMITED` `scope`, or signal `onboarder.match_keys` | Accept both spellings. Emit `passed`, `all`, and `full_name` only to a peer served 3.3 or later, and the deprecated `pass`, `global`, and `name` otherwise; keep the original in published files such as `adagents.json` through 3.x ([details](#reserved-word-safe-enum-replacements)). |

## Withdrawn from 3.3, planned for 4.0

Expand Down Expand Up @@ -191,6 +192,20 @@ Only the fields below change between beta.5 and rc.0 because of the triage, and

The values are renamed in place, with no alias. A seller or buyer built from a beta bundle sends and accepts the new spelling in `readiness_status` and the product rollup, `creative.live_updates.in_place[].change`, `staged_update.change_kinds[]` and the `CREATIVE_LIVE_UPDATE_UNSUPPORTED` details, and `projection.projected_end_state`.

### Reserved-word-safe enum replacements

([#8915](https://github.com/adcontextprotocol/adcp/pull/8915), rc.0.) Six enum positions used a value that an SDK target language reserves, so 3.3 adds a replacement and deprecates the original ([#8791](https://github.com/adcontextprotocol/adcp/issues/8791)). Each enum accepts both spellings through 3.x. The original is deprecated in 3.3 and removed in 4.0, and the [4.0 compatibility registry](/docs/reference/migration/v4-compatibility) lists every site.

| Deprecated | Replacement | Where | Why |
|---|---|---|---|
| `pass` | `passed` | `enums/binary-verdict.json`, `get_media_buy_artifacts` `local_verdict`, and the registry feed's compliance `tracks` status | A Python keyword |
| `global` | `all` | The `RATE_LIMITED` details `scope` | A Python keyword. Not `agent`, because `enums/error-scope.json` already uses `agent` for the calling buyer agent. |
| `name` | `full_name` | Signal definition `onboarder.match_keys`, on `core/signal-definition.json` and `core/signal-definition-enrichment.json` | Collides with the enum member protocol in Python and Java |

Each deprecated value is listed in `x-deprecated-enum-values` and carries `deprecated: true`, `x-deprecated-in: "3.3.0"`, `x-removed-in: "4.0.0"`, and `x-superseded-by` in a per-value `enumMetadata` entry.

**When to emit the replacement.** Send a replacement only when the release served is 3.3 or later; a 3.2 receiver treats it as an unknown value ([Send only to 3.3 peers](#send-only-to-3-3-peers)). Otherwise send the original. Receivers accept both. A published file, such as `adagents.json`, keeps the original through 3.x, because readers on any 3.x release consume it.

## Required to claim 3.3 behavior

### Discovery tasks never provision an account
Expand Down Expand Up @@ -664,6 +679,7 @@ Many 3.3 additions sit inside objects that 3.2.10 and earlier publish closed, so
| Buyer | `reporting_subscriptions` on `sync_principal` | A seller that lists only `sync_principal` in `reporting_delivery.configuration_tasks[]` serves reporting registration to 3.3 callers only. |
| Buyer | `pixel_tracker` `event` values `start`, `first_quartile`, `midpoint`, `third_quartile`, `complete` | 3.2 closes the `event` enum; send them as `event: custom` until the seller negotiates 3.3 ([below](#hosted-video-and-audio-playback-trackers)). |
| Buyer | `geo_value_labels` on targeting ([#8966](https://github.com/adcontextprotocol/adcp/pull/8966)) | The field is not in 3.2, and a 3.2 seller may treat an unknown targeting key as an unsupported dimension. |
| Buyer, seller | The `passed`, `all`, and `full_name` enum replacements ([#8915](https://github.com/adcontextprotocol/adcp/pull/8915)) | A 3.2 receiver treats each as an unknown value; send the deprecated original instead. |
| Seller | `match_keys` on `Product.identity` (experimental, beta.5) | 3.2 closes `core/product-identity.json`. `media_buy.supported_match_keys` on `get_adcp_capabilities` sits in an open object and is safe. |

New enum values (`nmo`, `videoamp`, `mxf`, `mpeg2`, `avc_intra`, `xavc`, `3gp`, `mpeg`, and `m4v` in video `containers`, `print_metrics` in `available-metric`, `operator_fee` in `adjustment-kind`, and the eight Instagram, Facebook, Snapchat and X values in `distribution-identifier-type` ([#8995](https://github.com/adcontextprotocol/adcp/pull/8995))) fall under the 3.x rule that clients tolerate unknown values, but a strict 3.2 validator still rejects them; send them only to 3.3 peers too.
Expand Down Expand Up @@ -970,7 +986,7 @@ Adopters of these patches have already seen these; their changesets reappear in

## Deprecations

3.3 deprecates two result fields, the principal kind field and assertion, the RFC 9421 signing profiles, one usage, the account identity-rekey machinery, and the boolean form of `demographics`. All remain functional throughout 3.x, and each is expected to be removed in 4.0. Removals happen in a major. 3.3 stays supported for at least 12 months after 4.0 reaches GA, so a 3.3 integration keeps working while it migrates ([support window](/docs/reference/versioning#support-window-for-previous-major)).
3.3 deprecates two result fields, the principal kind field and assertion, the RFC 9421 signing profiles, one usage, the account identity-rekey machinery, the boolean form of `demographics`, and six reserved-word enum values ([Reserved-word-safe enum replacements](#reserved-word-safe-enum-replacements)). All remain functional throughout 3.x, and each is expected to be removed in 4.0. Removals happen in a major. 3.3 stays supported for at least 12 months after 4.0 reaches GA, so a 3.3 integration keeps working while it migrates ([support window](/docs/reference/versioning#support-window-for-previous-major)).

- **`seller_id` on `sync_event_sources` and `sync_audiences` results.** Use the new optional `platform_id` for the object's ID in the seller's ad platform, matching `sync_creatives` and `sync_catalogs`. **Sellers** reporting a platform identifier in 3.3 and later 3.x responses MUST emit both fields with identical values, including discovery responses and seller-managed event sources. **Buyers** MUST prefer `platform_id` and fall back to `seller_id` only when `platform_id` is absent. Either field may be absent in legacy responses, and both may be absent when no platform identifier is available. Continue using `event_source_id` and `audience_id` in AdCP requests. The aliases keep their object-ID semantics; they are never seller identity. `adagents.json` `contact.seller_id` and publisher identifiers of type `seller_id` are unchanged. The aliases are expected to be removed in 4.0. See [event source migration](/docs/media-buy/task-reference/sync_event_sources#platform-identifier-migration-adcp-3-3) and [audience migration](/docs/media-buy/task-reference/sync_audiences#platform-identifier-migration-adcp-3-3) ([#8290](https://github.com/adcontextprotocol/adcp/issues/8290)).
- **`principal_kind` and `expected_principal_kind` on `sync_principal` and `get_principal`**, and the `enums/principal-kind.json` enum. A principal is the buyer agent as the seller has bound it, so the kind is always `buyer_agent` and carries no information. Sellers keep returning `principal_kind` and honoring `expected_principal_kind` throughout 3.x; buyers stop reading and sending them, and don't branch on `principal_kind`. They are expected to be removed in 4.0. The task names are unchanged ([#8443](https://github.com/adcontextprotocol/adcp/pull/8443), [#8280](https://github.com/adcontextprotocol/adcp/issues/8280)).
Expand Down
Loading
Loading