@adcp/sdk 6.5.0 → 6.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adcp/sdk",
-  "version": "6.5.0",
+  "version": "6.7.0",
   "description": "AdCP SDK — client, server, and compliance harnesses for the AdContext Protocol (MCP + A2A)",
   "workspaces": [
     ".",
@@ -110,6 +110,16 @@
       "require": "./dist/lib/express-mcp/index.js",
       "types": "./dist/lib/express-mcp/index.d.ts"
     },
+    "./mock-server": {
+      "import": "./dist/lib/mock-server/index.js",
+      "require": "./dist/lib/mock-server/index.js",
+      "types": "./dist/lib/mock-server/index.d.ts"
+    },
+    "./upstream-recorder": {
+      "import": "./dist/lib/upstream-recorder/index.js",
+      "require": "./dist/lib/upstream-recorder/index.js",
+      "types": "./dist/lib/upstream-recorder/index.d.ts"
+    },
     "./package.json": "./package.json"
   },
   "typesVersions": {
@@ -164,6 +174,12 @@
       ],
       "express-mcp": [
         "dist/lib/express-mcp/index.d.ts"
+      ],
+      "mock-server": [
+        "dist/lib/mock-server/index.d.ts"
+      ],
+      "upstream-recorder": [
+        "dist/lib/upstream-recorder/index.d.ts"
       ]
     }
   },
@@ -190,8 +206,12 @@
     "build": "npm run build:lib",
     "build:lib": "npm run sync-version && tsc --project tsconfig.lib.json && tsx scripts/copy-schemas-to-dist.ts",
     "build:test-agents": "npm run build:lib && tsc -p test-agents/tsconfig.json --rootDir test-agents",
+    "pretest": "npm run schemas:ensure",
     "test": "NODE_ENV=test node --test-timeout=60000 --test-force-exit --test test/*.test.js test/lib/*.test.js",
+    "pretest:lib": "npm run schemas:ensure",
     "test:lib": "NODE_ENV=test node --test-timeout=60000 --test-force-exit --test test/lib/*.test.js",
+    "pretest:examples": "npm run build",
+    "test:examples": "NODE_ENV=test node --test-timeout=180000 --test-force-exit --test-concurrency=1 --test test/examples/*.test.js",
     "test:e2e": "node test/e2e/adcp-e2e.test.js",
     "test:protocols": "node test/run-protocol-tests.js",
     "changeset": "changeset",
@@ -206,8 +226,11 @@
     "sync-schemas": "tsx scripts/sync-schemas.ts",
     "sync-schemas:v2.5": "tsx scripts/sync-v2-5-schemas.ts",
     "sync-schemas:all": "npm run sync-schemas && npm run sync-schemas:v2.5",
+    "schemas:ensure": "tsx scripts/schemas-ensure.ts",
     "schema-diff": "tsx scripts/schema-diff.ts",
-    "generate-types": "tsx scripts/generate-types.ts && tsx scripts/generate-enum-arrays.ts",
+    "generate-types": "tsx scripts/generate-types.ts && tsx scripts/generate-enum-arrays.ts && tsx scripts/generate-manifest-derived.ts && tsx scripts/generate-entity-hydration.ts",
+    "generate-manifest-derived": "tsx scripts/generate-manifest-derived.ts",
+    "generate-entity-hydration": "tsx scripts/generate-entity-hydration.ts",
     "generate-types:v2.5": "tsx scripts/generate-v2-5-types.ts",
     "generate-types:all": "npm run generate-types && npm run generate-types:v2.5",
     "generate-registry-types": "tsx scripts/generate-registry-types.ts",
@@ -220,6 +243,7 @@
     "compliance:skill-matrix": "tsx scripts/manual-testing/run-skill-matrix.ts",
     "typecheck:skill-examples": "tsx scripts/typecheck-skill-examples.ts",
     "check:skill-sync": "tsx scripts/check-skill-sync.ts",
