From 2dfa4b0ba4e930674dde757b6c8997f28809c845 Mon Sep 17 00:00:00 2001 From: "Constantine.mirin" Date: Mon, 9 Nov 2026 22:50:16 +0100 Subject: [PATCH 1/5] fix(schemas): acceptance of signed commercial terms binds every member terms_digest is SHA-256 over the JCS bytes of the whole commercial_terms value, and many schemas reachable from commercial-terms.json are already open, so members a party does not recognize can sit inside the signed bytes. The spec never said what accepting such terms means. State the rule in commercial-terms.json, the terms_digest description, check-governance-request.json, and the docs that specify the digest and acceptance: - The digest covers the entire commercial_terms JSON value, every member at every depth, including ext and unrecognized members. - 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 reason unrecognized_terms, a seller rejects the request with the new error code UNRECOGNIZED_TERMS, 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 the digest over the JSON value as received, never over a re-serialized parsed model. Correct the release notes, What's new in 3.3, and both migration guides, which gave "terms_digest signs exactly those terms" as a reason to keep commercial-terms closed. It stays closed because a minor release never changes a closed schema. Add the media_buy_seller/unrecognized_terms_rejected storyboard: a buy_products purchase carries an undefined member in format_option_refs[0], an open schema, and must fail with UNRECOGNIZED_TERMS; the same purchase without it must succeed. The training agent recorded the member inside the accepted commercial_terms; it now rejects any purchase member the source schemas do not declare. --- .changeset/signed-terms-acceptance.md | 12 + .../campaign/tasks/check_governance.mdx | 2 +- .../advanced-topics/pricing-models.mdx | 2 +- .../proposal-negotiation.mdx | 4 +- .../media-buy/task-reference/buy_products.mdx | 2 + .../task-reference/decline_proposals.mdx | 2 + docs/reference/migration/3-2-to-3-3.mdx | 2 +- docs/reference/migration/v4-compatibility.mdx | 2 +- docs/reference/release-notes.mdx | 2 +- docs/reference/whats-new-in-3-3.mdx | 2 +- docs/snippets/compliance-error-codes.mdx | 10 + scripts/error-code-drift-dispositions.json | 5 + .../training-agent/served-release-fields.ts | 51 ++++ server/src/training-agent/task-handlers.ts | 16 +- ...aining-agent-served-release-fields.test.ts | 25 ++ .../source/protocols/media-buy/index.yaml | 1 + .../unrecognized_terms_rejected.yaml | 235 ++++++++++++++++++ .../source/core/canonical-proposal.json | 2 +- static/schemas/source/enums/error-code.json | 6 + .../source/enums/proposal-decline-reason.json | 2 + .../governance/check-governance-request.json | 2 +- .../source/media-buy/commercial-terms.json | 2 +- 22 files changed, 378 insertions(+), 11 deletions(-) create mode 100644 .changeset/signed-terms-acceptance.md create mode 100644 static/compliance/source/protocols/media-buy/scenarios/unrecognized_terms_rejected.yaml diff --git a/.changeset/signed-terms-acceptance.md b/.changeset/signed-terms-acceptance.md new file mode 100644 index 00000000000..b63a08e0bf7 --- /dev/null +++ b/.changeset/signed-terms-acceptance.md @@ -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`, 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 migration guides no longer say that `terms_digest` "signs exactly those terms" as a reason for keeping `commercial-terms` closed; it stays closed because a minor release never changes a closed schema. No schema is opened or closed. + +The new storyboard `media_buy_seller/unrecognized_terms_rejected` sends a `buy_products` purchase whose `format_option_refs[0]` carries a member no release defines and expects `UNRECOGNIZED_TERMS`, then sends the same purchase without it and expects a MediaBuy. diff --git a/docs/governance/campaign/tasks/check_governance.mdx b/docs/governance/campaign/tasks/check_governance.mdx index d075bb2795e..73dab3a56b3 100644 --- a/docs/governance/campaign/tasks/check_governance.mdx +++ b/docs/governance/campaign/tasks/check_governance.mdx @@ -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. | diff --git a/docs/media-buy/advanced-topics/pricing-models.mdx b/docs/media-buy/advanced-topics/pricing-models.mdx index f31d880291a..26e2660c3bc 100644 --- a/docs/media-buy/advanced-topics/pricing-models.mdx +++ b/docs/media-buy/advanced-topics/pricing-models.mdx @@ -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 diff --git a/docs/media-buy/product-discovery/proposal-negotiation.mdx b/docs/media-buy/product-discovery/proposal-negotiation.mdx index 5e94ab9179e..a0505785149 100644 --- a/docs/media-buy/product-discovery/proposal-negotiation.mdx +++ b/docs/media-buy/product-discovery/proposal-negotiation.mdx @@ -324,7 +324,7 @@ 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`. @@ -332,6 +332,8 @@ For every returned proposal: 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 [`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 diff --git a/docs/media-buy/task-reference/buy_products.mdx b/docs/media-buy/task-reference/buy_products.mdx index 982a3a5652d..45ab1932554 100644 --- a/docs/media-buy/task-reference/buy_products.mdx +++ b/docs/media-buy/task-reference/buy_products.mdx @@ -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 diff --git a/docs/media-buy/task-reference/decline_proposals.mdx b/docs/media-buy/task-reference/decline_proposals.mdx index ee9ec495df6..45b7d82eab6 100644 --- a/docs/media-buy/task-reference/decline_proposals.mdx +++ b/docs/media-buy/task-reference/decline_proposals.mdx @@ -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`. 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. diff --git a/docs/reference/migration/3-2-to-3-3.mdx b/docs/reference/migration/3-2-to-3-3.mdx index d8b0b9984be..ae5dcc439d6 100644 --- a/docs/reference/migration/3-2-to-3-3.mdx +++ b/docs/reference/migration/3-2-to-3-3.mdx @@ -75,7 +75,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` stays closed within 3.x. A buyer must not be bound by terms it cannot read, and `terms_digest` signs exactly those terms. If the object were open, a 3.2 buyer could accept a 3.3 term it silently ignored, and a minor release never changes a closed schema ([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` stays closed within 3.x because a minor release never changes a closed schema ([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) diff --git a/docs/reference/migration/v4-compatibility.mdx b/docs/reference/migration/v4-compatibility.mdx index 0dd91d3d139..3fee3e37ca0 100644 --- a/docs/reference/migration/v4-compatibility.mdx +++ b/docs/reference/migration/v4-compatibility.mdx @@ -140,7 +140,7 @@ In 3.3 the experimental `target_audiences[]` is a sibling of `audience_evidence_ ## Planned for 4.0: withdrawn from 3.3 -The three checks below record 3.3 features that are withdrawn and planned for 4.0. All three add terms to `commercial_terms`. The `commercial-terms` schema is closed on purpose: a buyer must not be bound by terms it cannot read, and `terms_digest` signs exactly those terms. If the object were open, a 3.2 buyer could accept a 3.3 term it silently ignored. A minor release never changes a closed schema ([DR-0036](https://github.com/adcontextprotocol/adcp/blob/main/governance/decisions/DR-0036-closed-schemas-stay-closed-within-a-major.md)), so these features wait for 4.0, where `commercial_terms` gets a declared extension point with must-understand. The decision and its reasoning are in [adcp#8501](https://github.com/adcontextprotocol/adcp/issues/8501). The [3.3 migration guide](/docs/reference/migration/3-2-to-3-3#withdrawn-from-3-3-planned-for-4-0) says what changed between `3.3.0-beta.0` and `3.3.0-beta.1`. +The three checks below record 3.3 features that are withdrawn and planned for 4.0. All three add terms to `commercial_terms`. The `commercial-terms` schema is closed, and a minor release never changes a closed schema ([DR-0036](https://github.com/adcontextprotocol/adcp/blob/main/governance/decisions/DR-0036-closed-schemas-stay-closed-within-a-major.md)), so these features wait for 4.0, where `commercial_terms` gets a declared extension point with must-understand. The decision and its reasoning are in [adcp#8501](https://github.com/adcontextprotocol/adcp/issues/8501). The [3.3 migration guide](/docs/reference/migration/3-2-to-3-3#withdrawn-from-3-3-planned-for-4-0) says what changed between `3.3.0-beta.0` and `3.3.0-beta.1`. Nothing here is graded. 3.3 has no wire form for any of it after beta.1, so a run cannot observe it. The designs are preserved at the merge commits named below, so the 4.0 work starts from them instead of from a blank page: `git show :` prints any file. diff --git a/docs/reference/release-notes.mdx b/docs/reference/release-notes.mdx index 798873785f4..26ec9f66e05 100644 --- a/docs/reference/release-notes.mdx +++ b/docs/reference/release-notes.mdx @@ -184,7 +184,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`, and `commercial-terms` stays closed within 3.x: a buyer must not be bound by terms it cannot read, and `terms_digest` signs exactly those terms. Opening the object would let a 3.2 buyer accept a 3.3 term it silently ignored, and a minor release never changes a closed schema ([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`, and `commercial-terms` stays closed within 3.x because a minor release never changes a closed schema ([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. diff --git a/docs/reference/whats-new-in-3-3.mdx b/docs/reference/whats-new-in-3-3.mdx index 60c66a14479..c4fe1aa935a 100644 --- a/docs/reference/whats-new-in-3-3.mdx +++ b/docs/reference/whats-new-in-3-3.mdx @@ -321,7 +321,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`, and `commercial-terms` stays closed within 3.x: a buyer must not be bound by terms it cannot read, and `terms_digest` signs exactly those terms. If the object were open, a 3.2 buyer could accept a 3.3 term it silently ignored. 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`, and `commercial-terms` stays closed within 3.x because a minor release never changes a closed schema. 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 | |---|---|---| diff --git a/docs/snippets/compliance-error-codes.mdx b/docs/snippets/compliance-error-codes.mdx index b2ae494db13..96dc62dc3fb 100644 --- a/docs/snippets/compliance-error-codes.mdx +++ b/docs/snippets/compliance-error-codes.mdx @@ -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 {"error.details.cache_age_seconds"} 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 — {"account: {account_id: ...}"} for settings-update sellers with account-id namespaces, or {"brand+operator+billing"} for provisioning sellers; check seller documentation or capability declaration for which modes are implemented | @@ -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. + + + + + +**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). + diff --git a/scripts/error-code-drift-dispositions.json b/scripts/error-code-drift-dispositions.json index 93033d9bf77..5ee0fea1b7c 100644 --- a/scripts/error-code-drift-dispositions.json +++ b/scripts/error-code-drift-dispositions.json @@ -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", diff --git a/server/src/training-agent/served-release-fields.ts b/server/src/training-agent/served-release-fields.ts index 61d8c5c10c5..4d1b50dcd89 100644 --- a/server/src/training-agent/served-release-fields.ts +++ b/server/src/training-agent/served-release-fields.ts @@ -233,6 +233,57 @@ export function omitFieldsAddedAfterRelease(value: T, schemaFile: string, ser return copy; } +function collectUndeclared( + value: unknown, + schemas: readonly Located[], + path: string[], + found: string[][], +): void { + if (schemas.length === 0) return; + // context is opaque by definition (core/context.json), so its members are + // interpreted as opaque correlation data, not as terms. + if (schemas.some(({ file }) => file === 'core/context.json')) return; + if (Array.isArray(value)) { + const items = alternativesOf(schemas + .filter(({ node }) => node.items !== undefined) + .map(({ node, file }) => ({ node: node.items as Schema, file }))); + value.forEach((item, index) => collectUndeclared(item, items, [...path, String(index)], found)); + return; + } + if (!isRecord(value)) return; + for (const [key, child] of Object.entries(value)) { + const declarations: Located[] = []; + for (const { node, file } of schemas) { + const properties = node.properties; + if (isRecord(properties) && properties[key] !== undefined) { + declarations.push({ node: properties[key] as Schema, file }); + } else if (isRecord(node.additionalProperties)) { + declarations.push({ node: node.additionalProperties, file }); + } + } + if (declarations.length === 0) { + found.push([...path, key]); + continue; + } + collectUndeclared(child, alternativesOf(declarations), [...path, key], found); + } +} + +/** + * Paths of the members of `value` that no declaration in `schemaFile` + * (relative to static/schemas/source) covers, at any depth: keys under an + * open object that names no such property, `ext` members included. The walk + * treats composition as a union, like the release gate above, so a key any + * branch declares counts as declared. A party that interprets exactly the + * source schemas cannot interpret these members, so it must not accept + * commercial terms that carry them (media-buy/commercial-terms.json). + */ +export function undeclaredMembers(value: unknown, schemaFile: string): string[][] { + const found: string[][] = []; + collectUndeclared(value, alternatives(sourceSchemaDocument(schemaFile), schemaFile), [], found); + return found; +} + const servedEnums = new Map | null>(); function enumValues(schemaRef: string, version: string): unknown { diff --git a/server/src/training-agent/task-handlers.ts b/server/src/training-agent/task-handlers.ts index 8f291572b00..475ed43501f 100644 --- a/server/src/training-agent/task-handlers.ts +++ b/server/src/training-agent/task-handlers.ts @@ -81,7 +81,7 @@ import { resolveReportingAccountDurably, } from './reporting-reliability.js'; import { loadSourceSchema, validateSourceSchema } from './source-schema.js'; -import { omitFieldsAddedAfterRelease, propertiesAddedAfterRelease, servedReleaseEnum, toolAddedAfterRelease } from './served-release-fields.js'; +import { omitFieldsAddedAfterRelease, propertiesAddedAfterRelease, servedReleaseEnum, toolAddedAfterRelease, undeclaredMembers } from './served-release-fields.js'; import { TRAINING_AGGREGATE_FREQUENCY_CAPPING, TRAINING_PACKAGE_FREQUENCY_CAPPING, @@ -23751,6 +23751,20 @@ export async function handleBuyProducts( const targetedPackageCounts = new Map(); for (let index = 0; index < args.purchases.length; index++) { const purchase = args.purchases[index]!; + // Each purchase becomes accepted commercial_terms the seller is bound by, + // member for member (media-buy/commercial-terms.json). A member the agent + // cannot interpret is rejected, never dropped or carried uninterpreted. + const [unrecognized] = undeclaredMembers(purchase, 'media-buy/product-purchase-input.json'); + if (unrecognized) { + return { + errors: [{ + code: 'UNRECOGNIZED_TERMS', + message: 'The purchase carries a member this seller cannot interpret, so it cannot accept the terms.', + field: `purchases[${index}]${unrecognized.map(segment => (/^\d+$/.test(segment) ? `[${segment}]` : `.${segment}`)).join('')}`, + recovery: 'correctable', + }], + }; + } const product = catalog.get(purchase.product_id); const pricing = product?.pricing_options.find( option => option.pricing_option_id === purchase.pricing_option_id, diff --git a/server/tests/unit/training-agent-served-release-fields.test.ts b/server/tests/unit/training-agent-served-release-fields.test.ts index 5bb671098e1..5733e3d7055 100644 --- a/server/tests/unit/training-agent-served-release-fields.test.ts +++ b/server/tests/unit/training-agent-served-release-fields.test.ts @@ -6,6 +6,7 @@ import { omitFieldsAddedAfterRelease, propertiesAddedAfterRelease, servedReleaseEnum, + undeclaredMembers, } from '../../src/training-agent/served-release-fields.js'; const CAPABILITIES = 'protocol/get-adcp-capabilities-response.json'; @@ -68,3 +69,27 @@ describe('served-release field gate (#8487)', () => { expect(servedReleaseEnum('enums/specialism.json', '4.0')).toBeNull(); }); }); + +describe('undeclared members in commercial terms', () => { + const PURCHASE = 'media-buy/product-purchase-input.json'; + const purchase = { + product_id: 'p1', + pricing_option_id: 'cpm', + format_option_refs: [{ scope: 'product', format_option_id: 'f1' }], + budget: 1000, + }; + + it('finds a member no declaration covers under an open schema', () => { + expect(undeclaredMembers(purchase, PURCHASE)).toEqual([]); + const withMember = { + ...purchase, + format_option_refs: [{ scope: 'product', format_option_id: 'f1', delivery_share: 0.6 }], + }; + expect(undeclaredMembers(withMember, PURCHASE)).toEqual([['format_option_refs', '0', 'delivery_share']]); + }); + + it('counts ext members as uninterpreted and context members as opaque', () => { + expect(undeclaredMembers({ ...purchase, ext: { acme: { weight: 2 } } }, PURCHASE)).toEqual([['ext', 'acme']]); + expect(undeclaredMembers({ ...purchase, context: { trace_id: 't1' } }, PURCHASE)).toEqual([]); + }); +}); diff --git a/static/compliance/source/protocols/media-buy/index.yaml b/static/compliance/source/protocols/media-buy/index.yaml index 83faff0d9af..a176e9c1af2 100644 --- a/static/compliance/source/protocols/media-buy/index.yaml +++ b/static/compliance/source/protocols/media-buy/index.yaml @@ -23,6 +23,7 @@ requires_scenarios: - media_buy_seller/external_audience_source_binding - media_buy_seller/measurement_terms_rejected - media_buy_seller/measurement_terms_accepted + - media_buy_seller/unrecognized_terms_rejected - media_buy_seller/pending_creatives_to_start - media_buy_seller/inventory_list_targeting - media_buy_seller/inventory_list_no_match diff --git a/static/compliance/source/protocols/media-buy/scenarios/unrecognized_terms_rejected.yaml b/static/compliance/source/protocols/media-buy/scenarios/unrecognized_terms_rejected.yaml new file mode 100644 index 00000000000..2ab92a37432 --- /dev/null +++ b/static/compliance/source/protocols/media-buy/scenarios/unrecognized_terms_rejected.yaml @@ -0,0 +1,235 @@ +# Grades the acceptance rule for signed commercial terms (media-buy/commercial-terms.json, +# core/canonical-proposal.json terms_digest): terms_digest covers the entire commercial_terms +# JSON value, accepting the terms binds the accepting party to every member, and a seller that +# cannot interpret every member of terms it would record MUST reject the request with +# UNRECOGNIZED_TERMS instead of accepting it, dropping the member, or carrying it uninterpreted. +# +# buy_products purchases[] become accepted_proposal.commercial_terms.purchases[], so the seller +# is the accepting party. The unrecognized member sits in format_option_refs[0], a schema that is +# open (additionalProperties: true), so the request passes schema validation and fails for one +# reason only. The control step sends the same purchase without the member and must succeed. +id: media_buy_seller/unrecognized_terms_rejected +version: "1.0.0" +title: "Seller rejects commercial terms it cannot interpret" +category: media_buy_seller +summary: "Verifies that buy_products rejects a purchase carrying a member the seller cannot interpret with UNRECOGNIZED_TERMS, and accepts the same purchase without it." +track: media_buy +introduced_in: "3.3" + +requires: + - controller + +required_tools: + - list_products + - buy_products + +requires_capability: + path: media_buy.lifecycle_tools + contains: buy_products + +narrative: | + A buyer's buy_products purchases become the commercial_terms of the accepted + proposal the seller records, and terms_digest covers every member of them. + Accepting signed terms binds the accepting party to every member, so a + seller that cannot interpret a member must not accept the terms. Dropping the + member would record terms the buyer did not send; carrying it would bind the + seller to a term it never read. + + The buyer sends a purchase whose format option reference carries + delivery_share, a member no AdCP release defines. The format option + reference schema is open, so the request is schema-valid. The seller rejects + it with UNRECOGNIZED_TERMS. The same purchase without the member then + completes, which shows the member is the only reason for the rejection. + +agent: + interaction_model: media_buy_seller + capabilities: + - sells_media + examples: + - "Publisher with a versioned product catalog and direct-purchase workflow" + +caller: + role: buyer_agent + example: "Pinnacle Agency (buyer)" + +prerequisites: + description: "The controller seeds one non-guaranteed product with a single product-local format option and a fixed CPM pricing option." + test_kit: "test-kits/acme-outdoor.yaml" + controller_seeding: true + +fixtures: + products: + - product_id: "unrecognized_terms_display" + name: "Unrecognized Terms Display" + description: "Compliance fixture: non-guaranteed display product for the unrecognized-terms rejection." + delivery_type: "non_guaranteed" + channels: ["display"] + format_options: + - format_option_id: "unrecognized_terms_display_300x250" + format_kind: "image" + params: + width: 300 + height: 250 + pricing_options: + - product_id: "unrecognized_terms_display" + pricing_option_id: "unrecognized_terms_cpm" + pricing_model: "cpm" + currency: "USD" + fixed_price: 12 + +phases: + - id: setup + title: "Account setup" + steps: + - id: sync_accounts + title: "Establish account" + task: sync_accounts + schema_ref: "account/sync-accounts-request.json" + response_schema_ref: "account/sync-accounts-response.json" + doc_ref: "/accounts/tasks/sync_accounts" + stateful: true + expected: | + Return the account with account_id and status active. + + sample_request: + accounts: + - brand: + domain: "acmeoutdoor.example" + operator: "pinnacle-agency.example" + billing: "operator" + payment_terms: "net_30" + + idempotency_key: "$generate:uuid_v4#media_buy_seller_unrecognized_terms_setup_sync_accounts" + validations: + - check: response_schema + description: "Response matches sync-accounts-response.json schema" + - check: field_present + path: "accounts[0].account_id" + description: "Account has a platform-assigned ID" + + - id: discover_offer + title: "Discover the published offer" + depends_on: [setup] + steps: + - id: list_unrecognized_terms_product + title: "List the seeded product" + task: list_products + schema_ref: "media-buy/list-products-request.json" + response_schema_ref: "media-buy/list-products-response.json" + doc_ref: "/media-buy/task-reference/list_products" + stateful: true + expected: | + Return outcome listed with the seeded product, its feed_version, and its + pricing_version. + + sample_request: + idempotency_key: "$generate:uuid_v4#media_buy_seller_unrecognized_terms_discover_offer_list" + account: + brand: + domain: "acmeoutdoor.example" + operator: "pinnacle-agency.example" + criteria: + product_ids: ["unrecognized_terms_display"] + fields: ["product_id", "name", "format_options", "pricing_options"] + context_outputs: + - name: feed_version + path: "feed_version" + - name: pricing_version + path: "pricing_version" + validations: + - check: response_schema + description: "Response matches list-products-response.json schema" + - check: field_value + path: "outcome" + value: "listed" + description: "The response contains a product page" + - check: field_value + path: "products[0].product_id" + value: "unrecognized_terms_display" + description: "The seeded product is discoverable" + - check: field_present + path: "feed_version" + description: "The response carries the feed_version buy_products requires" + + - id: purchase + title: "Reject terms with an unrecognized member, then accept them without it" + depends_on: [discover_offer] + narrative: | + Both requests are identical except for delivery_share inside + format_option_refs[0]. Only the first carries it. + steps: + - id: reject_unrecognized_member + title: "Reject a purchase whose format option reference carries an unrecognized member" + task: buy_products + schema_ref: "media-buy/buy-products-request.json" + response_schema_ref: "media-buy/buy-products-response.json" + doc_ref: "/media-buy/task-reference/buy_products" + expect_error: true + negative_path: payload_well_formed + stateful: true + expected: | + Reject with UNRECOGNIZED_TERMS. The purchase would become commercial_terms + the seller is bound by, and the seller cannot interpret delivery_share. + Do not create a MediaBuy, drop the member, or record it uninterpreted. + + sample_request: + idempotency_key: "$generate:uuid_v4#media_buy_seller_unrecognized_terms_purchase_reject" + account: + brand: + domain: "acmeoutdoor.example" + operator: "pinnacle-agency.example" + feed_version: "$context.feed_version" + pricing_version: "$context.pricing_version" + purchases: + - product_id: "unrecognized_terms_display" + pricing_option_id: "unrecognized_terms_cpm" + format_option_refs: + - scope: "product" + format_option_id: "unrecognized_terms_display_300x250" + delivery_share: 0.6 + budget: 1000 + start_time: "asap" + end_time: "2099-09-30T23:59:59Z" + validations: + - check: response_schema + description: "Rejected response matches buy-products-response.json" + - check: error_code + value: "UNRECOGNIZED_TERMS" + description: "A member the seller cannot interpret blocks acceptance of the terms" + + - id: accept_without_member + title: "Accept the same purchase without the unrecognized member" + task: buy_products + schema_ref: "media-buy/buy-products-request.json" + response_schema_ref: "media-buy/buy-products-response.json" + doc_ref: "/media-buy/task-reference/buy_products" + stateful: true + expected: | + Create the MediaBuy and return the accepted proposal snapshot. + + sample_request: + idempotency_key: "$generate:uuid_v4#media_buy_seller_unrecognized_terms_purchase_accept" + account: + brand: + domain: "acmeoutdoor.example" + operator: "pinnacle-agency.example" + feed_version: "$context.feed_version" + pricing_version: "$context.pricing_version" + purchases: + - product_id: "unrecognized_terms_display" + pricing_option_id: "unrecognized_terms_cpm" + format_option_refs: + - scope: "product" + format_option_id: "unrecognized_terms_display_300x250" + budget: 1000 + start_time: "asap" + end_time: "2099-09-30T23:59:59Z" + validations: + - check: response_schema + description: "Response matches buy-products-response.json" + - check: field_present + path: "media_buy_id" + description: "The purchase without the member creates a MediaBuy" + - check: field_present + path: "accepted_proposal.terms_digest" + description: "The seller records the accepted terms and their digest" diff --git a/static/schemas/source/core/canonical-proposal.json b/static/schemas/source/core/canonical-proposal.json index 19328387b59..046eebf477e 100644 --- a/static/schemas/source/core/canonical-proposal.json +++ b/static/schemas/source/core/canonical-proposal.json @@ -96,7 +96,7 @@ "terms_digest": { "type": "string", "pattern": "^sha256:[A-Za-z0-9_-]{43}$", - "description": "Base64url SHA-256 digest of the RFC 8785 JCS serialization of commercial_terms, prefixed with sha256:." + "description": "Base64url SHA-256 digest of the RFC 8785 JCS serialization of commercial_terms, prefixed with sha256:. It covers the entire commercial_terms JSON value: every member at every depth, including ext and members a party does not recognize. A party computes or verifies it over the JSON value as received, never over a re-serialized parsed model, which can drop members the model does not declare. Accepting the terms binds the accepting party to every member, and a party that cannot interpret every member MUST NOT accept them (see commercial-terms.json)." }, "insertion_order": { "$ref": "/schemas/core/insertion-order.json" }, "total_budget_guidance": { diff --git a/static/schemas/source/enums/error-code.json b/static/schemas/source/enums/error-code.json index 4d6a9216651..6eaa15908de 100644 --- a/static/schemas/source/enums/error-code.json +++ b/static/schemas/source/enums/error-code.json @@ -78,6 +78,7 @@ "MULTI_FINALIZE_UNSUPPORTED", "IO_REQUIRED", "TERMS_REJECTED", + "UNRECOGNIZED_TERMS", "BIDDING_PLACEMENT_CONFLICT", "AMBIGUOUS_BIDDING_POLICY", "CONFLICTING_SELECTORS", @@ -204,6 +205,7 @@ "MULTI_FINALIZE_UNSUPPORTED": "Returned by sellers that cannot guarantee atomic commit across multiple proposals in a single finalize batch. Two call sites where this applies: (1) a `get_products` call with multiple `action: 'finalize'` entries in `refine[]` targeting different `proposal_id` values; (2) a `refine_proposals` call with multiple `action: 'finalize'` entries in `refinements[]` targeting different `proposal_id` values. The buyer's intent — atomic multi-proposal finalize — is structurally well-formed and per spec atomic on both surfaces, but this seller's downstream stack cannot satisfy the atomicity guarantee (e.g., the proposals route to two different ad servers with no 2PC). More specific than `INVALID_REQUEST` so buyers can distinguish 'this seller doesn't support multi-finalize' from 'the request itself is malformed'. Recovery: correctable (sequence the finalize calls one-`proposal_id`-per-call on whichever task surface the buyer is using; there is no capability flag for multi-finalize support, so a successful first-attempt is the only positive discovery signal). See [refinement guide § Finalize is exclusive](/docs/media-buy/product-discovery/refinement#finalize-is-exclusive-within-refine).", "IO_REQUIRED": "The committed proposal requires a signed insertion order but no io_acceptance was provided. Recovery: correctable (review the proposal's insertion_order, accept terms, and include io_acceptance on accept_proposal; 3.x compatibility callers use create_media_buy).", "TERMS_REJECTED": "Buyer-proposed measurement_terms were rejected by the seller. The error details SHOULD identify which specific term was rejected and the seller's acceptable range or supported vendors. Recovery: correctable (adjust the proposed terms and retry, or omit measurement_terms to accept the product's defaults).", + "UNRECOGNIZED_TERMS": "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).", "BIDDING_PLACEMENT_CONFLICT": "The authored media-buy/package bidding scopes cannot be represented by the provider's native campaign, package, or shared-strategy placement rules. Sellers MUST detect this before any provider mutation and SHOULD identify the conflicting scopes and provider constraint in error.details. Recovery: correctable (remove or align package overrides, move the policy to the supported scope, or choose a compatible budget mode/product combination).", "AMBIGUOUS_BIDDING_POLICY": "The same effective package combines the canonical bidding block with legacy bid_price or monetary optimization-goal target fields, so two bidding interpretations are present. Sellers MUST reject rather than choosing a winner. Recovery: correctable (emit only the 3.2 bidding block or only one legacy representation).", "CONFLICTING_SELECTORS": "A 3.x package request carries multiple resolvable format selector routes that select different canonical product format declaration sets. Sellers MUST first resolve every present route independently (`format_option_refs`, direct `format_kind` plus `params`, and deprecated `format_ids`) without applying precedence. An unresolved option reference or an unprojectable legacy ID is rejected with `UNSUPPORTED_FEATURE`, not this code. Once all routes resolve, sellers derive the product `format_options[]` entries selected by each route using directional product satisfaction and require those sets to match. Legacy parameter compatibility uses the asymmetric v2-narrows-v1 relation defined by canonical formats, not raw object equality. For fixed-size image selectors, both width and height participate in compatibility. Sellers MUST reject different format shapes, selected option sets, or incompatible dimensions rather than silently choosing the canonical route. `error.field` SHOULD point at the conflicting package, and `error.details` SHOULD identify the supplied selector routes and their normalized canonical summaries. Recovery: correctable (emit one canonical selector route, or make a required legacy 3.x compatibility projection select the same product format contract).", @@ -535,6 +537,10 @@ "recovery": "correctable", "suggestion": "adjust the proposed terms and retry, or omit measurement_terms to accept the product's defaults" }, + "UNRECOGNIZED_TERMS": { + "recovery": "correctable", + "suggestion": "remove the member the seller cannot interpret, or send it only to sellers that interpret it" + }, "BIDDING_PLACEMENT_CONFLICT": { "recovery": "correctable", "suggestion": "align media-buy and package bidding scopes with the provider's supported placement, or choose a compatible budget mode/product combination" diff --git a/static/schemas/source/enums/proposal-decline-reason.json b/static/schemas/source/enums/proposal-decline-reason.json index 10cd28ab96b..93a559e01c0 100644 --- a/static/schemas/source/enums/proposal-decline-reason.json +++ b/static/schemas/source/enums/proposal-decline-reason.json @@ -14,6 +14,7 @@ "timing", "budget_changed", "selected_alternative", + "unrecognized_terms", "other" ], "enumDescriptions": { @@ -26,6 +27,7 @@ "timing": "The schedule, expiry, approval timing, or delivery window did not fit.", "budget_changed": "The buyer's budget, scope, or campaign plan changed after evaluation.", "selected_alternative": "The buyer selected another approach or supply source.", + "unrecognized_terms": "commercial_terms carry a member, at any depth and including ext, that the buyer cannot interpret. Accepting signed terms binds the buyer to every member, so a buyer that cannot interpret every member MUST NOT accept the proposal and declines it with this reason.", "other": "Another reason; detail is required." } } diff --git a/static/schemas/source/governance/check-governance-request.json b/static/schemas/source/governance/check-governance-request.json index eb2a52feb44..f797408db57 100644 --- a/static/schemas/source/governance/check-governance-request.json +++ b/static/schemas/source/governance/check-governance-request.json @@ -289,7 +289,7 @@ }, "proposal": { "$ref": "/schemas/core/canonical-proposal.json", - "description": "Exact committed proposal being authorized for accept_proposal. The governance agent verifies proposal.terms_digest against commercial_terms and binds that digest into its decision state; the downstream payload carries the same digest without repeating the terms." + "description": "Exact committed proposal being authorized for accept_proposal. The governance agent verifies proposal.terms_digest against commercial_terms as received and binds that digest into its decision state; the downstream payload carries the same digest without repeating the terms. A governance agent that cannot interpret every member of commercial_terms, including ext, denies the check (see commercial-terms.json)." }, "governance_context": { "type": "string", diff --git a/static/schemas/source/media-buy/commercial-terms.json b/static/schemas/source/media-buy/commercial-terms.json index f8c29e5a546..b344f2c569c 100644 --- a/static/schemas/source/media-buy/commercial-terms.json +++ b/static/schemas/source/media-buy/commercial-terms.json @@ -2,7 +2,7 @@ "$schema": "http://json-schema.org/draft-07/schema#", "$id": "/schemas/media-buy/commercial-terms.json", "title": "Commercial Terms", - "description": "Complete typed commercial envelope for a compact-lifecycle proposal. This is the authoritative audit and refinement snapshot; allocations and narrative fields are explanatory views rather than substitutes for these terms.", + "description": "Complete typed commercial envelope for a compact-lifecycle proposal. This is the authoritative audit and refinement snapshot; allocations and narrative fields are explanatory views rather than substitutes for these terms. terms_digest covers this entire JSON value: every member at every depth, including ext and members a party does not recognize. Accepting the terms binds the accepting party to every member, so a party that cannot interpret every member MUST NOT accept them: a buyer declines the proposal with decline_proposals reason unrecognized_terms, a seller rejects the request that carries them (such as buy_products purchases) with UNRECOGNIZED_TERMS, and a governance agent denies through its existing deny path. 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.", "type": "object", "x-adcp-validation": { "verifier_constraints": { From 5b9ef2632753d64d8f01a2bc9b65d519aa4b56a9 Mon Sep 17 00:00:00 2001 From: "Constantine.mirin" Date: Tue, 10 Nov 2026 11:48:15 +0100 Subject: [PATCH 2/5] fix(compliance): unrecognized-terms storyboard grades one fault Spell the decline reason UNRECOGNIZED_TERMS, like the error code. It names the same condition from the buyer's side, and its description now says so. Split the storyboard so the control purchase runs in its own phase before the rejection, and make the rejection phase depend on it. The UNRECOGNIZED_TERMS check is graded only after the identical purchase is proven acceptable; if the control fails, the runner skips the check. Replace the undefined member with adcp_compliance_undefined_member, a name reserved as undefined so that no conformant seller can legitimately interpret it. --- .changeset/signed-terms-acceptance.md | 4 +- .../proposal-negotiation.mdx | 2 +- .../task-reference/decline_proposals.mdx | 2 +- ...aining-agent-served-release-fields.test.ts | 4 +- .../unrecognized_terms_rejected.yaml | 88 +++++++++++-------- .../source/enums/proposal-decline-reason.json | 4 +- .../source/media-buy/commercial-terms.json | 2 +- 7 files changed, 60 insertions(+), 46 deletions(-) diff --git a/.changeset/signed-terms-acceptance.md b/.changeset/signed-terms-acceptance.md index b63a08e0bf7..df437140903 100644 --- a/.changeset/signed-terms-acceptance.md +++ b/.changeset/signed-terms-acceptance.md @@ -4,9 +4,9 @@ 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`, and a governance agent denies the check. A member whose schema defines it as opaque, such as `context`, is interpreted by that definition. +- 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 migration guides no longer say that `terms_digest` "signs exactly those terms" as a reason for keeping `commercial-terms` closed; it stays closed because a minor release never changes a closed schema. No schema is opened or closed. -The new storyboard `media_buy_seller/unrecognized_terms_rejected` sends a `buy_products` purchase whose `format_option_refs[0]` carries a member no release defines and expects `UNRECOGNIZED_TERMS`, then sends the same purchase without it and expects a MediaBuy. +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. diff --git a/docs/media-buy/product-discovery/proposal-negotiation.mdx b/docs/media-buy/product-discovery/proposal-negotiation.mdx index a0505785149..c8f0ccbaf74 100644 --- a/docs/media-buy/product-discovery/proposal-negotiation.mdx +++ b/docs/media-buy/product-discovery/proposal-negotiation.mdx @@ -332,7 +332,7 @@ For every returned proposal: 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 [`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)). +`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 [`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. diff --git a/docs/media-buy/task-reference/decline_proposals.mdx b/docs/media-buy/task-reference/decline_proposals.mdx index 45b7d82eab6..bbeacc0b558 100644 --- a/docs/media-buy/task-reference/decline_proposals.mdx +++ b/docs/media-buy/task-reference/decline_proposals.mdx @@ -35,6 +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`. See [Verify terms independently](/docs/media-buy/product-discovery/proposal-negotiation#3-verify-terms-independently). +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`](/docs/building/verification/compliance-catalog#error-code-unrecognized-terms), the same condition a seller reports as the error code of that name. 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. diff --git a/server/tests/unit/training-agent-served-release-fields.test.ts b/server/tests/unit/training-agent-served-release-fields.test.ts index 5733e3d7055..67f6215f973 100644 --- a/server/tests/unit/training-agent-served-release-fields.test.ts +++ b/server/tests/unit/training-agent-served-release-fields.test.ts @@ -83,9 +83,9 @@ describe('undeclared members in commercial terms', () => { expect(undeclaredMembers(purchase, PURCHASE)).toEqual([]); const withMember = { ...purchase, - format_option_refs: [{ scope: 'product', format_option_id: 'f1', delivery_share: 0.6 }], + format_option_refs: [{ scope: 'product', format_option_id: 'f1', adcp_compliance_undefined_member: 0.6 }], }; - expect(undeclaredMembers(withMember, PURCHASE)).toEqual([['format_option_refs', '0', 'delivery_share']]); + expect(undeclaredMembers(withMember, PURCHASE)).toEqual([['format_option_refs', '0', 'adcp_compliance_undefined_member']]); }); it('counts ext members as uninterpreted and context members as opaque', () => { diff --git a/static/compliance/source/protocols/media-buy/scenarios/unrecognized_terms_rejected.yaml b/static/compliance/source/protocols/media-buy/scenarios/unrecognized_terms_rejected.yaml index 2ab92a37432..99a677d6113 100644 --- a/static/compliance/source/protocols/media-buy/scenarios/unrecognized_terms_rejected.yaml +++ b/static/compliance/source/protocols/media-buy/scenarios/unrecognized_terms_rejected.yaml @@ -5,14 +5,17 @@ # UNRECOGNIZED_TERMS instead of accepting it, dropping the member, or carrying it uninterpreted. # # buy_products purchases[] become accepted_proposal.commercial_terms.purchases[], so the seller -# is the accepting party. The unrecognized member sits in format_option_refs[0], a schema that is -# open (additionalProperties: true), so the request passes schema validation and fails for one -# reason only. The control step sends the same purchase without the member and must succeed. +# is the accepting party. The control phase first proves the purchase is acceptable as is. The +# rejection phase depends on it and sends the identical purchase plus one member, +# adcp_compliance_undefined_member, in format_option_refs[0]. That name is reserved as +# undefined: no AdCP release defines it and none will, so a conformant seller cannot +# legitimately interpret it. format_option_refs[] entries are open (additionalProperties: true), +# so the request passes schema validation and fails for that one reason only. id: media_buy_seller/unrecognized_terms_rejected version: "1.0.0" title: "Seller rejects commercial terms it cannot interpret" category: media_buy_seller -summary: "Verifies that buy_products rejects a purchase carrying a member the seller cannot interpret with UNRECOGNIZED_TERMS, and accepts the same purchase without it." +summary: "Verifies that buy_products accepts a purchase, then rejects the identical purchase carrying a reserved undefined member with UNRECOGNIZED_TERMS." track: media_buy introduced_in: "3.3" @@ -35,11 +38,14 @@ narrative: | member would record terms the buyer did not send; carrying it would bind the seller to a term it never read. - The buyer sends a purchase whose format option reference carries - delivery_share, a member no AdCP release defines. The format option - reference schema is open, so the request is schema-valid. The seller rejects - it with UNRECOGNIZED_TERMS. The same purchase without the member then - completes, which shows the member is the only reason for the rejection. + The buyer first buys the product with a plain purchase, which proves the + seller accepts that purchase as is. It then sends the identical purchase + with one added member in its format option reference: + adcp_compliance_undefined_member. The name is reserved as undefined, so no + conformant seller can legitimately interpret it. The format option reference + schema is open, so the request is schema-valid, and the seller rejects it + with UNRECOGNIZED_TERMS. The member is the only difference between the two + requests, so it is the only reason for the rejection. agent: interaction_model: media_buy_seller @@ -151,29 +157,25 @@ phases: path: "feed_version" description: "The response carries the feed_version buy_products requires" - - id: purchase - title: "Reject terms with an unrecognized member, then accept them without it" + - id: control_purchase + title: "Accept the purchase without the undefined member" depends_on: [discover_offer] narrative: | - Both requests are identical except for delivery_share inside - format_option_refs[0]. Only the first carries it. + Proves the purchase is acceptable as is, so the rejection phase that + follows can only fail on the added member. steps: - - id: reject_unrecognized_member - title: "Reject a purchase whose format option reference carries an unrecognized member" + - id: accept_without_member + title: "Accept the purchase" task: buy_products schema_ref: "media-buy/buy-products-request.json" response_schema_ref: "media-buy/buy-products-response.json" doc_ref: "/media-buy/task-reference/buy_products" - expect_error: true - negative_path: payload_well_formed stateful: true expected: | - Reject with UNRECOGNIZED_TERMS. The purchase would become commercial_terms - the seller is bound by, and the seller cannot interpret delivery_share. - Do not create a MediaBuy, drop the member, or record it uninterpreted. + Create the MediaBuy and return the accepted proposal snapshot. sample_request: - idempotency_key: "$generate:uuid_v4#media_buy_seller_unrecognized_terms_purchase_reject" + idempotency_key: "$generate:uuid_v4#media_buy_seller_unrecognized_terms_control_purchase_accept" account: brand: domain: "acmeoutdoor.example" @@ -186,29 +188,43 @@ phases: format_option_refs: - scope: "product" format_option_id: "unrecognized_terms_display_300x250" - delivery_share: 0.6 budget: 1000 start_time: "asap" end_time: "2099-09-30T23:59:59Z" validations: - check: response_schema - description: "Rejected response matches buy-products-response.json" - - check: error_code - value: "UNRECOGNIZED_TERMS" - description: "A member the seller cannot interpret blocks acceptance of the terms" + description: "Response matches buy-products-response.json" + - check: field_present + path: "media_buy_id" + description: "The purchase creates a MediaBuy" + - check: field_present + path: "accepted_proposal.terms_digest" + description: "The seller records the accepted terms and their digest" - - id: accept_without_member - title: "Accept the same purchase without the unrecognized member" + - id: reject_undefined_member + title: "Reject the identical purchase carrying the undefined member" + depends_on: [control_purchase] + narrative: | + The request is the control purchase plus adcp_compliance_undefined_member + inside format_option_refs[0]. Nothing else differs. + steps: + - id: reject_unrecognized_member + title: "Reject a purchase whose format option reference carries the undefined member" task: buy_products schema_ref: "media-buy/buy-products-request.json" response_schema_ref: "media-buy/buy-products-response.json" doc_ref: "/media-buy/task-reference/buy_products" + expect_error: true + negative_path: payload_well_formed stateful: true expected: | - Create the MediaBuy and return the accepted proposal snapshot. + Reject with UNRECOGNIZED_TERMS. The purchase would become commercial_terms + the seller is bound by, and no seller can interpret + adcp_compliance_undefined_member. Do not create a MediaBuy, drop the + member, or record it uninterpreted. sample_request: - idempotency_key: "$generate:uuid_v4#media_buy_seller_unrecognized_terms_purchase_accept" + idempotency_key: "$generate:uuid_v4#media_buy_seller_unrecognized_terms_reject_undefined_member" account: brand: domain: "acmeoutdoor.example" @@ -221,15 +237,13 @@ phases: format_option_refs: - scope: "product" format_option_id: "unrecognized_terms_display_300x250" + adcp_compliance_undefined_member: 0.6 budget: 1000 start_time: "asap" end_time: "2099-09-30T23:59:59Z" validations: - check: response_schema - description: "Response matches buy-products-response.json" - - check: field_present - path: "media_buy_id" - description: "The purchase without the member creates a MediaBuy" - - check: field_present - path: "accepted_proposal.terms_digest" - description: "The seller records the accepted terms and their digest" + description: "Rejected response matches buy-products-response.json" + - check: error_code + value: "UNRECOGNIZED_TERMS" + description: "A member the seller cannot interpret blocks acceptance of the terms" diff --git a/static/schemas/source/enums/proposal-decline-reason.json b/static/schemas/source/enums/proposal-decline-reason.json index 93a559e01c0..a49ef084ab2 100644 --- a/static/schemas/source/enums/proposal-decline-reason.json +++ b/static/schemas/source/enums/proposal-decline-reason.json @@ -14,7 +14,7 @@ "timing", "budget_changed", "selected_alternative", - "unrecognized_terms", + "UNRECOGNIZED_TERMS", "other" ], "enumDescriptions": { @@ -27,7 +27,7 @@ "timing": "The schedule, expiry, approval timing, or delivery window did not fit.", "budget_changed": "The buyer's budget, scope, or campaign plan changed after evaluation.", "selected_alternative": "The buyer selected another approach or supply source.", - "unrecognized_terms": "commercial_terms carry a member, at any depth and including ext, that the buyer cannot interpret. Accepting signed terms binds the buyer to every member, so a buyer that cannot interpret every member MUST NOT accept the proposal and declines it with this reason.", + "UNRECOGNIZED_TERMS": "The buyer declines because it cannot interpret every member of the proposal's signed commercial_terms, at any depth and including ext. This is the same condition a seller reports as error code UNRECOGNIZED_TERMS, seen from the buyer's side. Accepting signed terms binds the buyer to every member, so a buyer that cannot interpret every member MUST NOT accept the proposal.", "other": "Another reason; detail is required." } } diff --git a/static/schemas/source/media-buy/commercial-terms.json b/static/schemas/source/media-buy/commercial-terms.json index b344f2c569c..7720ce41ede 100644 --- a/static/schemas/source/media-buy/commercial-terms.json +++ b/static/schemas/source/media-buy/commercial-terms.json @@ -2,7 +2,7 @@ "$schema": "http://json-schema.org/draft-07/schema#", "$id": "/schemas/media-buy/commercial-terms.json", "title": "Commercial Terms", - "description": "Complete typed commercial envelope for a compact-lifecycle proposal. This is the authoritative audit and refinement snapshot; allocations and narrative fields are explanatory views rather than substitutes for these terms. terms_digest covers this entire JSON value: every member at every depth, including ext and members a party does not recognize. Accepting the terms binds the accepting party to every member, so a party that cannot interpret every member MUST NOT accept them: a buyer declines the proposal with decline_proposals reason unrecognized_terms, a seller rejects the request that carries them (such as buy_products purchases) with UNRECOGNIZED_TERMS, and a governance agent denies through its existing deny path. 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.", + "description": "Complete typed commercial envelope for a compact-lifecycle proposal. This is the authoritative audit and refinement snapshot; allocations and narrative fields are explanatory views rather than substitutes for these terms. terms_digest covers this entire JSON value: every member at every depth, including ext and members a party does not recognize. Accepting the terms binds the accepting party to every member, so a party that cannot interpret every member MUST NOT accept them: a buyer declines the proposal with decline_proposals reason UNRECOGNIZED_TERMS, a seller rejects the request that carries them (such as buy_products purchases) with UNRECOGNIZED_TERMS, and a governance agent denies through its existing deny path. 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.", "type": "object", "x-adcp-validation": { "verifier_constraints": { From fea86a26bf89d218f997408c90bcc9a836c4abff Mon Sep 17 00:00:00 2001 From: "Constantine.mirin" Date: Wed, 11 Nov 2026 12:00:56 +0100 Subject: [PATCH 3/5] fix(schemas): decline reason unrecognized_terms is lowercase like its enum proposal-decline-reason is a closed lowercase snake_case enum, so the decline reason is unrecognized_terms. The error code stays UNRECOGNIZED_TERMS, like the other error codes. Text that names both keeps the cross-reference with each vocabulary's own casing. --- .changeset/signed-terms-acceptance.md | 2 +- docs/media-buy/product-discovery/proposal-negotiation.mdx | 2 +- docs/media-buy/task-reference/decline_proposals.mdx | 2 +- static/schemas/source/enums/proposal-decline-reason.json | 4 ++-- static/schemas/source/media-buy/commercial-terms.json | 2 +- 5 files changed, 6 insertions(+), 6 deletions(-) diff --git a/.changeset/signed-terms-acceptance.md b/.changeset/signed-terms-acceptance.md index df437140903..72f3a053f2b 100644 --- a/.changeset/signed-terms-acceptance.md +++ b/.changeset/signed-terms-acceptance.md @@ -4,7 +4,7 @@ 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. +- 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 migration guides no longer say that `terms_digest` "signs exactly those terms" as a reason for keeping `commercial-terms` closed; it stays closed because a minor release never changes a closed schema. No schema is opened or closed. diff --git a/docs/media-buy/product-discovery/proposal-negotiation.mdx b/docs/media-buy/product-discovery/proposal-negotiation.mdx index c8f0ccbaf74..b04084ac7d5 100644 --- a/docs/media-buy/product-discovery/proposal-negotiation.mdx +++ b/docs/media-buy/product-discovery/proposal-negotiation.mdx @@ -332,7 +332,7 @@ For every returned proposal: 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 [`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)). +`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. diff --git a/docs/media-buy/task-reference/decline_proposals.mdx b/docs/media-buy/task-reference/decline_proposals.mdx index bbeacc0b558..a3b35c1bce9 100644 --- a/docs/media-buy/task-reference/decline_proposals.mdx +++ b/docs/media-buy/task-reference/decline_proposals.mdx @@ -35,6 +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`](/docs/building/verification/compliance-catalog#error-code-unrecognized-terms), the same condition a seller reports as the error code of that name. See [Verify terms independently](/docs/media-buy/product-discovery/proposal-negotiation#3-verify-terms-independently). +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. diff --git a/static/schemas/source/enums/proposal-decline-reason.json b/static/schemas/source/enums/proposal-decline-reason.json index a49ef084ab2..9f3662c829b 100644 --- a/static/schemas/source/enums/proposal-decline-reason.json +++ b/static/schemas/source/enums/proposal-decline-reason.json @@ -14,7 +14,7 @@ "timing", "budget_changed", "selected_alternative", - "UNRECOGNIZED_TERMS", + "unrecognized_terms", "other" ], "enumDescriptions": { @@ -27,7 +27,7 @@ "timing": "The schedule, expiry, approval timing, or delivery window did not fit.", "budget_changed": "The buyer's budget, scope, or campaign plan changed after evaluation.", "selected_alternative": "The buyer selected another approach or supply source.", - "UNRECOGNIZED_TERMS": "The buyer declines because it cannot interpret every member of the proposal's signed commercial_terms, at any depth and including ext. This is the same condition a seller reports as error code UNRECOGNIZED_TERMS, seen from the buyer's side. Accepting signed terms binds the buyer to every member, so a buyer that cannot interpret every member MUST NOT accept the proposal.", + "unrecognized_terms": "The buyer declines because it cannot interpret every member of the proposal's signed commercial_terms, at any depth and including ext. This is the same condition a seller reports as error code UNRECOGNIZED_TERMS, seen from the buyer's side. Accepting signed terms binds the buyer to every member, so a buyer that cannot interpret every member MUST NOT accept the proposal.", "other": "Another reason; detail is required." } } diff --git a/static/schemas/source/media-buy/commercial-terms.json b/static/schemas/source/media-buy/commercial-terms.json index 7720ce41ede..9ed6f0deeb5 100644 --- a/static/schemas/source/media-buy/commercial-terms.json +++ b/static/schemas/source/media-buy/commercial-terms.json @@ -2,7 +2,7 @@ "$schema": "http://json-schema.org/draft-07/schema#", "$id": "/schemas/media-buy/commercial-terms.json", "title": "Commercial Terms", - "description": "Complete typed commercial envelope for a compact-lifecycle proposal. This is the authoritative audit and refinement snapshot; allocations and narrative fields are explanatory views rather than substitutes for these terms. terms_digest covers this entire JSON value: every member at every depth, including ext and members a party does not recognize. Accepting the terms binds the accepting party to every member, so a party that cannot interpret every member MUST NOT accept them: a buyer declines the proposal with decline_proposals reason UNRECOGNIZED_TERMS, a seller rejects the request that carries them (such as buy_products purchases) with UNRECOGNIZED_TERMS, and a governance agent denies through its existing deny path. 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.", + "description": "Complete typed commercial envelope for a compact-lifecycle proposal. This is the authoritative audit and refinement snapshot; allocations and narrative fields are explanatory views rather than substitutes for these terms. terms_digest covers this entire JSON value: every member at every depth, including ext and members a party does not recognize. Accepting the terms binds the accepting party to every member, so a party that cannot interpret every member MUST NOT accept them: a buyer declines the proposal with decline_proposals reason unrecognized_terms, a seller rejects the request that carries them (such as buy_products purchases) with error code UNRECOGNIZED_TERMS, and a governance agent denies through its existing deny path. 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.", "type": "object", "x-adcp-validation": { "verifier_constraints": { From 817af787ccd1bd34b0fb18a3bbf20f38cdf2a054 Mon Sep 17 00:00:00 2001 From: "Constantine.mirin" Date: Wed, 11 Nov 2026 12:12:58 +0100 Subject: [PATCH 4/5] fix(training): accept the unrecognized_terms decline reason The decline_proposals check and the compact refine-decline check each kept a hand-written list of decline reasons, and neither had unrecognized_terms. Both now read one set from enums/proposal-decline-reason.json, so the agent accepts exactly the reasons the schema allows. --- server/src/training-agent/task-handlers.ts | 22 ++++----- server/tests/unit/training-agent.test.ts | 52 ++++++++++++++++++++++ 2 files changed, 64 insertions(+), 10 deletions(-) diff --git a/server/src/training-agent/task-handlers.ts b/server/src/training-agent/task-handlers.ts index 475ed43501f..4d35ba21937 100644 --- a/server/src/training-agent/task-handlers.ts +++ b/server/src/training-agent/task-handlers.ts @@ -10449,6 +10449,16 @@ function idempotencyPayloadForServedVersion( return toolName === 'get_products' ? args : { ...args, __adcp_operation: toolName }; } +/** + * The reasons a proposal decline may carry: the closed enum in + * enums/proposal-decline-reason.json, read from the source schema so both + * decline checks below accept exactly what the schema does. + */ +export const PROPOSAL_DECLINE_REASONS: ReadonlySet = new Set( + (loadSourceSchema('enums/proposal-decline-reason.json').enum as unknown[]) + .filter((reason): reason is string => typeof reason === 'string'), +); + export function validateProductDiscoveryAliasInput( toolName: string, args: Record, @@ -10620,10 +10630,6 @@ export function validateProductDiscoveryAliasInput( return { message: 'declines exceeds the maximum batch size (25)', field: 'declines' }; } const proposalIds = new Set(); - const reasons = new Set([ - 'price', 'inventory_fit', 'audience_fit', 'creative_unsupported', 'measurement_unsupported', - 'policy', 'timing', 'budget_changed', 'selected_alternative', 'other', - ]); for (let index = 0; index < args.declines.length; index += 1) { const entry = args.declines[index]; if (!isRecord(entry)) { @@ -10636,7 +10642,7 @@ export function validateProductDiscoveryAliasInput( return { message: 'proposal_id values in declines must be unique', field: `declines[${index}].proposal_id` }; } proposalIds.add(entry.proposal_id); - if (typeof entry.reason !== 'string' || !reasons.has(entry.reason)) { + if (typeof entry.reason !== 'string' || !PROPOSAL_DECLINE_REASONS.has(entry.reason)) { return { message: 'a supported reason is required for every decline', field: `declines[${index}].reason` }; } if (entry.reason === 'other' && !(typeof entry.detail === 'string' && entry.detail.length > 0)) { @@ -24893,10 +24899,6 @@ function validateIdempotencyProtectedInput( field: 'refine', }; } - const reasons = new Set([ - 'price', 'inventory_fit', 'audience_fit', 'creative_unsupported', 'measurement_unsupported', - 'policy', 'timing', 'budget_changed', 'selected_alternative', 'other', - ]); const invalidIndex = (args.refine as unknown[]).findIndex(entry => ( isRecord(entry) && entry.scope === 'proposal' @@ -24904,7 +24906,7 @@ function validateIdempotencyProtectedInput( && ( typeof entry.proposal_id !== 'string' || typeof entry.reason !== 'string' - || !reasons.has(entry.reason) + || !PROPOSAL_DECLINE_REASONS.has(entry.reason) || (entry.reason === 'other' && !(typeof entry.detail === 'string' && entry.detail.length > 0)) ) )); diff --git a/server/tests/unit/training-agent.test.ts b/server/tests/unit/training-agent.test.ts index 998954b6634..efb28e944a2 100644 --- a/server/tests/unit/training-agent.test.ts +++ b/server/tests/unit/training-agent.test.ts @@ -46,6 +46,8 @@ import { TRAINING_ACCEPTANCE_POLICY_CATALOG_DIGEST, TRAINING_ACCEPTANCE_POLICY_CATALOG_PATH, TRAINING_ACCEPTANCE_POLICY_DEFAULT_PROFILE, + PROPOSAL_DECLINE_REASONS, + validateProductDiscoveryAliasInput, } from '../../src/training-agent/task-handlers.js'; import { MUTATING_TOOLS, @@ -21915,6 +21917,56 @@ describe('proposal lifecycle', () => { }); }); + it('accepts the unrecognized_terms decline reason on both decline checks and rejects an unknown reason', async () => { + const schemaReasons = JSON.parse( + readFileSync(new URL('../../../static/schemas/source/enums/proposal-decline-reason.json', import.meta.url), 'utf8'), + ).enum as string[]; + expect([...PROPOSAL_DECLINE_REASONS]).toEqual(schemaReasons); + expect(PROPOSAL_DECLINE_REASONS.has('unrecognized_terms')).toBe(true); + + // decline_proposals request check. + const declineRequest = (reason: string) => validateProductDiscoveryAliasInput('decline_proposals', { + idempotency_key: randomUUID(), + declines: [{ proposal_id: 'p1', reason }], + }); + expect(declineRequest('unrecognized_terms')).toBeUndefined(); + expect(declineRequest('not_a_reason')).toMatchObject({ field: 'declines[0].reason' }); + + // Compact refine-decline check, reached directly with the internal flags. + const server = createTrainingAgentServer(DEFAULT_CTX); + const compactDecline = (reason: string) => simulateCallTool(server, 'get_products', { + buying_mode: 'refine', + __compact_proposal_lifecycle: true, + __decline_proposals: true, + refine: [{ scope: 'proposal', proposal_id: 'p1', action: 'decline', reason }], + }); + const compactAccepted = await compactDecline('unrecognized_terms'); + expect(compactAccepted.isError).toBeFalsy(); + expect(compactAccepted.result).not.toHaveProperty('code'); + const compactRejected = await compactDecline('not_a_reason'); + expect(compactRejected.isError).toBe(true); + expect(compactRejected.result).toMatchObject({ code: 'INVALID_REQUEST', field: 'refine[0]' }); + + // End to end, a decline_proposals call passes both checks. + const { result: requested } = await simulateCallTool(server, 'request_proposals', { + brand: account.brand, + brief: 'social engagement display', + }); + const proposal = (requested.proposals as Array>)[0]; + const declined = await simulateCallTool(server, 'decline_proposals', { + declines: [{ proposal_id: proposal.proposal_id, reason: 'unrecognized_terms' }], + }); + expect(declined.isError).toBeFalsy(); + expect(declined.result).toMatchObject({ + results: [{ proposal_id: proposal.proposal_id, outcome: 'declined' }], + }); + const rejected = await simulateCallTool(server, 'decline_proposals', { + declines: [{ proposal_id: proposal.proposal_id, reason: 'not_a_reason' }], + }); + expect(rejected.isError).toBe(true); + expect(rejected.result).toMatchObject({ code: 'INVALID_REQUEST' }); + }); + it('rejects duplicate decline proposal IDs and cannot decline registry proposals', async () => { const server = createTrainingAgentServer(DEFAULT_CTX); const duplicate = await simulateCallTool(server, 'decline_proposals', { From c734281bd85e990296f34c94dee9b8f163bf5b52 Mon Sep 17 00:00:00 2001 From: "Constantine.mirin" Date: Thu, 12 Nov 2026 17:30:28 +0100 Subject: [PATCH 5/5] docs(changeset): describe the release docs as merged with main After the merge of main, the release notes, What's new in 3.3 and the 3.2 to 3.3 migration guide keep the note that commercial-terms is held closed until 4.0 and state the acceptance rule after it. The changeset no longer gives the reason main already replaced. --- .changeset/signed-terms-acceptance.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.changeset/signed-terms-acceptance.md b/.changeset/signed-terms-acceptance.md index 72f3a053f2b..ae387fa0959 100644 --- a/.changeset/signed-terms-acceptance.md +++ b/.changeset/signed-terms-acceptance.md @@ -7,6 +7,6 @@ State what accepting signed commercial terms means. `terms_digest` covers the en - 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 migration guides no longer say that `terms_digest` "signs exactly those terms" as a reason for keeping `commercial-terms` closed; it stays closed because a minor release never changes a closed schema. No schema is opened or closed. +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.