diff --git a/.changeset/rc-promotion.json b/.changeset/rc-promotion.json index ad79c94276..b81bf6d05d 100644 --- a/.changeset/rc-promotion.json +++ b/.changeset/rc-promotion.json @@ -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" diff --git a/.changeset/rc0-docs-reserved-word-enums.md b/.changeset/rc0-docs-reserved-word-enums.md new file mode 100644 index 0000000000..6f7ae8a274 --- /dev/null +++ b/.changeset/rc0-docs-reserved-word-enums.md @@ -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. diff --git a/docs/reference/3-3-beta.mdx b/docs/reference/3-3-beta.mdx index 377cc13e99..8e412da32e 100644 --- a/docs/reference/3-3-beta.mdx +++ b/docs/reference/3-3-beta.mdx @@ -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. diff --git a/docs/reference/migration/3-2-to-3-3.mdx b/docs/reference/migration/3-2-to-3-3.mdx index 5eada5febc..e1d0e17ea4 100644 --- a/docs/reference/migration/3-2-to-3-3.mdx +++ b/docs/reference/migration/3-2-to-3-3.mdx @@ -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 @@ -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 @@ -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. @@ -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)). diff --git a/docs/reference/release-notes.mdx b/docs/reference/release-notes.mdx index e130f88191..0bce5fa7ac 100644 --- a/docs/reference/release-notes.mdx +++ b/docs/reference/release-notes.mdx @@ -11,7 +11,7 @@ Authoritative version-by-version release record for AdCP, with cumulative change ## Version 3.3.0 -**Status:** Release candidate. The latest checkpoint is `3.3.0-rc.0`, the first release candidate, published 2026-11-16. 3.3 is a minor release targeting the 3.3.0 milestone. Beta.0 was the protocol-first cut used as the canonical input for SDK work, beta.1 through beta.5 incorporated integration feedback, beta.6 carried the 2026-11-09 decision to open the schemas that were closed by accident, with the closed-schema triage that followed it, and rc.0 is the first release candidate. A checkpoint counts as SDK-backed only after SDK support for the exact bundle and integration evidence are published ([3.3 prerelease program](/docs/reference/3-3-beta#sdk-guidance)). No stable field, enum value, or task is removed. Three beta features, definition pins, purchase rights, and installment selection, are withdrawn after beta.1 and planned for 4.0, and the triage removes further beta fields before rc.0 ([below](#withdrawn-from-3-3-planned-for-4-0)). The `seller_id` result fields on event sources and audiences, `principal_kind`, the natural-key account reference after provisioning, the account identity-rekey machinery, the boolean form of `demographics`, and condition (b) of `request_signature_required` are deprecated, and the RFC 9421 signing profiles are deprecated in favor of the experimental Web Bot Auth profile. All remain functional throughout 3.x and are expected to be removed in 4.0. Normative changes that narrow conformant behavior, and the guarantees that loosen, are described under [Behavior changes to review](#behavior-changes-to-review). This section is the cumulative 3.3 narrative and is refreshed at each prerelease cut; `CHANGELOG.md` records what each individual cut consumed. +**Status:** Release candidate. The latest checkpoint is `3.3.0-rc.0`, the first release candidate, published 2026-11-16. 3.3 is a minor release targeting the 3.3.0 milestone. Beta.0 was the protocol-first cut used as the canonical input for SDK work, beta.1 through beta.5 incorporated integration feedback, beta.6 carried the 2026-11-09 decision to open the schemas that were closed by accident, with the closed-schema triage that followed it, and rc.0 is the first release candidate. A checkpoint counts as SDK-backed only after SDK support for the exact bundle and integration evidence are published ([3.3 prerelease program](/docs/reference/3-3-beta#sdk-guidance)). No stable field, enum value, or task is removed. Three beta features, definition pins, purchase rights, and installment selection, are withdrawn after beta.1 and planned for 4.0, and the triage removes further beta fields before rc.0 ([below](#withdrawn-from-3-3-planned-for-4-0)). The `seller_id` result fields on event sources and audiences, `principal_kind`, the natural-key account reference after provisioning, the account identity-rekey machinery, the boolean form of `demographics`, six reserved-word enum values (#8915), and condition (b) of `request_signature_required` are deprecated, and the RFC 9421 signing profiles are deprecated in favor of the experimental Web Bot Auth profile. All remain functional throughout 3.x and are expected to be removed in 4.0. Normative changes that narrow conformant behavior, and the guarantees that loosen, are described under [Behavior changes to review](#behavior-changes-to-review). This section is the cumulative 3.3 narrative and is refreshed at each prerelease cut; `CHANGELOG.md` records what each individual cut consumed. **Where to start:** [What's new in AdCP 3.3](/docs/reference/whats-new-in-3-3) is the adopter overview. [Migrating from 3.2 to 3.3](/docs/reference/migration/3-2-to-3-3) has the role-based checklist. The [3.3 prerelease program](/docs/reference/3-3-beta) covers artifacts, SDK timing, and the proposals still in review. @@ -30,7 +30,7 @@ AdCP 3.3 lets scheduled, human-gated, and offline media run through the same buy | `3.3.0-beta.4` | 2026-11-05 | Reporting-subscription coverage fixes (per-package `added_at`, a grant reduced without `get_reporting_status` as a loss of authority, schema-enforced durations) 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 | `@adcp/sdk` 17.0.0-beta.18 through 17.0.0-beta.20 and Python `adcp` 10.0.0b12 support this release | | `3.3.0-beta.5` | 2026-11-07 | Experimental match keys for cross-publisher frequency capping, `sales-fixed-rate` promoted to stable, the bundled Public Suffix List (DR-0037), and offline legacy creative fixtures | `@adcp/sdk` 17.0.0-beta.21 through 17.0.0-beta.23 and Python `adcp` 10.0.0b13 through 10.0.0b16 support this release | | `3.3.0-beta.6` | 2026-11-13 | Schemas open by default (DR-0036), the closed-schema triage that withdraws or moves the beta fields on deprecated tasks and on the commercial terms held closed until 4.0, the versioning rules for what changes between releases (#8704), origin-only `authorized_agents` URLs (#8939), declared-option creative conformance (#8941), TMP Context Match cache isolation (#7446), `creative.supports_registry_policy_enforcement` (#8857), `3gp`, `mpeg`, and `m4v` video containers (#8668), carousel `card_image_sizes` (#8937), loosened URL patterns (#8792), signed terms that bind every member (#8884), the experimental `https_put` reporting transport with no buyer secrets (#8793), `media_buy.supported_delivery_types` (#8458), display labels for geo targeting codes (#8966), experimental installment refinement (#8974) and per-installment creative assignment (#8972), and report definitions at `contract_version` `1.2` that carry `package_id` (#8983) | `@adcp/sdk` 17.0.0-beta.24 and later and Python `adcp` 10.0.0b17 and later support this release | -| `3.3.0-rc.0` | 2026-11-16 | First release candidate: everything in beta.6, plus prerelease pins, unpinned discovery, and anonymous capabilities, 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) | No published SDK supports it yet; new TypeScript and Python prereleases follow the cut | +| `3.3.0-rc.0` | 2026-11-16 | First release candidate: everything in beta.6, plus prerelease pins, unpinned discovery, and anonymous capabilities, 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) | No published SDK supports it yet; new TypeScript and Python prereleases follow the cut | Each prerelease is immutable. The `3.3-beta` documentation selector stays at beta.5, and `3.3-rc` advances to the latest release candidate, while pinned protocol, schema, compliance, and documentation artifacts remain available. See the [3.3 prerelease program](/docs/reference/3-3-beta). @@ -74,7 +74,7 @@ Each prerelease is immutable. The `3.3-beta` documentation selector stays at bet - **Public Suffix List (beta.5):** verifiers compute eTLD+1 with a Public Suffix List bundled with the verifier, never fetched at runtime; AdCP names no reference snapshot (#8702, DR-0037). - **Conformance (beta.4 and beta.5):** the `account_requests` storyboard (#8677); the reporting-subscription coverage and capacity storyboards with the advisory `owed_periods_match` check (#8680, #8724); six hold storyboards and the advisory `instant_offset_within` check (#8696); `media_buy_seller/assignment_replace_transfers_settings` (#8695); `sales-fixed-rate` promoted from preview to stable (#8445); `deterministic_testing` scoped to one sandbox account (#8731); offline legacy creative fixtures (#8684); and dependent observations skipped when controlled forcing is unavailable (#8642). - **beta.6:** the schemas that were meant to be open open, and the closed-schema triage withdraws or moves beta fields (#8866, #8501, below); an origin-only `authorized_agents[].url` in `adagents.json` authorizes the agent at that origin, whatever its path (#8939); a seller accepts a creative that conforms to the format option it targets (#8941); experimental TMP Context Match caches partition by trusted evaluation namespace (#7446); optional `creative.supports_registry_policy_enforcement` gates the policy-backed rejection storyboard (#8857); `3gp`, `mpeg`, and `m4v` video containers (#8668); optional `card_image_sizes` on `image_carousel` (#8937); seventeen URL patterns loosened to `^https://` (#8792); the rules for what changes between releases (#8704); accepting signed commercial terms binds every member, with `UNRECOGNIZED_TERMS` and the `unrecognized_terms` decline reason (#8884); Reliable Reporting managed delivery holds no buyer secret, row push is `reporting_webhook`, and an experimental `https_put` `file_transfer` transport writes signed objects to a buyer HTTPS endpoint (#8793); `media_buy.supported_delivery_types` declares whether a seller sells `guaranteed` or `non_guaranteed` inventory, or both (#8458); targeting can carry display names beside its geographic codes, `geo_value_labels` for ISO country and subdivision codes and `value_labels` on metro and place entries, and they never change what is targeted (#8966); Reliable Reporting report definitions at `contract_version` `1.2` require a `package_id` dimension whenever they include `media_buy_id` (#8983); experimental installment refinement: choose specific installments in `refine_proposals` with `installment_changes`, answered with a product whose installments are the chosen set, `media_buy.installment_refinement` (#8974), and per-installment creative assignment with `installment_refs` on `sync_creatives` `assign` and `replace` operations, `media_buy.installment_creative_assignment` (#8972). -- **rc.0:** everything in beta.6, plus prerelease pins, unpinned discovery, and anonymous capabilities; Instagram, Facebook, Snapchat and X distribution identifier types, each a canonical ID plus a handle alias (#8995); sellers declare the `sync_creatives` assignment operations they accept in `creative.assignment_operations`, and a seller declaring `creative.live_updates` lists `replace` (#8997); `media_buy.audience_targeting` promises audience overlays and discovery-only `sync_audiences`, not inline member push (#8996); optional `cta_values` on `image_carousel` constrains each card's `cta` (#9001); the inline `submitted` branches of eight tasks match their published async status files (#8934); `get_media_buy_delivery` sellers SHOULD return at least one `by_package` row, one per package, and omit a buy they can't report (#8970); when several `authorized_agents[]` entries match one agent, its scope is the union of theirs, and a `signing_keys` pin holds only if every entry that matches and authorizes the message pins keys (#9011, #9017); three experimental values take their counterparts' spelling, with no alias: `input_required` → `input-required` (`media_buy.execution_readiness`), `click_through` → `clickthrough` (`creative.live_updates`), and `underdelivery` → `under_delivery` (`media_buy.delivery_projection`) (#8989); campaign governance accepts a `sync_plans` plan that omits `human_review_required` and states two `sync_plans` validation rules (#9007); in compliance, `audience_buy_flow` pushes members only to sellers that accept inline pushes (#9013), and `inline_creatives_without_sync` sends `format_option_ref` (#9005); the public test agent's opt-in preview moves to `3.3-beta.6` (#9018). +- **rc.0:** everything in beta.6, plus prerelease pins, unpinned discovery, and anonymous capabilities; Instagram, Facebook, Snapchat and X distribution identifier types, each a canonical ID plus a handle alias (#8995); sellers declare the `sync_creatives` assignment operations they accept in `creative.assignment_operations`, and a seller declaring `creative.live_updates` lists `replace` (#8997); `media_buy.audience_targeting` promises audience overlays and discovery-only `sync_audiences`, not inline member push (#8996); optional `cta_values` on `image_carousel` constrains each card's `cta` (#9001); the inline `submitted` branches of eight tasks match their published async status files (#8934); `get_media_buy_delivery` sellers SHOULD return at least one `by_package` row, one per package, and omit a buy they can't report (#8970); when several `authorized_agents[]` entries match one agent, its scope is the union of theirs, and a `signing_keys` pin holds only if every entry that matches and authorizes the message pins keys (#9011, #9017); three experimental values take their counterparts' spelling, with no alias: `input_required` → `input-required` (`media_buy.execution_readiness`), `click_through` → `clickthrough` (`creative.live_updates`), and `underdelivery` → `under_delivery` (`media_buy.delivery_projection`) (#8989); campaign governance accepts a `sync_plans` plan that omits `human_review_required` and states two `sync_plans` validation rules (#9007); in compliance, `audience_buy_flow` pushes members only to sellers that accept inline pushes (#9013), and `inline_creatives_without_sync` sends `format_option_ref` (#9005); the public test agent's opt-in preview moves to `3.3-beta.6` (#9018); reserved-word-safe enum values replace six that collide with SDK target languages, and the originals are deprecated, not removed: `pass` → `passed` in `enums/binary-verdict.json`, `get_media_buy_artifacts` `local_verdict`, and the registry feed's compliance `tracks` status; `global` → `all` in the `RATE_LIMITED` details `scope`; and `name` → `full_name` in `onboarder.match_keys` on `core/signal-definition.json` and `core/signal-definition-enrichment.json` (#8915). ### Behavior changes to review - **Discovery never provisions (#7848).** Discovery and negotiation tasks MUST NOT create or activate an account or accept default terms. A lazily provisioning seller provisions only on a task that commits spend or creates account-owned resources. This narrows the 3.2 wording "first account-scoped request". Schemas are unchanged. @@ -139,6 +139,7 @@ Each prerelease is immutable. The `3.3-beta` documentation selector stays at bet - **Deprecated: `principal_kind` and `expected_principal_kind` (#8443).** A principal is the buyer agent as the seller has bound it, so the kind is always `buyer_agent`. Sellers keep returning and honoring them through 3.x, and `enums/principal-kind.json` is deprecated with them. - **Deprecated: condition (b) of `request_signature_required` (#8064).** It exists only for the deprecated webhook `authentication` block and is removed in 4.0 with it. - **Deprecated: `configuration_task` in `media_buy.reporting_delivery` (experimental, #8552).** Sellers list accepted registration tasks in `configuration_tasks[]`; `configuration_task` stays `"sync_accounts"` for callers pinned below 3.3. +- **Deprecated: six reserved-word enum values (#8915, rc.0).** `pass` → `passed` in `enums/binary-verdict.json`, `get_media_buy_artifacts` `local_verdict`, and the registry feed's compliance `tracks` status; `global` → `all` in the `RATE_LIMITED` details `scope`; and `name` → `full_name` in `onboarder.match_keys` on `core/signal-definition.json` and `core/signal-definition-enrichment.json`. Each enum accepts both spellings through 3.x; the original is deprecated in 3.3 and removed in 4.0. Send a replacement only when the release served is 3.3 or later, because a 3.2 receiver treats it as an unknown value. A published file, such as `adagents.json`, keeps the original through 3.x. - **Deprecated: the boolean form of `demographics` (#8866, from #8772).** In product `overlay_support` and in `required_overlay_support`, `demographics: true` is the 3.2 shorthand for `{ "age": true }`. Senders MUST send the object form. Receivers MUST accept `true` and read it as `{ "age": true }`, so it satisfies an age requirement and never a `gender` requirement. It is planned for removal in 4.0 ([#8778](https://github.com/adcontextprotocol/adcp/issues/8778)). - **Reminder, not new in 3.3: `adcp_major_version` is removed in 4.0 ([DR-0035](https://github.com/adcontextprotocol/adcp/blob/main/governance/decisions/DR-0035-adcp-major-version-removed-in-4-0.md)).** The integer request field and the `adcp.major_versions` capability field have been deprecated since 3.1. They keep working through 3.x, and 4.0 removes both. Send `adcp_version` on every request, keeping the `adcp_major_version` mirror through 3.x. In-house clients that still send only the integer should switch before 4.0. The compliance grader already blocks sellers that do not echo `adcp_version` or emit `adcp.supported_versions`, and at 4.0 rejects the legacy fields. diff --git a/docs/reference/versions.mdx b/docs/reference/versions.mdx index 282da99797..242c63cb1e 100644 --- a/docs/reference/versions.mdx +++ b/docs/reference/versions.mdx @@ -51,7 +51,7 @@ Supported patches don't change stable wire surfaces. Upgrading among supported 3 | Version | Released | Notes | |---|---|---| -| **3.3.0-rc.0** | 2026-11-16 | **Current 3.3 prerelease**, the first release candidate. Carries 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). No published SDK bundles it yet. See the [3.3 prerelease program](/docs/reference/3-3-beta). | +| **3.3.0-rc.0** | 2026-11-16 | **Current 3.3 prerelease**, the first release candidate. Carries 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). No published SDK bundles it yet. See the [3.3 prerelease program](/docs/reference/3-3-beta). | | 3.3.0-beta.6 | 2026-11-13 | Superseded. Opens the schemas that were closed by accident (DR-0036) and applies the closed-schema triage, which removes or moves the beta fields on deprecated tasks and on the commercial terms held closed until 4.0. `@adcp/sdk` 17.0.0-beta.24 and later and Python `adcp` 10.0.0b17 and later embed it. | | 3.3.0-beta.5 | 2026-11-07 | Superseded. Experimental match keys, `sales-fixed-rate` promoted to stable, and the bundled Public Suffix List. `@adcp/sdk` 17.0.0-beta.21 through 17.0.0-beta.23 and Python `adcp` 10.0.0b13 through 10.0.0b16 embed it. | | 3.3.0-beta.4 | 2026-11-05 | Superseded. Reporting-subscription coverage fixes, assignment `replace` settings transfer, and the hold, account-request, and reporting-subscription storyboards. `@adcp/sdk` 17.0.0-beta.18 through 17.0.0-beta.20 and Python `adcp` 10.0.0b12 embed it. | diff --git a/docs/reference/whats-new-in-3-3.mdx b/docs/reference/whats-new-in-3-3.mdx index bb17355dca..5bb9348b78 100644 --- a/docs/reference/whats-new-in-3-3.mdx +++ b/docs/reference/whats-new-in-3-3.mdx @@ -21,7 +21,7 @@ No stable field, enum value, or task is removed. Two result fields, one usage, t ## New in rc.0 -rc.0 (2026-11-16) is the first release candidate. Its main changes since beta.5 open the schemas that were closed by accident and settle which beta features stay in 3.3. Most of it first shipped in `3.3.0-beta.6` (2026-11-13), cut for SDK testing ahead of rc.0. New in rc.0 itself: the guidance on prerelease pins, unpinned discovery, and anonymous capabilities; the [declared assignment operations](#sellers-declare-the-assignment-operations-they-accept) ([#8997](https://github.com/adcontextprotocol/adcp/pull/8997)); audience targeting without member push ([#8996](https://github.com/adcontextprotocol/adcp/pull/8996)); [carousel card CTA values](#carousel-card-cta-values) ([#9001](https://github.com/adcontextprotocol/adcp/pull/9001)); the `by_package` guidance ([#8970](https://github.com/adcontextprotocol/adcp/pull/8970)); the scope and `signing_keys` rules for several matching `authorized_agents` entries ([#9011](https://github.com/adcontextprotocol/adcp/pull/9011), [#9017](https://github.com/adcontextprotocol/adcp/pull/9017)); three renamed experimental values ([#8989](https://github.com/adcontextprotocol/adcp/pull/8989)); an omitted `human_review_required` in campaign governance ([#9007](https://github.com/adcontextprotocol/adcp/pull/9007)); inline `submitted` branches that match their published status files ([#8934](https://github.com/adcontextprotocol/adcp/pull/8934)); compliance gates for `audience_buy_flow` and `inline_creatives_without_sync` ([#9013](https://github.com/adcontextprotocol/adcp/pull/9013), [#9005](https://github.com/adcontextprotocol/adcp/pull/9005)); the public test agent's `3.3-beta.6` preview ([#9018](https://github.com/adcontextprotocol/adcp/pull/9018)); and the Instagram, Facebook, Snapchat and X distribution identifier types ([#8995](https://github.com/adcontextprotocol/adcp/pull/8995)). +rc.0 (2026-11-16) is the first release candidate. Its main changes since beta.5 open the schemas that were closed by accident and settle which beta features stay in 3.3. Most of it first shipped in `3.3.0-beta.6` (2026-11-13), cut for SDK testing ahead of rc.0. New in rc.0 itself: the guidance on prerelease pins, unpinned discovery, and anonymous capabilities; the [declared assignment operations](#sellers-declare-the-assignment-operations-they-accept) ([#8997](https://github.com/adcontextprotocol/adcp/pull/8997)); audience targeting without member push ([#8996](https://github.com/adcontextprotocol/adcp/pull/8996)); [carousel card CTA values](#carousel-card-cta-values) ([#9001](https://github.com/adcontextprotocol/adcp/pull/9001)); the `by_package` guidance ([#8970](https://github.com/adcontextprotocol/adcp/pull/8970)); the scope and `signing_keys` rules for several matching `authorized_agents` entries ([#9011](https://github.com/adcontextprotocol/adcp/pull/9011), [#9017](https://github.com/adcontextprotocol/adcp/pull/9017)); three renamed experimental values ([#8989](https://github.com/adcontextprotocol/adcp/pull/8989)); an omitted `human_review_required` in campaign governance ([#9007](https://github.com/adcontextprotocol/adcp/pull/9007)); inline `submitted` branches that match their published status files ([#8934](https://github.com/adcontextprotocol/adcp/pull/8934)); compliance gates for `audience_buy_flow` and `inline_creatives_without_sync` ([#9013](https://github.com/adcontextprotocol/adcp/pull/9013), [#9005](https://github.com/adcontextprotocol/adcp/pull/9005)); the public test agent's `3.3-beta.6` preview ([#9018](https://github.com/adcontextprotocol/adcp/pull/9018)); reserved-word-safe enum replacements ([#8915](https://github.com/adcontextprotocol/adcp/pull/8915)); and the Instagram, Facebook, Snapchat and X distribution identifier types ([#8995](https://github.com/adcontextprotocol/adcp/pull/8995)). **Schemas are open by default ([#8866](https://github.com/adcontextprotocol/adcp/pull/8866), [DR-0036](https://github.com/adcontextprotocol/adcp/blob/main/governance/decisions/DR-0036-closed-schemas-stay-closed-within-a-major.md), decided 2026-11-09).** Closing a schema only breaks validators that hard-code it, so 3.x opens the schemas that were meant to be open: 744 of the 859 closed locations in the 3.3 schemas. 115 stay closed. Most have a structural reason, such as unions told apart by key presence, join keys, privacy clamps, and `trust.json`. The nodes inside `commercial_terms`, with `proposal-budget-constraint`, are held closed until 4.0. - Every payload that was valid stays valid. Where closure also rejected a specific field, the opened schema rejects it by name. - Generated types change. TypeScript types gain index signatures, Pydantic models stop forbidding extra fields, and Zod validators accept unknown keys where the schema opened. @@ -43,6 +43,7 @@ rc.0 (2026-11-16) is the first release candidate. Its main changes since beta.5 - **Installments (experimental).** A buyer can ask for specific installments of a product through `refine_proposals` `installment_changes` (`media_buy.installment_refinement`, [#8974](https://github.com/adcontextprotocol/adcp/pull/8974)), and the seller answers with a product that declares exactly those installments, so nothing new goes into `commercial_terms` and binding the slots themselves stays a 4.0 item ([Choose installments](/docs/media-buy/task-reference/refine_proposals#choose-installments-experimental)). `installment_refs` on a `sync_creatives` `assign` or `replace` operation limits the assignment to those installments of the package, with readback on `get_media_buys` and `list_creatives` (`media_buy.installment_creative_assignment`, [#8972](https://github.com/adcontextprotocol/adcp/pull/8972)); see [Assigning to specific installments](/docs/creative/task-reference/sync_creatives#assigning-to-specific-installments-experimental). - **Three experimental values renamed ([#8989](https://github.com/adcontextprotocol/adcp/pull/8989)).** `input_required` → `input-required` (`media_buy.execution_readiness`), `click_through` → `clickthrough` (`creative.live_updates`), and `underdelivery` → `under_delivery` (`media_buy.delivery_projection`), each the spelling its stable or sibling counterpart already uses. There is no alias, so an implementation built from a beta bundle changes to the new spelling. See [Three experimental values renamed](/docs/reference/migration/3-2-to-3-3#three-experimental-values-renamed). +- **Reserved-word-safe enum values ([#8915](https://github.com/adcontextprotocol/adcp/pull/8915)).** Six enum positions get a replacement that no SDK target language reserves, and the originals are deprecated, not removed: `pass` → `passed` in `enums/binary-verdict.json`, `get_media_buy_artifacts` `local_verdict`, and the registry feed's compliance `tracks` status; `global` → `all` in the `RATE_LIMITED` details `scope`; and `name` → `full_name` in `onboarder.match_keys` on `core/signal-definition.json` and `core/signal-definition-enrichment.json`. Both spellings are valid through 3.x, and 4.0 removes the originals. Send a replacement only to a peer served 3.3 or later. See [Reserved-word-safe enum replacements](/docs/reference/migration/3-2-to-3-3#reserved-word-safe-enum-replacements). - **Origin-only agent URLs ([#8939](https://github.com/adcontextprotocol/adcp/pull/8939)).** An origin-only `authorized_agents[].url` in `adagents.json` authorizes the agent at that origin, whatever its path. An entry with a path still matches only that URL. When several entries match one agent, its scope is the union of theirs, and a `signing_keys` pin holds only if every entry that matches and authorizes the message pins keys ([#9011](https://github.com/adcontextprotocol/adcp/pull/9011), [#9017](https://github.com/adcontextprotocol/adcp/pull/9017)). - **Declared-option conformance ([#8941](https://github.com/adcontextprotocol/adcp/pull/8941)).** A seller accepts a creative that conforms to the format option it targets, and enforces only the limits it declared. See [Format conformance](/docs/creative/task-reference/sync_creatives#format-conformance). - **Signed terms bind every member ([#8884](https://github.com/adcontextprotocol/adcp/pull/8884)).** Accepting signed commercial terms binds a party to every member `terms_digest` covers, including members it does not recognize, so a party that cannot interpret one declines (`unrecognized_terms`) or rejects (`UNRECOGNIZED_TERMS`) instead of accepting. See [Verify terms independently](/docs/media-buy/product-discovery/proposal-negotiation#3-verify-terms-independently).