@adcp/sdk 14.0.0-beta.0 → 14.0.0-beta.1

package/docs/guides/MEDIA-BUY-3.2-COMPATIBILITY.md

@@ -0,0 +1,119 @@
+# AdCP 3.2 media-buy lifecycle compatibility
+
+SDK 14 separates the tools an MCP seller **advertises** from the compatibility
+routes it can still **call**. A 3.2 seller should make the compact lifecycle the
+obvious path for new buyers without breaking a 3.0 or 3.1 buyer that already
+calls the established names.
+
+## MCP surface comparison
+
+The active 3.2 `media-buy` profile advertises these registered tools:
+
+| Area | AdCP 3.2 active media-buy profile |
+|---|---|
+| Product and proposal lifecycle | `list_products`, `request_proposals`, `refine_proposals`, `decline_proposals` |
+| Purchase and control | `buy_products`, `accept_proposal`, `control_media_buy` |
+| Readback | `get_media_buys`, `get_media_buy_delivery` |
+| Accounts | `list_accounts`, `sync_accounts`, `get_account_financials`, `report_usage` |
+| Creative library | `list_creatives`, `sync_creatives` |
+| Media data | `sync_audiences`, `sync_catalogs`, `sync_event_sources`, `log_event`, `provide_performance_feedback` |
+| Governance and notifications | `sync_governance`, `sync_agent_notification_configs` |
+| Protocol | `get_adcp_capabilities`, `get_task_status`, `list_tasks` |
+
+The deprecated `get_products`, `create_media_buy`, and `update_media_buy` names
+are not advertised in that profile. AdCP 3.0/3.1 sellers advertise the legacy
+lifecycle instead. `get_media_buys` and `get_media_buy_delivery` remain current
+in both generations.
+
+Every framework tool in `tools/list` carries `_meta.adcp_version`. The list
+result also carries `_meta.adcp_version` and `_meta.adcp_profile` so a generic
+MCP host can display the exact protocol pin and selected role surface without
+inferring either from input schemas. Active-profile entries publish the exact,
+self-contained draft-2020-12 request projection. Response validation remains
+with the framework's AJV validator because current MCP clients apply a declared
+success-only `outputSchema` to structured error results too.
+
+## Implement both surfaces from one seller
+
+Use `mediaBuyLifecycle` for the primary 3.2 implementation and keep `sales`
+when the endpoint must continue serving older buyers:
+
+```ts
+const platform = {
+  // accounts, capabilities, statusMappers, ...
+
+  mediaBuyLifecycle: {
+    proposalRefinement: {
+      supported_dimensions: ['total_budget', 'product_changes'],
+    },
+    listProducts,
+    requestProposals,
+    refineProposals,
+    declineProposals,
+    buyProducts,
+    acceptProposal,
+    controlMediaBuy,
+  },
+
+  // Compatibility facade for AdCP 3.0/3.1 callers.
+  sales: {
+    getProducts,
+    createMediaBuy,
+    updateMediaBuy,
+    getMediaBuys,
+    getMediaBuyDelivery,
+  },
+};
+
+createAdcpServerFromPlatform(platform, {
+  name: 'seller',
+  version: '1.0.0',
+  adcpVersion: '3.2.0-beta.0',
+});
+```
+
+With the default `mcpToolProfile: 'auto'`, registering any compact lifecycle
+handler on a 3.2 server selects the active media-buy profile. The legacy
+handlers stay registered and callable but disappear from `tools/list`.
+`mcpToolProfile: 'all'` is available for migration diagnostics; it should not
+be the normal production discovery surface.
+
+The compact tools are not mere renames. Proposal digests, immutable terms,
+feed and pricing versions, optimistic revisions, and accepted commercial
+snapshots make a general field-cast downgrade unsafe. SDK 14 therefore does
+not silently translate a compact call into an older tool. A buyer talking to a
+3.0/3.1 seller selects the established client methods; a dual-surface seller
+implements both facades over the same authorization, storage, idempotency, and
+commercial service layer.
+
+A 3.2-only seller may omit `sales` entirely. `getMediaBuys` and
+`getMediaBuyDelivery` can live on `mediaBuyLifecycle` alongside the seven
+compact lifecycle methods. Authenticated mutations receive an immutable
+`ctx.callerMutationScope`; `refineProposals` also receives the framework-owned
+`ctx.proposalRefinementScope`. Persist and query proposal state under these
+trusted namespaces, never a buyer-supplied proposal ID alone.
+
+## Compatibility matrix to keep in CI
+
+| Buyer | Seller | Expected path |
+|---|---|---|
+| SDK 14 / AdCP 3.2 | SDK 14 / AdCP 3.2 | Compact lifecycle is advertised and called |
+| SDK 14 pinned to AdCP 3.1 | AdCP 3.1 | `get_products` / `create_media_buy` / `update_media_buy` |
+| SDK 14 pinned to AdCP 3.0 | AdCP 3.0 | Established tools plus canonical-to-legacy projection |
+| Existing AdCP 3.0/3.1 buyer | Dual-surface SDK 14 seller | Known legacy names remain directly callable |
+
+For each lane, assert more than tool presence:
+
+1. `tools/list` exposes the version-appropriate surface and metadata.
+2. The request validates against the selected 3.0, 3.1, or 3.2 bundle.
+3. Tenant and authenticated-principal scope reaching the business handler is
+   identical across both facades.
+4. Exact retry keys replay; changed payloads conflict; no cache entry crosses
+   a tool, tenant, account, or buyer principal.
+5. Product, proposal, media-buy, and delivery reads return the same underlying
+   commercial state through the appropriate versioned response projection.
+6. Both MCP SDK clients and raw legacy-name calls are covered, so discovery
+   filtering cannot accidentally remove compatibility dispatch.
+
+Do not test a compact request by casting it to a legacy request type. Exercise
+the actual buyer method and wire schema for each lane.

