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

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .changeset/proposal-verifier-schema-contracts.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
'@adcp/sdk': minor
---

Expose the standalone proposal commercial-terms verifier through `@adcp/sdk/negotiation/verification` with ESM/CJS types. Fail closed on unsupported schema keywords, cross-bundle references, and changed validation contracts throughout the commercial-terms schema graph. Preserve digest-first exhaustive comparison and legacy opaque contract-reference behavior, and document runtime schema coupling and upstream shim retirement.

Enforce schema-declared targeting disjointness, geographic label membership, language-tag grammar, and IANA timezone annotations before comparing terms, with validators isolated from ordinary SDK schema validation. Pin extensible-enum annotations while preserving explicit enum membership for binding snapshots.
5 changes: 5 additions & 0 deletions docs/guides/BUYER-QUICKSTART-3.2.md
Original file line number Diff line number Diff line change
Expand Up @@ -106,5 +106,10 @@ request_proposals → refine_proposals → accept_proposal
those values locally. See the
[type summary](../TYPE-SUMMARY.md#request_proposals) for exact request shapes.

Before acceptance, compare the complete reviewed commercial snapshot with
`verifyProposalCommercialTerms` from `@adcp/sdk/negotiation/verification`.
See [proposal term verification](./PROPOSAL-TERMS-VERIFICATION.md) for digest
integrity, schema-version selection, and typed mismatch paths.

For compatibility behavior with AdCP 3.0/3.1 sellers, see
[Media-buy 3.2 compatibility](./MEDIA-BUY-3.2-COMPATIBILITY.md).
153 changes: 153 additions & 0 deletions docs/guides/PROPOSAL-TERMS-VERIFICATION.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,153 @@
# Verify proposal terms before acceptance

Use the standalone buyer API to compare a seller's proposal with the **complete
commercial terms the buyer reviewed**. The existing root exports remain available.

```ts
import {
verifyProposalCommercialTerms,
assertProposalCommercialTerms,
type ProposalCommercialTermsMismatch,
} from '@adcp/sdk/negotiation/verification';

const result = verifyProposalCommercialTerms(proposal, reviewedCommercialTerms, {
adcpVersion: sellerAdcpVersion, // seller-served release; defaults to the SDK schema pin
});
if (!result.ok) {
for (const mismatch of result.mismatches) {
console.error(mismatch.kind, mismatch.path, mismatch.message);
}
// Stop acceptance, including when result.truncated is true.
} else {
// Continue the buyer's status, expiry, governance, and acceptance checks.
}

// Alternatively, throws ProposalCommercialTermsVerificationError on failure.
assertProposalCommercialTerms(proposal, reviewedCommercialTerms, {
adcpVersion: sellerAdcpVersion,
});
```

This is a synchronous, tree-shakeable **Node.js** entry point with ESM and CJS
declarations. It loads local schema bundles and uses Node crypto. It neither
constructs a protocol client nor contacts an agent or a contract URL. Browser
applications should perform this verification in their buyer backend; this entry
does not bundle Node polyfills or a browser schema store.

## Verification order and mismatch paths

The verifier first bounds the supplied JSON tree, then verifies `terms_digest`
against `sha256:` plus base64url SHA-256 of RFC 8785 JCS `commercial_terms`.
A digest failure returns only `digest_mismatch` at `/terms_digest`, before reading
the selected schema or the expected terms. This checks content integrity; a
matching digest by itself does not mean the buyer agreed to the contents.

Both complete snapshots must satisfy the same schema. The comparison includes
every admitted value recursively: price, currency, aggregate and purchase flights,
purchases, budgets, change rights, status scope, service modes, SLA, opaque
conditions, contract pointers, and nested extension data. Object key order is
irrelevant. Array order and the difference between absence and presence remain
binding. Schema errors return `invalid_terms` with the affected subject; comparisons
return `missing`, `unexpected`, or `changed` with RFC 6901 JSON Pointers such as
`/commercial_terms/purchases/0/pricing/fixed_price`. Pointers escape `/` as `~1`
and `~` as `~0`. Diagnostics omit field values and are bounded; paths preserve
property names. Schema-support failures identify the affected schema location.

Package IDs assigned during execution are outside the commercial envelope. The
canonical schema uses ordered `purchases`; the verifier does not silently turn a
legacy `packages` array into purchases. Narrative, allocation, and display fields
outside `commercial_terms` cannot substitute for the reviewed snapshot.

## Runtime schema coupling and additions

The comparison shape comes from the selected bundle's
`media-buy/commercial-terms.json` and its references, including `patternProperties`
and open extension objects. There is no SDK binding-field list. A new optional
field requires both an installed matching schema and an explicitly reviewed
snapshot containing that field; otherwise verification fails. An equal unknown
field outside the selected schema fails too. Never build the expected snapshot by
blindly copying the unreviewed candidate.

For binding snapshots, enum values must be listed in the selected schema even
when taxonomy annotations advertise extensibility. `x-extensible` and `x-pattern`
do not relax this conservative pre-acceptance policy; changed annotations require
review. An unknown industry value therefore needs an updated matching enum bundle.

Unknown schema keywords, a different schema dialect, cross-bundle references, and
changed `x-adcp-validation` contracts return `unsupported_schema`, even for equal
snapshots. The reviewed semantic annotations in
`src/lib/negotiation/commercial-terms-semantics.ts` are deliberately separate from
the runtime field shape. Explanatory `description` and `spec` metadata may change;
normative rule values, including prose inside `verifier_constraints`, require
review. Historical omissions are recorded in release-scoped semantic profiles.
On a schema upgrade, audit new annotations and implement
any required pre-acceptance behavior before updating that semantic support record.
Pricing integrity and portable change-term consistency checks run before the diff.
Schema-selected checks also reject contradictory place/region targeting, place
labels without a matching identifier, malformed language tags, and timezones
absent from the runtime's IANA database where the schema declares that check.
Bare string fields such as `budget_cap_timezone` receive only their schema-declared
validation. These checks run only on the applicable schema
branch; an `inventory_local` daypart remains valid. These specialized validators
are cached separately from ordinary SDK schema validators.
Preserving an opaque condition or contract pointer does not evaluate that
condition, resolve the contract, or grant permission to execute an action.

Pass the seller-served release. Full prerelease pins remain exact; release-precision
pins such as `3.2-rc.2` resolve to their installed bundle. Stable patch selection
follows the SDK loader's minor-line compatibility rules. `schemaVersion` records
the actual selected release. Missing bundles return `schema_unavailable`. There is
no network fallback, downgrade, field stripping, or automatic version projection.
External roots must retain the reviewed semantic graph. Canonical root-relative
schema IDs work, as do `latest` IDs when a matching root `index.json` pins the release.
Schema documents and support audits are cached together with validator state.
Treat an active schema root as immutable; registering a replacement root or
restarting the application refreshes all three. Timezone and language checks
use the runtime's ICU data; Python implementations should test against their
supported locale and timezone databases as well as the portable fixtures.
Use the same module format for external-root registration and verification:
the SDK's ESM and CJS module graphs maintain separate loader state.
The bundle must have unambiguous schema identities throughout its registered
documents; identical published mirrors are allowed, conflicting definitions fail closed.

The reviewed rc.3 semantic profile removes the direct `buy_products` offer-matching
annotation from product purchases while retaining accepted-snapshot preservation
and pricing identity. That change is scoped to the exact rc.3 release; it does not
weaken the rc.2 contract or automatically approve future annotation changes.

The released `3.2.0-beta.8` bundle has commercial terms but no `change_terms`;
it rejects that later field. The pinned 3.1 bundle has no canonical commercial
envelope and returns `schema_unavailable`. Existing 3.1 action readers continue
to treat `available_actions[].terms_ref` as opaque. A proposal's
`change_terms[].terms_ref` is a contract reference and may differ from `term_id`.
Only a live 3.2 action carrying `change_term_id` and its compatibility `terms_ref`
alias has an equality obligation. Joining those actions to accepted terms belongs
to Part A of [#2664](https://github.com/adcontextprotocol/adcp-client/issues/2664);
this pre-acceptance API does not infer that join or grant authority from a legacy
pointer that happens to resemble a term ID.

## Upstream coordination and Python parity

The initial Part B implementation landed in SDK
[#2757](https://github.com/adcontextprotocol/adcp-client/pull/2757). Upstream
[`adcp#6794`](https://github.com/adcontextprotocol/adcp/pull/6794), implementing RFC
[#6750](https://github.com/adcontextprotocol/adcp/issues/6750), temporarily patched
the installed SDK's `dist/lib/negotiation/verification.{js,mjs}` allowlist in
`scripts/overlay-compliance-cache.sh` to admit `change_terms`.

That coordination is already complete:
[`adcp#7018`](https://github.com/adcontextprotocol/adcp/pull/7018) upgraded to
`@adcp/sdk@14.0.0-beta.16`, deleted the overlay, and switched storyboard runs to
public `schemaRoot`/`complianceDir` options. Current upstream pins SDK rc.35.
No companion patch-removal PR remains necessary. When upstream consumes this
hardening, update its SDK pin and lockfile together and run `test:sdk-shims` plus
the current and frozen compatibility storyboard matrices; do not restore a dist
patch to bypass an unsupported semantic contract.

Python tracking remains
[`adcp-client-python#1067`](https://github.com/adcontextprotocol/adcp-client-python/issues/1067).
Parity requires digest-first rejection, complete schema-admitted comparison,
ordered-array behavior, precise escaped pointers, failure on unreviewed schema
semantics, and the same absence/opaque-reference/version behavior. The fixtures
under `test/fixtures/proposal-commercial-terms` are portable JSON. Part A's unified
action assessment and seller resolver remain separate work.
2 changes: 2 additions & 0 deletions docs/llms.txt
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ SDK 14 requires Node.js `^20.19.0 || >=22.12.0`; install the newest v14 prerelea
SDK 14 is compact-lifecycle first: `list_products → buy_products → control_media_buy`, with `request_proposals → refine_proposals → accept_proposal` when terms need negotiation.

- **Buyer** (calling a seller): read `docs/guides/BUYER-QUICKSTART-3.2.md` first.
- **Before proposal acceptance:** use `verifyProposalCommercialTerms` from `@adcp/sdk/negotiation/verification` with a complete, independently reviewed snapshot and the seller-served schema version. Never use an unreviewed candidate as its own expected terms. See `docs/guides/PROPOSAL-TERMS-VERIFICATION.md`.
- **Seller** (implementing an agent that others call): read `docs/guides/SELLER-QUICKSTART-3.2.md` first, then `docs/guides/BUILD-AN-AGENT.md` for the complete framework surface.
- **Upgrading an existing application:** read `docs/migration-13-to-14.md`; established 3.0/3.1 tools remain supported as an explicit compatibility path.

Expand Down Expand Up @@ -2079,6 +2080,7 @@ These docs are available locally in the repo and hosted at https://adcontextprot
|------|-----------|--------|
| Full type signatures | docs/TYPE-SUMMARY.md | [link](https://adcontextprotocol.github.io/adcp-client/TYPE-SUMMARY.md) |
| Buyer quick start (AdCP 3.2) | docs/guides/BUYER-QUICKSTART-3.2.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/BUYER-QUICKSTART-3.2.md) |
| Verify proposal terms before acceptance | docs/guides/PROPOSAL-TERMS-VERIFICATION.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/PROPOSAL-TERMS-VERIFICATION.md) |
| Seller quick start (AdCP 3.2) | docs/guides/SELLER-QUICKSTART-3.2.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/SELLER-QUICKSTART-3.2.md) |
| Production durability checklist | docs/guides/PRODUCTION-DURABILITY.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/PRODUCTION-DURABILITY.md) |
| Persistent notification subscriptions | docs/guides/PERSISTENT-NOTIFICATION-RUNTIME.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/PERSISTENT-NOTIFICATION-RUNTIME.md) |
Expand Down
5 changes: 5 additions & 0 deletions docs/migration-adcp-3.1-to-3.2-proposals.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,11 @@ Pass the result through `unwrapVerifiedRefineProposals(result, request)` or use

Exact transport retries reuse the same request and key. A changed refinement is a new intent and must use a fresh key; `ProposalNegotiator.changedRequest()` enforces that split. Check the committed proposal's `expires_at` immediately before `accept_proposal`/`buy_products`.

Use the standalone `verifyProposalCommercialTerms` API to compare the complete
buyer-reviewed commercial snapshot before acceptance. See
[proposal term verification](./guides/PROPOSAL-TERMS-VERIFICATION.md) for the
schema-version coupling and preservation of legacy opaque contract references.

If `lifecycle_tools` omits `refine_proposals`, translate supported requests to the legacy `get_products({ buying_mode: 'refine', refine: [...] })` flow. Free-text `ask` maps to the legacy proposal ask. Product include/omit actions map directly. Hard constraints require explicit adapter policy: legacy discovery cannot guarantee the 3.2 hard-constraint semantics, so verify the returned proposal locally or report the dimension as unsupported.

When that fallback sends a proposal refinement with `action: 'finalize'`, it
Expand Down
13 changes: 13 additions & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -366,6 +366,16 @@
"default": "./dist/lib/reporting/ledger/index.js"
}
},
"./negotiation/verification": {
"import": {
"types": "./dist/lib/negotiation/verification.d.mts",
"default": "./dist/lib/negotiation/verification.mjs"
},
"require": {
"types": "./dist/lib/negotiation/verification.d.ts",
"default": "./dist/lib/negotiation/verification.js"
}
},
"./package.json": "./package.json"
},
"typesVersions": {
Expand Down Expand Up @@ -474,6 +484,9 @@
],
"types/*": [
"dist/lib/types/*.d.ts"
],
"negotiation/verification": [
"dist/lib/negotiation/verification.d.ts"
]
}
},
Expand Down
4 changes: 3 additions & 1 deletion scripts/check-package-size.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,9 @@ const MAX_UNPACKED_PACKAGE_BYTES = 120 * 1024 * 1024;
// cross-SDK consumer-status vector adds one published JSON artifact.
// Account-feed adoption adds five runtime/declaration module sets (20 files)
// and one migration guide. Byte budgets remain unchanged.
const MAX_PACKED_FILE_COUNT = 6_016;
// The standalone proposal verifier adds twelve helper module artifacts and
// one buyer guide; byte budgets remain unchanged.
const MAX_PACKED_FILE_COUNT = 6_029;
const MAX_BUNDLED_SCHEMA_BYTES = 1280 * 1024;
const MAX_CJS_SCHEMA_DECLARATION_BYTES = 45 * 1024 * 1024;
const MAX_ESM_SCHEMA_FACADE_BYTES = 1024;
Expand Down
4 changes: 4 additions & 0 deletions scripts/generate-agent-docs.ts
Original file line number Diff line number Diff line change
Expand Up @@ -615,6 +615,9 @@ function generateLlmsTxt(
);
ln();
ln(`- **Buyer** (calling a seller): read \`docs/guides/BUYER-QUICKSTART-3.2.md\` first.`);
ln(
`- **Before proposal acceptance:** use \`verifyProposalCommercialTerms\` from \`@adcp/sdk/negotiation/verification\` with a complete, independently reviewed snapshot and the seller-served schema version. Never use an unreviewed candidate as its own expected terms. See \`docs/guides/PROPOSAL-TERMS-VERIFICATION.md\`.`
);
ln(
`- **Seller** (implementing an agent that others call): read \`docs/guides/SELLER-QUICKSTART-3.2.md\` first, then \`docs/guides/BUILD-AN-AGENT.md\` for the complete framework surface.`
);
Expand Down Expand Up @@ -1287,6 +1290,7 @@ function generateLlmsTxt(
const docLinks: [string, string][] = [
['Full type signatures', 'TYPE-SUMMARY.md'],
['Buyer quick start (AdCP 3.2)', 'guides/BUYER-QUICKSTART-3.2.md'],
['Verify proposal terms before acceptance', 'guides/PROPOSAL-TERMS-VERIFICATION.md'],
['Seller quick start (AdCP 3.2)', 'guides/SELLER-QUICKSTART-3.2.md'],
['Production durability checklist', 'guides/PRODUCTION-DURABILITY.md'],
['Persistent notification subscriptions', 'guides/PERSISTENT-NOTIFICATION-RUNTIME.md'],
Expand Down
2 changes: 2 additions & 0 deletions scripts/verify-package.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -141,6 +141,7 @@ try {
'package/docs/migration-12-to-14.md',
'package/docs/migration-13-to-14.md',
'package/docs/migration-12-to-13.md',
'package/docs/guides/PROPOSAL-TERMS-VERIFICATION.md',
'package/MIGRATION-v8.md',
];
for (const guide of requiredGuides) {
Expand Down Expand Up @@ -268,6 +269,7 @@ try {
{ specifier: '@adcp/sdk/server', symbol: 'A2AInvocationError' },
{ specifier: '@adcp/sdk/signing/server', symbol: 'resolveAgent' },
{ specifier: '@adcp/sdk/testing', symbol: 'mergeSeedProductLegacy' },
{ specifier: '@adcp/sdk/negotiation/verification', symbol: 'verifyProposalCommercialTerms' },
{ specifier: '@adcp/sdk/schemas', symbol: 'CreativeAssetSchema' },
];

Expand Down
Loading
Loading