@adcp/sdk 5.25.1 → 6.0.0

package/examples/decisioning-platform-programmatic.ts

@@ -0,0 +1,254 @@
+/**
+ * ProgrammaticSeller — worked example for `sales-non-guaranteed`.
+ *
+ * Programmatic non-guaranteed is the canonical sync case: buyer hits
+ * `create_media_buy`, gets a `media_buy_id` immediately, the SSP queues
+ * the line item for serving. Lifecycle changes (`pending_creatives` →
+ * `active` once creatives clear review; `active` → `completed` at
+ * end_time; pacing-driven `paused` events) flow via `publishStatusChange`.
+ *
+ * Demonstrates the v2.1 sync-first shape:
+ *
+ *   - Sync `getProducts` (catalog read; no async ceremony).
+ *   - Sync `createMediaBuy` (returns MediaBuy immediately on commit).
+ *   - Sync `syncCreatives` (per-creative status; mixed approved/pending in
+ *     one response — review continues async, status-change fires when
+ *     review terminal).
+ *   - `publishStatusChange` for everything that happens *after* the
+ *     synchronous request returns.
+ *
+ * @see `docs/proposals/decisioning-platform-v2-hitl-split.md`
+ */
+
+import {
+  AdcpError,
+  publishStatusChange,
+  type DecisioningPlatform,
+  type SalesPlatform,
+  type AccountStore,
+} from '@adcp/sdk/server';
+import type { SyncCreativesRow } from '@adcp/sdk/server';
+import type {
+  GetProductsRequest,
+  GetProductsResponse,
+  CreateMediaBuyRequest,
+  CreateMediaBuySuccess,
+  UpdateMediaBuyRequest,
+  UpdateMediaBuySuccess,
+  GetMediaBuyDeliveryRequest,
+  GetMediaBuyDeliveryResponse,
+  CreativeAsset,
+  AccountReference,
+} from '@adcp/sdk/types';
+
+export interface ProgrammaticConfig {
+  /** SSP network identifier. */
+  networkId: string;
+  /** Floor CPM in USD. */
+  floorCpm: number;
+  /**
+   * Latency (ms) between sync `createMediaBuy` returning and the
+   * `pending_creatives` → `active` status-change firing. Demo simulates
+   * the time creative review takes after the buy is committed.
+   */
+  creativeReviewMs: number;
+}
+
+interface ProgrammaticMeta {
+  network_id: string;
+  advertiser_id: string;
+  [key: string]: unknown;
+}
+
+type ProgrammaticBuy = CreateMediaBuySuccess;
+
+export class ProgrammaticSeller implements DecisioningPlatform<ProgrammaticConfig, ProgrammaticMeta> {
+  private mediaBuys = new Map<string, ProgrammaticBuy>();
+
+  capabilities = {
+    specialisms: ['sales-non-guaranteed'] as const,
+    creative_agents: [{ agent_url: 'https://example.com/programmatic-creative-agent/mcp' }],
+    channels: ['display', 'olv'] as const,
+    pricingModels: ['cpm'] as const,
+    config: {
+      networkId: 'NET_42',
+      floorCpm: 1.5,
+      creativeReviewMs: 60,
+    } satisfies ProgrammaticConfig,
+  };
+
+  statusMappers = {};
+
+  accounts: AccountStore<ProgrammaticMeta> = {
+    resolve: async (ref: AccountReference) => {
+      const id = 'account_id' in ref ? ref.account_id : 'prog_acc_1';
+      return {
+        id,
+        name: `Programmatic — ${id}`,
+        status: 'active',
+        operator: 'programmatic.example.com',
+        ctx_metadata: { network_id: this.capabilities.config.networkId, advertiser_id: 'adv_42' },
+        authInfo: { kind: 'api_key' },
+      };
+    },
+  };
+
+  sales: SalesPlatform<ProgrammaticMeta> = {
+    /** Sync discovery: catalog read; no async ceremony. */
+    getProducts: async (_req: GetProductsRequest): Promise<GetProductsResponse> => ({
+      products: [
+        {
+          product_id: 'prod_run_of_network_display',
+          name: 'RON Display',
+          description: 'Run-of-network display, 300x250 + 728x90',
+          format_ids: [{ id: 'display_300x250', agent_url: 'https://example.com/programmatic-creative-agent/mcp' }],
+          delivery_type: 'non_guaranteed',
+          publisher_properties: [{ publisher_domain: 'programmatic.example.com', selection_type: 'all' }],
+          reporting_capabilities: {
+            available_reporting_frequencies: ['daily'],
+            expected_delay_minutes: 60,
+            timezone: 'UTC',
+            supports_webhooks: false,
+            available_metrics: [],
+            date_range_support: 'date_range',
+          },
+          pricing_options: [
+            {
+              pricing_option_id: 'cpm_2_50',
+              pricing_model: 'cpm',
+              fixed_price: 2.5,
+              currency: 'USD',
+            },
+          ],
+        },
+        {
+          product_id: 'prod_premium_video_15s',
+          name: 'Premium Video 15s',
+          description: 'In-stream video on premium publishers',
+          format_ids: [{ id: 'video_15s', agent_url: 'https://example.com/programmatic-creative-agent/mcp' }],
+          delivery_type: 'non_guaranteed',
+          publisher_properties: [{ publisher_domain: 'programmatic.example.com', selection_type: 'all' }],
+          reporting_capabilities: {
+            available_reporting_frequencies: ['daily'],
+            expected_delay_minutes: 60,
+            timezone: 'UTC',
+            supports_webhooks: false,
+            available_metrics: [],
+            date_range_support: 'date_range',
+          },
+          pricing_options: [
+            {
+              pricing_option_id: 'cpm_18_00',
+              pricing_model: 'cpm',
+              fixed_price: 18.0,
+              currency: 'USD',
+            },
+          ],
+        },
+      ],
+    }),
+
+    /**
+     * Sync media-buy creation. Buyer gets media_buy_id immediately; status
+     * transitions out of `pending_creatives` flow via publishStatusChange.
+     */
+    createMediaBuy: async (req: CreateMediaBuyRequest) => {
+      const totalBudget =
+        typeof req.total_budget === 'number'
+          ? req.total_budget
+          : ((req.total_budget as { amount?: number })?.amount ?? 0);
+      if (totalBudget < this.capabilities.config.floorCpm * 1000) {
+        throw new AdcpError('BUDGET_TOO_LOW', {
+          recovery: 'correctable',
+          message: `total_budget below floor (${this.capabilities.config.floorCpm} CPM × 1000 imp)`,
+          field: 'total_budget',
+          suggestion: `Raise to at least ${this.capabilities.config.floorCpm * 1000}`,
+        });
+      }
+
+      const buyId = `mb_${this.capabilities.config.networkId}_${Date.now()}`;
+      const buy: ProgrammaticBuy = {
+        media_buy_id: buyId,
+        status: 'pending_creatives',
+        confirmed_at: new Date().toISOString(),
+        revision: 1,
+        packages: [],
+      };
+      this.mediaBuys.set(buyId, buy);
+      void totalBudget;
+
+      // Demo: schedule the pending_creatives → active transition once
+      // creative review clears. In production this fires from the SSP's
+      // creative-review webhook handler.
+      const account = (req as { account?: { account_id?: string } }).account;
+      const accountId = account?.account_id ?? 'prog_acc_1';
+      setTimeout(() => {
+        buy.status = 'active';
+        publishStatusChange({
+          account_id: accountId,
+          resource_type: 'media_buy',
+          resource_id: buyId,
+          payload: { status: 'active', activated_at: new Date().toISOString() },
+        });
+      }, this.capabilities.config.creativeReviewMs).unref?.();
+
+      return buy;
+    },
+
+    updateMediaBuy: async (buyId: string, patch: UpdateMediaBuyRequest): Promise<UpdateMediaBuySuccess> => {
+      const existing = this.mediaBuys.get(buyId);
+      if (!existing) {
+        throw new AdcpError('MEDIA_BUY_NOT_FOUND', {
+          recovery: 'terminal',
+          message: `media buy ${buyId} not found`,
+          field: 'media_buy_id',
+        });
+      }
+      if (patch.paused === true) existing.status = 'paused';
+      if (patch.paused === false && existing.status === 'paused') existing.status = 'active';
+      return { media_buy_id: existing.media_buy_id, status: existing.status, revision: existing.revision };
+    },
+
+    /**
+     * Sync per-creative review with mixed approved/pending rows. Review
+     * continues async — the seller's review pipeline pushes status changes
+     * via publishStatusChange when each creative reaches terminal state.
+     */
+    syncCreatives: async (creatives: CreativeAsset[]): Promise<SyncCreativesRow[]> => {
+      return creatives.map(c => {
+        const id = (c as { creative_id?: string }).creative_id ?? `cr_${Math.random()}`;
+        const formatId = (c as { format_id?: { id?: string } }).format_id?.id ?? '';
+        const needsReview = formatId.startsWith('video_');
+        if (needsReview) {
+          // Schedule the pending → approved transition for the demo
+          setTimeout(() => {
+            publishStatusChange({
+              account_id: 'prog_acc_1',
+              resource_type: 'creative',
+              resource_id: id,
+              payload: { status: 'approved', reviewed_at: new Date().toISOString() },
+            });
+          }, this.capabilities.config.creativeReviewMs).unref?.();
+        }
+        return {
+          creative_id: id,
+          action: 'created',
+          status: needsReview ? 'pending_review' : 'approved',
+        };
+      });
+    },
+
+    getMediaBuyDelivery: async (filter: GetMediaBuyDeliveryRequest): Promise<GetMediaBuyDeliveryResponse> => ({
+      currency: 'USD',
+      reporting_period: {
+        start: filter.start_date ?? '2026-04-01',
+        end: filter.end_date ?? '2026-04-30',
+      },
+      media_buy_deliveries: [],
+    }),
+
+    // Required on SalesPlatform — the example doesn't model persistent buys,
+    // so return empty array. Production adopters would query their store.
+    getMediaBuys: async () => ({ media_buys: [] }),
+  };
+}