package/docs/llms.txt

@@ -1,7 +1,7 @@
 # Ad Context Protocol (AdCP)
 
 > Generated at: 2026-08-18
-> Library: @adcp/sdk v14.0.0-beta.0
+> Library: @adcp/sdk v14.0.0-beta.1
 > AdCP major version: 3
 > Canonical URL: https://adcontextprotocol.github.io/adcp-client/llms.txt
 > Note: the `Library` stamp reflects the package.json version at doc-generation time. The narrative below describes the surface that lands on the next-published minor — including any 6.7 helpers documented here ahead of the release tag.

package/docs/migration-12-to-14.md

@@ -102,6 +102,14 @@ SDK 14 adds convenience methods and generated server/type/schema support for:
 
 These do not replace the established tools for older agents. Discover `lifecycle_tools` and branch. Keep `getProducts()`/`createMediaBuy()`/`updateMediaBuy()` available for AdCP 3.0 and 3.1. Preserve the same idempotency key only for an exact retry; changed commercial intent requires a fresh key.
 
+For sellers, implement the compact handlers on
+`platform.mediaBuyLifecycle`; keep `platform.sales` as the 3.0/3.1 facade when
+the endpoint serves mixed buyers. SDK 14's default MCP discovery then shows
+the active 3.2 media-buy profile while leaving configured legacy names directly
+callable. It also exposes `_meta.adcp_version` and `_meta.adcp_profile` in
+`tools/list`. See the [surface comparison and compatibility test
+matrix](guides/MEDIA-BUY-3.2-COMPATIBILITY.md).
+
 For the established proposal path, treat only `get_products` refinements with
 `scope: 'proposal'` and `action: 'finalize'` as mutations. SDK 14 clients attach
 an idempotency key and exact retries must reuse it; SDK 14 servers replay a

package/docs/migration-13-to-14.md

@@ -46,8 +46,17 @@ by their other commercial mutations.
 
 SDK 14 also hardens replay-cache isolation by including the tool and trusted
 resolved session/account identity in canonical replay identity. Existing-tool
-cache keys retain their SDK 13 scope so an older durable entry cannot be
-missed and executed twice. Because SDK 14's stronger payload identity differs,
+cache keys retain both their SDK 13 scope and bare `authInfo.clientId`
+principal format, so an older durable entry cannot be missed and executed
+twice during a rolling upgrade. The new 3.2 compact mutation tools instead use
+credential-kind-prefixed principals such as `oauth:<client_id>`,
+`api_key:<key_id>`, or `agent:<agent_url>` and do not fall back to session or
+account identity. Those tools have no SDK 13 cache entries to migrate.
+
+If you supply `resolveIdempotencyPrincipal`, your resolver remains
+authoritative for both established and compact tools; keep its output stable
+across the deployment or deliberately dual-read/migrate your backing store.
+Because SDK 14's stronger payload identity differs,
 a retry against an SDK 13 entry returns `IDEMPOTENCY_CONFLICT` instead of the
 old cached body; reconcile by natural key rather than minting a replacement
 key until the original replay TTL expires. New entries cannot replay a body
@@ -103,14 +112,31 @@ Do not select a signing profile from a version value inside an unverified reques
 
 ## Server handler additions
 
