diff --git a/.changeset/signed-terms-acceptance.md b/.changeset/signed-terms-acceptance.md new file mode 100644 index 00000000000..ae387fa0959 --- /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` (the decline reason names the same condition from the buyer's side), and a governance agent denies the check. A member whose schema defines it as opaque, such as `context`, is interpreted by that definition. +- A party computes or verifies `terms_digest` over the JSON value as received, never over a re-serialized parsed model, which can drop members the model does not declare. + +The rule is stated in `media-buy/commercial-terms.json`, the `terms_digest` description in `core/canonical-proposal.json`, `governance/check-governance-request.json`, and the proposal negotiation, `buy_products`, `decline_proposals`, and `check_governance` pages. The release notes, What's new in 3.3, and the 3.2 to 3.3 migration guide now state the acceptance rule after the note that `commercial-terms` is held closed until 4.0. No schema is opened or closed. + +The new storyboard `media_buy_seller/unrecognized_terms_rejected` first proves a plain `buy_products` purchase is accepted, then sends the identical purchase with `adcp_compliance_undefined_member` in `format_option_refs[0]` and expects `UNRECOGNIZED_TERMS`. That member name is reserved as undefined, so no conformant seller can interpret it. 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 53b85d9fc60..47798bc2310 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 5307a8c2162..a4370b2a565 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 error code [`UNRECOGNIZED_TERMS`](/docs/building/verification/compliance-catalog#error-code-unrecognized-terms) (see [`buy_products`](/docs/media-buy/task-reference/buy_products)), and a governance agent denies the check (see [`check_governance`](/docs/governance/campaign/tasks/check_governance)). + Digest uniqueness alone is not enough for alternatives. Verify that `commercial_terms` are distinct after canonicalization; a seller cannot create fake diversity by changing only IDs, names, descriptions, or digest strings. ### 4. Retry safely 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..a3b35c1bce9 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`, 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/docs/reference/migration/3-2-to-3-3.mdx b/docs/reference/migration/3-2-to-3-3.mdx index 909a55dff34..f0ba7d9fbf8 100644 --- a/docs/reference/migration/3-2-to-3-3.mdx +++ b/docs/reference/migration/3-2-to-3-3.mdx @@ -77,7 +77,7 @@ Everything else is an optional declaration or a clarification. Agent identity (D ## Withdrawn from 3.3, planned for 4.0 -Three features are not part of 3.3. All three add terms to `commercial_terms`, and `commercial-terms` and the term objects inside it are held closed until 4.0 ([DR-0036](https://github.com/adcontextprotocol/adcp/blob/main/governance/decisions/DR-0036-closed-schemas-stay-closed-within-a-major.md)). 4.0 gives `commercial_terms` a declared extension point with must-understand, and the three features come back through it. The decision is in [adcp#8501](https://github.com/adcontextprotocol/adcp/issues/8501). +Three features are not part of 3.3. All three add terms to `commercial_terms`, and `commercial-terms` and the term objects inside it are held closed until 4.0 ([DR-0036](https://github.com/adcontextprotocol/adcp/blob/main/governance/decisions/DR-0036-closed-schemas-stay-closed-within-a-major.md)). A buyer must not be bound by terms it cannot read: `terms_digest` covers every member of `commercial_terms`, including members under the open schemas inside it, and a party that cannot interpret every member must not accept the terms ([Verify terms independently](/docs/media-buy/product-discovery/proposal-negotiation#3-verify-terms-independently)). 4.0 gives `commercial_terms` a declared extension point with must-understand, and the three features come back through it. The decision is in [adcp#8501](https://github.com/adcontextprotocol/adcp/issues/8501). ### Definition pins (published in beta.0 and beta.1, removed after beta.1) diff --git a/docs/reference/release-notes.mdx b/docs/reference/release-notes.mdx index c5332a0db35..c6449cea529 100644 --- a/docs/reference/release-notes.mdx +++ b/docs/reference/release-notes.mdx @@ -187,7 +187,7 @@ These merged on `main` during the 3.3 cycle and were also released on the 3.2 li ### Withdrawn from 3.3, planned for 4.0 -Three features are not part of 3.3. All three add terms to `commercial_terms`, which is held closed until 4.0 ([DR-0036](https://github.com/adcontextprotocol/adcp/blob/main/governance/decisions/DR-0036-closed-schemas-stay-closed-within-a-major.md)). 4.0 gives `commercial_terms` a declared extension point with must-understand and brings the features back ([adcp#8501](https://github.com/adcontextprotocol/adcp/issues/8501)). The removal merged in [#8537](https://github.com/adcontextprotocol/adcp/pull/8537) and first takes effect in `3.3.0-beta.2`. +Three features are not part of 3.3. All three add terms to `commercial_terms`, which is held closed until 4.0 ([DR-0036](https://github.com/adcontextprotocol/adcp/blob/main/governance/decisions/DR-0036-closed-schemas-stay-closed-within-a-major.md)). A buyer must not be bound by terms it cannot read: `terms_digest` covers every member of `commercial_terms`, including members under the open schemas inside it, and a party that cannot interpret every member must not accept the terms ([Verify terms independently](/docs/media-buy/product-discovery/proposal-negotiation#3-verify-terms-independently)). 4.0 gives `commercial_terms` a declared extension point with must-understand and brings the features back ([adcp#8501](https://github.com/adcontextprotocol/adcp/issues/8501)). The removal merged in [#8537](https://github.com/adcontextprotocol/adcp/pull/8537) and first takes effect in `3.3.0-beta.2`. - **Definition pins (#7960), published in `3.3.0-beta.0` and `3.3.0-beta.1`, removed after beta.1.** `commercial_terms.definition_pins[]`, the `definition_changed` refinement reason with `drifted_pins[]`, `REFERENCE_DEFINITION_CHANGED`, the `definition_pin_probe` controller scenario, the `definition_pin_drift` storyboard, and the `definition-pins` test vectors are removed. The beta rule that sellers MUST pin covered third-party definitions no longer applies. This is a beta-to-beta change, not a change to any stable release. - **Purchase rights (#8101), published in `3.3.0-beta.1` as experimental `media_buy.purchase_rights` and removed after beta.1.** `purchases[].rights[]`, `brand/rights-scope.json` (so `brand/rights-terms.json` returns to its 3.2 form), and the `paid_amplification` and `content_reuse` values of `right-use` are removed. diff --git a/docs/reference/whats-new-in-3-3.mdx b/docs/reference/whats-new-in-3-3.mdx index 115ecdd5374..f5f710b864f 100644 --- a/docs/reference/whats-new-in-3-3.mdx +++ b/docs/reference/whats-new-in-3-3.mdx @@ -325,7 +325,7 @@ These merged on `main` during the 3.3 cycle and were also released on the 3.2 li ## Withdrawn from 3.3, planned for 4.0 -Three features are not part of 3.3. All three add terms to `commercial_terms`, which is held closed until 4.0. 4.0 gives `commercial_terms` a declared extension point with must-understand and brings them back ([adcp#8501](https://github.com/adcontextprotocol/adcp/issues/8501)). +Three features are not part of 3.3. All three add terms to `commercial_terms`, which is held closed until 4.0. A buyer must not be bound by terms it cannot read: `terms_digest` covers every member of `commercial_terms`, including members under the open schemas inside it, and a party that cannot interpret every member must not accept the terms ([Verify terms independently](/docs/media-buy/product-discovery/proposal-negotiation#3-verify-terms-independently)). 4.0 gives `commercial_terms` a declared extension point with must-understand and brings them back ([adcp#8501](https://github.com/adcontextprotocol/adcp/issues/8501)). | Feature | Where it stood | What changes | |---|---|---| diff --git a/docs/snippets/compliance-error-codes.mdx b/docs/snippets/compliance-error-codes.mdx index f7836636180..95f92e22ce7 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 e966eb36377..7903d85d84a 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, @@ -10718,6 +10718,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, @@ -10889,10 +10899,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)) { @@ -10905,7 +10911,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)) { @@ -24120,6 +24126,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, @@ -25248,10 +25268,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' @@ -25259,7 +25275,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-served-release-fields.test.ts b/server/tests/unit/training-agent-served-release-fields.test.ts index 5bb671098e1..67f6215f973 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', adcp_compliance_undefined_member: 0.6 }], + }; + expect(undeclaredMembers(withMember, PURCHASE)).toEqual([['format_option_refs', '0', 'adcp_compliance_undefined_member']]); + }); + + 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/server/tests/unit/training-agent.test.ts b/server/tests/unit/training-agent.test.ts index 235783c8403..e497b676507 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, @@ -21956,6 +21958,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', { diff --git a/static/compliance/source/protocols/media-buy/index.yaml b/static/compliance/source/protocols/media-buy/index.yaml index 3d0f2eb2d20..e6735141dbe 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..99a677d6113 --- /dev/null +++ b/static/compliance/source/protocols/media-buy/scenarios/unrecognized_terms_rejected.yaml @@ -0,0 +1,249 @@ +# 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 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 accepts a purchase, then rejects the identical purchase carrying a reserved undefined member with UNRECOGNIZED_TERMS." +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 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 + 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: control_purchase + title: "Accept the purchase without the undefined member" + depends_on: [discover_offer] + narrative: | + Proves the purchase is acceptable as is, so the rejection phase that + follows can only fail on the added member. + steps: + - 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" + stateful: true + expected: | + Create the MediaBuy and return the accepted proposal snapshot. + + sample_request: + idempotency_key: "$generate:uuid_v4#media_buy_seller_unrecognized_terms_control_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 creates a MediaBuy" + - check: field_present + path: "accepted_proposal.terms_digest" + description: "The seller records the accepted terms and their digest" + + - 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: | + 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_reject_undefined_member" + 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" + adcp_compliance_undefined_member: 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" diff --git a/static/schemas/source/core/canonical-proposal.json b/static/schemas/source/core/canonical-proposal.json index 368bda74765..66199511b7f 100644 --- a/static/schemas/source/core/canonical-proposal.json +++ b/static/schemas/source/core/canonical-proposal.json @@ -98,7 +98,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 dbee1152222..a9b2512fc40 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..9f3662c829b 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": "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/governance/check-governance-request.json b/static/schemas/source/governance/check-governance-request.json index a68efa8a300..de7ead745d0 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..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.", + "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": {