+    "check:adopter-types": "tsx scripts/check-adopter-types.ts",
     "sync-version": "tsx scripts/sync-version.ts",
     "validate-schemas": "tsx scripts/validate-schemas.ts",
     "lint": "eslint 'src/lib/testing/**/*.ts'",
@@ -238,6 +262,7 @@
     "ci:pre-push": "npm run ci:schema-check && npm run ci:quick",
     "hooks:install": "node scripts/install-hooks.js",
     "hooks:uninstall": "rm -f .git/hooks/pre-push",
+    "hello-cluster": "tsx examples/hello-cluster.ts",
     "registry:cron": "tsx src/registry/cron.ts",
     "registry:validate-all": "tsx src/registry/cron.ts --all",
     "registry:validate-pending": "tsx src/registry/cron.ts --pending",
@@ -275,7 +300,9 @@
     "ajv-formats": "^3.0.1",
     "fast-check": "^3.23.2",
     "jose": "^6.2.2",
+    "secure-json-parse": "^4.1.0",
     "structured-headers": "^2.0.2",
+    "tldts": "^7.0.29",
     "undici": "^6.25.0",
     "yaml": "^2.7.1"
   },
@@ -332,5 +359,5 @@
     },
     "minimatch": "^10.2.1"
   },
-  "adcp_version": "3.0.1"
+  "adcp_version": "3.0.5"
 }

package/skills/SHAPE-GOTCHAS.md