package/examples/signals-agent.ts

@@ -16,7 +16,7 @@
  *   npx @adcp/sdk@latest http://localhost:3001/mcp get_signals '{"filters":{"catalog_types":["marketplace"]}}'
  */
 
-import { createAdcpServer, serve } from '@adcp/sdk';
+import { createAdcpServer, serve } from '@adcp/sdk/server/legacy/v5';
 import { createIdempotencyStore, memoryBackend } from '@adcp/sdk/server';
 import type { GetSignalsResponse, ServeContext } from '@adcp/sdk';
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adcp/sdk",
-  "version": "5.25.1",
+  "version": "6.0.0",
   "description": "AdCP SDK — client, server, and compliance harnesses for the AdContext Protocol (MCP + A2A)",
   "workspaces": [
     ".",
@@ -40,6 +40,11 @@
       "require": "./dist/lib/testing/index.js",
       "types": "./dist/lib/testing/index.d.ts"
     },
+    "./testing/personas": {
+      "import": "./dist/lib/testing/personas/index.js",
+      "require": "./dist/lib/testing/personas/index.js",
+      "types": "./dist/lib/testing/personas/index.d.ts"
+    },
     "./auth": {
       "import": "./dist/lib/auth/index.js",
       "require": "./dist/lib/auth/index.js",
@@ -50,6 +55,11 @@
       "require": "./dist/lib/server/index.js",
       "types": "./dist/lib/server/index.d.ts"
     },
