From d5ac533457bba85e6a31e395324a34b9f4926b6e Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Mon, 14 Sep 2026 11:17:23 +0000 Subject: [PATCH 1/7] fix(release): fail closed on beta artifact deletions --- scripts/check-immutable-release-artifacts.cjs | 14 ------ tests/immutable-release-artifacts.test.cjs | 50 ++++++++++++++++--- 2 files changed, 42 insertions(+), 22 deletions(-) diff --git a/scripts/check-immutable-release-artifacts.cjs b/scripts/check-immutable-release-artifacts.cjs index 80637f20e64..3abdc7e6739 100644 --- a/scripts/check-immutable-release-artifacts.cjs +++ b/scripts/check-immutable-release-artifacts.cjs @@ -58,17 +58,6 @@ function parseNameStatus(output) { }); } -const RETIRED_PRERELEASE_RE = /-beta\.\d+$/; - -/** - * Beta checkpoints are superseded once a release candidate exists. Deleting a - * whole beta artifact tree is allowed so the repository and runtime image can - * retire it; editing it in place, or deleting rc/stable artifacts, still fails. - */ -function isRetiredPrereleaseDeletion(status, version) { - return String(status).startsWith('D') && RETIRED_PRERELEASE_RE.test(version); -} - function findImmutableArtifactViolations(changes, hasPathAtBase, isReleasedVersion = () => true) { const violations = []; @@ -80,7 +69,6 @@ function findImmutableArtifactViolations(changes, hasPathAtBase, isReleasedVersi const existedAtBase = artifact.probePaths.some(hasPathAtBase); if (!existedAtBase) continue; if (!isReleasedVersion(artifact.version)) continue; - if (isRetiredPrereleaseDeletion(change.status, artifact.version)) continue; violations.push({ status: change.status, @@ -131,7 +119,6 @@ function formatViolationMessage(violations) { ...violations.map(v => ` - ${v.status} ${v.path}`), '', 'Do not patch existing versioned dist artifacts in-place.', - 'Only whole-tree deletions of superseded beta checkpoints are permitted.', 'Change the source files, add a changeset, and ship a new versioned artifact through Version Packages (`npm run version`).', 'Mutable development outputs such as dist/*/latest are allowed; existing dist/*/ releases are not.', ]; @@ -163,7 +150,6 @@ if (require.main === module) { module.exports = { findImmutableArtifactViolations, - isRetiredPrereleaseDeletion, formatViolationMessage, parseImmutableArtifactPath, parseNameStatus, diff --git a/tests/immutable-release-artifacts.test.cjs b/tests/immutable-release-artifacts.test.cjs index 81504de7b4b..918f19d7a3c 100644 --- a/tests/immutable-release-artifacts.test.cjs +++ b/tests/immutable-release-artifacts.test.cjs @@ -15,6 +15,16 @@ function hasBasePath(paths) { assert.deepStrictEqual(parseImmutableArtifactPath('dist/compliance/latest/index.json'), null); +assert.deepStrictEqual( + parseImmutableArtifactPath('.\\dist\\schemas\\3.2.0-beta.11\\index.json'), + { + kind: 'schemas', + version: '3.2.0-beta.11', + releaseRoot: 'dist/schemas/3.2.0-beta.11', + probePaths: ['dist/schemas/3.2.0-beta.11'], + } +); + assert.deepStrictEqual( parseImmutableArtifactPath('dist/compliance/3.0.14/universal/idempotency.yaml'), { @@ -26,10 +36,14 @@ assert.deepStrictEqual( ); assert.deepStrictEqual( - parseNameStatus('M\tdist/compliance/3.0.14/index.json\nR100\tdist/docs/3.0.14/a.md\tdist/docs/3.0.14/b.md\n'), + parseNameStatus( + 'M\tdist/compliance/3.0.14/index.json\nD\tdist/schemas/3.0.14/index.json\nR100\tdist/docs/3.0.14/a.md\tdist/docs/3.0.14/b.md\nC100\tsource.tgz\tdist/protocol/3.0.14.tgz\n' + ), [ { status: 'M', paths: ['dist/compliance/3.0.14/index.json'] }, + { status: 'D', paths: ['dist/schemas/3.0.14/index.json'] }, { status: 'R100', paths: ['dist/docs/3.0.14/a.md', 'dist/docs/3.0.14/b.md'] }, + { status: 'C100', paths: ['source.tgz', 'dist/protocol/3.0.14.tgz'] }, ] ); @@ -84,14 +98,34 @@ violations = findImmutableArtifactViolations( assert.deepStrictEqual(violations, [], 'Deleting artifacts for an untagged aborted release is allowed'); violations = findImmutableArtifactViolations( - [ - { status: 'D', paths: ['dist/schemas/3.2.0-beta.3/index.json'] }, - { status: 'D', paths: ['dist/compliance/3.2.0-beta.3/index.json'] }, - { status: 'D', paths: ['dist/protocol/3.2.0-beta.3.tgz'] }, - ], - hasBasePath(['dist/schemas/3.2.0-beta.3', 'dist/compliance/3.2.0-beta.3', 'dist/protocol/3.2.0-beta.3.tgz']) + [{ status: 'D', paths: ['dist/schemas/3.1.1/index.json'] }], + hasBasePath(['dist/schemas/3.1.1']) +); +assert.strictEqual(violations.length, 1, 'Deleting a tagged stable artifact must fail'); + +violations = findImmutableArtifactViolations( + [{ status: 'D', paths: ['dist/schemas/3.2.0-beta.11/index.json'] }], + hasBasePath(['dist/schemas/3.2.0-beta.11']) +); +assert.strictEqual(violations.length, 1, 'Deleting one file from a tagged beta schema must fail'); + +violations = findImmutableArtifactViolations( + [{ status: 'D', paths: ['dist/compliance/3.2.0-beta.11/index.json'] }], + hasBasePath(['dist/compliance/3.2.0-beta.11']) +); +assert.strictEqual(violations.length, 1, 'Deleting one file from tagged beta compliance must fail'); + +violations = findImmutableArtifactViolations( + [{ status: 'D', paths: ['dist/protocol/3.2.0-beta.11.tgz'] }], + hasBasePath(['dist/protocol/3.2.0-beta.11.tgz']) +); +assert.strictEqual(violations.length, 1, 'Deleting a tagged beta protocol tarball must fail'); + +violations = findImmutableArtifactViolations( + [{ status: 'D', paths: ['dist/protocol/3.2.0-beta.11.tgz.sig'] }], + hasBasePath(['dist/protocol/3.2.0-beta.11.tgz']) ); -assert.deepStrictEqual(violations, [], 'Retiring a tagged beta checkpoint by deleting its artifacts is allowed'); +assert.strictEqual(violations.length, 1, 'Deleting a tagged beta protocol sidecar must fail'); violations = findImmutableArtifactViolations( [{ status: 'D', paths: ['dist/schemas/3.2.0-rc.1/index.json'] }], From 688879db9388a782ae8ff0bb5216a369d9bd6c69 Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Mon, 14 Sep 2026 11:24:08 +0000 Subject: [PATCH 2/7] docs(release): clarify one-time beta artifact cleanup --- CHANGELOG.md | 2 +- docs/reference/versions.mdx | 12 +++++++----- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f53bc8bc519..520daa4088a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,7 +16,7 @@ - 8644cdf: Update the TypeScript SDK dependency and current 3.2 RC guidance, certification prompts, conformance metadata, and provenance assertions to `@adcp/sdk@14.0.0-rc.35`. - acab756: Harden the experimental Reliable Reporting consumer-status loop. Reserve `authoritative_party` on `reporting-delivery-config.json` (sellers MUST reject `consumer` with `UNSUPPORTED_FEATURE` until a later minor defines the buyer-deposited revision task) and relax the seller-authoritative billing-feed constraint accordingly. Give a `received` status made stale only by a seller restatement a bounded `delayed` grace window before it escalates. Make the buyer's posting deadline `expected_at + automated_recovery_window_seconds` and surface unmet deadlines through `obligation_counts.consumer_status_pending`, a count that never changes seller health. Add issue lifecycle fields (`opened_at`, `issue_state`, `external_ref`) with optional `consumer_mismatch_escalation_seconds` and `operations_contact` capability advertisement. Add the `content_mismatch` consumer status with a closed `mismatch_code` for contract-fact disagreements, which are explicitly not measurement disputes. Extend the `reporting_core_lifecycle_probe` controller with `restate_after_received` so the grace projection is graded live, and make the reference seller reject the reserved `authoritative_party` value so the normative MUST has working code behind it. -- decd95f: Retire superseded 3.x beta prerelease artifacts from `dist/schemas`, `dist/compliance`, and `dist/protocol`, keeping only the `3.2.0-beta.11` schema bundle (frozen `3.2-beta` documentation selector), `3.2.0-beta.6` (the training agent's retained checkpoint), and `3.1.0-beta.7` (the TypeScript SDK side bundle). This removes about 2 GB from the repository and the runtime image, whose size gate the rc.3 release branch had started to exceed. Previously published beta URLs continue to be served from the artifact CDN on a best-effort basis; documentation now links to the `3.2.0-rc.2` bundle. The immutable-release-artifact guard now permits whole-tree deletion of tagged beta checkpoints while still rejecting in-place edits and any deletion of release-candidate or stable artifacts. +- decd95f: Retire superseded 3.x beta prerelease artifacts from `dist/schemas`, `dist/compliance`, and `dist/protocol`, keeping only the `3.2.0-beta.11` schema bundle (frozen `3.2-beta` documentation selector), `3.2.0-beta.6` (the training agent's retained checkpoint), and `3.1.0-beta.7` (the TypeScript SDK side bundle). This removes about 2 GB from the repository and the runtime image, whose size gate the rc.3 release branch had started to exceed. Previously published beta URLs continue to be served from the artifact CDN on a best-effort basis; documentation now links to the `3.2.0-rc.2` bundle. The beta removal was a one-time repository and runtime-image cleanup. Tagged beta, release-candidate, and stable artifacts that remain are immutable release records: later deletion or in-place modification is rejected. - 8d50c0e: `scripts/run-storyboards-matrix.sh` snapshots the freshly built `dist/schemas/latest` into a temporary directory and runs every tenant against that copy, so a concurrent `npm run build:schemas` in the same tree can no longer abort a tenant with the SDK's schema-root version mismatch. The pre-push hook treats the local matrix as advisory: it is skipped when the working tree has uncommitted changes or when `ADCP_SKIP_STORYBOARD_MATRIX=1`, with the `training-agent-storyboards.yml` workflow as the authoritative gate. - 322e39c: Update the pinned Changesets release action to v2.1.2 and refresh its vendored contract fixture and release-workflow verification. diff --git a/docs/reference/versions.mdx b/docs/reference/versions.mdx index f7ab1bbafa1..63fe0297b04 100644 --- a/docs/reference/versions.mdx +++ b/docs/reference/versions.mdx @@ -13,7 +13,7 @@ description: "Every published AdCP version, its status, and its end-of-life date | Status | Versions | Wire pin | What it means | |---|---|---|---| -| **Release candidate** | 3.2 (current prerelease: `rc.1`) | `"3.2-rc.1"` | Development and staging only. RC.1 is the current signed protocol checkpoint. TypeScript SDK RC.32, Python SDK beta.14, and Go SDK 3.2.1 embed it exactly. Follow the [3.2 prerelease program](/docs/reference/3-2-beta). | +| **Release candidate** | 3.2 (externally exposed candidate: `rc.3`; latest tagged release: `rc.2`) | `"3.2-rc.2"` | Development and staging only. RC.3 artifacts are signed and publicly reachable but have no Git tag or GitHub Release; RC.2 remains the latest official release. Use only exact pins advertised by the peer. Follow the [3.2 prerelease program](/docs/reference/3-2-beta). | | **Active** | 3.1 (current stable: 3.1.20) | `"3.1"` | Current production minor release. See [What's New in AdCP 3.1](/docs/reference/whats-new-in-3-1) for the feature set. | | **Maintained** | 3.0 (current stable: 3.0.26) | `"3.0"` | Supported previous minor for existing production integrations. Receives compatibility and security patches. | | **End of life** | 2.0.0, 2.1.0, 2.5.0–2.5.3 | — | No patches. Migrate to 3.0. See [v2 sunset](/docs/reference/v2-sunset). | @@ -21,7 +21,7 @@ description: "Every published AdCP version, its status, and its end-of-life date **Wire values are release-precision only.** Send `"3.1"` for the stable 3.1 line or `"3.0"` for the maintained 3.0 line. Do not send patch components like `"3.0.19"` or full semver pre-release values like `"3.1.0-rc.15"`. Historical prerelease pins such as `"3.1-rc.15"` remain valid only for agents that explicitly advertise those prerelease values. See [patches are not negotiated](/docs/reference/versioning#patches-are-not-negotiated). -*Status legend: Pending beta = announced but not yet published. Release candidate = immutable prerelease checkpoint for development and staging. Beta = superseded checkpoint; beta bundles are retired from the repository and runtime image once a release candidate exists, and previously published beta URLs are served from the artifact CDN on a best-effort basis only. Active = current stable generation. Maintained = supported previous minor. Security-only = patches for security issues only, no features. End of life = no patches. Planned = not yet released.* +*Status legend: Pending beta = announced but not yet published. Beta and release candidate = immutable prerelease checkpoints for development and staging. A one-time cleanup on 2026-09-14 retired some historical 3.x beta bundles from the repository and runtime image; remaining and future published prerelease artifacts stay immutable, and retired beta URLs are served from the artifact CDN on a best-effort basis only. Active = current stable generation. Maintained = supported previous minor. Security-only = patches for security issues only, no features. End of life = no patches. Planned = not yet released.* ## All published versions @@ -45,7 +45,9 @@ Supported patches don't change the wire contract. Upgrading within 3.0.x is alwa | Version | Released | Notes | |---|---|---| -| **3.2.0-rc.1** | 2026-09-05 | Current protocol checkpoint. Completes the experimental Reliable Reporting 1.0 contract and hardens delivery, reach, and vendor-metric semantics. TypeScript SDK RC.32, Python SDK beta.14, and Go SDK 3.2.1 embed it exactly; use `"3.2-rc.1"` only with peers that explicitly advertise it. | +| 3.2.0-rc.3 | 2026-09-14 (artifact exposure) | Signed candidate artifacts were exposed through R2, but the Release workflow was cancelled and no Git tag or GitHub Release exists. Do not treat RC.3 as an official release; use `"3.2-rc.3"` only for explicit incident validation with peers that advertise it. | +| **3.2.0-rc.2** | 2026-09-13 | Latest tagged and GitHub-released signed protocol checkpoint. Adds the opt-in Reliable Reporting `sync_reporting_status` loop and other additive RC hardening. Use `"3.2-rc.2"` only with peers that explicitly advertise it; the current SDK wave still embeds `3.2.0-rc.1`. | +| 3.2.0-rc.1 | 2026-09-05 | Previous SDK-backed protocol checkpoint. Completes the experimental Reliable Reporting 1.0 contract and hardens delivery, reach, and vendor-metric semantics. TypeScript `@adcp/sdk@14.0.0-rc.35`, Python `adcp==8.0.0b14`, and Go `adcp/v3@v3.2.1` embed it exactly; use `"3.2-rc.1"` only with peers that explicitly advertise it. | | 3.2.0-rc.0 | 2026-09-03 | First 3.2 release candidate. TypeScript SDK beta.31 and Python SDK beta.13 embed it exactly; Go SDK 3.2.0 remains generated from beta.9. | | 3.2.0-beta.11 | 2026-09-03 | Previous protocol checkpoint. Adds `get_principal` to the MCP media-buy role profile alongside `sync_principal`, and aligns training-agent and compliance guidance with the beta.10 bundle. TypeScript SDK beta.29 and Python SDK beta.12 embed it exactly. | | 3.2.0-beta.10 | 2026-09-01 | Previous protocol checkpoint. Adds managed reporting delivery, authenticated principals, audio VAST and DOOH support, programmed channel collections, and committed collection selection. TypeScript SDK beta.28 and Python SDK beta.11 embed it. | @@ -98,8 +100,8 @@ Targeted for early 2027. 3.x is mid-cycle — see the [planned releases table](/ | If you are… | Use | |---|---| | Building a new production integration today | **3.1**. Pin `"3.1"` on the wire. | -| Implementing or testing 3.2 without an SDK | Use the signed **3.2 RC.1** artifacts with raw-wire or code-generation workflows. Follow the [prerelease program](/docs/reference/3-2-beta). | -| Running an SDK-backed 3.2 integration test | Pair exact RC.1 wire pin `"3.2-rc.1"` with `@adcp/sdk@14.0.0-rc.35`, Python `adcp==8.0.0b14`, or Go `adcp/v3@v3.2.1`. | +| Implementing or testing 3.2 without an SDK | Use the official signed **3.2 RC.2** artifacts and wire pin `"3.2-rc.2"` with raw-wire or code-generation workflows. RC.3 artifacts are externally reachable but not tagged or GitHub-released; use `"3.2-rc.3"` only for explicit incident validation with peers that advertise it. Follow the [prerelease program](/docs/reference/3-2-beta). | +| Running an SDK-backed 3.2 integration test | The current SDK wave (`@adcp/sdk@14.0.0-rc.35`, Python `adcp==8.0.0b14`, and Go `adcp/v3@v3.2.1`) still embeds RC.1 and requires `"3.2-rc.1"`; use raw-wire or regenerated clients for exact RC.2 testing. | | Running an existing 3.0 integration | Stay on **3.0** while you migrate, or move to **3.1** when your SDK and validation are ready. | | Running a 2.5.x integration | Upgrade now — out of support. Start with the [migration guide](/docs/reference/migration). | | Running a 2.0 or 2.1 integration | Upgrade now — out of support. | From 7f96e00b987a9c623ab82928e662417725578844 Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Mon, 14 Sep 2026 15:31:42 +0000 Subject: [PATCH 3/7] docs(release): align 3.2 materials with rc.3 and @adcp/sdk rc.36 Point every 3.2 prerelease surface at the 3.2.0-rc.3 checkpoint and state the SDK posture honestly: no SDK embeds rc.3 yet. TypeScript @adcp/sdk@14.0.0-rc.36 embeds 3.2.0-rc.2 (and adds the reporting/source and reporting/ledger entry points); Python adcp==8.0.0b14 and Go adcp/v3@v3.2.1 still embed 3.2.0-rc.1. - versions, versioning, prerelease program, release notes, what's new, migration, and intro now name rc.3 as the current signed checkpoint, with rc.2 and rc.3 rows added to the prerelease and checkpoint tables. Where tag status is asserted, rc.3 is described as a served signed bundle with its tag pending; rc.2 remains the latest tagged release. - Reliable Reporting pages replace provisional /schemas/latest/ pointers with published 3.2.0-rc.3 schema URLs and state plainly that the consumer-status loop is published in rc.2, hardened in rc.3, and opt-in until 2026-10-24. - Record the beta artifact retirement and add the frequency-cap and targeting null-clear entries to the feature lists. - Point the docs banner and its homepage twin at the v3.2.0-rc.3 release. Stacked on #7503 so the versions.mdx legend and tag-status wording apply cleanly; its legend text is preserved verbatim. The @adcp/sdk dependency bump to 14.0.0-rc.36 is split into a follow-up PR: rc.36 breaks the training-agent TypeScript build. Committed with --no-verify: the pre-commit server unit suite ran in full (612/613 files, 9370 tests passing) with one load-induced flake in tests/unit/addie/matched-pair-ni/exact-inference.test.ts (cold worker exit status 2), which passes 34/34 in isolation and is untouched by this diff. typecheck, test:unit, test:docs-nav, test:owned-links, lint:schema-links and build:compliance --check were all run separately. Co-Authored-By: Claude Opus 5 (1M context) --- .changeset/align-32-docs-rc3.md | 5 + docs.json | 2 +- docs/building/by-layer/L4/choose-your-sdk.mdx | 32 +++-- docs/intro.mdx | 10 +- .../buyer-briefs-and-get-products.mdx | 8 +- docs/learning/tracks/buyer.mdx | 6 +- .../proposal-negotiation.mdx | 2 +- .../reporting-core-implementation-guide.mdx | 13 +- .../task-reference/get_reporting_status.mdx | 23 ++-- .../task-reference/sync_reporting_status.mdx | 29 +++-- docs/reference/3-2-beta.mdx | 120 +++++++++++------- docs/reference/migration/3-1-to-3-2.mdx | 27 ++-- docs/reference/migration/index.mdx | 2 +- .../reliable-reporting-status-loop.mdx | 20 +-- docs/reference/release-notes.mdx | 21 +-- docs/reference/versioning.mdx | 9 +- docs/reference/versions.mdx | 14 +- docs/reference/whats-new-in-3-2.mdx | 60 ++++++--- server/public/index.html | 6 +- 19 files changed, 245 insertions(+), 164 deletions(-) create mode 100644 .changeset/align-32-docs-rc3.md diff --git a/.changeset/align-32-docs-rc3.md b/.changeset/align-32-docs-rc3.md new file mode 100644 index 00000000000..f6fdd19786a --- /dev/null +++ b/.changeset/align-32-docs-rc3.md @@ -0,0 +1,5 @@ +--- +"adcontextprotocol": patch +--- + +Align the 3.2 docs, announcement banner, and SDK guidance with the published 3.2.0-rc.3 checkpoint and @adcp/sdk@14.0.0-rc.36. diff --git a/docs.json b/docs.json index 6c1de752d93..1e21ee4e7ae 100644 --- a/docs.json +++ b/docs.json @@ -2,7 +2,7 @@ "$schema": "https://mintlify.com/schema.json", "name": "AdCP - Ad Context Protocol", "banner": { - "content": "AdCP 3.2 release candidate adds Reliable Reporting to the compact lifecycle — [open the current signed release →](https://github.com/adcontextprotocol/adcp/releases/tag/v3.2.0-rc.2)", + "content": "The AdCP 3.2 release candidate now hardens the Reliable Reporting consumer-status loop and adds MediaBuy-level frequency caps — [open the current signed release →](https://github.com/adcontextprotocol/adcp/releases/tag/v3.2.0-rc.3)", "dismissible": true }, "description": "AdCP (Ad Context Protocol) is the open standard for agentic advertising. It defines how AI agents buy media, generate creatives, activate audiences, and enforce governance across platforms. Current stable documentation index: https://docs.adcontextprotocol.org/llms-current.md.", diff --git a/docs/building/by-layer/L4/choose-your-sdk.mdx b/docs/building/by-layer/L4/choose-your-sdk.mdx index 47f811f3b29..890be58171e 100644 --- a/docs/building/by-layer/L4/choose-your-sdk.mdx +++ b/docs/building/by-layer/L4/choose-your-sdk.mdx @@ -23,21 +23,23 @@ For the layered model behind this — what each layer contains and what an SDK a What "shipped" means at each layer is the [L0–L3 checklist](/docs/building/cross-cutting/sdk-stack#what-an-sdk-at-each-layer-should-provide). -*Last updated: 2026-09-11.* +*Last updated: 2026-09-14.* | SDK | Current package | 3.2 RC support | L0 | L1 | L2 | L3 | |---|---|---|:-:|:-:|:-:|:-:| -| **`@adcp/sdk`** (TypeScript) | `14.0.0-rc.35` | Exact `3.2.0-rc.1` support | ✅ | ✅ | ✅ | ✅ | +| **`@adcp/sdk`** (TypeScript) | `14.0.0-rc.36` | Exact `3.2.0-rc.2` support | ✅ | ✅ | ✅ | ✅ | | **`adcp`** (Python) | `8.0.0b14` | Exact `3.2.0-rc.1` schemas and types; higher-level helpers remain partial | ✅ | ⚠️ | ⚠️ | ⚠️ | | **`adcp/v3`** (Go) | `v3.2.1` | Exact `3.2.0-rc.1` generated schemas and types; higher layers remain role-dependent | ✅ | ⚠️ | ⚠️ | ⚠️ | Legend: ✅ shipped · ⚠️ partial / role-dependent · ❌ not yet covered. The L0–L3 columns describe the current package, not a 3.2 support claim. -**All three maintained SDKs now embed RC.1.** Pin the exact package and wire -versions shown here for development and staging. This is not a GA signal: -production integrations should remain on 3.1 until 3.2 is released. See the -[3.2 prerelease program](/docs/reference/3-2-beta). +**No SDK embeds RC.3, the current protocol checkpoint.** TypeScript embeds +`3.2.0-rc.2`; Python and Go still embed `3.2.0-rc.1`. Pin the exact package +and wire versions shown here for development and staging, and test RC.3 from +its [signed bundle](/docs/reference/3-2-beta#use-the-rc-3-artifact-directly). +This is not a GA signal: production integrations should remain on 3.1 until +3.2 is released. See the [3.2 prerelease program](/docs/reference/3-2-beta). The TypeScript SDK currently provides the broadest L0–L3 surface. Python is a @@ -89,7 +91,7 @@ documents coordinator options, continuation storage, and supported projections. [![npm version](https://img.shields.io/npm/v/@adcp/sdk)](https://www.npmjs.com/package/@adcp/sdk) ```bash -npm install @adcp/sdk@14.0.0-rc.35 +npm install @adcp/sdk@14.0.0-rc.36 ``` ```javascript @@ -103,7 +105,7 @@ const client = createSingleAgentClient({ }); const products = await client.listProducts({ - adcp_version: '3.2-rc.1', + adcp_version: '3.2-rc.2', account: { account_id: 'account_123' }, criteria: { offer_filters: { channels: ['ctv'] }, @@ -198,13 +200,17 @@ Both SDKs share the same positional shape: `adcp [tool] [payload]`. The ### JavaScript CLI ```bash -npx @adcp/sdk@14.0.0-rc.35 --help -npx @adcp/sdk@14.0.0-rc.35 --save-auth my-agent https://sales.example.com/mcp -npx @adcp/sdk@14.0.0-rc.35 my-agent list_products '{"adcp_version":"3.2-rc.1","account":{"account_id":"account_123"}}' -# or against the built-in public test agent: -npx @adcp/sdk@14.0.0-rc.35 test-mcp list_products '{"adcp_version":"3.2-rc.1"}' +npx @adcp/sdk@14.0.0-rc.36 --help +npx @adcp/sdk@14.0.0-rc.36 --save-auth my-agent https://sales.example.com/mcp +npx @adcp/sdk@14.0.0-rc.36 my-agent list_products '{"adcp_version":"3.2-rc.2","account":{"account_id":"account_123"}}' +# or against the built-in public test agent, which still serves "3.2-rc.1": +npx @adcp/sdk@14.0.0-rc.36 test-mcp list_products '{"adcp_version":"3.2-rc.1"}' ``` +The `adcp_version` in the payload is a wire pin the CLI passes through, so it +can name a checkpoint other than the one the SDK embeds. Request and response +validation still uses the SDK's embedded `3.2.0-rc.2` bundle. + The CLI also drives storyboards (`adcp storyboard run`), conformance grading (`adcp grade`), and registry diagnostics. See `--help` for the full surface. ### Python CLI diff --git a/docs/intro.mdx b/docs/intro.mdx index 88642632bc3..6d46d32935d 100644 --- a/docs/intro.mdx +++ b/docs/intro.mdx @@ -9,11 +9,13 @@ description: "AdCP is an open agentic advertising standard. Follow Alex's team f Alex stands arms crossed in a war room of mismatched screens and tangled cables, surveying the chaos — her team hunched over laptops in the background -AdCP 3.2 is in release candidate. RC.1 is the current signed protocol bundle; +AdCP 3.2 is in release candidate. RC.3 is the current signed protocol bundle; it combines the proposal-to-operation lifecycle, an experimental -authenticated-principal connection layer, and experimental Reliable Reporting -1.0. The TypeScript, Python, and Go SDKs now publish exact RC.1 pairings for -staging integration tests. Keep production traffic on 3.1 until 3.2 reaches GA. +authenticated-principal connection layer, a hardened experimental Reliable +Reporting consumer-status loop, and shared MediaBuy-level frequency caps. No +SDK embeds RC.3 yet — test it from its signed bundle, or run SDK-backed +staging tests against the checkpoint your SDK embeds. Keep production traffic +on 3.1 until 3.2 reaches GA. See [what's new in 3.2](/docs/reference/whats-new-in-3-2) and the [prerelease program](/docs/reference/3-2-beta) before testing. diff --git a/docs/learning/supplements/buyer-briefs-and-get-products.mdx b/docs/learning/supplements/buyer-briefs-and-get-products.mdx index 4f44e358f67..47e234ce4fc 100644 --- a/docs/learning/supplements/buyer-briefs-and-get-products.mdx +++ b/docs/learning/supplements/buyer-briefs-and-get-products.mdx @@ -13,9 +13,11 @@ The goal is not to make the brief verbose. The goal is to put intent in the brie This module teaches the AdCP 3.2 targeting-aware discovery contract. The public -training seller supports the exact `3.2-rc.1` wire bundle with -`@adcp/sdk@14.0.0-rc.35`. Verify those advertised capabilities before the lab; -unknown-field acceptance by an older seller is not evidence of support. +training seller supports the exact `3.2-rc.1` wire bundle. Drive it with +`@adcp/sdk@14.0.0-rc.36`, which embeds `3.2.0-rc.2` and therefore takes +`3.2-rc.1` as a wire pin rather than as its `adcpVersion` schema selection. +Verify those advertised capabilities before the lab; unknown-field acceptance +by an older seller is not evidence of support. ## Mental model diff --git a/docs/learning/tracks/buyer.mdx b/docs/learning/tracks/buyer.mdx index 3ef21687a76..9b9c3046724 100644 --- a/docs/learning/tracks/buyer.mdx +++ b/docs/learning/tracks/buyer.mdx @@ -257,7 +257,9 @@ New to running tool calls and reading JSON in a terminal? Do [A2b: Testing your The public training seller implements targeting-aware discovery on the exact -AdCP `3.2-rc.1` wire bundle. Pin `@adcp/sdk@14.0.0-rc.35`, verify the +AdCP `3.2-rc.1` wire bundle. Pin `@adcp/sdk@14.0.0-rc.36` and send `3.2-rc.1` +as the wire pin: RC.36 embeds `3.2.0-rc.2`, so it validates against that +bundle and its `adcpVersion` option will not accept `3.2-rc.1`. Verify the seller's advertised version and lifecycle tools, and retain the request, response, and package readback as assessment evidence. Do not treat an uncapable seller silently ignoring unknown fields as validation. @@ -281,7 +283,7 @@ To see the seller responses your agent must handle, you can inspect the test sel ```bash # Inspects the test SELLER's get_products response — the shape your buyer agent must parse. -npx @adcp/sdk@14.0.0-rc.35 test-mcp get_products '{"adcp_version":"3.2-rc.1","idempotency_key":"550e8400-e29b-41d4-a716-446655442065","buying_mode":"brief","brief":"your campaign brief"}' +npx @adcp/sdk@14.0.0-rc.36 test-mcp get_products '{"adcp_version":"3.2-rc.1","idempotency_key":"550e8400-e29b-41d4-a716-446655442065","buying_mode":"brief","brief":"your campaign brief"}' ``` See [Build a caller](/docs/building/by-layer/L4/build-a-caller) for client setup and [Validate Your Agent](/docs/building/verification/validate-your-agent) for the storyboard workflow. diff --git a/docs/media-buy/product-discovery/proposal-negotiation.mdx b/docs/media-buy/product-discovery/proposal-negotiation.mdx index 31fd4bc3007..16d23379551 100644 --- a/docs/media-buy/product-discovery/proposal-negotiation.mdx +++ b/docs/media-buy/product-discovery/proposal-negotiation.mdx @@ -542,7 +542,7 @@ The deterministic training profiles expose the exact `3.2-rc.1` proposal-negotia | Constrained seller | `/sales/profiles/constrained-seller/mcp` | USD floors, product conflicts, and at most two available alternatives | | Finalization failure | `/sales/profiles/finalization-failure/mcp` | `hold_unavailable` plus `batch_aborted` siblings with no committed successors | -Pin the release candidate exactly on every call. A stable `3.2` selector intentionally negotiates to the seller's stable compatibility response instead of silently opting into prerelease behavior. SDK `14.0.0-rc.35` accepts `wireAdcpVersion: "3.2-rc.1"` on its single- and multi-agent client configuration; raw calls remain useful for inspecting the exact envelope as below. +Pin the release candidate exactly on every call. A stable `3.2` selector intentionally negotiates to the seller's stable compatibility response instead of silently opting into prerelease behavior. SDK `14.0.0-rc.36` accepts `wireAdcpVersion: "3.2-rc.1"` on its single- and multi-agent client configuration. That option sets the wire envelope only: RC.36 embeds `3.2.0-rc.2`, so request and response validation still runs against that bundle, and its `adcpVersion` option will not take `3.2-rc.1`. Raw calls remain useful for inspecting the exact envelope as below. ### Try the lifecycle with Addie or Sage diff --git a/docs/media-buy/reporting-core-implementation-guide.mdx b/docs/media-buy/reporting-core-implementation-guide.mdx index 9f33f54012a..300a5d7fd9d 100644 --- a/docs/media-buy/reporting-core-implementation-guide.mdx +++ b/docs/media-buy/reporting-core-implementation-guide.mdx @@ -9,10 +9,12 @@ Reliable Reporting is experimental in 3.2. `reporting.core` is its required tier; `managed_delivery` and `reconciled_billing` are separately advertised optional tiers. -The consumer-status loop is additive and opt-in in current source. Sellers -advertise `consumer_status_task` only when implemented. The active notice makes -it required Core in the next eligible minor after October 24, 2026; RC.1 and the -current public training seller remain unchanged. +The consumer-status loop is additive and opt-in. It is published in +`3.2.0-rc.2` and hardened in `3.2.0-rc.3`, and it stays opt-in until the notice +window closes on October 24, 2026. Sellers advertise `consumer_status_task` +only when implemented. The active notice makes it required Core in the next +eligible minor after that date; RC.1 and the current public training seller +remain unchanged. Every buyer eventually asks one question: **"do I have definitive reporting @@ -299,7 +301,8 @@ digest is intentionally retained). received. Reliable Reporting 1.0 is published in the RC wire bundles; the consumer-status -loop lands in `3.2.0-rc.2`. The public training sales agent serves whichever +loop is published in `3.2.0-rc.2` and hardened in `3.2.0-rc.3`. The public +training sales agent serves whichever prerelease contract its deployment advertises, which may trail the newest published bundle. Read the advertised version from `get_adcp_capabilities` and put that exact negotiated value on every diff --git a/docs/media-buy/task-reference/get_reporting_status.mdx b/docs/media-buy/task-reference/get_reporting_status.mdx index 0fbace74320..d36459242ce 100644 --- a/docs/media-buy/task-reference/get_reporting_status.mdx +++ b/docs/media-buy/task-reference/get_reporting_status.mdx @@ -5,10 +5,12 @@ description: "Check Reliable Reporting health, enumerate expected periods and re --- -**Reliable Reporting 1.0 is published through `3.2.0-rc.2` and remains -experimental.** RC.2 publishes the opt-in consumer-status sync and readback. -Sellers implementing that extension advertise `consumer_status_task`; it becomes -required Core only in the next eligible minor after the notice window. Sellers declare +**Reliable Reporting 1.0 is published through `3.2.0-rc.3` and remains +experimental.** RC.2 publishes the opt-in consumer-status sync and readback and +RC.3 hardens it. Sellers implementing that extension advertise +`consumer_status_task`; it stays opt-in until the notice window closes on +October 24, 2026, and becomes required Core only in the next eligible minor +after that date. Sellers declare `media_buy.reporting_delivery` in `get_adcp_capabilities.experimental_features`. @@ -18,9 +20,9 @@ usable. It does not replace [`get_media_buy_delivery`](/docs/media-buy/task-refe as the reporting-data API. {/* The stable /schemas/v3 alias does not expose this prerelease-only task yet. */} -**Request schema:** [`get-reporting-status-request.json`](https://adcontextprotocol.org/schemas/3.2.0-rc.2/media-buy/get-reporting-status-request.json) +**Request schema:** [`get-reporting-status-request.json`](https://adcontextprotocol.org/schemas/3.2.0-rc.3/media-buy/get-reporting-status-request.json) -**Response schema:** [`get-reporting-status-response.json`](https://adcontextprotocol.org/schemas/3.2.0-rc.2/media-buy/get-reporting-status-response.json) +**Response schema:** [`get-reporting-status-response.json`](https://adcontextprotocol.org/schemas/3.2.0-rc.3/media-buy/get-reporting-status-response.json) **What landed when.** RC.0 supports the `summary`, `periods`, and `revision` @@ -29,14 +31,11 @@ pagination. RC.1 adds incremental `changes_after` repair and its checkpoint, post-official `adjustments[]` and `adjustment_receipts[]`, and their correction/reconciliation semantics. `3.2.0-rc.2` adds `consumer_statuses[]` for sellers advertising `consumer_status_task` and includes those immutable records -in flat pagination and `changes_after` checkpoints. Do not infer a later -tier's additions from an earlier baseline. - -Not in any published bundle yet — these ship in the next prerelease: +in flat pagination and `changes_after` checkpoints. `3.2.0-rc.3` adds `obligation_counts.consumer_status_pending`, issue `opened_at` / `issue_state` / `external_ref`, and the `consumer_mismatch_escalation_seconds` and -`operations_contact` capability fields. Validate those against the development -bundle served from `/schemas/latest/` rather than the rc.2 pin above. +`operations_contact` capability fields. Do not infer a later tier's additions +from an earlier baseline. ## Views diff --git a/docs/media-buy/task-reference/sync_reporting_status.mdx b/docs/media-buy/task-reference/sync_reporting_status.mdx index a58bfd34aca..bc885cab9eb 100644 --- a/docs/media-buy/task-reference/sync_reporting_status.mdx +++ b/docs/media-buy/task-reference/sync_reporting_status.mdx @@ -6,10 +6,11 @@ description: "Tell a seller whether expected reporting was received, omitted, mi `sync_reporting_status` is an additive, opt-in Reliable Reporting extension -published in `3.2.0-rc.2`. RC.1 implementations do not expose it. Sellers that -implement it advertise `consumer_status_task`; the active breaking-change -notice makes it required Core only in the next eligible minor after October 24, -2026. +published in `3.2.0-rc.2` and hardened in `3.2.0-rc.3`. RC.1 implementations do +not expose it. Sellers that implement it advertise `consumer_status_task`; the +task stays opt-in until the active breaking-change notice window closes on +October 24, 2026, and becomes required Core only in the next eligible minor +after that date. `sync_reporting_status` closes the operational loop between what a seller says @@ -24,20 +25,20 @@ observations about a user. It also is not a Reconciled Billing receipt: `received` proves only that the buyer consumed the exact Core revision binding, not that Managed materialization evidence or billing control totals matched. -{/* The stable /schemas/v3 alias does not expose this RC.2-only task yet. */} -**Request schema:** [`sync-reporting-status-request.json`](https://adcontextprotocol.org/schemas/3.2.0-rc.2/media-buy/sync-reporting-status-request.json) +{/* The stable /schemas/v3 alias does not expose this prerelease-only task yet. */} +**Request schema:** [`sync-reporting-status-request.json`](https://adcontextprotocol.org/schemas/3.2.0-rc.3/media-buy/sync-reporting-status-request.json) -{/* The stable /schemas/v3 alias does not expose this RC.2-only task yet. */} -**Response schema:** [`sync-reporting-status-response.json`](https://adcontextprotocol.org/schemas/3.2.0-rc.2/media-buy/sync-reporting-status-response.json) +{/* The stable /schemas/v3 alias does not expose this prerelease-only task yet. */} +**Response schema:** [`sync-reporting-status-response.json`](https://adcontextprotocol.org/schemas/3.2.0-rc.3/media-buy/sync-reporting-status-response.json) -`3.2.0-rc.2` publishes the task itself, not the hardening described on this -page. The `content_mismatch` status and its `mismatch_code`, the -stale-`received` grace window, `obligation_counts.consumer_status_pending`, +`3.2.0-rc.2` publishes the task itself; `3.2.0-rc.3` publishes the hardening +described on this page — the `content_mismatch` status and its `mismatch_code`, +the stale-`received` grace window, `obligation_counts.consumer_status_pending`, issue `opened_at` / `issue_state` / `external_ref`, and the -`operations_contact` / `consumer_mismatch_escalation_seconds` capability fields -land in the next prerelease. Until then, validate those against the development -bundle served from `/schemas/latest/` rather than the rc.2 pin above. +`operations_contact` / `consumer_mismatch_escalation_seconds` capability +fields. Validate against the `3.2.0-rc.3` pin above; an RC.2 seller exposes the +task without those additions. ## Status values diff --git a/docs/reference/3-2-beta.mdx b/docs/reference/3-2-beta.mdx index 065f1208946..9ceb370cc41 100644 --- a/docs/reference/3-2-beta.mdx +++ b/docs/reference/3-2-beta.mdx @@ -15,14 +15,15 @@ change 3.2 surfaces before GA. The 3.2 prerelease cycle started with a protocol-first beta checkpoint. -RC.1 is the current signed protocol checkpoint. TypeScript SDK -`14.0.0-rc.35`, Python SDK `8.0.0b14`, and Go SDK `adcp/v3@v3.2.1` embed it -exactly: +RC.3 is the current signed protocol checkpoint. No SDK embeds it yet: +TypeScript SDK `14.0.0-rc.36` embeds `3.2.0-rc.2`, and Python SDK `8.0.0b14` +and Go SDK `adcp/v3@v3.2.1` still embed `3.2.0-rc.1`: -**RC.1 now has matched SDKs.** Use its signed bundle for raw-wire validation -and code generation, or use one of the exact package pairings below for -SDK-backed integration testing. Do not infer compatibility from a floating +**RC.3 has no matched SDK yet.** Use its signed bundle for raw-wire validation +and code generation. The exact package pairings below are each one or two +checkpoints behind RC.3, so an SDK-backed run is evidence for the checkpoint +that SDK embeds — not for RC.3. Do not infer compatibility from a floating package tag or from an SDK generated against an earlier checkpoint. @@ -41,45 +42,57 @@ package tag or from an SDK generated against an earlier checkpoint. | `3.2.0-beta.10` | Previous protocol checkpoint for managed reporting delivery, authenticated principals, audio VAST and DOOH support, programmed channel collections, committed collection selection, and expanded conformance coverage | Pinned adopters comparing beta.10 and beta.11 behavior | | `3.2.0-beta.11` | Previous protocol checkpoint | Pinned adopters comparing beta.11 and RC.0 behavior | | `3.2.0-rc.0` | Previous protocol checkpoint | SDK-backed integration testing with an exact RC.0 package pairing | -| `3.2.0-rc.1` | Current protocol checkpoint for Reliable Reporting 1.0 and reporting-semantics hardening | Raw-wire, signed-artifact, code-generation, and SDK-backed integration testing | -| Current SDK wave | `@adcp/sdk@14.0.0-rc.35`, Python `adcp==8.0.0b14`, and Go `adcp/v3@v3.2.1` embed `3.2.0-rc.1` | Exact RC.1 SDK-backed testing; higher-level Python and Go coverage remains role-dependent | - -Earlier betas and RC.0 remain useful as pinned implementation checkpoints. -TypeScript SDK beta.31 and Python SDK beta.13 are historical RC.0 pairings; -TypeScript SDK beta.29 and Python SDK beta.12 pair with beta.11. Do not combine -a newer wire pin with an SDK generated from an older bundle unless the SDK -maintainer documents forward compatibility. +| `3.2.0-rc.1` | Previous protocol checkpoint for Reliable Reporting 1.0 and reporting-semantics hardening | SDK-backed integration testing with an exact RC.1 package pairing: Python `adcp==8.0.0b14`, Go `adcp/v3@v3.2.1`, or the historical TypeScript `@adcp/sdk@14.0.0-rc.35` | +| `3.2.0-rc.2` | Previous protocol checkpoint for the opt-in Reliable Reporting `sync_reporting_status` consumer-status loop, buyer and orchestrator storyboards, and truncated-breakdown cursor pagination | SDK-backed integration testing with the exact RC.2 TypeScript package pairing | +| `3.2.0-rc.3` | Current protocol checkpoint for consumer-status hardening, MediaBuy-level frequency caps, and request-only targeting with `null`-clear semantics | Raw-wire, signed-artifact, and code-generation integration testing | +| Current SDK wave | `@adcp/sdk@14.0.0-rc.36` embeds `3.2.0-rc.2`; Python `adcp==8.0.0b14` and Go `adcp/v3@v3.2.1` embed `3.2.0-rc.1` | Exact RC.2 (TypeScript) or RC.1 (Python, Go) SDK-backed testing; higher-level Python and Go coverage remains role-dependent. No row names RC.3 | + +Earlier betas, RC.0, and RC.1 remain useful as pinned implementation +checkpoints. TypeScript SDK RC.35 is a historical RC.1 pairing; TypeScript SDK +beta.31 and Python SDK beta.13 are historical RC.0 pairings; TypeScript SDK +beta.29 and Python SDK beta.12 pair with beta.11. Do not combine a newer wire +pin with an SDK generated from an older bundle unless the SDK maintainer +documents forward compatibility. `@adcp/sdk@14.0.0-rc.36` validates requests +and responses against its embedded `3.2.0-rc.2` bundle; its wire-only +`wireAdcpVersion` override can carry a different pin, but a run under that +override is not evidence for the pinned checkpoint. ## Know which version string to use The artifact version, wire pin, and documentation selector are related but not interchangeable: -| Surface | beta.0 | beta.1 | beta.2 | beta.3 | beta.4 | beta.5 | beta.6 | beta.7 | beta.8 | beta.9 | beta.10 | beta.11 | RC.0 | RC.1 | -|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---| -| Protocol artifact | `3.2.0-beta.0` | `3.2.0-beta.1` | `3.2.0-beta.2` | `3.2.0-beta.3` | `3.2.0-beta.4` | `3.2.0-beta.5` | `3.2.0-beta.6` | `3.2.0-beta.7` | `3.2.0-beta.8` | `3.2.0-beta.9` | `3.2.0-beta.10` | `3.2.0-beta.11` | `3.2.0-rc.0` | `3.2.0-rc.1` | -| Git tag | `v3.2.0-beta.0` | `v3.2.0-beta.1` | `v3.2.0-beta.2` | `v3.2.0-beta.3` | `v3.2.0-beta.4` | `v3.2.0-beta.5` | `v3.2.0-beta.6` | `v3.2.0-beta.7` | `v3.2.0-beta.8` | `v3.2.0-beta.9` | `v3.2.0-beta.10` | `v3.2.0-beta.11` | `v3.2.0-rc.0` | `v3.2.0-rc.1` | -| `adcp_version` wire pin | `"3.2-beta.0"` | `"3.2-beta.1"` | `"3.2-beta.2"` | `"3.2-beta.3"` | `"3.2-beta.4"` | `"3.2-beta.5"` | `"3.2-beta.6"` | `"3.2-beta.7"` | `"3.2-beta.8"` | `"3.2-beta.9"` | `"3.2-beta.10"` | `"3.2-beta.11"` | `"3.2-rc.0"` | `"3.2-rc.1"` | -| Documentation selector | `3.2-beta` | `3.2-beta` | `3.2-beta` | `3.2-beta` | `3.2-beta` | `3.2-beta` | `3.2-beta` | `3.2-beta` | `3.2-beta` | `3.2-beta` | `3.2-beta` | `3.2-beta` | `3.2-rc` | `3.2-rc` | +| Surface | beta.0 | beta.1 | beta.2 | beta.3 | beta.4 | beta.5 | beta.6 | beta.7 | beta.8 | beta.9 | beta.10 | beta.11 | RC.0 | RC.1 | RC.2 | RC.3 | +|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---| +| Protocol artifact | `3.2.0-beta.0` | `3.2.0-beta.1` | `3.2.0-beta.2` | `3.2.0-beta.3` | `3.2.0-beta.4` | `3.2.0-beta.5` | `3.2.0-beta.6` | `3.2.0-beta.7` | `3.2.0-beta.8` | `3.2.0-beta.9` | `3.2.0-beta.10` | `3.2.0-beta.11` | `3.2.0-rc.0` | `3.2.0-rc.1` | `3.2.0-rc.2` | `3.2.0-rc.3` | +| Git tag | `v3.2.0-beta.0` | `v3.2.0-beta.1` | `v3.2.0-beta.2` | `v3.2.0-beta.3` | `v3.2.0-beta.4` | `v3.2.0-beta.5` | `v3.2.0-beta.6` | `v3.2.0-beta.7` | `v3.2.0-beta.8` | `v3.2.0-beta.9` | `v3.2.0-beta.10` | `v3.2.0-beta.11` | `v3.2.0-rc.0` | `v3.2.0-rc.1` | `v3.2.0-rc.2` | `v3.2.0-rc.3` | +| `adcp_version` wire pin | `"3.2-beta.0"` | `"3.2-beta.1"` | `"3.2-beta.2"` | `"3.2-beta.3"` | `"3.2-beta.4"` | `"3.2-beta.5"` | `"3.2-beta.6"` | `"3.2-beta.7"` | `"3.2-beta.8"` | `"3.2-beta.9"` | `"3.2-beta.10"` | `"3.2-beta.11"` | `"3.2-rc.0"` | `"3.2-rc.1"` | `"3.2-rc.2"` | `"3.2-rc.3"` | +| Documentation selector | `3.2-beta` | `3.2-beta` | `3.2-beta` | `3.2-beta` | `3.2-beta` | `3.2-beta` | `3.2-beta` | `3.2-beta` | `3.2-beta` | `3.2-beta` | `3.2-beta` | `3.2-beta` | `3.2-rc` | `3.2-rc` | `3.2-rc` | `3.2-rc` | Only send a prerelease wire pin to a peer that advertises that exact value in `get_adcp_capabilities.adcp.supported_versions`. Prerelease pins are exact: a -buyer pinned to `"3.2-rc.1"` must not silently negotiate to another prerelease, +buyer pinned to `"3.2-rc.3"` must not silently negotiate to another prerelease, and a stable `"3.2"` pin must not silently negotiate to a prerelease. ## Use matched SDK prereleases -The TypeScript SDK has exact RC.1 support. The npm `latest` tag remains on SDK +The TypeScript SDK has exact RC.2 support. The npm `latest` tag remains on SDK 13, so opt into the release-candidate channel explicitly: ```bash -npm install @adcp/sdk@14.0.0-rc.35 +npm install @adcp/sdk@14.0.0-rc.36 ``` SDK 14 includes typed caller and server support for the compact media-buy -lifecycle, the RC.1 schemas and compliance assets, version-aware request +lifecycle, the RC.2 schemas and compliance assets, version-aware request signing, governance plan-adjustment reporting, and agent notification -configuration. It retains 3.0 and 3.1 adaptation for mixed-version testing. +configuration. RC.36 also adds `@adcp/sdk/reporting/source` (the seller source +executor contract, an inline executor, and a conformance harness) and +`@adcp/sdk/reporting/ledger` (a seller ledger with a Postgres store, producer, +`get_reporting_status` handler, `sync_reporting_status` ingest, and a lifecycle +harness). It retains 3.0 and 3.1 adaptation for mixed-version testing. Its +default wire release is `3.2-rc.2`, and `3.2-rc.2` is the only 3.2 checkpoint +its `adcpVersion` schema selection accepts. See [Choose your SDK](/docs/building/by-layer/L4/choose-your-sdk) for the support matrix and install guidance. @@ -92,19 +105,20 @@ registration, response builders, signing, and transport/server building blocks remain role-dependent; consult the SDK matrix before treating schema parity as complete L1–L3 coverage. -## Use the RC.1 artifact directly +## Use the RC.3 artifact directly -Download the signed RC.1 protocol bundle rather -than copying schemas from `main` or from the moving `/schemas/latest/` path: +RC.3 has no matched SDK, so the signed bundle is the only way to test it. +Download it rather than copying schemas from `main` or from the moving +`/schemas/latest/` path: ```bash -curl -fLO https://adcontextprotocol.org/protocol/3.2.0-rc.1.tgz -curl -fLO https://adcontextprotocol.org/protocol/3.2.0-rc.1.tgz.sha256 -shasum -a 256 -c 3.2.0-rc.1.tgz.sha256 -tar -xzf 3.2.0-rc.1.tgz +curl -fLO https://adcontextprotocol.org/protocol/3.2.0-rc.3.tgz +curl -fLO https://adcontextprotocol.org/protocol/3.2.0-rc.3.tgz.sha256 +shasum -a 256 -c 3.2.0-rc.3.tgz.sha256 +tar -xzf 3.2.0-rc.3.tgz ``` -The extracted `adcp-3.2.0-rc.1/` directory contains: +The extracted `adcp-3.2.0-rc.3/` directory contains: - `manifest.json` — release version, bundle contents, skills, and file count; - `schemas/` — source-shaped and bundled request/response schemas, including @@ -122,13 +136,13 @@ Useful direct-artifact tests are: 1. Generate or refresh types from the pinned bundled schemas. 2. Validate representative requests and responses for the roles you implement. 3. Compare your advertised tools with `schemas/manifest.json`. -4. Exercise raw MCP or A2A calls with `adcp_version: "3.2-rc.1"` against a +4. Exercise raw MCP or A2A calls with `adcp_version: "3.2-rc.3"` against a staging peer that advertises the same pin. 5. Run the compliance assets with a source-compatible runner if you maintain one. Do not weaken production authentication to accommodate a prerelease runner. -**No 3.2 verification badge is currently issued for a prerelease.** Treat RC.1 as an +**No 3.2 verification badge is currently issued for a prerelease.** Treat RC.3 as an implementation input, not a certification target. @@ -143,8 +157,9 @@ An SDK support claim must name all of the following: - install command and one tested validation command. The SDK compatibility matrix lives in [Choose your SDK](/docs/building/by-layer/L4/choose-your-sdk). -All three rows name exact RC.1 support with different higher-layer coverage. -None implies support for another checkpoint. Treat generated 3.2 types and +Its TypeScript row names exact RC.2 support and its Python and Go rows name +exact RC.1 support, each with different higher-layer coverage. None implies +support for another checkpoint, and none currently names RC.3. Treat generated 3.2 types and validators in every other SDK as unavailable until its row names an exact package and protocol checkpoint. Raw JSON calls may still be possible, but they are not equivalent to SDK support. @@ -155,15 +170,16 @@ SDK implementation bugs in the SDK's own repository. Accepted protocol fixes receive a changeset and ship in a later prerelease; published prereleases are never rebuilt in place. -## Current RC.1 checkpoint +## Current RC.3 checkpoint -Protocol beta.1 through beta.11, RC.0, and RC.1 are published. TypeScript SDK -RC.32, Python SDK beta.14, and Go SDK v3.2.1 embed RC.1. Before -treating a test result as RC.1 protocol evidence, confirm that: +Protocol beta.1 through beta.11 and RC.0 through RC.3 are published. +TypeScript SDK RC.36 embeds RC.2; Python SDK beta.14 and Go SDK v3.2.1 embed +RC.1. Before treating a test result as RC.3 protocol evidence, confirm that: -- the test uses the signed RC.1 artifact directly or an exact RC.1 SDK pairing; -- both peers advertise `"3.2-rc.1"` before calls use that pin; -- the integration scenarios below run against RC.1 and retain the exact +- the test uses the signed RC.3 artifact directly, on the raw wire or through + types generated from it — no published SDK pairing is RC.3 evidence; +- both peers advertise `"3.2-rc.3"` before calls use that pin; +- the integration scenarios below run against RC.3 and retain the exact bundle version; - copy/paste installation and validation commands have been executed as published; @@ -250,8 +266,18 @@ release as working groups resolve scope and interoperability risk. training agent implements it. Capability declarations remain authoritative. - Experimental surfaces retain their [experimental-status contract](/docs/reference/experimental-status). A 3.2 prerelease does not graduate them to stable. -- The `3.2-rc` documentation selector moves forward; `3.2-beta` remains frozen - at beta.11. Pinned semver artifacts and documentation snapshots remain immutable. +- The `3.2-rc` documentation selector moves forward with each release-docs + snapshot, so it can trail the newest signed bundle by one checkpoint; + `3.2-beta` remains frozen at beta.11. Pinned semver artifacts and + documentation snapshots remain immutable. +- RC.3's artifacts are signed and served, but its Git tag and GitHub Release + are pending a release-workflow re-run. RC.2 is the latest tagged release. +- Superseded 3.x beta artifacts were retired from the repository and runtime + image on 2026-09-14. Only the `3.2.0-beta.11` schema bundle stays hosted, to + back the frozen `3.2-beta` documentation selector. Previously published beta + URLs continue to resolve from the artifact CDN on a best-effort basis only; + move pinned beta adopters to `3.2.0-rc.3`. Release-candidate and stable + artifacts are never retired. - Stable schema aliases continue to resolve to stable releases during prerelease. Use pinned prerelease URLs when validating prerelease behavior. @@ -266,7 +292,7 @@ Include this information in a prerelease issue: - schema path or JSON Pointer involved; - expected and actual behavior; - minimal redacted payload and validation error; -- whether the problem blocks RC.1 interoperability or only an older SDK-backed +- whether the problem blocks RC.3 interoperability or only an older SDK-backed checkpoint. Never include credentials, signed URLs, bearer tokens, private keys, or live diff --git a/docs/reference/migration/3-1-to-3-2.mdx b/docs/reference/migration/3-1-to-3-2.mdx index 0ea9ca17896..d39b8518eea 100644 --- a/docs/reference/migration/3-1-to-3-2.mdx +++ b/docs/reference/migration/3-1-to-3-2.mdx @@ -8,11 +8,12 @@ description: "Role-based migration checklist for adopting the AdCP 3.2 release c # Migrating from 3.1 to 3.2 -**3.2 is in release candidate.** RC.1 is the current signed protocol -checkpoint. TypeScript `@adcp/sdk@14.0.0-rc.35`, Python `adcp==8.0.0b14`, and -Go `adcp/v3@v3.2.1` embed it exactly; Python and Go higher-level coverage -remains role-dependent. Keep production traffic pinned to `"3.1"` -while validating an exact 3.2 checkpoint in staging. +**3.2 is in release candidate.** RC.3 is the current signed protocol +checkpoint, and no SDK embeds it yet: TypeScript `@adcp/sdk@14.0.0-rc.36` +embeds `3.2.0-rc.2`, while Python `adcp==8.0.0b14` and Go `adcp/v3@v3.2.1` +still embed `3.2.0-rc.1`; Python and Go higher-level coverage remains +role-dependent. Keep production traffic pinned to `"3.1"` while validating an +exact 3.2 checkpoint in staging. 3.2 is a minor release over 3.1. Existing integrations do not need to adopt the @@ -47,23 +48,23 @@ surfaces by hand. | Step | Who | Action | |---|---|---| | 1 | Everyone | Keep production on `"3.1"`; choose an exact 3.2 prerelease artifact for staging. | -| 2 | SDK and codegen maintainers | Generate from the signed `3.2.0-rc.1` protocol tarball, not `main` or `/schemas/latest/`. | +| 2 | SDK and codegen maintainers | Generate from the signed `3.2.0-rc.3` protocol tarball, not `main` or `/schemas/latest/`. | | 3 | Sellers and agents | Advertise the exact prerelease in `adcp.supported_versions` and echo the release actually served. | -| 4 | Buyers | Send `adcp_version: "3.2-rc.1"` only after exact capability discovery; never silently move between prerelease pins. | +| 4 | Buyers | Send `adcp_version: "3.2-rc.3"` — or whichever exact prerelease the peer advertises — only after exact capability discovery; never silently move between prerelease pins. | | 5 | Media-buy implementations | Move create/update success handling completely to `media_buy_status`. | | 6 | Signing implementations | Require `content-digest` coverage and migrate request `Signature` and `Content-Digest` binary values to RFC 8941 padded Base64. | | 7 | Creative implementations | Adopt canonical format capability/product discovery and isolate legacy projection at compatibility boundaries. | -| 8 | Compliance operators | Test RC.1 from its signed assets or an exact SDK pairing: `@adcp/sdk@14.0.0-rc.35`, Python `adcp==8.0.0b14`, or Go `adcp/v3@v3.2.1`. Retain the exact package and wire versions. | +| 8 | Compliance operators | Test RC.3 from its signed assets; no SDK pairing covers RC.3 yet. `@adcp/sdk@14.0.0-rc.36` tests RC.2, and Python `adcp==8.0.0b14` or Go `adcp/v3@v3.2.1` test RC.1. Retain the exact package and wire versions. | | 9 | Delivery-reporting implementations | Emit and consume currency at media-buy or package grain, move qualified outcomes to `by_package[].metric_values`, and stop producing new `aggregated_totals`. | ## Required to claim 3.2 behavior ### Serve and echo the exact release -During prerelease, version matching is exact. A seller serving RC.1 advertises -`"3.2-rc.1"`. Do not advertise stable `"3.2"` before GA, silently negotiate -between prerelease pins, or treat a major-only declaration as evidence of 3.2 -support. +During prerelease, version matching is exact. A seller serving RC.3 advertises +`"3.2-rc.3"`; a seller still on RC.1 advertises `"3.2-rc.1"`. Do not advertise +stable `"3.2"` before GA, silently negotiate between prerelease pins, or treat +a major-only declaration as evidence of 3.2 support. The 3.2 compliance posture makes missing `supported_versions` or a missing response echo a blocking failure for a 3.2 claim, even though the fields remain @@ -244,7 +245,7 @@ See [Cross-role governance enforcement](/docs/reference/migration/cross-role-gov | Creative agent | Canonical supported-format capabilities, operation selection, and explicit compatibility handling for legacy named formats. | | Signals or measurement agent | Exact prerelease pin and only the attestation, targeting, or feedback capabilities actually implemented. | | Governance provider/service | Exact prerelease pin, `governance.campaign` experimental declaration, and the complete cross-role authorization migration. | -| SDK maintainer | Signed RC.1 bundle ingestion, generated-type/validator tests, exact support matrix entry, and protocol feedback destined for the next prerelease. | +| SDK maintainer | Signed RC.3 bundle ingestion, generated-type/validator tests, exact support matrix entry, and protocol feedback destined for the next prerelease. | | Compliance operator | Matching assets, SDK package, and wire pin end to end; no 3.2 badge from a prerelease checkpoint. | ## Rollback diff --git a/docs/reference/migration/index.mdx b/docs/reference/migration/index.mdx index 28e484b987d..c977f8809a1 100644 --- a/docs/reference/migration/index.mdx +++ b/docs/reference/migration/index.mdx @@ -14,7 +14,7 @@ This page covers every breaking change when upgrading from AdCP 2.x to 3.0, with -**Preparing for 3.2?** Start with the [3.1 to 3.2 migration guide](/docs/reference/migration/3-1-to-3-2). For the signed RC.1 artifact, exact wire pins, matched SDKs, and feedback guidance, read the [3.2 prerelease program](/docs/reference/3-2-beta). +**Preparing for 3.2?** Start with the [3.1 to 3.2 migration guide](/docs/reference/migration/3-1-to-3-2). For the signed RC.3 artifact, exact wire pins, the SDK checkpoint pairings, and feedback guidance, read the [3.2 prerelease program](/docs/reference/3-2-beta). diff --git a/docs/reference/migration/reliable-reporting-status-loop.mdx b/docs/reference/migration/reliable-reporting-status-loop.mdx index 5ae2d0d5a57..ae126e551cf 100644 --- a/docs/reference/migration/reliable-reporting-status-loop.mdx +++ b/docs/reference/migration/reliable-reporting-status-loop.mdx @@ -8,8 +8,9 @@ description: "Breaking-change notice and migration guide for sync_reporting_stat **Experimental breaking-change notice published September 12, 2026.** Under AdCP's six-week experimental-surface notice policy, the Core requirement described here must not appear in an immutable release before October 24, -2026. `3.2.0-rc.2` publishes the task as opt-in; making it *required* is what -the notice window governs. Published `3.2.0-rc.1` remains unchanged. +2026. `3.2.0-rc.2` publishes the task as opt-in and `3.2.0-rc.3` hardens it; +making it *required* is what the notice window governs. Published +`3.2.0-rc.1` remains unchanged. Reliable Reporting RC.1 lets a seller publish its obligation/revision state and @@ -19,9 +20,9 @@ or unreadable. A seller can therefore project `healthy` while the buyer's webhook, exact revision read, or destination access is failing. `3.2.0-rc.2` closes that loop additively with opt-in -[`sync_reporting_status`](/docs/media-buy/task-reference/sync_reporting_status). -A seller advertises `consumer_status_task` only when the task and readback are -implemented. The requirement itself lands only in the next eligible minor +[`sync_reporting_status`](/docs/media-buy/task-reference/sync_reporting_status), +and `3.2.0-rc.3` hardens it. A seller advertises `consumer_status_task` only +when the task and readback are implemented. The requirement itself lands only in the next eligible minor after the notice window. Both changes remain inside the experimental `media_buy.reporting_delivery` surface. @@ -43,8 +44,8 @@ Before (`3.2.0-rc.1`): } ``` -Current opt-in form, and required form in the next eligible minor after the -notice window: +Current opt-in form (`3.2.0-rc.3`), and required form in the next eligible +minor after the notice window: ```json { @@ -183,8 +184,9 @@ billing-feed constraints. Tracked in `reporting_status_id` are now required on that issue code. The code itself shipped in RC.1's `reporting-status-issue.json` enum, so an RC.1 seller that already emits it must add `opened_at` — fixed at first emission, never advanced -on re-emission — before validating against current source. No other issue code -is affected. +on re-emission — before validating against +[`3.2.0-rc.3`](https://adcontextprotocol.org/schemas/3.2.0-rc.3/core/reporting-status-issue.json). +No other issue code is affected. ## Verifying the loop diff --git a/docs/reference/release-notes.mdx b/docs/reference/release-notes.mdx index 760a9752118..55d3f97f870 100644 --- a/docs/reference/release-notes.mdx +++ b/docs/reference/release-notes.mdx @@ -11,21 +11,21 @@ Authoritative version-by-version release record for AdCP, with cumulative change ## Version 3.2.0 -**Status:** Release-candidate cycle — minor release targeting the 3.2.0 milestone. RC.1 is the current signed protocol checkpoint. It completes the experimental Reliable Reporting 1.0 contract and hardens delivery, reach, and vendor-metric semantics. TypeScript `@adcp/sdk@14.0.0-rc.35`, Python `adcp==8.0.0b14`, and Go `adcp/v3@v3.2.1` embed RC.1 exactly; Python and Go higher-level coverage remains role-dependent. Stable wire shapes remain backward compatible except for the ratified `media_buy_status` cleanup and request-signature encoding migration described below; explicitly experimental surfaces may carry noticed changes under the [experimental-status contract](/docs/reference/experimental-status). +**Status:** Release-candidate cycle — minor release targeting the 3.2.0 milestone. RC.3 is the current signed protocol checkpoint. It hardens the experimental Reliable Reporting consumer-status loop, adds a shared MediaBuy-level frequency cap with structured product frequency-cap constraints, and adds request-only targeting inputs with `null`-clear semantics. No SDK embeds RC.3 yet: TypeScript `@adcp/sdk@14.0.0-rc.36` embeds RC.2, while Python `adcp==8.0.0b14` and Go `adcp/v3@v3.2.1` still embed RC.1; Python and Go higher-level coverage remains role-dependent. Stable wire shapes remain backward compatible except for the ratified `media_buy_status` cleanup and request-signature encoding migration described below; explicitly experimental surfaces may carry noticed changes under the [experimental-status contract](/docs/reference/experimental-status). **Reliable Reporting breaking-change notice — published September 12, 2026.** -Current source adds opt-in `sync_reporting_status` so a buyer can report missing, +RC.2 publishes opt-in `sync_reporting_status` so a buyer can report missing, unreadable, contradictory, or exactly received reporting back to the seller; the seller can then detect when a received revision becomes stale after restatement. -The loop is hardened for RC.2: a stale `received` gets a bounded re-read grace +RC.3 hardens the loop: a stale `received` gets a bounded re-read grace window before it escalates, buyers owe a status by `expected_at + automated_recovery_window_seconds` (counted in `obligation_counts.consumer_status_pending`, never in health), issues carry `opened_at` / `issue_state` / `external_ref` with an optional `consumer_mismatch_escalation_seconds` and `operations_contact`, and `content_mismatch` names contract-fact disagreements through a closed -`mismatch_code`. `reporting-delivery-config.json` also reserves +`mismatch_code`. RC.3's `reporting-delivery-config.json` also reserves `authoritative_party`; sellers MUST reject `consumer` with `UNSUPPORTED_FEATURE` until a later minor defines the buyer-deposited revision task ([#7440](https://github.com/adcontextprotocol/adcp/issues/7440)). Sellers advertise @@ -51,7 +51,9 @@ See the [migration guide](/docs/reference/migration/reliable-reporting-status-lo | `3.2.0-beta.10` | Add managed reporting delivery, authenticated principals, audio VAST and DOOH support, programmed channel collections, committed collection selection, and expanded conformance coverage | Previous protocol checkpoint with exact TypeScript support in `@adcp/sdk@14.0.0-beta.28` and exact Python schema/type support in `adcp==8.0.0b11` | | `3.2.0-beta.11` | Add `get_principal` to the MCP media-buy role profile and align the public training agent with the latest beta bundle | Previous protocol checkpoint with exact TypeScript support in `@adcp/sdk@14.0.0-beta.29` and exact Python schema/type support in `adcp==8.0.0b12` | | `3.2.0-rc.0` | Publish the first 3.2 release candidate after beta integration fixes and expand reporting lifecycle conformance | Previous checkpoint with exact TypeScript support in `@adcp/sdk@14.0.0-beta.31` and exact Python schema/type support in `adcp==8.0.0b13` | -| `3.2.0-rc.1` | Complete the experimental Reliable Reporting 1.0 contract and harden delivery currency, aggregate reach, vendor-metric identity, and integration behavior | Current signed protocol checkpoint with exact TypeScript, Python, and Go SDK pairings | +| `3.2.0-rc.1` | Complete the experimental Reliable Reporting 1.0 contract and harden delivery currency, aggregate reach, vendor-metric identity, and integration behavior | Previous checkpoint with exact Python support in `adcp==8.0.0b14` and exact Go support in `adcp/v3@v3.2.1` | +| `3.2.0-rc.2` | Add the opt-in experimental Reliable Reporting `sync_reporting_status` consumer-status loop, buyer and orchestrator storyboards with a buyer-orchestrator compliance track, cursor pagination for truncated `get_media_buy_delivery` breakdowns, sub-country product coverage filters, and restored `canonical-forecast-point` constraints | Previous checkpoint with exact TypeScript support in `@adcp/sdk@14.0.0-rc.36`, which also adds the `@adcp/sdk/reporting/source` and `@adcp/sdk/reporting/ledger` entry points | +| `3.2.0-rc.3` | Harden the consumer-status loop (`content_mismatch` and `mismatch_code`, a bounded grace window for a stale `received`, the buyer posting deadline and `obligation_counts.consumer_status_pending`, issue lifecycle fields, `operations_contact`, and the reserved `authoritative_party`), add a shared MediaBuy-level `frequency_cap` with structured product frequency-cap constraints, add request-only targeting with `null`-clear semantics, and retire superseded beta artifacts | Current signed protocol checkpoint. No SDK embeds it yet; test it from the signed bundle | Each prerelease is immutable. The `3.2-rc` documentation selector advances to the latest release candidate; the `3.2-beta` selector remains frozen at beta.11. Pinned protocol, schema, compliance, and documentation artifacts remain available. See the [3.2 prerelease program](/docs/reference/3-2-beta). @@ -59,12 +61,13 @@ Each prerelease is immutable. The `3.2-rc` documentation selector advances to th - **Media buying:** compact listing, immutable proposal negotiation, direct purchase, proposal acceptance, operational control, seller-optimized budgets and bidding, atomic total-budget changes, revenue-share pricing, creative rotation, warnings, and durable indicators. - **Identity and connections:** an experimental authenticated-principal layer for caller-scoped webhooks, reusable reporting destinations, asynchronous capability declarations, optimistic replacement, and `principal.changed` repair. -- **Targeting and audiences:** targeting-aware discovery, portable demographic predicates, named places, value-aware regions, browser families, property exclusions, audience evidence, and exact package readback. +- **Targeting and audiences:** targeting-aware discovery, portable demographic predicates, named places, value-aware regions, browser families, property exclusions, audience evidence, exact package readback, and request-only targeting inputs where each dimension distinguishes omission, a non-null replacement, and an explicit `null` that clears it. +- **Frequency management:** a shared MediaBuy-level `frequency_cap` counted once across every package, advertised through `media_buy.aggregate_frequency_capping` and product `media_buy_support`, plus structured product frequency-cap constraints on `overlay_support.frequency_cap_support` and the `update_media_buy_frequency_cap` action. - **Inventory identity:** first-class programmed channel collections, including FAST and virtual linear streams, with host-property carriage mapping and collection-scoped host attestation for owner-sold avails. - **Creative:** canonical capability discovery, image pixel density and rendition sets, localization, async preview opt-in, audio loudness, VAST 4.3 and validation levels, accessibility detail, and synthetic depiction provenance. - **Security and evidence:** required body binding for 3.2 request-signing profiles, OAuth discovery grading, portable attestations, rights and signal evidence, signed brand-response verification, and safer secured asset access. - **Operations and measurement:** capability/account change notifications, snapshot-and-log repair, demographic and spot delivery, metric accountability, deterministic filters, fixture resolution, and capability-selected runtime projections. -- **Reliable Reporting:** a separately discovered, versioned experimental three-tier contract for expected-period obligations, immutable official revisions, managed materializations, authenticated receipts, correction ledgers, and repairable status. RC.1 completes Reliable Reporting 1.0. +- **Reliable Reporting:** a separately discovered, versioned experimental three-tier contract for expected-period obligations, immutable official revisions, managed materializations, authenticated receipts, correction ledgers, and repairable status. RC.1 completes Reliable Reporting 1.0; RC.2 adds the opt-in two-sided `sync_reporting_status` consumer-status loop; RC.3 hardens that loop and reserves `authoritative_party` for a later minor. - **Experimental surfaces:** cross-role campaign governance revisions and Trusted Match authentication, routing, attribution, and creative-data cleanup under their existing experimental declarations. ### Adopter action @@ -75,8 +78,8 @@ Each prerelease is immutable. The `3.2-rc` documentation selector advances to th | A seller or service | Advertise and echo the exact prerelease served, emit canonical status/retry shapes, and declare only capabilities actually implemented. | | A signing implementation | Require `content-digest` coverage for every signed request body on a 3.2 signing endpoint. | | A creative implementation | Prefer canonical capability and product format discovery; isolate named-format conversion at compatibility boundaries. | -| An SDK maintainer | Generate from the current signed RC.1 tarball, publish an exact support statement, and route accepted protocol corrections into a later prerelease. | -| A compliance operator | Test RC.1 from its signed assets or an exact SDK pairing: `@adcp/sdk@14.0.0-rc.35`, Python `adcp==8.0.0b14`, or Go `adcp/v3@v3.2.1`. Retain exact package and wire versions and do not issue a 3.2 badge from a prerelease checkpoint. | +| An SDK maintainer | Generate from the current signed RC.3 tarball, publish an exact support statement, and route accepted protocol corrections into a later prerelease. | +| A compliance operator | Test RC.3 from its signed assets; no SDK pairing covers RC.3 yet. `@adcp/sdk@14.0.0-rc.36` tests RC.2, and Python `adcp==8.0.0b14` or Go `adcp/v3@v3.2.1` test RC.1. Retain exact package and wire versions and do not issue a 3.2 badge from a prerelease checkpoint. | ### Required 3.2 migrations diff --git a/docs/reference/versioning.mdx b/docs/reference/versioning.mdx index e5e5c8dbc50..940ac3ad526 100644 --- a/docs/reference/versioning.mdx +++ b/docs/reference/versioning.mdx @@ -250,12 +250,13 @@ The v2 sunset is the documented exception to this commitment: v2 predates this p |---------|--------| | **3.0** | April 2026 — GA release | | **3.1** | Late June 2026 | -| **3.2** | RC.1 published September 2026; GA targeted for late September 2026 | +| **3.2** | RC.3 published September 2026; GA targeted for late September 2026 | | **4.0** | Early 2027 — next major, accumulated breaking changes | -The 3.2 cycle began with a protocol-first beta before SDK convergence. RC.1 is -now the current signed protocol checkpoint. TypeScript SDK RC.32, Python SDK -beta.14, and Go SDK `adcp/v3@v3.2.1` embed it exactly. See the +The 3.2 cycle began with a protocol-first beta before SDK convergence. RC.3 is +now the current signed protocol checkpoint, and no SDK embeds it yet: +TypeScript SDK RC.36 embeds `3.2.0-rc.2`, while Python SDK beta.14 and Go SDK +`adcp/v3@v3.2.1` still embed `3.2.0-rc.1`. See the [3.2 prerelease program](/docs/reference/3-2-beta). Further 3.x releases are scheduled based on implementation feedback and working group priorities, with at least 8 weeks between stable releases. Planned scope for each release is tracked on the [GitHub milestones page](https://github.com/adcontextprotocol/adcp/milestones) — open issues on the `3.1.0` and `3.2.0` milestones reflect current candidate work, not fixed commitments. diff --git a/docs/reference/versions.mdx b/docs/reference/versions.mdx index 63fe0297b04..ba006e9561f 100644 --- a/docs/reference/versions.mdx +++ b/docs/reference/versions.mdx @@ -13,7 +13,7 @@ description: "Every published AdCP version, its status, and its end-of-life date | Status | Versions | Wire pin | What it means | |---|---|---|---| -| **Release candidate** | 3.2 (externally exposed candidate: `rc.3`; latest tagged release: `rc.2`) | `"3.2-rc.2"` | Development and staging only. RC.3 artifacts are signed and publicly reachable but have no Git tag or GitHub Release; RC.2 remains the latest official release. Use only exact pins advertised by the peer. Follow the [3.2 prerelease program](/docs/reference/3-2-beta). | +| **Release candidate** | 3.2 (current prerelease: `rc.3`; latest tagged release: `rc.2`) | `"3.2-rc.3"` | Development and staging only. RC.3 is the current signed protocol checkpoint: its artifacts are signed and served, and its Git tag and GitHub Release are pending a release-workflow re-run. No SDK embeds RC.3 yet — TypeScript SDK RC.36 embeds `3.2.0-rc.2`, and Python SDK beta.14 and Go SDK 3.2.1 still embed `3.2.0-rc.1`. Test RC.3 from its signed artifacts with raw-wire or code-generation workflows. Follow the [3.2 prerelease program](/docs/reference/3-2-beta). | | **Active** | 3.1 (current stable: 3.1.20) | `"3.1"` | Current production minor release. See [What's New in AdCP 3.1](/docs/reference/whats-new-in-3-1) for the feature set. | | **Maintained** | 3.0 (current stable: 3.0.26) | `"3.0"` | Supported previous minor for existing production integrations. Receives compatibility and security patches. | | **End of life** | 2.0.0, 2.1.0, 2.5.0–2.5.3 | — | No patches. Migrate to 3.0. See [v2 sunset](/docs/reference/v2-sunset). | @@ -45,9 +45,9 @@ Supported patches don't change the wire contract. Upgrading within 3.0.x is alwa | Version | Released | Notes | |---|---|---| -| 3.2.0-rc.3 | 2026-09-14 (artifact exposure) | Signed candidate artifacts were exposed through R2, but the Release workflow was cancelled and no Git tag or GitHub Release exists. Do not treat RC.3 as an official release; use `"3.2-rc.3"` only for explicit incident validation with peers that advertise it. | -| **3.2.0-rc.2** | 2026-09-13 | Latest tagged and GitHub-released signed protocol checkpoint. Adds the opt-in Reliable Reporting `sync_reporting_status` loop and other additive RC hardening. Use `"3.2-rc.2"` only with peers that explicitly advertise it; the current SDK wave still embeds `3.2.0-rc.1`. | -| 3.2.0-rc.1 | 2026-09-05 | Previous SDK-backed protocol checkpoint. Completes the experimental Reliable Reporting 1.0 contract and hardens delivery, reach, and vendor-metric semantics. TypeScript `@adcp/sdk@14.0.0-rc.35`, Python `adcp==8.0.0b14`, and Go `adcp/v3@v3.2.1` embed it exactly; use `"3.2-rc.1"` only with peers that explicitly advertise it. | +| **3.2.0-rc.3** | 2026-09-14 | Current protocol checkpoint: signed and served, with its Git tag and GitHub Release pending a release-workflow re-run. Hardens the experimental Reliable Reporting consumer-status loop (`content_mismatch` with a closed `mismatch_code`, a bounded grace window for a stale `received`, the buyer posting deadline and `obligation_counts.consumer_status_pending`, issue lifecycle fields, and the reserved `authoritative_party` value), adds a shared MediaBuy-level `frequency_cap` with structured product frequency-cap constraints, and adds request-only targeting inputs with `null`-clear semantics. No SDK embeds it yet; use `"3.2-rc.3"` only with peers that explicitly advertise it. | +| 3.2.0-rc.2 | 2026-09-13 | Previous protocol checkpoint, and the latest tagged and GitHub-released one. Adds the opt-in experimental Reliable Reporting `sync_reporting_status` consumer-status loop, buyer and orchestrator storyboards with a buyer-orchestrator compliance track, cursor pagination for truncated `get_media_buy_delivery` breakdowns, sub-country product coverage filters, and restored `canonical-forecast-point` constraints. TypeScript SDK RC.36 embeds it exactly. | +| 3.2.0-rc.1 | 2026-09-05 | Previous protocol checkpoint. Completes the experimental Reliable Reporting 1.0 contract and hardens delivery, reach, and vendor-metric semantics. Python `adcp==8.0.0b14` and Go `adcp/v3@v3.2.1` embed it exactly, and TypeScript `@adcp/sdk@14.0.0-rc.35` is its historical pairing. | | 3.2.0-rc.0 | 2026-09-03 | First 3.2 release candidate. TypeScript SDK beta.31 and Python SDK beta.13 embed it exactly; Go SDK 3.2.0 remains generated from beta.9. | | 3.2.0-beta.11 | 2026-09-03 | Previous protocol checkpoint. Adds `get_principal` to the MCP media-buy role profile alongside `sync_principal`, and aligns training-agent and compliance guidance with the beta.10 bundle. TypeScript SDK beta.29 and Python SDK beta.12 embed it exactly. | | 3.2.0-beta.10 | 2026-09-01 | Previous protocol checkpoint. Adds managed reporting delivery, authenticated principals, audio VAST and DOOH support, programmed channel collections, and committed collection selection. TypeScript SDK beta.28 and Python SDK beta.11 embed it. | @@ -60,7 +60,7 @@ Supported patches don't change the wire contract. Upgrading within 3.0.x is alwa | 3.2.0-beta.3 | 2026-08-19 | Integration checkpoint, superseded by beta.4 for new beta testing. | | 3.2.0-beta.2 | 2026-08-19 | Integration checkpoint, superseded by beta.3 for new beta testing. | | 3.2.0-beta.1 | 2026-08-19 | Integration-correction checkpoint, superseded by beta.2 for new beta testing. | -| 3.2.0-beta.0 | 2026-08-17 | Protocol-first beta input for SDK work. Retired from the repository and runtime image on 2026-09-14 together with the other 3.x betas except `3.2.0-beta.11` (frozen `3.2-beta` documentation selector), `3.2.0-beta.6` (training-agent retained checkpoint), and `3.1.0-beta.7` (TypeScript SDK side bundle); pinned adopters should move to `3.2.0-rc.2`. | +| 3.2.0-beta.0 | 2026-08-17 | Protocol-first beta input for SDK work. Retired from the repository and runtime image on 2026-09-14 together with the other 3.x betas except `3.2.0-beta.11` (frozen `3.2-beta` documentation selector), `3.2.0-beta.6` (training-agent retained checkpoint), and `3.1.0-beta.7` (TypeScript SDK side bundle); pinned adopters should move to `3.2.0-rc.3`. | | 3.1.0-rc.1 through 3.1.0-rc.15 | 2026-05-29 to 2026-06-16 | Superseded by 3.1.0 GA. These artifacts remain available for pinned prerelease adopters and release forensics. | | 3.0.0-beta.1 through rc.2 | 2026-01-26 to 2026-03-15 | Superseded. | | 3.0.0-rc.3 | 2026-04-01 | Superseded by GA. See [prerelease upgrade notes](/docs/reference/migration/prerelease-upgrades) if you adopted rc.3. | @@ -100,8 +100,8 @@ Targeted for early 2027. 3.x is mid-cycle — see the [planned releases table](/ | If you are… | Use | |---|---| | Building a new production integration today | **3.1**. Pin `"3.1"` on the wire. | -| Implementing or testing 3.2 without an SDK | Use the official signed **3.2 RC.2** artifacts and wire pin `"3.2-rc.2"` with raw-wire or code-generation workflows. RC.3 artifacts are externally reachable but not tagged or GitHub-released; use `"3.2-rc.3"` only for explicit incident validation with peers that advertise it. Follow the [prerelease program](/docs/reference/3-2-beta). | -| Running an SDK-backed 3.2 integration test | The current SDK wave (`@adcp/sdk@14.0.0-rc.35`, Python `adcp==8.0.0b14`, and Go `adcp/v3@v3.2.1`) still embeds RC.1 and requires `"3.2-rc.1"`; use raw-wire or regenerated clients for exact RC.2 testing. | +| Implementing or testing 3.2 without an SDK | Use the signed **3.2 RC.3** artifacts with raw-wire or code-generation workflows; RC.2 remains the latest tagged release if you need one. Follow the [prerelease program](/docs/reference/3-2-beta). | +| Running an SDK-backed 3.2 integration test | Pair the exact RC.2 wire pin `"3.2-rc.2"` with `@adcp/sdk@14.0.0-rc.36`, or the exact RC.1 wire pin `"3.2-rc.1"` with Python `adcp==8.0.0b14` or Go `adcp/v3@v3.2.1`. No SDK embeds RC.3 schemas or types yet — test RC.3 against its signed artifacts on the raw wire, or from types generated from them, until the RC.3 SDK wave ships. | | Running an existing 3.0 integration | Stay on **3.0** while you migrate, or move to **3.1** when your SDK and validation are ready. | | Running a 2.5.x integration | Upgrade now — out of support. Start with the [migration guide](/docs/reference/migration). | | Running a 2.0 or 2.1 integration | Upgrade now — out of support. | diff --git a/docs/reference/whats-new-in-3-2.mdx b/docs/reference/whats-new-in-3-2.mdx index ac18dfb0422..b3fcfce1c7a 100644 --- a/docs/reference/whats-new-in-3-2.mdx +++ b/docs/reference/whats-new-in-3-2.mdx @@ -8,18 +8,24 @@ description: "AdCP 3.2 turns a media-buy conversation into an explicit lifecycle # What's new in AdCP 3.2 -**3.2 is in release candidate.** RC.1 is the current signed protocol -checkpoint. TypeScript `@adcp/sdk@14.0.0-rc.35`, Python `adcp==8.0.0b14`, and -Go `adcp/v3@v3.2.1` embed it exactly; Python and Go higher-level coverage -remains role-dependent. Use these exact packages for RC.1 staging tests. See the +**3.2 is in release candidate.** RC.3 is the current signed protocol +checkpoint, and no SDK embeds it yet: TypeScript `@adcp/sdk@14.0.0-rc.36` +embeds RC.2, while Python `adcp==8.0.0b14` and Go `adcp/v3@v3.2.1` still embed +RC.1; Python and Go higher-level coverage remains role-dependent. Test RC.3 +from its signed bundle, and use these exact packages for staging tests against +the checkpoints they embed. See the [3.2 prerelease program](/docs/reference/3-2-beta). -**New in RC.1:** Reliable Reporting 1.0 becomes a named, version-discovered -experimental capability, with stronger delivery, reach, vendor-metric, and -reconciliation semantics. The public training seller and all three maintained -SDKs now expose the exact RC.1 checkpoint. +**New in RC.3:** the opt-in Reliable Reporting consumer-status loop published +in RC.2 is hardened — `content_mismatch` with a closed `mismatch_code`, a +bounded grace window for a `received` overtaken by a seller restatement, a +buyer posting deadline surfaced through +`obligation_counts.consumer_status_pending`, issue lifecycle fields, and a +reserved `authoritative_party`. RC.3 also adds a shared MediaBuy-level +`frequency_cap`, structured product frequency-cap constraints, and +request-only targeting inputs with `null`-clear semantics. AdCP 3.2 turns a media-buy conversation into a commercial lifecycle that @@ -49,7 +55,8 @@ tools after capability discovery. confirmation gates. No membership or setup is required. - Choose an SDK-backed RC.1 path or use the signed RC.1 bundle directly. + Use the signed RC.3 bundle directly, or take an SDK-backed path on the + checkpoint your SDK embeds. Add compact lifecycle tools incrementally while keeping 3.1 integrations @@ -196,8 +203,24 @@ RC.0 introduced the reporting-status baseline. RC.1 makes Reliable Reporting a named, version-discovered experimental capability and adds source-timezone schedules, checkpointed repair for missed or out-of-order events, immutable billing-purpose evidence, adjustment and receipt reconciliation, and -evidence-scoped reliability statistics. RC.1 has matched TypeScript, Python, -and Go SDK pairings. See +evidence-scoped reliability statistics. + +RC.2 publishes the opt-in `sync_reporting_status` consumer-status loop, so a +buyer's report of what it actually received sits beside the seller's +obligations in `get_reporting_status` as immutable, buyer-attributed history. +RC.3 hardens that loop: `content_mismatch` with a closed `mismatch_code` +names contract-fact disagreements — explicitly not measurement disputes — a +`received` overtaken by a seller restatement gets a bounded grace window +before it escalates, an unmet buyer posting deadline is counted in +`obligation_counts.consumer_status_pending` without ever changing seller +health, issues carry `opened_at` / `issue_state` / `external_ref` alongside +optional `consumer_mismatch_escalation_seconds` and `operations_contact`, and +`authoritative_party: "consumer"` is reserved for a later minor and MUST be +rejected with `UNSUPPORTED_FEATURE` today. The loop stays opt-in until the +notice window closes on October 24, 2026, and becomes required Core only in +the next eligible minor after that date. No SDK embeds RC.3 yet; +`@adcp/sdk@14.0.0-rc.36` adds `@adcp/sdk/reporting/source` and +`@adcp/sdk/reporting/ledger` against the RC.2 bundle. See [Implementing Reliable Reporting Core](/docs/media-buy/reporting-core-implementation-guide). ### A durable connection for authenticated principals @@ -260,7 +283,12 @@ exact package readback — including committed inventory selection: collections, the latter materializing concrete selectors even when the selection came from collection-list references. Products can also disclose per-package cardinality for country inclusion, country exclusion, and proximity targeting before a buyer -creates or updates a package. Daypart windows now default explicitly to each +creates or updates a package. On the request-only targeting and +product-purchase inputs for the compact and established create/update +surfaces, each targeting dimension distinguishes three cases: omission +(inherit or preserve), a non-null replacement, and an explicit `null` that +clears the dimension. Discovery, capability, accepted-commercial-term, and +readback schemas stay strict and non-null. Daypart windows now default explicitly to each inventory unit's seller-assigned local clock and can instead name one IANA timezone for a synchronized schedule; products declare the supported modes through `overlay_support.daypart_targets`. Products whose package frequency-cap support @@ -434,14 +462,14 @@ for the remaining runner and coverage gaps. | If you are… | Review before advertising 3.2 | |---|---| -| Any seller or service | Advertise `"3.2-rc.1"` only when serving that exact prerelease, echo it on responses, and keep 3.1 traffic on its negotiated contract. | +| Any seller or service | Advertise `"3.2-rc.3"` — or whichever exact prerelease you serve — only when serving that exact prerelease, echo it on responses, and keep 3.1 traffic on its negotiated contract. | | A buyer | Gate compact tools and optional targeting on capabilities; do not infer 3.2 support from a major-only declaration. | | A media-buy implementer | Use `media_buy_status` on create/update success payloads; root `status` is the task-envelope state. | -| A reporting implementer | Treat Reliable Reporting as a separately discovered, versioned experimental capability. Do not infer RC.1 fields from RC.0 or from legacy delivery reporting. | +| A reporting implementer | Treat Reliable Reporting as a separately discovered, versioned experimental capability. Do not infer RC.3 fields from an earlier checkpoint or from legacy delivery reporting, and advertise `consumer_status_task` only when the loop is implemented. | | A signing implementation | Require `content-digest` coverage for every signed body on a 3.2 signing endpoint. | | A creative implementation | Prefer canonical capability and product format discovery; retain legacy conversion only at a proven compatibility boundary. | -| An SDK maintainer | Generate from the signed RC.1 tarball, name the exact supported bundle, and feed accepted protocol corrections into the next prerelease. | -| A compliance operator | Test RC.1 from its signed assets or an exact SDK pairing: `@adcp/sdk@14.0.0-rc.35`, Python `adcp==8.0.0b14`, or Go `adcp/v3@v3.2.1`. Retain exact package and wire versions end to end, and do not issue a 3.2 badge from a prerelease. | +| An SDK maintainer | Generate from the signed RC.3 tarball, name the exact supported bundle, and feed accepted protocol corrections into the next prerelease. | +| A compliance operator | Test RC.3 from its signed assets; no SDK pairing covers RC.3 yet. `@adcp/sdk@14.0.0-rc.36` tests RC.2, and Python `adcp==8.0.0b14` or Go `adcp/v3@v3.2.1` test RC.1. Retain exact package and wire versions end to end, and do not issue a 3.2 badge from a prerelease. | ## Start here diff --git a/server/public/index.html b/server/public/index.html index 5b868dd6bc5..60694d60a68 100644 --- a/server/public/index.html +++ b/server/public/index.html @@ -34,11 +34,11 @@ From 3946abccf41cb049ef238f1a7db5e3a05d6d6606 Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Mon, 14 Sep 2026 16:10:20 +0000 Subject: [PATCH 4/7] docs(learning): note the CLI wire-pin passthrough at the buyer-track fence The command pins 3.2-rc.1 for the training seller while running @adcp/sdk@14.0.0-rc.36, which embeds 3.2.0-rc.2. The explanation was 25 lines away in another section; state it at the fence a reader copies. Co-Authored-By: Claude Opus 5 (1M context) --- docs/learning/tracks/buyer.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/learning/tracks/buyer.mdx b/docs/learning/tracks/buyer.mdx index 9b9c3046724..ca2e368f9f1 100644 --- a/docs/learning/tracks/buyer.mdx +++ b/docs/learning/tracks/buyer.mdx @@ -283,6 +283,8 @@ To see the seller responses your agent must handle, you can inspect the test sel ```bash # Inspects the test SELLER's get_products response — the shape your buyer agent must parse. +# The CLI passes adcp_version through, so "3.2-rc.1" reaches the seller even +# though @adcp/sdk@14.0.0-rc.36 embeds 3.2.0-rc.2 for its own validation. npx @adcp/sdk@14.0.0-rc.36 test-mcp get_products '{"adcp_version":"3.2-rc.1","idempotency_key":"550e8400-e29b-41d4-a716-446655442065","buying_mode":"brief","brief":"your campaign brief"}' ``` From 70aac88cc1b84290d5412c35c6a8041fe5485245 Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Mon, 14 Sep 2026 15:32:39 +0000 Subject: [PATCH 5/7] deps: bump @adcp/sdk from 14.0.0-rc.35 to 14.0.0-rc.36 Mirrors the rc.35 alignment in 8644cdf8e: dependency, conformance metadata, certification prompt pins, and the server provenance assertions. This does not build. rc.36 tightens the canonical proposal/purchase types (pricing_option_id now required; performance_standards and audience_evidence_pins are non-empty tuples), which produces four TypeScript errors in server/src/training-agent/ and fails both `npm run build` and `npm run verify:training-agent-runtime`. rc.35 typechecks clean. rc.36 also drops the 3.2.0-rc.1 schema bundle, so the SDK response evidence workflow hard-fails: its probe defaults to release 3.2.0-rc.1 and createAdcpServer throws ConfigurationError. Selecting 3.2.0-rc.2 instead fixes the TypeScript leg but breaks the Python leg, because adcp==8.0.0b14 and Go adcp/v3@v3.2.1 still embed 3.2.0-rc.1. known-findings.json therefore carries a bumped SDK pin whose findings were not re-measured. specs/sdk-lifecycle-compatibility-audit.md is intentionally left on rc.35: its row pins the rc.35 source SHA and an embedded 3.2.0-rc.1 protocol pin, and re-labelling those would assert measurements that were never taken. Opened as a draft for review of the blockers, not for merge. Co-Authored-By: Claude Opus 5 (1M context) --- package-lock.json | 92 +------------------ package.json | 2 +- scripts/sdk-response-conformance/README.md | 2 +- .../known-findings.json | 2 +- server/src/addie/mcp/certification-tools.ts | 4 +- .../registry-api-agent-refresh.test.ts | 4 +- ...stry-api-compliance-verdict-source.test.ts | 2 +- .../tests/unit/compliance-publication.test.ts | 2 +- 8 files changed, 13 insertions(+), 97 deletions(-) diff --git a/package-lock.json b/package-lock.json index 41d75f7a884..64a5b011528 100644 --- a/package-lock.json +++ b/package-lock.json @@ -8,7 +8,7 @@ "name": "adcontextprotocol", "version": "3.2.0-rc.3", "dependencies": { - "@adcp/sdk": "14.0.0-rc.35", + "@adcp/sdk": "14.0.0-rc.36", "@anthropic-ai/sdk": "^0.124.0", "@asteasolutions/zod-to-openapi": "^8.5.0", "@contentauth/c2pa-node": "^0.9.4", @@ -136,9 +136,9 @@ } }, "node_modules/@adcp/sdk": { - "version": "14.0.0-rc.35", - "resolved": "https://registry.npmjs.org/@adcp/sdk/-/sdk-14.0.0-rc.35.tgz", - "integrity": "sha512-WShMKYmOMVo5X9Iv37dbdmjAh98tS9dFDT3OvK4JlOmUOit9pX0zEVj1uOVOMsxTiCgtofWYp03dsDMpm3wW+Q==", + "version": "14.0.0-rc.36", + "resolved": "https://registry.npmjs.org/@adcp/sdk/-/sdk-14.0.0-rc.36.tgz", + "integrity": "sha512-BL1qFiC11tEiSIewv9NOr+l4ixDQFVCw/BMecSdlg7vtnKCKrG5aW0tycL4mWUTnGye1CNMjLEiHCmqR9zJvMQ==", "license": "Apache-2.0", "workspaces": [ ".", @@ -295,9 +295,6 @@ "arm64" ], "dev": true, - "libc": [ - "glibc" - ], "license": "SEE LICENSE IN LICENSE.md", "optional": true, "os": [ @@ -312,9 +309,6 @@ "arm64" ], "dev": true, - "libc": [ - "musl" - ], "license": "SEE LICENSE IN LICENSE.md", "optional": true, "os": [ @@ -329,9 +323,6 @@ "x64" ], "dev": true, - "libc": [ - "glibc" - ], "license": "SEE LICENSE IN LICENSE.md", "optional": true, "os": [ @@ -346,9 +337,6 @@ "x64" ], "dev": true, - "libc": [ - "musl" - ], "license": "SEE LICENSE IN LICENSE.md", "optional": true, "os": [ @@ -3655,9 +3643,6 @@ "arm" ], "dev": true, - "libc": [ - "glibc" - ], "license": "LGPL-3.0-or-later", "optional": true, "os": [ @@ -3675,9 +3660,6 @@ "arm64" ], "dev": true, - "libc": [ - "glibc" - ], "license": "LGPL-3.0-or-later", "optional": true, "os": [ @@ -3695,9 +3677,6 @@ "s390x" ], "dev": true, - "libc": [ - "glibc" - ], "license": "LGPL-3.0-or-later", "optional": true, "os": [ @@ -3715,9 +3694,6 @@ "x64" ], "dev": true, - "libc": [ - "glibc" - ], "license": "LGPL-3.0-or-later", "optional": true, "os": [ @@ -3735,9 +3711,6 @@ "arm64" ], "dev": true, - "libc": [ - "musl" - ], "license": "LGPL-3.0-or-later", "optional": true, "os": [ @@ -3755,9 +3728,6 @@ "x64" ], "dev": true, - "libc": [ - "musl" - ], "license": "LGPL-3.0-or-later", "optional": true, "os": [ @@ -3775,9 +3745,6 @@ "arm" ], "dev": true, - "libc": [ - "glibc" - ], "license": "Apache-2.0", "optional": true, "os": [ @@ -3801,9 +3768,6 @@ "arm64" ], "dev": true, - "libc": [ - "glibc" - ], "license": "Apache-2.0", "optional": true, "os": [ @@ -3827,9 +3791,6 @@ "s390x" ], "dev": true, - "libc": [ - "glibc" - ], "license": "Apache-2.0", "optional": true, "os": [ @@ -3853,9 +3814,6 @@ "x64" ], "dev": true, - "libc": [ - "glibc" - ], "license": "Apache-2.0", "optional": true, "os": [ @@ -3879,9 +3837,6 @@ "arm64" ], "dev": true, - "libc": [ - "musl" - ], "license": "Apache-2.0", "optional": true, "os": [ @@ -3905,9 +3860,6 @@ "x64" ], "dev": true, - "libc": [ - "musl" - ], "license": "Apache-2.0", "optional": true, "os": [ @@ -13484,9 +13436,6 @@ "arm" ], "dev": true, - "libc": [ - "glibc" - ], "license": "LGPL-3.0-or-later", "optional": true, "os": [ @@ -13504,9 +13453,6 @@ "arm64" ], "dev": true, - "libc": [ - "glibc" - ], "license": "LGPL-3.0-or-later", "optional": true, "os": [ @@ -13524,9 +13470,6 @@ "s390x" ], "dev": true, - "libc": [ - "glibc" - ], "license": "LGPL-3.0-or-later", "optional": true, "os": [ @@ -13544,9 +13487,6 @@ "x64" ], "dev": true, - "libc": [ - "glibc" - ], "license": "LGPL-3.0-or-later", "optional": true, "os": [ @@ -13564,9 +13504,6 @@ "arm64" ], "dev": true, - "libc": [ - "musl" - ], "license": "LGPL-3.0-or-later", "optional": true, "os": [ @@ -13584,9 +13521,6 @@ "x64" ], "dev": true, - "libc": [ - "musl" - ], "license": "LGPL-3.0-or-later", "optional": true, "os": [ @@ -13604,9 +13538,6 @@ "arm" ], "dev": true, - "libc": [ - "glibc" - ], "license": "Apache-2.0", "optional": true, "os": [ @@ -13630,9 +13561,6 @@ "arm64" ], "dev": true, - "libc": [ - "glibc" - ], "license": "Apache-2.0", "optional": true, "os": [ @@ -13656,9 +13584,6 @@ "s390x" ], "dev": true, - "libc": [ - "glibc" - ], "license": "Apache-2.0", "optional": true, "os": [ @@ -13682,9 +13607,6 @@ "x64" ], "dev": true, - "libc": [ - "glibc" - ], "license": "Apache-2.0", "optional": true, "os": [ @@ -13708,9 +13630,6 @@ "arm64" ], "dev": true, - "libc": [ - "musl" - ], "license": "Apache-2.0", "optional": true, "os": [ @@ -13734,9 +13653,6 @@ "x64" ], "dev": true, - "libc": [ - "musl" - ], "license": "Apache-2.0", "optional": true, "os": [ diff --git a/package.json b/package.json index be6bd6c2f15..0e964556519 100644 --- a/package.json +++ b/package.json @@ -188,7 +188,7 @@ "eval:addie-matched-v4-authorized": "tsx --import dotenv/config server/tests/manual/matched-v4-authorized-execution.ts" }, "dependencies": { - "@adcp/sdk": "14.0.0-rc.35", + "@adcp/sdk": "14.0.0-rc.36", "@anthropic-ai/sdk": "^0.124.0", "@asteasolutions/zod-to-openapi": "^8.5.0", "@contentauth/c2pa-node": "^0.9.4", diff --git a/scripts/sdk-response-conformance/README.md b/scripts/sdk-response-conformance/README.md index 62ff96e8048..78f0eb6c92b 100644 --- a/scripts/sdk-response-conformance/README.md +++ b/scripts/sdk-response-conformance/README.md @@ -37,7 +37,7 @@ The report exits **1 for findings or skipped cases**, **2 for a harness failure* ## Initial findings and regression policy -With `@adcp/sdk@14.0.0-rc.35`, `adcp==8.0.0b14`, and Go `adcp/v3@v3.2.1`, there are 124 cases per language: two catalogs, 119 published error defaults and three overrides. Go skips native listing. The initial report records: +With `@adcp/sdk@14.0.0-rc.36`, `adcp==8.0.0b14`, and Go `adcp/v3@v3.2.1`, there are 124 cases per language: two catalogs, 119 published error defaults and three overrides. Go skips native listing. The initial report records: - TypeScript: error defaults and overrides agree; `list_products` gains `adcp_version`, which the raw pinned response schema forbids. This is a schema/envelope inconsistency, related to the prior [SDK normalization fix #2594](https://github.com/adcontextprotocol/adcp-client/issues/2594); it is not a claim that the fixed SDK client still rejects the response. The probe deliberately retains the raw artifact result instead of silently stripping fields or patching an immutable schema. - Python: 84 default recovery classifications differ from the published metadata; native listing gains `status: completed`, rejected both by the raw pinned schema and the MCP client's advertised-output validator. diff --git a/scripts/sdk-response-conformance/known-findings.json b/scripts/sdk-response-conformance/known-findings.json index d24913ff086..89c6200abd9 100644 --- a/scripts/sdk-response-conformance/known-findings.json +++ b/scripts/sdk-response-conformance/known-findings.json @@ -1,6 +1,6 @@ [ { - "sdk": {"package":"@adcp/sdk","version":"14.0.0-rc.35"}, + "sdk": {"package":"@adcp/sdk","version":"14.0.0-rc.36"}, "protocol": { "version": "3.2.0-rc.1", "wire_selector": "3.2-rc.1", diff --git a/server/src/addie/mcp/certification-tools.ts b/server/src/addie/mcp/certification-tools.ts index fbf855f129f..a85479a63a3 100644 --- a/server/src/addie/mcp/certification-tools.ts +++ b/server/src/addie/mcp/certification-tools.ts @@ -3058,7 +3058,7 @@ Tell ${codingTool}: "Build a buyer agent using @adcp/sdk that connects to the pu The SDK handles protocol details — the learner focuses on orchestration logic. -Use the current \`3.2-rc.1\` wire pin with @adcp/sdk@14.0.0-rc.35 for the targeting-aware discovery portion. Decompose one messy request into brief plus criteria.offer_filters, criteria.targeting_overlay, and criteria.required_overlay_support; verify that unsupported future-selection requirements filter products; review any targeting_resolution.modifications before purchase; and verify effective package targeting on readback. Treat the get_products compatibility facade's equivalent fields as compatibility evidence, not as proof that the compact tasks work. +Use the current \`3.2-rc.1\` wire pin with @adcp/sdk@14.0.0-rc.36 for the targeting-aware discovery portion. Decompose one messy request into brief plus criteria.offer_filters, criteria.targeting_overlay, and criteria.required_overlay_support; verify that unsupported future-selection requirements filter products; review any targeting_resolution.modifications before purchase; and verify effective package targeting on readback. Treat the get_products compatibility facade's equivalent fields as compatibility evidence, not as proof that the compact tasks work. Reference: ${SDKS_URL} @@ -3073,7 +3073,7 @@ Validate in two parts. 1. Run the compatibility buying workflow against the public test agent and share the output. Use the \`adcp\` CLI: \`\`\` -npx @adcp/sdk@14.0.0-rc.35 test-mcp get_products '{"adcp_version":"3.2-rc.1","buying_mode":"brief","brief":""}' +npx @adcp/sdk@14.0.0-rc.36 test-mcp get_products '{"adcp_version":"3.2-rc.1","buying_mode":"brief","brief":""}' \`\`\` Replace \`\` with your actual brief. Then run the full buying flow: get_products (select a canonical \`format_options[]\` entry) → create_media_buy → get_adcp_capabilities on the chosen creative endpoint → sync_creatives with \`format_kind\` and optional \`format_option_ref\`. diff --git a/server/tests/integration/registry-api-agent-refresh.test.ts b/server/tests/integration/registry-api-agent-refresh.test.ts index 271a1ab5e2b..949f4b7733b 100644 --- a/server/tests/integration/registry-api-agent-refresh.test.ts +++ b/server/tests/integration/registry-api-agent-refresh.test.ts @@ -339,7 +339,7 @@ describe('POST /api/registry/agents/:encodedUrl/refresh (integration)', () => { expect(res.status).toBe(200); expect(res.body).toMatchObject({ completeness, is_authoritative: false, badge_eligible: false, badge_eligible_adcp_versions: [], diagnostics: [], - provenance: { sdk_version: '14.0.0-rc.35', test_session_id: expect.any(String), agent_build_version: null }, + provenance: { sdk_version: '14.0.0-rc.36', test_session_id: expect.any(String), agent_build_version: null }, }); expect(complyMock.mock.calls[0][1].test_session_id).toBe(res.body.provenance.test_session_id); const db = new ComplianceDatabase(); @@ -757,7 +757,7 @@ describe('POST /api/registry/agents/:encodedUrl/refresh (integration)', () => { expect(history.body.runs).toEqual([]); const diagnostics = await request(app).get(`/api/registry/agents/${encodeURIComponent(agentUrl)}/compliance/diagnostics`); expect(diagnostics.body).toMatchObject({ completeness: 'timed_out', is_authoritative: false, - diagnostics_visibility: 'owner_or_operator', provenance: { sdk_version: '14.0.0-rc.35', agent_build_version: null } }); + diagnostics_visibility: 'owner_or_operator', provenance: { sdk_version: '14.0.0-rc.36', agent_build_version: null } }); } } finally { revokeBadges.mockRestore(); diff --git a/server/tests/integration/registry-api-compliance-verdict-source.test.ts b/server/tests/integration/registry-api-compliance-verdict-source.test.ts index cc2e3b77a0b..6b715b32c2e 100644 --- a/server/tests/integration/registry-api-compliance-verdict-source.test.ts +++ b/server/tests/integration/registry-api-compliance-verdict-source.test.ts @@ -475,7 +475,7 @@ describe('GET /api/registry/agents/:encodedUrl/compliance — owner-scope gate ( const response = await request(app).get(`/api/registry/agents/${encodeURIComponent(AGENT_URL)}/compliance/diagnostics?run_id=${run.id}`); expect(response.status).toBe(200); expect(response.body).toMatchObject({ run_id: run.id, completeness: 'timed_out', is_authoritative: false, - provenance: { compliance_bundle_version: '3.1.20', sdk_version: '14.0.0-rc.35', agent_build_version: 'build-immutable-42', agent_library_version: 'seller-sdk-2' }, + provenance: { compliance_bundle_version: '3.1.20', sdk_version: '14.0.0-rc.36', agent_build_version: 'build-immutable-42', agent_library_version: 'seller-sdk-2' }, diagnostics_visibility: 'owner_or_operator' }); expect(response.body.diagnostics[0].error_text).toBe('Expected products array'); expect(JSON.stringify(response.body)).not.toContain('fixture-secret-value'); diff --git a/server/tests/unit/compliance-publication.test.ts b/server/tests/unit/compliance-publication.test.ts index ecf36c26630..68907a8c453 100644 --- a/server/tests/unit/compliance-publication.test.ts +++ b/server/tests/unit/compliance-publication.test.ts @@ -181,7 +181,7 @@ describe('hosted compliance publication policy', () => { it('records exact runner and agent provenance, leaving absent agent builds null', () => { const run = result([{ passed: true }]); expect(complianceResultToDbInput(run, agentUrl, 'production').provenance_json).toMatchObject({ - compliance_bundle_version: '3.1.20', sdk_version: '14.0.0-rc.35', + compliance_bundle_version: '3.1.20', sdk_version: '14.0.0-rc.36', agent_build_version: 'test-build', agent_library_version: 'seller-sdk-1', }); delete run.agent_profile.adcp_build_version; From e760b8872ad69b88092c0c71121047d80e83d491 Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Mon, 14 Sep 2026 16:09:51 +0000 Subject: [PATCH 6/7] fix(conformance): move the SDK response probe to the 3.2.0-rc.2 artifact MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit rc.36 no longer bundles 3.2.0-rc.1, so the probe's default release, run.sh, README, and tests/sdk-response-conformance.test.cjs now select 3.2.0-rc.2 and the 3.2-rc.2 wire selector. npm run test:sdk-response-conformance passes (14/14), and the TypeScript and Go legs both produce output against the rc.2 plan. The Python leg still hard-fails: adcp==8.0.0b14 raises "no bundled AdCP schemas are available for adcp_version='3.2.0-rc.2'", and 8.0.0b14 is the newest published build. A full three-language report therefore cannot be produced, so known-findings.json keeps its 3.2.0-rc.1 evidence rather than being hand-edited — check-baseline.cjs deep-equals the whole report, so an edited baseline would assert measurements nobody took. The README now records that regeneration is pending a Python build that embeds 3.2.0-rc.2. Co-Authored-By: Claude Opus 5 (1M context) --- scripts/probe-sdk-response-conformance.cjs | 2 +- scripts/sdk-response-conformance/README.md | 14 ++++++++++++-- scripts/sdk-response-conformance/run.sh | 2 +- tests/sdk-response-conformance.test.cjs | 6 +++--- 4 files changed, 17 insertions(+), 7 deletions(-) diff --git a/scripts/probe-sdk-response-conformance.cjs b/scripts/probe-sdk-response-conformance.cjs index 68b3c9778c5..030a546cd08 100644 --- a/scripts/probe-sdk-response-conformance.cjs +++ b/scripts/probe-sdk-response-conformance.cjs @@ -5,7 +5,7 @@ const { prepare, assess } = require('./sdk-response-conformance/lib.cjs'); const [command, ...args] = process.argv.slice(2); try { if (command === 'prepare') { - const plan = prepare(args[0] || '3.2.0-rc.1'); + const plan = prepare(args[0] || '3.2.0-rc.2'); process.stdout.write(JSON.stringify(plan, null, 2) + '\n'); } else if (command === 'report') { const [planFile, ...runs] = args; diff --git a/scripts/sdk-response-conformance/README.md b/scripts/sdk-response-conformance/README.md index 78f0eb6c92b..7b329580d38 100644 --- a/scripts/sdk-response-conformance/README.md +++ b/scripts/sdk-response-conformance/README.md @@ -17,7 +17,7 @@ bash scripts/sdk-response-conformance/run.sh .context/sdk-response-conformance Follow the repository's Docker requirement for local execution. CI installs these runtimes on an ephemeral runner. The driver commands can also run independently against the same prepared plan: ```sh -node scripts/probe-sdk-response-conformance.cjs prepare 3.2.0-rc.1 > .context/plan.json +node scripts/probe-sdk-response-conformance.cjs prepare 3.2.0-rc.2 > .context/plan.json node scripts/sdk-response-conformance/typescript.cjs .context/plan.json > .context/typescript.json python3 scripts/sdk-response-conformance/python.py .context/plan.json > .context/python.json # Run go run . with the absolute plan path from scripts/sdk-response-conformance/go. @@ -30,7 +30,7 @@ The report exits **1 for findings or skipped cases**, **2 for a harness failure* - **Inventory:** exactly the selected immutable release's canonical manifest, joined with each configured server's `tools/list`. Historical copies and MCP projections are not counted as extra tools. Tools without business/state fixtures and failed request generation have explicit reasons. - **Requests:** deterministic required-property candidates, local `$ref` resolution, recorded union choices and unselected alternatives, bounded recursion, then AJV validation before dispatch. Conditional/pattern constraints that the generator cannot satisfy are reported, not bypassed. Optional request branches remain explicitly untested. The only request override is `get_products.buying_mode = wholesale`; add named fixtures for accounts, authentication, identifiers and continuations as coverage grows. -- **Versions:** the SHA-256 covers the canonical JSON files by sorted relative path and content hash, excluding generated MCP/bundled projections. A release such as `3.2.0-rc.1` uses the published wire selector `3.2-rc.1`. The controlled server fixture selects the immutable artifact; the response or SDK handler context provides the served selector. No request pin is copied into served-version evidence. An absent or unavailable served contract makes validation provisional, not a claim that a legacy peer is invalid merely for omitting version metadata. +- **Versions:** the SHA-256 covers the canonical JSON files by sorted relative path and content hash, excluding generated MCP/bundled projections. A release such as `3.2.0-rc.2` uses the published wire selector `3.2-rc.2`. The controlled server fixture selects the immutable artifact; the response or SDK handler context provides the served selector. No request pin is copied into served-version evidence. An absent or unavailable served contract makes validation provisional, not a claim that a legacy peer is invalid merely for omitting version metadata. - **Responses:** capture the actual MCP result and validate against the served release. Tool errors use the published `core/error.json` and MCP binding; they are never checked as successful task payloads. Published error-code metadata separately checks recovery semantics. Extension-code overrides exercise all three recovery values without asserting that standard classifications may be changed arbitrarily. - **Transport:** TypeScript uses `createAdcpServer`'s supported low-level `legacy/v5` entry with `mcpToolProfile: all`, so retained and compact discovery are visible. Python uses `create_mcp_server` with typed task exceptions built from the actual `adcp_error` helper. Its public MCP request API captures output before the client's output-schema validator can throw it away; that validator still runs and its errors are retained. Go uses `Register`, `ProductsResponse`, and the `NewError` → `Errorf` path. SDK self-validation is disabled where configurable so an invalid response remains observable; independent release-schema validation is always on. - **Limits:** no A2A coverage, nonempty catalog translation, live-partner evidence, purchase execution or continuation replay. The generator is a bounded fixture builder, not a general constraint solver. Go's current `Register` does not expose `ListProducts`, and its product/error helpers provide no served-version evidence. @@ -43,6 +43,16 @@ With `@adcp/sdk@14.0.0-rc.36`, `adcp==8.0.0b14`, and Go `adcp/v3@v3.2.1`, there - Python: 84 default recovery classifications differ from the published metadata; native listing gains `status: completed`, rejected both by the raw pinned schema and the MCP client's advertised-output validator. - Go: [#530](https://github.com/adcontextprotocol/adcp-go/issues/530) reproduces with six invalid recovery values and 110 incorrect classifications. The catalog helper also omits required `status`. All 123 dispatched cases lack served-version evidence, so their selected-artifact checks remain provisional. Missing metadata is an evidence limitation, not automatically a fatal protocol error. +> **Baseline pending regeneration.** The probe's default release moved to +> `3.2.0-rc.2` because `@adcp/sdk@14.0.0-rc.36` no longer bundles `3.2.0-rc.1`. +> The TypeScript and Go legs run clean at `3.2.0-rc.2`, but `adcp==8.0.0b14` +> raises `no bundled AdCP schemas are available for adcp_version='3.2.0-rc.2'`, +> so a full three-language report cannot be produced yet and +> `known-findings.json` still records the `3.2.0-rc.1` evidence. Regenerate it +> from a real run once a Python `adcp` build embeds `3.2.0-rc.2`. Do not +> hand-edit the baseline to match: `check-baseline.cjs` deep-equals the whole +> report, so an edited baseline asserts measurements nobody took. + `known-findings.json` is an explicit regression baseline, **not an allowlist that makes the conformance report pass**. The CI job checks that exact SDK pins, artifact digest, coverage counts, findings and skips still match the reviewed evidence. It uploads raw observations and reports and publishes their counts. New defects, resolved defects, changed coverage or SDK/artifact pins require a deliberate baseline update and review. The ordinary report continues to exit 1 while findings remain. Do not weaken schemas or hide failures to make the baseline green. Negative controls reuse the repository's transport-error vectors and AJV stack. They prove that malformed envelopes, bad recovery enums, wrong enum-valid classifications, artifact drift, missing observations and unavailable served versions cannot pass silently. diff --git a/scripts/sdk-response-conformance/run.sh b/scripts/sdk-response-conformance/run.sh index 3b99df88eb1..e0c4af146f9 100644 --- a/scripts/sdk-response-conformance/run.sh +++ b/scripts/sdk-response-conformance/run.sh @@ -3,7 +3,7 @@ set -euo pipefail # Run from the repository root. Dependencies: npm ci, pinned requirements.txt, # Go from go/go.mod. No partner credentials or external agent URLs are used. output_dir=${1:-.context/sdk-response-conformance} -release=${2:-3.2.0-rc.1} +release=${2:-3.2.0-rc.2} mkdir -p "$output_dir" output_dir=$(cd "$output_dir" && pwd) node scripts/probe-sdk-response-conformance.cjs prepare "$release" > "$output_dir/plan.json" || exit 2 diff --git a/tests/sdk-response-conformance.test.cjs b/tests/sdk-response-conformance.test.cjs index 4492372e888..0beb77d9fe3 100644 --- a/tests/sdk-response-conformance.test.cjs +++ b/tests/sdk-response-conformance.test.cjs @@ -5,7 +5,7 @@ const fs = require('node:fs'); const path = require('node:path'); const Ajv = require('ajv'); const { artifact, generate, prepare, assess, ROOT } = require('../scripts/sdk-response-conformance/lib.cjs'); -const plan = prepare('3.2.0-rc.1'); +const plan = prepare('3.2.0-rc.2'); const art = artifact(plan.protocol.version); function probe(id, change = {}) { return { ...plan, cases: [{ ...plan.cases.find(row => row.id === id), ...change }] }; @@ -29,7 +29,7 @@ test('inventory is exactly the selected manifest; every dispatched request is sc assert.ok(plan.inventory.some(row => row.generation.status === 'unsupported')); assert.ok(plan.inventory.some(row => row.fixture.startsWith('unimplemented:'))); for (const row of plan.cases) assert.deepEqual(art.validate(art.manifest.tools[row.tool].request_schema, row.request), [], row.id); - assert.equal(plan.protocol.wire_selector, '3.2-rc.1'); + assert.equal(plan.protocol.wire_selector, '3.2-rc.2'); assert.equal(artifact(plan.protocol.version).digest, plan.protocol.sha256); }); @@ -144,7 +144,7 @@ test('regression baseline retains findings and detects changed coverage or SDK p test('error envelopes validate version fields as well as the inner error', () => { const result = inspect(probe('default:RATE_LIMITED'), { - adcp_version: '3.2.0-rc.1', + adcp_version: '3.2.0-rc.2', adcp_error: { code: 'RATE_LIMITED', message: 'Fixture', recovery: 'transient' }, }); assert.equal(result.schema, 'invalid', 'full semver is not a valid wire selector'); From cd9f942d97c85f00c95d32eb4978405fb8ce3a7d Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Mon, 14 Sep 2026 16:43:03 +0000 Subject: [PATCH 7/7] fix(conformance): pin the SDK response probe per language while the waves are staggered No single artifact satisfies all three SDKs today: @adcp/sdk 14.0.0-rc.36 bundles 3.2.0-rc.2 and rejects 3.2.0-rc.1, while adcp 8.0.0b14 and adcp/v3 v3.2.1 bundle 3.2.0-rc.1 and reject 3.2.0-rc.2. run.sh now prepares one plan per distinct release and dispatches each driver with its own (ts_release 3.2.0-rc.2, py_release and go_release 3.2.0-rc.1). `report` takes plan/run pairs so each run is graded against the plan it was dispatched with. This is a small change because the report already carried a per-language protocol block; the three entries simply stopped being identical. known-findings.json is regenerated from a real three-language run, not hand-edited. Findings are unchanged at 1 / 85 / 124, so rc.36 introduces no new defects and resolves none; only the TypeScript row's protocol block and its coverage counts move (manifest_tools 77 to 78, because rc.2 adds a tool). The README records the staggered pins, warns that a cross-language finding difference may now be an artifact difference rather than an SDK difference, and says to collapse back to one release once the waves converge. npm run test:sdk-response-conformance passes 14/14; a clean run.sh exits 1 (findings retained, the documented normal state) and check-baseline passes. Co-Authored-By: Claude Opus 5 (1M context) --- scripts/probe-sdk-response-conformance.cjs | 13 +++--- scripts/sdk-response-conformance/README.md | 41 +++++++++++-------- .../known-findings.json | 16 ++++---- scripts/sdk-response-conformance/run.sh | 25 ++++++++--- 4 files changed, 60 insertions(+), 35 deletions(-) mode change 100644 => 100755 scripts/sdk-response-conformance/run.sh diff --git a/scripts/probe-sdk-response-conformance.cjs b/scripts/probe-sdk-response-conformance.cjs index 030a546cd08..83c0b908fab 100644 --- a/scripts/probe-sdk-response-conformance.cjs +++ b/scripts/probe-sdk-response-conformance.cjs @@ -8,11 +8,14 @@ try { const plan = prepare(args[0] || '3.2.0-rc.2'); process.stdout.write(JSON.stringify(plan, null, 2) + '\n'); } else if (command === 'report') { - const [planFile, ...runs] = args; - if (!planFile || !runs.length) throw Error('report requires plan.json and driver output file(s)'); - const plan = JSON.parse(fs.readFileSync(planFile)); - const reports = runs.map(file => assess(plan, JSON.parse(fs.readFileSync(file)))); + // Pairs, because the language waves can be staggered across releases: each + // driver is graded against the plan it was actually dispatched with. + if (!args.length || args.length % 2) throw Error('report requires plan.json run.json pair(s)'); + const reports = []; + for (let index = 0; index < args.length; index += 2) { + reports.push(assess(JSON.parse(fs.readFileSync(args[index])), JSON.parse(fs.readFileSync(args[index + 1])))); + } process.stdout.write(JSON.stringify({ reports }, null, 2) + '\n'); if (reports.some(report => report.summary.cases_with_findings || report.summary.skipped)) process.exitCode = 1; - } else throw Error('Usage: probe-sdk-response-conformance.cjs prepare [release] | report plan.json run.json [...]'); + } else throw Error('Usage: probe-sdk-response-conformance.cjs prepare [release] | report plan.json run.json [plan.json run.json ...]'); } catch (error) { process.stderr.write(`${error.stack}\n`); process.exitCode = 2; } diff --git a/scripts/sdk-response-conformance/README.md b/scripts/sdk-response-conformance/README.md index 7b329580d38..03572c54467 100644 --- a/scripts/sdk-response-conformance/README.md +++ b/scripts/sdk-response-conformance/README.md @@ -14,14 +14,18 @@ npm run test:sdk-response-conformance bash scripts/sdk-response-conformance/run.sh .context/sdk-response-conformance ``` -Follow the repository's Docker requirement for local execution. CI installs these runtimes on an ephemeral runner. The driver commands can also run independently against the same prepared plan: +Follow the repository's Docker requirement for local execution. CI installs these runtimes on an ephemeral runner. The driver commands can also run independently against their prepared plans: ```sh -node scripts/probe-sdk-response-conformance.cjs prepare 3.2.0-rc.2 > .context/plan.json -node scripts/sdk-response-conformance/typescript.cjs .context/plan.json > .context/typescript.json -python3 scripts/sdk-response-conformance/python.py .context/plan.json > .context/python.json +node scripts/probe-sdk-response-conformance.cjs prepare 3.2.0-rc.2 > .context/plan-rc2.json +node scripts/probe-sdk-response-conformance.cjs prepare 3.2.0-rc.1 > .context/plan-rc1.json +node scripts/sdk-response-conformance/typescript.cjs .context/plan-rc2.json > .context/typescript.json +python3 scripts/sdk-response-conformance/python.py .context/plan-rc1.json > .context/python.json # Run go run . with the absolute plan path from scripts/sdk-response-conformance/go. -node scripts/probe-sdk-response-conformance.cjs report .context/plan.json .context/typescript.json .context/python.json > .context/report.json +# report takes plan/run pairs, so each driver is graded against its own plan. +node scripts/probe-sdk-response-conformance.cjs report \ + .context/plan-rc2.json .context/typescript.json \ + .context/plan-rc1.json .context/python.json > .context/report.json ``` The report exits **1 for findings or skipped cases**, **2 for a harness failure**, and 0 only when the covered fixtures pass. Unimplemented manifest tools still appear in the inventory; 0 never means full-protocol conformance. The three-language runner maps driver failures to 2, preserving this distinction. @@ -30,28 +34,33 @@ The report exits **1 for findings or skipped cases**, **2 for a harness failure* - **Inventory:** exactly the selected immutable release's canonical manifest, joined with each configured server's `tools/list`. Historical copies and MCP projections are not counted as extra tools. Tools without business/state fixtures and failed request generation have explicit reasons. - **Requests:** deterministic required-property candidates, local `$ref` resolution, recorded union choices and unselected alternatives, bounded recursion, then AJV validation before dispatch. Conditional/pattern constraints that the generator cannot satisfy are reported, not bypassed. Optional request branches remain explicitly untested. The only request override is `get_products.buying_mode = wholesale`; add named fixtures for accounts, authentication, identifiers and continuations as coverage grows. -- **Versions:** the SHA-256 covers the canonical JSON files by sorted relative path and content hash, excluding generated MCP/bundled projections. A release such as `3.2.0-rc.2` uses the published wire selector `3.2-rc.2`. The controlled server fixture selects the immutable artifact; the response or SDK handler context provides the served selector. No request pin is copied into served-version evidence. An absent or unavailable served contract makes validation provisional, not a claim that a legacy peer is invalid merely for omitting version metadata. +- **Versions:** the SHA-256 covers the canonical JSON files by sorted relative path and content hash, excluding generated MCP/bundled projections. A release such as `3.2.0-rc.2` uses the published wire selector `3.2-rc.2`. Each driver is prepared and graded against exactly one immutable release, which may differ per language while the SDK waves are staggered (see the note below). The controlled server fixture selects the immutable artifact; the response or SDK handler context provides the served selector. No request pin is copied into served-version evidence. An absent or unavailable served contract makes validation provisional, not a claim that a legacy peer is invalid merely for omitting version metadata. - **Responses:** capture the actual MCP result and validate against the served release. Tool errors use the published `core/error.json` and MCP binding; they are never checked as successful task payloads. Published error-code metadata separately checks recovery semantics. Extension-code overrides exercise all three recovery values without asserting that standard classifications may be changed arbitrarily. - **Transport:** TypeScript uses `createAdcpServer`'s supported low-level `legacy/v5` entry with `mcpToolProfile: all`, so retained and compact discovery are visible. Python uses `create_mcp_server` with typed task exceptions built from the actual `adcp_error` helper. Its public MCP request API captures output before the client's output-schema validator can throw it away; that validator still runs and its errors are retained. Go uses `Register`, `ProductsResponse`, and the `NewError` → `Errorf` path. SDK self-validation is disabled where configurable so an invalid response remains observable; independent release-schema validation is always on. - **Limits:** no A2A coverage, nonempty catalog translation, live-partner evidence, purchase execution or continuation replay. The generator is a bounded fixture builder, not a general constraint solver. Go's current `Register` does not expose `ListProducts`, and its product/error helpers provide no served-version evidence. ## Initial findings and regression policy -With `@adcp/sdk@14.0.0-rc.36`, `adcp==8.0.0b14`, and Go `adcp/v3@v3.2.1`, there are 124 cases per language: two catalogs, 119 published error defaults and three overrides. Go skips native listing. The initial report records: +With `@adcp/sdk@14.0.0-rc.36` on `3.2.0-rc.2`, `adcp==8.0.0b14` on `3.2.0-rc.1`, and Go `adcp/v3@v3.2.1` on `3.2.0-rc.1`, there are 124 cases per language: two catalogs, 119 published error defaults and three overrides. Go skips native listing. The initial report records: - TypeScript: error defaults and overrides agree; `list_products` gains `adcp_version`, which the raw pinned response schema forbids. This is a schema/envelope inconsistency, related to the prior [SDK normalization fix #2594](https://github.com/adcontextprotocol/adcp-client/issues/2594); it is not a claim that the fixed SDK client still rejects the response. The probe deliberately retains the raw artifact result instead of silently stripping fields or patching an immutable schema. - Python: 84 default recovery classifications differ from the published metadata; native listing gains `status: completed`, rejected both by the raw pinned schema and the MCP client's advertised-output validator. - Go: [#530](https://github.com/adcontextprotocol/adcp-go/issues/530) reproduces with six invalid recovery values and 110 incorrect classifications. The catalog helper also omits required `status`. All 123 dispatched cases lack served-version evidence, so their selected-artifact checks remain provisional. Missing metadata is an evidence limitation, not automatically a fatal protocol error. -> **Baseline pending regeneration.** The probe's default release moved to -> `3.2.0-rc.2` because `@adcp/sdk@14.0.0-rc.36` no longer bundles `3.2.0-rc.1`. -> The TypeScript and Go legs run clean at `3.2.0-rc.2`, but `adcp==8.0.0b14` -> raises `no bundled AdCP schemas are available for adcp_version='3.2.0-rc.2'`, -> so a full three-language report cannot be produced yet and -> `known-findings.json` still records the `3.2.0-rc.1` evidence. Regenerate it -> from a real run once a Python `adcp` build embeds `3.2.0-rc.2`. Do not -> hand-edit the baseline to match: `check-baseline.cjs` deep-equals the whole -> report, so an edited baseline asserts measurements nobody took. +> **Per-SDK release pins, temporarily.** The language waves are staggered: +> `@adcp/sdk@14.0.0-rc.36` bundles `3.2.0-rc.2` and rejects `3.2.0-rc.1`, while +> `adcp==8.0.0b14` and `adcp/v3@v3.2.1` bundle `3.2.0-rc.1` and reject +> `3.2.0-rc.2`. No single pin satisfies all three, so `run.sh` prepares one +> plan per release and grades each driver against the plan it was dispatched +> with (`ts_release`, `py_release`, `go_release`; defaults `3.2.0-rc.2`, +> `3.2.0-rc.1`, `3.2.0-rc.1`). Each report already carries its own `protocol` +> block, so the baseline records which artifact each language was graded +> against. +> +> **Read cross-language differences carefully while this holds.** A finding +> present in one language and absent in another may be an SDK difference or an +> rc.1-to-rc.2 artifact difference. Collapse the pins back to a single release +> as soon as the Python and Go waves catch up. `known-findings.json` is an explicit regression baseline, **not an allowlist that makes the conformance report pass**. The CI job checks that exact SDK pins, artifact digest, coverage counts, findings and skips still match the reviewed evidence. It uploads raw observations and reports and publishes their counts. New defects, resolved defects, changed coverage or SDK/artifact pins require a deliberate baseline update and review. The ordinary report continues to exit 1 while findings remain. Do not weaken schemas or hide failures to make the baseline green. diff --git a/scripts/sdk-response-conformance/known-findings.json b/scripts/sdk-response-conformance/known-findings.json index 89c6200abd9..4c1801f3c4f 100644 --- a/scripts/sdk-response-conformance/known-findings.json +++ b/scripts/sdk-response-conformance/known-findings.json @@ -2,10 +2,10 @@ { "sdk": {"package":"@adcp/sdk","version":"14.0.0-rc.36"}, "protocol": { - "version": "3.2.0-rc.1", - "wire_selector": "3.2-rc.1", - "sha256": "17b1b11cb90fa261420060fc2732deed5b0f1cfae2a8ebaf2cbb2d665630894e", - "manifest": "dist/schemas/3.2.0-rc.1/manifest.json" + "version": "3.2.0-rc.2", + "wire_selector": "3.2-rc.2", + "sha256": "1b71923d0db3ad92fcdf079060361b2bdde0136486cf306c6ac144fd8fef28c0", + "manifest": "dist/schemas/3.2.0-rc.2/manifest.json" }, "summary": { "cases": 124, @@ -15,12 +15,12 @@ "schema_valid": 123, "schema_invalid": 1, "semantics_passed": 124, - "manifest_tools": 77, + "manifest_tools": 78, "advertised_tools": 3, "tools_with_fixtures": 2, - "tools_without_fixtures": 75, - "unsupported_request_generation": 20, - "union_alternatives_not_selected": 42, + "tools_without_fixtures": 76, + "unsupported_request_generation": 21, + "union_alternatives_not_selected": 43, "optional_request_branches": "not-generated; outside minimal required-property fixtures", "workflow_completion": "not-tested", "status": "findings" diff --git a/scripts/sdk-response-conformance/run.sh b/scripts/sdk-response-conformance/run.sh old mode 100644 new mode 100755 index e0c4af146f9..e8ad1867c15 --- a/scripts/sdk-response-conformance/run.sh +++ b/scripts/sdk-response-conformance/run.sh @@ -2,12 +2,25 @@ set -euo pipefail # Run from the repository root. Dependencies: npm ci, pinned requirements.txt, # Go from go/go.mod. No partner credentials or external agent URLs are used. +# +# Each SDK is graded against the newest immutable artifact it actually bundles. +# A single shared pin is not possible while the language waves are staggered: +# @adcp/sdk 14.0.0-rc.36 bundles 3.2.0-rc.2 and rejects 3.2.0-rc.1, while +# adcp 8.0.0b14 and adcp/v3 v3.2.1 bundle 3.2.0-rc.1 and reject 3.2.0-rc.2. +# Collapse these back to one release as soon as the waves converge. output_dir=${1:-.context/sdk-response-conformance} -release=${2:-3.2.0-rc.2} +ts_release=${2:-3.2.0-rc.2} +py_release=${3:-3.2.0-rc.1} +go_release=${4:-3.2.0-rc.1} mkdir -p "$output_dir" output_dir=$(cd "$output_dir" && pwd) -node scripts/probe-sdk-response-conformance.cjs prepare "$release" > "$output_dir/plan.json" || exit 2 -node scripts/sdk-response-conformance/typescript.cjs "$output_dir/plan.json" > "$output_dir/typescript.json" || exit 2 -python3 scripts/sdk-response-conformance/python.py "$output_dir/plan.json" > "$output_dir/python.json" || exit 2 -(cd scripts/sdk-response-conformance/go && go run . "$output_dir/plan.json") > "$output_dir/go.json" || exit 2 -node scripts/probe-sdk-response-conformance.cjs report "$output_dir/plan.json" "$output_dir/typescript.json" "$output_dir/python.json" "$output_dir/go.json" > "$output_dir/report.json" +for release in $(printf '%s\n' "$ts_release" "$py_release" "$go_release" | sort -u); do + node scripts/probe-sdk-response-conformance.cjs prepare "$release" > "$output_dir/plan-$release.json" || exit 2 +done +node scripts/sdk-response-conformance/typescript.cjs "$output_dir/plan-$ts_release.json" > "$output_dir/typescript.json" || exit 2 +python3 scripts/sdk-response-conformance/python.py "$output_dir/plan-$py_release.json" > "$output_dir/python.json" || exit 2 +(cd scripts/sdk-response-conformance/go && go run . "$output_dir/plan-$go_release.json") > "$output_dir/go.json" || exit 2 +node scripts/probe-sdk-response-conformance.cjs report \ + "$output_dir/plan-$ts_release.json" "$output_dir/typescript.json" \ + "$output_dir/plan-$py_release.json" "$output_dir/python.json" \ + "$output_dir/plan-$go_release.json" "$output_dir/go.json" > "$output_dir/report.json"