@@ -0,0 +1,233 @@
+# Common shape gotchas
+
+Discriminated-union and embedded-shape patterns adopters consistently get wrong on the first pass. The strict response validators in the storyboard runner catch these at runtime; type checkers don't, because the types are technically satisfiable in the wrong shape. Each entry below: the wrong shape adopters write first, the right shape, and a one-line "why."
+
+Six patterns surfaced repeatedly while building reference adapters (`examples/hello_{seller,creative,signals}_adapter_*.ts`) and during blind LLM matrix runs. Catching them costs 1–3 iterations of "why is this field reported missing?" — this page is the shortcut.
+
+---
+
+## 1. `ActivationKey` `oneOf` — `key`/`value` are top-level, not nested
+
+When returning `activate_signal` deployments with `type: 'key_value'` activation keys, `key` and `value` sit at the TOP level of `activation_key`. NOT nested under a `key_value` sub-field.
+
+✗ Wrong (intuitive — the discriminator name *suggests* nesting):
+
+```ts
+activation_key: {
+  type: 'key_value',
+  key_value: { key: 'segment', value: 'abc123' },
+}
+```
+
+✓ Right (matches `/schemas/3.0/core/activation-key.json` `oneOf[1]`):
+
+```ts
+activation_key: {
+  type: 'key_value',
+  key: 'segment',
+  value: 'abc123',
+}
+```
+
+`value` MUST be a string. The schema allows a `segment_id` variant for platform-segment-id activations:
+
+```ts
+activation_key: { type: 'segment_id', segment_id: 'plat_seg_xyz' }
+```
+
+— same flatness, single string ID under the discriminator.
+
+---
+
+## 2. `signal_ids` is `signal_id[]` (provenance objects), not `string[]`
+
+`get_signals` accepts a `signal_ids` filter to look up specific signals by data-provider provenance. The filter is an array of provenance tuples, NOT bare ID strings.
+
+✗ Wrong:
+
+```ts
+{ signal_ids: ['cohort_abc', 'cohort_xyz'] }
+```
+
+✓ Right (matches `/schemas/3.0/core/signal-id.json`):
+
+```ts
+{
+  signal_ids: [
+    { source: 'catalog', data_provider_domain: 'tridentauto.example', id: 'likely_ev_buyers' },
+    { source: 'catalog', data_provider_domain: 'tridentauto.example', id: 'purchase_propensity' },
+  ],
+}
+```
+
+`SignalID` is a discriminated union: `source: 'catalog'` (with `data_provider_domain` + `id`) or `source: 'agent'` (with `agent_url` + `id`). When implementing the filter on the seller side, narrow on `source` before reading `data_provider_domain` — only the catalog variant has it.
+
+---
+
+## 3. `VASTAsset` requires an embedded `delivery_type` discriminator
+
+`asset_type: 'vast'` is itself a discriminator at the asset level. A *second* discriminator (`delivery_type`) picks between inline VAST XML and a redirect URL. Both are required; you can't pass `content` or `vast_url` without `delivery_type`.
+
+✗ Wrong (flat `content` without `delivery_type`):
+
+```ts
+{ asset_type: 'vast', content: '<VAST version="4.2">...</VAST>' }
+```
+
+✓ Right — inline VAST:
+
+```ts
+{ asset_type: 'vast', delivery_type: 'inline', content: '<VAST version="4.2">...</VAST>' }
+```
+
+✓ Right — redirect VAST:
+
+```ts
+{ asset_type: 'vast', delivery_type: 'redirect', vast_url: 'https://ad-server.example/vast/abc.xml' }
+```
+
+Same pattern applies to `DAASTAsset` (audio).
+
+---
+
+## 4. `PreviewCreativeResponse` is a three-way discriminated union
+
+`preview_creative` returns one of `single | batch | variant`, with `response_type` as the discriminator. Even single-preview responses use the `previews[]` ARRAY shape — the validator grades per variant and won't accept a flat single-preview shape.
+
+✗ Wrong (flat object, no discriminator):
+
+```ts
+{ preview: { type: 'url', url: 'https://...', expires_at: '...' } }
+```
+
+✓ Right (single-variant `previews[]` array):
+
+```ts
+{
+  response_type: 'single',
+  previews: [
+    {
+      preview_id: 'prv_abc',
+      renders: [
+        {
+          render_id: 'rnd_1',
+          output_format: 'url',
+          preview_url: 'https://preview.example/abc',
+          role: 'primary',
+        },
+      ],
+      input: { name: 'default' },
+    },
+  ],
+  expires_at: '2026-05-03T00:00:00Z',
+}
+```
+
+Each `PreviewRender` requires `render_id`, `output_format: 'url'` (or `'inline_html'`), `preview_url`, and `role`. Don't omit `role` — the validator requires it.
+
+---
+
+## 5. `BuildCreativeReturn` has 4 valid shapes — framework auto-wraps the bare manifest
+
+`build_creative` handlers can return any of:
+
+```ts
+type BuildCreativeReturn =
+  | CreativeManifest                    // bare single — framework wraps as { creative_manifest: <obj> }
+  | CreativeManifest[]                  // bare multi  — framework wraps as { creative_manifests: <arr> }
+  | BuildCreativeSuccess                // shaped single — passthrough; you set sandbox/expires_at/preview
+  | BuildCreativeMultiSuccess           // shaped multi  — passthrough
+```
+
+Easy mistake: return a bare `CreativeManifest` and confirm the response *seems* fine via tests that read `response.format_id` directly. The wire shape after framework wrapping is `response.creative_manifest.format_id` — a level deeper. Storyboards check the wire path; if you didn't go through the framework wrapper in your test, the storyboard will surface "field missing at `creative_manifest.format_id`" while your local test passes.
+
+If you need to set `sandbox: true` or attach `preview` previews, return the shaped envelope directly:
+
+```ts
+return {
+  creative_manifest: { format_id: { agent_url, id }, assets },
+  sandbox: true,
+  expires_at: '2026-05-03T00:00:00Z',
+};
+```
+
+---
+
+## 6. `log_event` projection for walled-garden CAPIs
+
+Sales-social adopters fronting walled-garden conversion APIs translate AdCP's `log_event` wire shape onto the upstream CAPI's. Three projections trip every walled-garden integration on the first pass — the upstream returns `400` and the AdCP wire surface gives no hint that the field name or encoding was the problem.
+
+| AdCP wire (`Event`)                                                            | Walled-garden CAPI                                                                          | Translation                                                                  |
+| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| `event_type` (string)                                                          | `event_name` (string)                                                                       | rename on the way out                                                        |
+| `event_time` (ISO 8601 string)                                                 | `event_time` (UNIX seconds, number)                                                         | `Math.floor(new Date(t).getTime() / 1000)`                                   |
+| `user_match` (`hashed_email` / `hashed_phone` / `uids[]` / `click_id` / `client_ip`+`client_user_agent`) | `user_data.{email_sha256,phone_sha256,external_id_sha256}` (≥1 required) | map per the upstream's identifier types; drop events with empty `user_match` |
+
+### 6.1 `event_name`, not `event_type`
+
+✗ Wrong (passes AdCP type-check, fails the walled-garden 400):
+
+```ts
+upstream.trackEvents({ events: req.events });
+```
+
+✓ Right:
+
+```ts
+upstream.trackEvents({
+  events: req.events.map(e => ({
+    event_name: e.event_type,
+    // …other fields…
+  })),
+});
+```
+
+### 6.2 UNIX seconds, not ISO 8601
+
+✗ Wrong:
+
+```ts
+{ event_time: e.event_time }                 // '2026-04-05T14:30:00Z'
+```
+
+✓ Right:
+
+```ts
+{ event_time: Math.floor(new Date(e.event_time).getTime() / 1000) }
+```
+
+### 6.3 Hashed-identifier requirement — read `Event.user_match`, drop on empty
+
+Every walled-garden CAPI rejects events without at least one matchable identifier in `user_data` — typically `email_sha256`, `phone_sha256`, or `external_id_sha256` (64-char lowercase hex SHA-256). The AdCP wire field is `Event.user_match` (per `/schemas/3.0.4/core/user-match.json` — `hashed_email`, `hashed_phone`, `uids[]`, `click_id`, `client_ip`+`client_user_agent`). Project it onto the upstream's `user_data` shape; **drop events with empty `user_match`** rather than synthesize a fake identifier.
+
+```ts
+const userData: { external_id_sha256?: string; email_sha256?: string; phone_sha256?: string } = {};
+if (e.user_match?.hashed_email) userData.email_sha256 = e.user_match.hashed_email;
+if (e.user_match?.hashed_phone) userData.phone_sha256 = e.user_match.hashed_phone;
+const firstUid = e.user_match?.uids?.[0]?.value;
+if (firstUid && /^[a-f0-9]{64}$/.test(firstUid)) userData.external_id_sha256 = firstUid;
+if (Object.keys(userData).length === 0) continue; // drop unmatchable events
+```
+
+✗ **Do not** synthesize `external_id_sha256` from `event_id` (or any non-identity field). `event_id` is a buyer-side dedup string per `/schemas/3.0.4/core/event.json`; hashing it and shipping as a stable user identifier fabricates a matching signal the buyer never granted, joins unrelated events as the "same user" in the platform's identity graph, and pollutes attribution. The defensible behavior is to drop unmatchable events and surface the delta via `events_received` − `events_processed` so the buyer can populate `user_match` and retry.
+
+The `examples/hello_seller_adapter_social.ts` reference adapter codifies all three patterns in its `logEvent` handler; build-seller-agent §sales-social references this section, and AdCP's `createTranslationMap` helper (#1285) handles the buyer→upstream id mapping when the buyer carries a `media_buy_id` that needs translation to an upstream pixel-source id.
+
+---
+
+## How to debug a "Field not found at path: …" error fast
+
+The validator's path naming is precise. When you see:
+
+```
+✗ Response matches schema: : Invalid input;
+✗ Field not found at path: deployments[0].activation_key
+```
+
+Three steps:
+
+1. Find the schema file the validator names (typically `/schemas/3.0/<protocol>/<task>-response.json` or `/schemas/3.0/core/<type>.json`).
+2. Inside the schema, find the `oneOf` (or `anyOf`) at that path. The error path tells you which variant the validator was trying to match.
+3. Compare the schema's required fields to your actual response. The wrong shape tells you which discriminator branch you accidentally landed on.
+
+Schemas are the authoritative spec for shape. Prose around the schema (in skills, in field descriptions) is supplementary — when prose and schema disagree, the schema wins, and the validator agrees with the schema.

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