+    "./server/legacy/v5": {
+      "import": "./dist/lib/server/legacy/v5/index.js",
+      "require": "./dist/lib/server/legacy/v5/index.js",
+      "types": "./dist/lib/server/legacy/v5/index.d.ts"
+    },
     "./signing": {
       "import": "./dist/lib/signing/index.js",
       "require": "./dist/lib/signing/index.js",
@@ -261,7 +271,8 @@
     "@a2a-js/sdk": "^0.3.4",
     "@modelcontextprotocol/sdk": "^1.17.5",
     "@opentelemetry/api": "^1.0.0",
-    "pg": "^8.0.0"
+    "pg": "^8.0.0",
+    "zod": "^4.1.0"
   },
   "peerDependenciesMeta": {
     "@opentelemetry/api": {

package/skills/build-brand-rights-agent/SKILL.md

@@ -219,7 +219,9 @@ Every AdCP request may include a `context` field. The framework echoes it back o
 | `serve(() => createAdcpServer(...))`         | Start HTTP server on `:3001/mcp`                             |
 | `adcpError(code, { message })`               | Structured error (BRAND_NOT_FOUND, RIGHTS_UNAVAILABLE, etc.) |
 
-Import: `import { createAdcpServer, serve, adcpError } from '@adcp/sdk';`
+Import: `import { createAdcpServer, serve, adcpError } from '@adcp/sdk/server/legacy/v5';`
+
+> **v6 specialism status.** `brandRights` is wired via the v5 `createAdcpServer` handler bag today. A v6 `BrandRightsPlatform` interface ships at `src/lib/server/decisioning/specialisms/brand-rights.ts` but the dispatcher path through `createAdcpServerFromPlatform` is not yet documented for adopters — pin to the legacy subpath until that lands.
 
 ## Setup
 
@@ -255,8 +257,13 @@ Single `.ts` file, one `createAdcpServer` call with a `brandRights` domain group
 Creative-approval webhooks are implemented as a regular outbound HTTP call — outside the MCP server, after you accept `acquire_rights`.
 
 ```typescript
-import { createAdcpServer, serve, adcpError } from '@adcp/sdk';
-import { createIdempotencyStore, memoryBackend } from '@adcp/sdk/server';
+import {
+  createAdcpServer,
+  serve,
+  adcpError,
+  createIdempotencyStore,
+  memoryBackend,
+} from '@adcp/sdk/server/legacy/v5';
 
 // Idempotency — required for v3. `acquire_rights` is mutating (issues
 // credentials + may trigger billing); `get_brand_identity` and

package/skills/build-creative-agent/SKILL.md

@@ -37,7 +37,7 @@ The `interaction_model` in each specialism's `index.yaml` is the forcing functio
 
 Full treatment in `skills/build-seller-agent/SKILL.md` §Protocol-Wide Requirements and §Composing. Minimum viable pointers for a creative agent:
 
-- **`idempotency_key`** on every mutating request (`sync_creatives`, `build_creative`, `report_usage`, any `sync_*` you implement). Wire `createIdempotencyStore` into `createAdcpServer({ idempotency })`.
+- **`idempotency_key`** on every mutating request (`sync_creatives`, `build_creative`, `report_usage`, any `sync_*` you implement). Pass `createIdempotencyStore` to `createAdcpServerFromPlatform(platform, { idempotency })`.
 - **Authentication** via `serve({ authenticate })` with `verifyApiKey`/`verifyBearer` from `@adcp/sdk/server`. Unauthenticated agents fail the universal `security_baseline` storyboard.
 - **Signature-header transparency**: accept requests with `Signature-Input`/`Signature` headers even if you don't claim `signed-requests`.
 
@@ -45,7 +45,7 @@ Full treatment in `skills/build-seller-agent/SKILL.md` §Protocol-Wide Requireme
 
 Creative review flows are naturally async — `sync_creatives` may return `pending_review` with a task envelope, and your review pipeline emits completion webhooks when the creative is approved, rejected, or transitions to a new state. `build_creative` for the ad-server archetype emits `report_usage` completion webhooks. Use `ctx.emitWebhook` — don't hand-roll `fetch` with HMAC signing.
 
-Wire `createAdcpServer({ webhooks: { signerKey } })` and call `ctx.emitWebhook({ url, payload, operation_id })` from any handler. The framework handles RFC 9421 signing, stable `idempotency_key` across retries, backoff + terminal error handling. Full pattern in [`skills/build-seller-agent/SKILL.md`](../build-seller-agent/SKILL.md) § Webhooks.
+Pass `webhooks: { signerKey }` to `createAdcpServerFromPlatform(platform, { webhooks })` and call `ctx.emitWebhook({ url, payload, operation_id })` from any handler. The framework handles RFC 9421 signing, stable `idempotency_key` across retries, backoff + terminal error handling. Full pattern in [`skills/build-seller-agent/SKILL.md`](../build-seller-agent/SKILL.md) § Webhooks.
 
 **`operation_id` rules** (the top at-least-once-delivery bug): stable across retries. `creative_review.${creative_id}` or `report_usage.${report_batch_id}` — NOT a fresh UUID per retry.
 
@@ -92,7 +92,7 @@ What happens when a creative is synced:
 >
 > **Cross-cutting pitfalls matrix runs keep catching:**
 >
-> - **Declare `capabilities: { specialisms: ['creative-ad-server'] }` (or `'creative-template'` / `'creative-generative'`) on `createAdcpServer`.** Value is `string[]` of enum ids (not `[{id, version}]`). Agents that don't declare their specialism fail the grader with "No applicable tracks found" even if every tool works — tracks are gated on the specialism claim.
+> - **Declare `capabilities.specialisms: ['creative-ad-server'] as const` (or `'creative-template'` / `'creative-generative'`) on the `DecisioningPlatform` you pass to `createAdcpServerFromPlatform`.** Value is `string[]` of enum ids (not `[{id, version}]`). Agents that don't declare their specialism fail the grader with "No applicable tracks found" even if every tool works — tracks are gated on the specialism claim.
 > - `build_creative` response is `{ creative_manifest: { format_id, assets } }` (single) or `{ creative_manifests: [...] }` (multi). Platform-native fields at the top level (`tag_url`, `creative_id`, `media_type`) are **invalid** — use `buildCreativeResponse({ creative_manifest })` / `buildCreativeMultiResponse({ creative_manifests })` from `@adcp/sdk/server` to lock the shape at compile time.
 > - Each asset in `creative_manifest.assets` requires an `asset_type` discriminator. Use the typed factories (`imageAsset`, `videoAsset`, `audioAsset`, `htmlAsset`, `urlAsset`, `textAsset`) so the discriminator is injected for you; a plain `{ serving_tag: { content: '<vast>...' } }` fails validation.
 > - `preview_creative` renders have the same pattern — each `renders[]` entry is a oneOf on `output_format`. Use `urlRender({...})`, `htmlRender({...})`, or `bothRender({...})` to inject the discriminator and require the matching `preview_url` / `preview_html` field automatically.
@@ -102,14 +102,14 @@ What happens when a creative is synced:
 
 **Handler bindings — read the Contract column entry before writing each return:**
 
-| Tool                    | Handler                        | Contract (field list)                                                 | Gotchas                                                                                                                                                                                            |
-| ----------------------- | ------------------------------ | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `get_adcp_capabilities` | auto-generated                 | n/a                                                                   | Do not register manually.                                                                                                                                                                          |
-| `list_creative_formats` | `creative.listCreativeFormats` | [`#list_creative_formats`](../../docs/llms.txt#list_creative_formats) | Each `renders[]` entry MUST have `role` + exactly one of `dimensions` (object) OR `parameters_from_format_id: true`. `{width, height}` shorthand fails — wrap in `dimensions`.                     |
-| `sync_creatives`        | `creative.syncCreatives`       | [`#sync_creatives`](../../docs/llms.txt#sync_creatives)               | Echo `creative_id`; `action` ∈ `created \| updated \| unchanged \| failed \| deleted`.                                                                                                             |
-| `list_creatives`        | `creative.listCreatives`       | [`#list_creatives`](../../docs/llms.txt#list_creatives)               | Honor `args.filters?.format_ids` when present. `created_date` + `updated_date` on each row are required ISO timestamps.                                                                            |
+| Tool                    | Handler                        | Contract (field list)                                                 | Gotchas                                                                                                                                                                                                                              |
+| ----------------------- | ------------------------------ | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `get_adcp_capabilities` | auto-generated                 | n/a                                                                   | Do not register manually.                                                                                                                                                                                                            |
+| `list_creative_formats` | `creative.listCreativeFormats` | [`#list_creative_formats`](../../docs/llms.txt#list_creative_formats) | Each `renders[]` entry MUST have `role` + exactly one of `dimensions` (object) OR `parameters_from_format_id: true`. `{width, height}` shorthand fails — wrap in `dimensions`.                                                       |
+| `sync_creatives`        | `creative.syncCreatives`       | [`#sync_creatives`](../../docs/llms.txt#sync_creatives)               | Echo `creative_id`; `action` ∈ `created \| updated \| unchanged \| failed \| deleted`.                                                                                                                                               |
+| `list_creatives`        | `creative.listCreatives`       | [`#list_creatives`](../../docs/llms.txt#list_creatives)               | Honor `args.filters?.format_ids` when present. `created_date` + `updated_date` on each row are required ISO timestamps.                                                                                                              |
 | `preview_creative`      | `creative.previewCreative`     | [`#preview_creative`](../../docs/llms.txt#preview_creative)           | `renders[].output_format` is a discriminator — use `urlRender({...})`, `htmlRender({...})`, or `bothRender({...})` so the discriminator is injected and the required `preview_url`/`preview_html` field is enforced at compile time. |
-| `build_creative`        | `creative.buildCreative`       | [`#build_creative`](../../docs/llms.txt#build_creative)               | Check `args.target_format_id` → library lookup; fall back to `args.creative_id`. Response requires `creative_manifest.format_id` + `creative_manifest.assets`.                                     |
+| `build_creative`        | `creative.buildCreative`       | [`#build_creative`](../../docs/llms.txt#build_creative)               | Check `args.target_format_id` → library lookup; fall back to `args.creative_id`. Response requires `creative_manifest.format_id` + `creative_manifest.assets`.                                                                       |
 
 Asset values use type-specific shapes, not a generic `asset_type` discriminator:
 
@@ -121,7 +121,7 @@ Asset values use type-specific shapes, not a generic `asset_type` discriminator:
 
 ### Context and Ext Passthrough
 
-`createAdcpServer` auto-echoes the request's `context` into every response from domain-grouped handlers — **do not set `context` yourself in your handler return values.** The framework injects it post-handler only when the field isn't already present.
+The framework auto-echoes the request's `context` into every response from typed sub-platform handlers — **do not set `context` yourself in your handler return values.** It's injected post-handler only when the field isn't already present.
 
 **Crucial:** `context` is schema-typed as an object. If your handler hand-sets a string or narrative description, validation fails with `/context: must be object` and the framework does not overwrite. Leave the field out entirely.
 
@@ -129,22 +129,23 @@ Some schemas also define an `ext` field for vendor-namespaced extensions. If you
 
 ## SDK Quick Reference
 
-| SDK piece                                                           | Usage                                                                     |
-| ------------------------------------------------------------------- | ------------------------------------------------------------------------- |
-| `createAdcpServer(config)`                                          | Create server with domain-grouped handlers and auto-capabilities          |
-| `serve(() => createAdcpServer(config))`                             | Start HTTP server on `:3001/mcp`                                          |
-| `creative: { listCreativeFormats, syncCreatives, ... }`             | Domain group — register handlers by name                                  |
-| `ctx.store.put(collection, id, data)`                               | Persist state (creative library) across requests                          |
-| `ctx.store.get(collection, id)`                                     | Retrieve persisted state                                                  |
-| `ctx.store.list(collection)`                                        | List all items in a collection (for `list_creatives`)                     |
-| `listCreativeFormatsResponse(data)`                                 | Auto-applied response builder (don't call manually)                       |
-| `syncCreativesResponse(data)`                                       | Auto-applied response builder (don't call manually)                       |
-| `listCreativesResponse(data)`                                       | Auto-applied response builder (don't call manually)                       |
-| `buildCreativeResponse(data)`                                       | Auto-applied response builder (don't call manually)                       |
-| `previewCreativeResponse(data)`                                     | Auto-applied response builder (don't call manually)                       |
-| `adcpError(code, { message })`                                      | Structured error                                                          |
-
-Import: `import { createAdcpServer, serve, adcpError } from '@adcp/sdk';`
+| SDK piece                                               | Usage                                                            |
+| ------------------------------------------------------- | ---------------------------------------------------------------- |
+| `createAdcpServerFromPlatform(platform, opts)`          | Create server from a typed `DecisioningPlatform` — compile-time specialism enforcement, auto-capabilities |
+| `createAdcpServer(config)` *(legacy)*                   | v5 handler-bag entry. Mid-migration / escape-hatch only; reach via `@adcp/sdk/server/legacy/v5`            |
+| `serve(() => createAdcpServerFromPlatform(platform, opts))` | Start HTTP server on `:3001/mcp`                                                                       |
+| `creative: { listCreativeFormats, syncCreatives, ... }` | Domain group — register handlers by name                         |
+| `ctx.store.put(collection, id, data)`                   | Persist state (creative library) across requests                 |
+| `ctx.store.get(collection, id)`                         | Retrieve persisted state                                         |
+| `ctx.store.list(collection)`                            | List all items in a collection (for `list_creatives`)            |
+| `listCreativeFormatsResponse(data)`                     | Auto-applied response builder (don't call manually)              |
+| `syncCreativesResponse(data)`                           | Auto-applied response builder (don't call manually)              |
+| `listCreativesResponse(data)`                           | Auto-applied response builder (don't call manually)              |
+| `buildCreativeResponse(data)`                           | Auto-applied response builder (don't call manually)              |
+| `previewCreativeResponse(data)`                         | Auto-applied response builder (don't call manually)              |
+| `adcpError(code, { message })`                          | Structured error                                                 |
+
+Import: `import { createAdcpServerFromPlatform, serve, adcpError } from '@adcp/sdk/server';`
 
 ## Setup
 
@@ -174,7 +175,7 @@ Minimal `tsconfig.json`:
 ## Implementation
 
 1. Single `.ts` file — all tools in one file
-2. Use `createAdcpServer` with a `creative` domain group — `get_adcp_capabilities` is auto-generated
+2. Use `createAdcpServerFromPlatform` with `creative: CreativeAdServerPlatform` (or `CreativeBuilderPlatform`) on a `DecisioningPlatform` class — `get_adcp_capabilities` is auto-generated
 3. Handlers return raw data objects — response builders are auto-applied
 4. Use `ctx.store` for persisting the creative library across requests (InMemoryStateStore by default)
 5. Register `preview_creative` manually on the returned server (union schema not in domain group)
@@ -182,8 +183,17 @@ Minimal `tsconfig.json`:
 7. Context passthrough is handled by the framework — no need to manually echo `args.context`
 
 ```typescript
-import { createAdcpServer, serve, adcpError, urlRender } from '@adcp/sdk';
-import { createIdempotencyStore, memoryBackend } from '@adcp/sdk/server';
+import {
+  createAdcpServerFromPlatform,
+  serve,
+  adcpError,
+  urlRender,
+  createIdempotencyStore,
+  memoryBackend,
+  type DecisioningPlatform,
+  type CreativeAdServerPlatform,
+  type AccountStore,
+} from '@adcp/sdk/server';
 
 const formats = [
   {
@@ -218,18 +228,24 @@ const idempotency = createIdempotencyStore({
   ttlSeconds: 86400, // 24 hours (spec bounds: 1h–7d)
 });
 
-serve(() => createAdcpServer({
-    name: 'My Creative Agent',
-    version: '1.0.0',
-    idempotency,
+class MyCreative implements DecisioningPlatform {
+  capabilities = {
+    specialisms: ['creative-ad-server'] as const,
+    config: {},
+  };
 
-    // Principal scoping for idempotency. MUST never return undefined —
-    // every mutating request would reject as SERVICE_UNAVAILABLE. A
-    // constant works for a demo; use ctx.account for multi-tenant prod.
-    resolveSessionKey: () => 'default-principal',
+  accounts: AccountStore = {
+    resolve: async ref => ({
+      id: 'account_id' in ref ? ref.account_id : 'cr_acc_1',
+      operator: 'me',
+      ctx_metadata: {},
+    }),
+    upsert: async () => ({ ok: true, items: [] }),
+    list: async () => ({ items: [], nextCursor: null }),
+  };
 
-    creative: {
-      listCreativeFormats: async (params, ctx) => {
+  creative: CreativeAdServerPlatform = {
+    listCreativeFormats: async (params, ctx) => {
         return { formats };
       },
 
@@ -288,28 +304,41 @@ serve(() => createAdcpServer({
         };
       },
 
-      previewCreative: async (params) => {
-        return {
-          response_type: 'single',
-          previews: [
-            {
-              preview_id: `prev_${Date.now()}`,
-              input: { name: params.creative_manifest?.name ?? 'Preview' },
-              renders: [
-                urlRender({
-                  render_id: `r_${Date.now()}`,
-                  preview_url: 'https://example.com/preview.png',
-                  role: 'primary',
-                  dimensions: { width: 300, height: 250 },
-                }),
-              ],
-            },
-          ],
-          expires_at: new Date(Date.now() + 3600000).toISOString(),
-        };
-      },
+    previewCreative: async params => {
+      return {
+        response_type: 'single',
+        previews: [
+          {
+            preview_id: `prev_${Date.now()}`,
+            input: { name: params.creative_manifest?.name ?? 'Preview' },
+            renders: [
+              urlRender({
+                render_id: `r_${Date.now()}`,
+                preview_url: 'https://example.com/preview.png',
+                role: 'primary',
+                dimensions: { width: 300, height: 250 },
+              }),
+            ],
+          },
+        ],
+        expires_at: new Date(Date.now() + 3600000).toISOString(),
+      };
     },
-  }));
+  };
+}
+
+const platform = new MyCreative();
+
+serve(() =>
+  createAdcpServerFromPlatform(platform, {
+    name: 'My Creative Agent',
+    version: '1.0.0',
+    idempotency,
+    // Principal scoping for idempotency. MUST never return undefined —
+    // every mutating request would reject as SERVICE_UNAVAILABLE.
+    resolveSessionKey: () => 'default-principal',
+  })
+);
 ```
 
 ### Key implementation detail: creative library
@@ -511,9 +540,10 @@ Common failure decoder:
 
 | Mistake                                                                | Fix                                                                                                                                 |
 | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| Using `createTaskCapableServer` + `server.tool()`                      | Use `createAdcpServer` with `creative` domain group                                                                                 |
-| Manually registering `get_adcp_capabilities`                           | Auto-generated by `createAdcpServer` from registered handlers                                                                       |
-| Calling `server.registerTool('preview_creative', ...)`                 | `AdcpServer` does not expose `registerTool` — put `previewCreative` in the `creative:` domain group like the other handlers        |
+| Using `createTaskCapableServer` + `server.tool()`                      | Use `createAdcpServerFromPlatform` with a typed `creative: CreativeAdServerPlatform` (or `CreativeBuilderPlatform`) field           |
+| Calling `createAdcpServer` directly in new code                        | Reach for `createAdcpServerFromPlatform`; `createAdcpServer` lives at `@adcp/sdk/server/legacy/v5` for mid-migration / escape-hatch only |
+| Manually registering `get_adcp_capabilities`                           | Auto-generated by `createAdcpServerFromPlatform` from your typed `DecisioningPlatform` — do not register it                         |
+| Calling `server.registerTool('preview_creative', ...)`                 | `AdcpServer` does not expose `registerTool` — put `previewCreative` in the `creative:` domain group like the other handlers         |
 | Using module-level Maps for state                                      | Use `ctx.store.put/get/list` — framework provides `InMemoryStateStore` by default                                                   |
 | Calling response builders manually in domain handlers                  | Handlers return raw data — response builders are auto-applied across the `creative:` group, including `preview_creative`            |
 | `list_creatives` ignores format filter                                 | Check `args.filters?.format_ids` and filter results                                                                                 |