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
12 changes: 12 additions & 0 deletions .changeset/signed-terms-acceptance.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
---
"adcontextprotocol": minor
---

State what accepting signed commercial terms means. `terms_digest` covers the entire `commercial_terms` JSON value: every member at every depth, including `ext` and members a party does not recognize. Several schemas inside `commercial_terms` are already open, so the signed bytes can carry members a party's release does not define.

- Accepting the terms binds the accepting party to every member. A party that cannot interpret every member MUST NOT accept them: a buyer declines with the new `decline_proposals` reason `unrecognized_terms`, a seller rejects the request that carries them (such as `buy_products` purchases) with the new error code `UNRECOGNIZED_TERMS` (the decline reason names the same condition from the buyer's side), and a governance agent denies the check. A member whose schema defines it as opaque, such as `context`, is interpreted by that definition.
- A party computes or verifies `terms_digest` over the JSON value as received, never over a re-serialized parsed model, which can drop members the model does not declare.

The rule is stated in `media-buy/commercial-terms.json`, the `terms_digest` description in `core/canonical-proposal.json`, `governance/check-governance-request.json`, and the proposal negotiation, `buy_products`, `decline_proposals`, and `check_governance` pages. The release notes, What's new in 3.3, and the 3.2 to 3.3 migration guide now state the acceptance rule after the note that `commercial-terms` is held closed until 4.0. No schema is opened or closed.

The new storyboard `media_buy_seller/unrecognized_terms_rejected` first proves a plain `buy_products` purchase is accepted, then sends the identical purchase with `adcp_compliance_undefined_member` in `format_option_refs[0]` and expects `UNRECOGNIZED_TERMS`. That member name is reserved as undefined, so no conformant seller can interpret it.
2 changes: 1 addition & 1 deletion docs/governance/campaign/tasks/check_governance.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -675,7 +675,7 @@ The seller MUST pause delivery immediately and correct the geo targeting before
| `execution_commitment` | object | Update execution | Seller-computed `{amount, currency}` positive delta for `update_media_buy`. The seller derives it from authoritative current state atomically with the revision check and write. It must not exceed or change the currency of `proposed_commitment`; a mismatch requires a fresh intent. |
| `tool` | string | Intent | The AdCP tool being checked, including compact `buy_products`, `accept_proposal`, and `control_media_buy`. Present on intent checks; `tool` + `payload` identifies an intent check. |
| `payload` | object | Intent | Full downstream tool arguments exactly as they will be sent to `target_agent`. Present on intent checks. |
| `proposal` | CanonicalProposal | `accept_proposal` | Exact committed proposal being authorized. The governance agent verifies `terms_digest` over `commercial_terms` and binds that digest into its decision; the downstream payload carries the same digest. |
| `proposal` | CanonicalProposal | `accept_proposal` | Exact committed proposal being authorized. The governance agent verifies `terms_digest` over the `commercial_terms` JSON value as received and binds that digest into its decision; the downstream payload carries the same digest. A governance agent that cannot interpret every member of `commercial_terms`, including `ext`, denies the check. |
| `governance_context` | string | Execution | Opaque context from a prior approved response. Required with `planned_delivery` or `delivery_metrics`; the governance agent derives the plan from it. Services persist and forward it without business-level parsing. |
| `consultation_context` | string | Intent re-check | Non-authorizing handle from a conditions response. Return only with the adjusted intent and the same authenticated principal, caller, plan, tool, purchase type, and target audience; never forward it to a service. |
| `phase` | enum | Execution | `purchase`, `modification`, or `delivery`. Defaults to `purchase`. Present on execution checks. |
Expand Down
2 changes: 1 addition & 1 deletion docs/media-buy/advanced-topics/pricing-models.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -622,7 +622,7 @@ When buyer and seller have negotiated discounts and commissions, the `price_brea
- `adjustments` — ordered list of adjustments, each categorized by `kind`
- `fixed_price` (on the parent pricing option) — must equal the result of applying all `fee` and `discount` adjustments sequentially to `list_price`. A breakdown from the operator's buying platform also applies `operator_fee` adjustments; see [Operator fees](#operator-fees)

Implementations should ignore unrecognized fields in `price_breakdown` and its adjustments to support forward compatibility. A reader that meets an unrecognized adjustment `kind` SHOULD skip the invariant check rather than report a mismatch.
Implementations should ignore unrecognized fields in `price_breakdown` and its adjustments to support forward compatibility. A reader that meets an unrecognized adjustment `kind` SHOULD skip the invariant check rather than report a mismatch. Reading is not accepting: inside a proposal's `commercial_terms`, `terms_digest` covers every member of the breakdown, and a party that cannot interpret every member must not accept the terms (see [Verify terms independently](/docs/media-buy/product-discovery/proposal-negotiation#3-verify-terms-independently)).

### Adjustment Kinds

Expand Down
4 changes: 3 additions & 1 deletion docs/media-buy/product-discovery/proposal-negotiation.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -324,14 +324,16 @@ An honest refusal that produces no draft uses the same response envelope but no

For every returned proposal:

1. Recompute `sha256:base64url(SHA-256(JCS(commercial_terms)))` using RFC 8785 JSON Canonicalization Scheme bytes.
1. Recompute `sha256:base64url(SHA-256(JCS(commercial_terms)))` using RFC 8785 JSON Canonicalization Scheme bytes, over the `commercial_terms` JSON value as received. Never compute it over a re-serialized parsed model, which can drop members the model does not declare.
2. Compare the recomputed digest byte-for-byte with `terms_digest`.
3. Verify `parent_proposal_id` equals `source_proposal_id`.
4. Re-evaluate budgets, fixed rates, impression totals, flight bounds, product membership, and structured criteria from `commercial_terms`.
5. Verify any `targeting_resolution.brief_targeting` against the hard targeting in `ask`, and review every sparse product `targeting_resolution.modifications` departure before selecting that configured product.
6. On `partial`, enforce the partial invariant: every requirement absent from the unsatisfied sets still passes.
7. Treat `reason`, `description`, `suggestions`, and `ask` as non-contractual prose.

`terms_digest` covers the entire `commercial_terms` value: every member at every depth, including `ext` and members you don't recognize. Several schemas inside `commercial_terms` are open, so the terms can carry members your release does not define. Accepting the terms binds you to every member, so a buyer that cannot interpret every member MUST NOT accept them. Decline the proposal with [`decline_proposals`](/docs/media-buy/task-reference/decline_proposals) reason `unrecognized_terms` instead. A member whose schema defines it as opaque, such as `context`, is interpreted by that definition. The same rule binds every party: a seller rejects a request carrying terms it cannot interpret with error code [`UNRECOGNIZED_TERMS`](/docs/building/verification/compliance-catalog#error-code-unrecognized-terms) (see [`buy_products`](/docs/media-buy/task-reference/buy_products)), and a governance agent denies the check (see [`check_governance`](/docs/governance/campaign/tasks/check_governance)).

Digest uniqueness alone is not enough for alternatives. Verify that `commercial_terms` are distinct after canonicalization; a seller cannot create fake diversity by changing only IDs, names, descriptions, or digest strings.

### 4. Retry safely
Expand Down
2 changes: 2 additions & 0 deletions docs/media-buy/task-reference/buy_products.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,8 @@ The media-buy `daily_budget_cap` is a hard aggregate ceiling and does not alloca

Success returns the MediaBuy identity and an `accepted_proposal` snapshot. Its typed `commercial_terms` preserve the exact feed and pricing versions, product and format selections, catalogs, budgets, targeting, flight, billing, and reporting commitments; `terms_digest` binds that envelope for governance and audit. The separate `purchase_bindings[]` maps each zero-based purchase position to its seller-assigned `package_id`, which SDKs use for later creative assignment without placing execution IDs inside the immutable digest. The seller creates this snapshot even though the buyer did not negotiate first, giving every MediaBuy the same commercial history for later [`refine_proposals`](/docs/media-buy/task-reference/refine_proposals).

Each purchase becomes part of those `commercial_terms`, and `terms_digest` covers every member of them at every depth, including `ext`. Accepting the purchase binds the seller to every member. A seller that cannot interpret every member of a purchase MUST reject the request with [`UNRECOGNIZED_TERMS`](/docs/building/verification/compliance-catalog#error-code-unrecognized-terms), and SHOULD set `error.field` to the member's path. It MUST NOT drop the member or record it without interpreting it. Several schemas a purchase reaches are open, such as `format_option_refs[]` entries and `targeting_overlay`, so such a request can pass schema validation. A member whose schema defines it as opaque, such as `context`, is interpreted by that definition. The seller computes `terms_digest` over the exact `commercial_terms` JSON value it returns. See [Verify terms independently](/docs/media-buy/product-discovery/proposal-negotiation#3-verify-terms-independently).

An optional buyer-supplied `name` is persisted and echoed on the completed
commitment and subsequent [`get_media_buys`](/docs/media-buy/task-reference/get_media_buys)
reads. It is operational display metadata outside `accepted_proposal` and is
Expand Down
2 changes: 2 additions & 0 deletions docs/media-buy/task-reference/decline_proposals.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -35,4 +35,6 @@ When `opportunity` is present, every proposal must belong to its `opportunity_id

Declining a seller offer (experimental in AdCP 3.3, a proposal with `proposal_initiator: "seller"` against an accepted buy) works the same way: the signed terms of the accepted buy stand and the offer can no longer be accepted. An offer the buyer ignores lapses at `expires_at` (disposition `expired`) with no call and the signed terms stand, and declining an offer that has already lapsed returns `declined`. See [Seller offers](/docs/media-buy/product-discovery/proposal-negotiation#seller-offers).

A buyer that cannot interpret every member of a proposal's `commercial_terms` must not accept it, because acceptance binds it to every member. It declines with reason `unrecognized_terms`, the same condition a seller reports as error code [`UNRECOGNIZED_TERMS`](/docs/building/verification/compliance-catalog#error-code-unrecognized-terms). See [Verify terms independently](/docs/media-buy/product-discovery/proposal-negotiation#3-verify-terms-independently).

The request does not carry `proposal_version`. Each `proposal_id` identifies one immutable commercial snapshot; [`refine_proposals`](/docs/media-buy/task-reference/refine_proposals) mints a new ID whenever terms change.
2 changes: 1 addition & 1 deletion docs/reference/migration/3-2-to-3-3.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,7 @@ Everything else is an optional declaration or a clarification. Agent identity (D

## Withdrawn from 3.3, planned for 4.0

Three features are not part of 3.3. All three add terms to `commercial_terms`, and `commercial-terms` and the term objects inside it are held closed until 4.0 ([DR-0036](https://github.com/adcontextprotocol/adcp/blob/main/governance/decisions/DR-0036-closed-schemas-stay-closed-within-a-major.md)). 4.0 gives `commercial_terms` a declared extension point with must-understand, and the three features come back through it. The decision is in [adcp#8501](https://github.com/adcontextprotocol/adcp/issues/8501).
Three features are not part of 3.3. All three add terms to `commercial_terms`, and `commercial-terms` and the term objects inside it are held closed until 4.0 ([DR-0036](https://github.com/adcontextprotocol/adcp/blob/main/governance/decisions/DR-0036-closed-schemas-stay-closed-within-a-major.md)). A buyer must not be bound by terms it cannot read: `terms_digest` covers every member of `commercial_terms`, including members under the open schemas inside it, and a party that cannot interpret every member must not accept the terms ([Verify terms independently](/docs/media-buy/product-discovery/proposal-negotiation#3-verify-terms-independently)). 4.0 gives `commercial_terms` a declared extension point with must-understand, and the three features come back through it. The decision is in [adcp#8501](https://github.com/adcontextprotocol/adcp/issues/8501).

### Definition pins (published in beta.0 and beta.1, removed after beta.1)

Expand Down
2 changes: 1 addition & 1 deletion docs/reference/release-notes.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -187,7 +187,7 @@ These merged on `main` during the 3.3 cycle and were also released on the 3.2 li

### Withdrawn from 3.3, planned for 4.0

Three features are not part of 3.3. All three add terms to `commercial_terms`, which is held closed until 4.0 ([DR-0036](https://github.com/adcontextprotocol/adcp/blob/main/governance/decisions/DR-0036-closed-schemas-stay-closed-within-a-major.md)). 4.0 gives `commercial_terms` a declared extension point with must-understand and brings the features back ([adcp#8501](https://github.com/adcontextprotocol/adcp/issues/8501)). The removal merged in [#8537](https://github.com/adcontextprotocol/adcp/pull/8537) and first takes effect in `3.3.0-beta.2`.
Three features are not part of 3.3. All three add terms to `commercial_terms`, which is held closed until 4.0 ([DR-0036](https://github.com/adcontextprotocol/adcp/blob/main/governance/decisions/DR-0036-closed-schemas-stay-closed-within-a-major.md)). A buyer must not be bound by terms it cannot read: `terms_digest` covers every member of `commercial_terms`, including members under the open schemas inside it, and a party that cannot interpret every member must not accept the terms ([Verify terms independently](/docs/media-buy/product-discovery/proposal-negotiation#3-verify-terms-independently)). 4.0 gives `commercial_terms` a declared extension point with must-understand and brings the features back ([adcp#8501](https://github.com/adcontextprotocol/adcp/issues/8501)). The removal merged in [#8537](https://github.com/adcontextprotocol/adcp/pull/8537) and first takes effect in `3.3.0-beta.2`.

- **Definition pins (#7960), published in `3.3.0-beta.0` and `3.3.0-beta.1`, removed after beta.1.** `commercial_terms.definition_pins[]`, the `definition_changed` refinement reason with `drifted_pins[]`, `REFERENCE_DEFINITION_CHANGED`, the `definition_pin_probe` controller scenario, the `definition_pin_drift` storyboard, and the `definition-pins` test vectors are removed. The beta rule that sellers MUST pin covered third-party definitions no longer applies. This is a beta-to-beta change, not a change to any stable release.
- **Purchase rights (#8101), published in `3.3.0-beta.1` as experimental `media_buy.purchase_rights` and removed after beta.1.** `purchases[].rights[]`, `brand/rights-scope.json` (so `brand/rights-terms.json` returns to its 3.2 form), and the `paid_amplification` and `content_reuse` values of `right-use` are removed.
Expand Down
2 changes: 1 addition & 1 deletion docs/reference/whats-new-in-3-3.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -325,7 +325,7 @@ These merged on `main` during the 3.3 cycle and were also released on the 3.2 li

## Withdrawn from 3.3, planned for 4.0

Three features are not part of 3.3. All three add terms to `commercial_terms`, which is held closed until 4.0. 4.0 gives `commercial_terms` a declared extension point with must-understand and brings them back ([adcp#8501](https://github.com/adcontextprotocol/adcp/issues/8501)).
Three features are not part of 3.3. All three add terms to `commercial_terms`, which is held closed until 4.0. A buyer must not be bound by terms it cannot read: `terms_digest` covers every member of `commercial_terms`, including members under the open schemas inside it, and a party that cannot interpret every member must not accept the terms ([Verify terms independently](/docs/media-buy/product-discovery/proposal-negotiation#3-verify-terms-independently)). 4.0 gives `commercial_terms` a declared extension point with must-understand and brings them back ([adcp#8501](https://github.com/adcontextprotocol/adcp/issues/8501)).

| Feature | Where it stood | What changes |
|---|---|---|
Expand Down
10 changes: 10 additions & 0 deletions docs/snippets/compliance-error-codes.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -128,6 +128,7 @@ description: "Canonical AdCP error codes with recovery classifications, remediat
| `STALE_RESPONSE` | transient | advisory — emitted alongside a populated payload that was served from cache past the seller's freshness target because an upstream or sub-agent was unreachable. The response is usable; treat as non-fatal. Inspect <code>{"error.details.cache_age_seconds"}</code> to decide whether to immediately retry for fresh data or accept the cached value; the seller's own service is healthy, so retry is safe (it does not amplify the upstream failure) |
| `TERMS_REJECTED` | correctable | adjust the proposed terms and retry, or omit measurement_terms to accept the product's defaults |
| `UNPRICEABLE_OUTPUT` | correctable | target an output format the transformer prices, or have the seller add a pricing option covering it |
| `UNRECOGNIZED_TERMS` | correctable | remove the member the seller cannot interpret, or send it only to sellers that interpret it |
| `UNSUPPORTED_FEATURE` | correctable | check get_adcp_capabilities (or the product's overlay_support for a rejected targeting dimension), remove unsupported fields, and use details.replacement_dimension when present |
| `UNSUPPORTED_GRANULARITY` | correctable | pick a granularity from the product's reporting_capabilities.windowed_pull_granularities (via get_adcp_capabilities) and resubmit, or omit time_granularity to fall back to cumulative date-range pulls |
| `UNSUPPORTED_PROVISIONING` | correctable | re-issue with the entry shape the seller supports — <code>{"account: {account_id: ...}"}</code> for settings-update sellers with account-id namespaces, or <code>{"brand+operator+billing"}</code> for provisioning sellers; check seller documentation or capability declaration for which modes are implemented |
Expand Down Expand Up @@ -1255,6 +1256,15 @@ Buyer-proposed measurement_terms were rejected by the seller. The error details

A creative transformer build targets an output capability that no pricing option covers — no transformer.pricing_options entry has a matching applies_to_output_capability_ids and none is unscoped. The build is rejected rather than billed at a guessed rate. Recovery: correctable.

</Accordion>
<a id="error-code-unrecognized-terms"></a>

<Accordion title="UNRECOGNIZED_TERMS — correctable">

**Suggested action:** remove the member the seller cannot interpret, or send it only to sellers that interpret it

The request carries commercial terms the seller would record and be bound by, such as a buy_products purchase, and at least one member of them, at any depth and including ext, is one the seller cannot interpret. Accepting signed terms binds the accepting party to every member, so the seller MUST reject the request instead of accepting it, dropping the member, or carrying it without interpreting it. A member whose schema defines it as opaque, such as context, is interpreted by that definition. The seller SHOULD set error.field to the path of the first such member. Distinct from UNSUPPORTED_FEATURE (a field the seller recognizes but does not support) and INVALID_REQUEST (a request that fails the schema). Recovery: correctable (remove the member, or send it only to sellers that interpret it).

</Accordion>
<a id="error-code-unsupported-feature"></a>

Expand Down
5 changes: 5 additions & 0 deletions scripts/error-code-drift-dispositions.json
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,11 @@
"target_version": "3.3",
"note": "request_account and sync_accounts settings updates return this when the seller would accept the change only as a separate account and the caller did not allow one. New 3.3 account wire code \u2014 held for 3.3."
},
"UNRECOGNIZED_TERMS": {
"disposition": "held-for-next-minor",
"target_version": "3.3",
"note": "A seller rejects a request carrying commercial terms it would be bound by, such as buy_products purchases, when it cannot interpret every member. New 3.3 media-buy wire code \u2014 held for 3.3."
},
"CREATIVE_LIVE_UPDATE_UNSUPPORTED": {
"disposition": "held-for-next-minor",
"target_version": "3.3",
Expand Down
Loading
Loading