@@ -13,7 +13,7 @@ A brand rights agent represents a brand's identity and licensing. Buyers discove
 
 - User wants to build an agent that manages brand identity and licensing
 - User mentions brand rights, brand guidelines, creative approval, or licensing
-- User references `get_brand_identity`, `get_rights`, or `acquire_rights`
+- User references `get_brand_identity`, `get_rights`, `acquire_rights`, `update_rights`, or `creative_approval`
 
 **Not this skill:**
 
@@ -23,9 +23,9 @@ A brand rights agent represents a brand's identity and licensing. Buyers discove
 
 ## Specialisms This Skill Covers
 
-| Specialism     | Status | Delta                                                                                                                                                                                |
-| -------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------ |
-| `brand-rights` | stable | First-class tools: `get_brand_identity`, `get_rights`, `acquire_rights`. `update_rights` and `creative_approval` are spec-tracked but not schema-backed (see Protocol Status below). | [§ brand-rights](#specialism-brand-rights) |
+| Specialism     | Status | Delta                                                                                                                                                                                  | See                                        |
+| -------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
+| `brand-rights` | stable | First-class tools: `get_brand_identity`, `get_rights`, `acquire_rights`, `update_rights`. `creative_approval` is webhook-only — wire your HTTP receiver at the `approval_webhook` URL. | [§ brand-rights](#specialism-brand-rights) |
 
 Storyboard: `brand_rights`. The specialism tests identity discovery → rights search → acquisition → enforcement (including expired-campaign denial).
 
@@ -33,7 +33,7 @@ Storyboard: `brand_rights`. The specialism tests identity discovery → rights s
 
 Full treatment in `skills/build-seller-agent/SKILL.md` §Protocol-Wide Requirements and §Composing. Minimum viable pointers:
 
-- **`idempotency_key`** on every mutating request (`acquire_rights` — and `update_rights` / `creative_approval` once their schemas land). Wire `createIdempotencyStore` into `createAdcpServer({ idempotency })`.
+- **`idempotency_key`** on every mutating request (`acquire_rights`, `update_rights`, and the `creative_approval` webhook payload). Wire `createIdempotencyStore` into `createAdcpServer({ idempotency })`. The framework auto-applies idempotency middleware to mutating tools; for the `creative_approval` webhook receiver, validate `idempotency_key` yourself and replay the cached verdict on resubmission.
 - **Authentication** via `serve({ authenticate })` with `verifyApiKey`/`verifyBearer` from `@adcp/sdk/server`. Unauthenticated agents fail the universal `security_baseline` storyboard.
 - **Signature-header transparency**: accept `Signature-Input`/`Signature` headers even if you don't claim `signed-requests`.
 
@@ -68,17 +68,15 @@ How are generated creatives reviewed?
 
 ## Protocol Status
 
-Three tools are first-class in the `brandRights` domain group. Two additional operations are spec-tracked but not yet schema-backed.
+Four MCP/A2A tools are first-class in the `brandRights` domain group. `creative_approval` is webhook-only — the spec models it as an HTTP POST from the buyer to the `approval_webhook` URL the seller returned in `acquire_rights`.
 
-| Operation            | Status                                        | How to implement                                                  |
-| -------------------- | --------------------------------------------- | ----------------------------------------------------------------- |
-| `get_brand_identity` | Published schema — `brand/get-brand-identity` | `brandRights.getBrandIdentity` handler                            |
-| `get_rights`         | Published schema — `brand/get-rights`         | `brandRights.getRights` handler                                   |
-| `acquire_rights`     | Published schema — `brand/acquire-rights`     | `brandRights.acquireRights` handler                               |
-| `update_rights`      | Spec prose only — no JSON schema              | HTTP endpoint outside MCP surface                                 |
-| `creative_approval`  | Webhook contract, no JSON schema              | HTTP endpoint your agent hosts (URL returned in `acquire_rights`) |
-
-Upstream tracking for the two schema gaps: https://github.com/adcontextprotocol/adcp/issues/2253. The SDK will register handlers for both once schemas land.
+| Operation            | Status                                          | How to implement                                                                                       |
+| -------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `get_brand_identity` | Published schema — `brand/get-brand-identity`   | `brandRights.getBrandIdentity` handler                                                                 |
+| `get_rights`         | Published schema — `brand/get-rights`           | `brandRights.getRights` handler                                                                        |
+| `acquire_rights`     | Published schema — `brand/acquire-rights`       | `brandRights.acquireRights` handler                                                                    |
+| `update_rights`      | Published schema — `brand/update-rights`        | `brandRights.updateRights` handler (mutating)                                                          |
+| `creative_approval`  | Published schema — `brand/creative-approval`    | Webhook receiver at the URL you returned in `acquire_rights.approval_webhook`; dispatch to `brandRights.reviewCreativeApproval` |
 
 <a name="specialism-brand-rights"></a>
 
@@ -193,7 +191,114 @@ Three success variants plus an error variant. The most common is `acquired`. Thr
 { rights_id, status: 'rejected', brand_id, reason, suggestions? }
 ```
 
-**Creative approval.** The `approval_webhook` in your `acquire_rights` response is a URL **your agent hosts** — the buyer POSTs `creative-approval-request` there when a generated creative needs review. Payload shapes (`creative-approval-request`/`creative-approval-response`) are spec-tracked but not yet schema-published (adcontextprotocol/adcp#2253); accept at minimum the creative reference and a `rights_grant_id`, return a decision.
+**`update_rights`** — returns either a success arm (with re-issued credentials) or the error arm
+
+Mutating; framework auto-applies idempotency middleware. Carry only the fields you're changing — omitted fields stay at their current value (parallels `update_media_buy` semantics). The framework hydrates the underlying grant from `rights_id`, so handlers read the resolved grant from `ctx.store`.
+
+```typescript
+// Success — change applied
+{
+  rights_id: 'likeness_commercial_standard',
+  terms: { /* updated rights-terms shape */ },
+  generation_credentials: [ /* re-issued with the new constraint */ ],
+  rights_constraint: { /* updated for re-embedding in creative manifests */ },
+  paused: false,
+  implementation_date: '2026-05-02T19:00:00Z',  // string when live immediately
+}
+// Pending rights-holder approval
+{
+  rights_id: 'likeness_commercial_standard',
+  terms: { /* updated terms */ },
+  implementation_date: null,                     // null = follow-up via push_notification_config webhook
+}
+// Error — buyer-fixable rejection. Throw `adcpError('INVALID_REQUEST', ...)`
+// for single-error cases; the multi-error arm is for batch failures.
+{
+  errors: [{ code: 'INVALID_REQUEST', message: 'impression_cap below delivered count' }],
+}
+```
+
+Common rejections to surface as errors: `impression_cap` below already-delivered count, `end_date` earlier than current `end_date`, switching to a `pricing_option_id` from a different `get_rights` offering than the original.
+
+**Creative approval (webhook).** The `approval_webhook` in your `acquire_rights` response is a URL **your agent hosts** — the buyer POSTs `CreativeApprovalRequest` there when a generated creative needs review. Schema is published in 3.0.x (`brand/creative-approval-{request,response}.json`); the SDK does NOT register this as an MCP/A2A tool because it's webhook-only.
+
+The receiver pattern: **authenticate first**, then validate the request body with `CreativeApprovalRequestSchema`, dispatch to `brandRights.reviewCreativeApproval(req, ctx)`, and serialize the result with the typed builders.
+
+> **Security order matters.** The auth check (Bearer token from `acquire_rights.approval_webhook.authentication.credentials`, or your RFC 9421 signature verifier) MUST run **before** the idempotency-store lookup. The cache is a verdict store keyed by `(principal, idempotency_key)`; an unauthenticated lookup turns the endpoint into a replay-existence oracle and lets anyone who can reach the URL pull back a previously-issued verdict. Same posture as `acquire_rights` — apply the same `verifyApiKey` / signature middleware to this route.
+
+> **SSRF on `creative_url`.** The buyer's `creative_url` is a buyer-controlled URL the brand-rights agent typically fetches to render or scan for review. Treat it like any inbound URL: route through your standard SSRF-guarded HTTP client (https-only in prod, no RFC 1918 / loopback / link-local / metadata-service IPs). The SDK applies the same allowlist on `push_notification_config.url` via `extractPushConfig` — match that posture for `creative_url`.
+
+```typescript
+import express from 'express';
+import {
+  creativeApprovalApproved,
+  creativeApprovalRejected,
+  creativeApprovalPendingReview,
+} from '@adcp/sdk/server';
+import { CreativeApprovalRequestSchema } from '@adcp/sdk/types';
+
+const app = express();
+// Cap payload size to bound a hostile body.
+app.use(express.json({ limit: '256kb' }));
+
+// Auth middleware — verify Bearer token / RFC 9421 signature against the
+// (principal, rights_id) you advertised on `acquire_rights`. Run BEFORE
+// idempotency-store lookup; verdicts are tenant-scoped state.
+app.use('/webhooks/creative-approval', verifyApprovalWebhookAuth);
+
+app.post('/webhooks/creative-approval', async (req, res) => {
+  const parsed = CreativeApprovalRequestSchema.safeParse(req.body);
+  if (!parsed.success) {
+    return res.status(400).json({ errors: [{ code: 'INVALID_REQUEST', message: 'malformed creative-approval request' }] });
+  }
+
+  // Idempotency — keyed by (authenticated principal, idempotency_key) so
+  // verdicts can't leak across tenants. Replay the cached verdict if seen.
+  const principal = req.adcpPrincipal; // set by verifyApprovalWebhookAuth
+  const cached = await idempotencyStore.get(`${principal}:${parsed.data.idempotency_key}`);
+  if (cached) return res.json(cached);
+
+  // Dispatch to the platform — same `reviewCreativeApproval` method shape
+  // as if it were a tool. The framework doesn't auto-wire HTTP for webhook-
+  // only surfaces, so adopters host the route themselves.
+  try {
+    const verdict = await platform.brandRights.reviewCreativeApproval(parsed.data, /* ctx built per request */);
+    await idempotencyStore.set(`${principal}:${parsed.data.idempotency_key}`, verdict);
+    return res.json(verdict);
+  } catch (err) {
+    return res.status(500).json({ errors: [{ code: 'INTERNAL_ERROR', message: err.message }] });
+  }
+});
+```
+
+Three success arms (Approved / Rejected / PendingReview) plus an error arm. Arm choice depends on review pipeline — auto-approve immediately, route to human review, or pre-flight reject for hard violations. Use the typed builders so the discriminator (`status`) is injected for you:
+
+```typescript
+// Approved
+creativeApprovalApproved({
+  rights_id: 'likeness_commercial_standard',
+  creative_id: 'cr_42',
+  creative_url: 'https://buyer.example.com/creatives/42.mp4',
+  approved_at: new Date().toISOString(),
+  conditions: ['approved for NL only'],   // optional
+});
+
+// Rejected
+creativeApprovalRejected({
+  rights_id: 'likeness_commercial_standard',
+  creative_id: 'cr_42',
+  reason: 'logo not visible per brand standards',
+  suggestions: ['enlarge the logo to 15% of the frame'],
+});
+
+// Pending — buyer polls `status_url` or waits up to `estimated_response_time`
+creativeApprovalPendingReview({
+  rights_id: 'likeness_commercial_standard',
+  creative_id: 'cr_42',
+  estimated_response_time: '24h',
+  status_url: 'https://brand.example/approvals/cr_42',
+});
+```
 
 **Revocation webhook.** The `acquire_rights` _request_ carries a required `revocation_webhook`. Persist it against the grant. When you need to revoke (credential rotation, terms violation, brand takedown), use `ctx.emitWebhook` — don't hand-roll `fetch`. See [`skills/build-seller-agent/SKILL.md`](../build-seller-agent/SKILL.md) § Webhooks for the full wiring; minimal call:
 

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

@@ -9,6 +9,8 @@ description: Use when building an AdCP creative agent — an ad server, creative
 
 A creative agent manages the creative lifecycle: accepts assets from buyers, stores them in a library, builds serving tags, and renders previews. Unlike a generative seller (which also sells inventory), a creative agent is a standalone creative platform — it manages creatives but doesn't sell media.
 
+> **Common shape gotchas:** `PreviewCreativeResponse` is a three-way discriminated union (`single` | `batch` | `variant`); `BuildCreativeReturn` has 4 valid shapes (framework auto-wraps bare manifests); `VASTAsset` requires `delivery_type` (`'inline'` or `'redirect'`) before `content`/`vast_url`. See [SHAPE-GOTCHAS.md](../SHAPE-GOTCHAS.md) for the patterns adopters consistently get wrong on first pass — schema validators catch these at runtime; type checkers don't.
+
 ## When to Use
 
 - User wants to build an ad server, creative management platform, or creative rendering service
@@ -93,6 +95,26 @@ What happens when a creative is synced:
 > **Cross-cutting pitfalls matrix runs keep catching:**
 >
 > - **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.
+> - **`list_creative_formats` response — each `Format` MUST have strict-shape `renders[]` and `assets[]`** (matrix v2 PR #1207 keeps catching this).
+>   - `renders[i]` requires `role` (string) PLUS exactly one of `dimensions: { width, height }` (object — NOT `{ width, height }` inline at the render root) OR `parameters_from_format_id: true`.
+>   - `assets[i]` requires the **discriminator quartet**: `item_type: 'individual' as const` + `asset_id` + `asset_type` (`'image'`/`'video'`/`'audio'`/`'text'`/`'click_url'`/`'html'`) + `required: boolean`. Missing any of these fails strict validation with `must match exactly one schema in oneOf`.
+>
+>   ```ts
+>   // ✗ WRONG — passes lenient mode but fails strict (the actual mistake matrix v2 catches)
+>   { format_id, renders: [{ width: 300, height: 250 }],
+>     assets: [{ asset_id: 'image', required: true }] }
+>
+>   // ✓ RIGHT — passes strict
+>   { format_id,
+>     renders: [{ role: 'primary', dimensions: { width: 300, height: 250 } }],
+>     assets: [{
+>       item_type: 'individual' as const,
+>       asset_id: 'image',
+>       asset_type: 'image',
+>       required: true,
+>       accepted_media_types: ['image/jpeg', 'image/png'],
+>     }] }
+>   ```
 > - `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.
@@ -105,7 +127,7 @@ What happens when a creative is synced:
 | 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`.                                                       |
+| `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. Each `assets[]` entry MUST have `item_type: 'individual' as const` + `asset_id` + `asset_type` (image/video/audio/text/click_url/html) + `required: boolean`. See the strict-shape callout above the table. |
 | `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. |
@@ -670,6 +692,8 @@ Output formats returned by `list_creative_formats` for ad servers are **serving-
 
 Storyboard: `creative_template`. Stateless — build from the inline `creative_manifest` in the request, do not call `ctx.store`.
 
+**Fork target**: `examples/hello_creative_adapter_template.ts` is the worked, passing reference adapter for this specialism. CI gates strict tsc + storyboard pass + upstream-traffic façade. Replace the `// SWAP:` markers with calls to your real backend.
+
 Formats declare `variables` the template will substitute:
 
 ```typescript