-`createAdcpServerFromPlatform()` can route the new compact lifecycle, governance adjustment, and agent notification tasks. The generated handler maps cover:
+`createAdcpServerFromPlatform()` routes the new compact lifecycle through
+`platform.mediaBuyLifecycle`, including `proposalRefinement` capability
+metadata for `refineProposals`. Keep `platform.sales` beside it when the same
+seller must accept 3.0/3.1 callers. Both facades should call the same business
+services rather than maintaining parallel commercial state.
+
+The generated handler maps cover:
 
 - `list_products`, `request_proposals`, `refine_proposals`, `decline_proposals`
 - `buy_products`, `accept_proposal`, `control_media_buy`
 - `report_plan_adjustment`
 - `sync_agent_notification_configs`
 
-An SDK 14 server may continue serving 3.0/3.1 clients through the established tool names. Advertise only handlers that are configured and verify both the old facade and new compact path use the same authorization, tenant isolation, idempotency, and commercial source of truth.
+On a 3.2 server, the default `mcpToolProfile: 'auto'` advertises only the
+intersection of registered tools and the active spec `media-buy` profile. The
+deprecated names remain callable compatibility routes. Use
+`mcpToolProfile: 'all'` only for migration diagnostics. MCP `tools/list`
+includes `_meta.adcp_version` and `_meta.adcp_profile`, and each framework tool
+includes `_meta.adcp_version`.
+
+An SDK 14 server may therefore continue serving 3.0/3.1 clients through the
+established tool names without steering new MCP clients toward them. Verify
+both facades use the same authorization, tenant isolation, idempotency, and
+commercial source of truth. The exact surface comparison and test matrix are
+in [AdCP 3.2 media-buy lifecycle compatibility](guides/MEDIA-BUY-3.2-COMPATIBILITY.md).
 
 For create/update media-buy handlers, use `media_buy_status` for the business state:
 

package/docs/releases/14.0.0-beta.0.md

@@ -35,7 +35,25 @@ The generated client, server handler maps, request validators, response types, Z
 
 `AgentClient` exposes matching camel-case methods. Mutating methods accept the SDK's idempotency-aware request input, and the existing generic `executeTask()` path remains available.
 
-The established 3.x tools—including `get_products`, `create_media_buy`, and `update_media_buy`—remain available for 3.0/3.1 interoperability. Capability discovery should decide which lifecycle to use; do not send a 3.2-only tool to a seller that does not advertise it.
+`createAdcpServerFromPlatform()` now exposes the same lifecycle through the
+first-class `mediaBuyLifecycle` platform interface. Compose it with `sales`
+when one deployment must also serve the established 3.0/3.1 tool names.
+
+MCP discovery defaults to the spec's active 3.2 `media-buy` profile whenever a
+3.2 server registers a compact lifecycle handler. It omits deprecated
+`get_products`, `create_media_buy`, and `update_media_buy` from `tools/list`,
+but keeps configured compatibility handlers directly callable by older buyers.
+Each listed tool and the list response expose the server's protocol pin under
+`_meta.adcp_version`; the response also exposes `_meta.adcp_profile`.
+Active-profile entries include their exact, self-contained draft-2020-12
+request schemas. Compact-only sellers can implement current readback methods on
+`mediaBuyLifecycle` without also defining deprecated handlers.
+
+The established 3.x tools remain available for 3.0/3.1 interoperability. A
+compact call is not silently field-cast into a legacy call because proposal
+terms, feed versions, and revisions require orchestration. Capability discovery
+should decide which lifecycle to use. See the complete [3.2 media-buy surface
+and compatibility matrix](../guides/MEDIA-BUY-3.2-COMPATIBILITY.md).
 
 AdCP 3.2 adds optional-key replay semantics to the already state-changing,
 legacy-compatible `get_products` proposal-finalize variant. SDK 14 clients

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adcp/sdk",
-  "version": "14.0.0-beta.0",
+  "version": "14.0.0-beta.1",
   "description": "AdCP SDK — client, server, and compliance harnesses for the AdContext Protocol (MCP + A2A)",
   "workspaces": [
     ".",
@@ -451,6 +451,7 @@
     "docs/migration-*.md",
     "MIGRATION-*.md",
     "docs/guides/BUILD-AN-AGENT.md",
+    "docs/guides/MEDIA-BUY-3.2-COMPATIBILITY.md",
     "docs/guides/CANONICAL-REFERENCE-RESOLVER.md",
     "docs/guides/PREVIEW-ASSET-DURABILITY.md",
     "examples/**/*",