@adcp/sdk 6.6.0 → 6.7.0

package/docs/llms.txt

@@ -1,9 +1,10 @@
 # Ad Context Protocol (AdCP)
 
-> Generated at: 2026-05-01
-> Library: @adcp/sdk v6.1.0
+> Generated at: 2026-05-03
+> Library: @adcp/sdk v6.6.0
 > 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.
 
 ## What is AdCP
 
@@ -16,22 +17,25 @@ AdCP is an open protocol for AI agents to buy, manage, and optimize advertising
 
 ```typescript
 import { serve } from '@adcp/sdk';
-import { createAdcpServerFromPlatform } from '@adcp/sdk/server';
+import {
+  createAdcpServerFromPlatform,
+  definePlatform,
+  defineSignalsPlatform,
+} from '@adcp/sdk/server';
 
-const platform = {
+const platform = definePlatform({
   capabilities: {
     specialisms: ['signal-marketplace'] as const,
-    creative_agents: [], channels: [], pricingModels: ['cpm'] as const, config: {},
+    pricingModels: ['cpm'] as const,
   },
-  statusMappers: {},
   accounts: {
-    resolve: async () => ({ id: 'acc_1', ctx_metadata: {}, authInfo: { kind: 'api_key' } }),
+    resolve: async () => ({ id: 'acc_1', ctx_metadata: {} }),
   },
-  signals: {
+  signals: defineSignalsPlatform({
     getSignals: async (req, ctx) => ({ signals: [/* ... */], sandbox: true }),
     activateSignal: async (req, ctx) => ({ /* ... */ }),
-  },
-};
+  }),
+});
 
 serve(() => createAdcpServerFromPlatform(platform, {
   name: 'My Signals Agent',
@@ -43,6 +47,32 @@ Compile-time enforcement: `RequiredPlatformsFor<S>` catches missing specialism m
 
 Lower-level option: `createAdcpServer({ signals: { getSignals: ... } })` from `@adcp/sdk/server/legacy/v5` — handler-bag API. Still fully supported, the substrate the platform path calls into. Use when you need fine control over individual handlers, mid-migration from a v5 codebase, or custom-shaped tools the platform interface doesn't yet model. `wrapEnvelope(inner, { replayed, context, operationId })` from `@adcp/sdk/server` attaches protocol envelope fields with the per-error-code allowlist (IDEMPOTENCY_CONFLICT drops `replayed`).
 
+**Identity helpers (drop `req: unknown` casts on inline platforms).** `definePlatform` / `defineSalesCorePlatform` / `defineSalesIngestionPlatform` / `defineSignalsPlatform` / `defineCreativeBuilderPlatform` / `defineCreativeAdServerPlatform` / `defineCampaignGovernancePlatform` / `defineContentStandardsPlatform` / `definePropertyListsPlatform` / `defineCollectionListsPlatform` / `defineBrandRightsPlatform` / `definePlatformWithCompliance` are pure identity helpers from `@adcp/sdk/server`. They force a concrete platform interface as the parameter type so TypeScript flows `req` / `ctx` typing into nested handler bodies. Class-pattern adopters with explicit property annotations (`sales: SalesCorePlatform<Meta> & SalesIngestionPlatform<Meta> = { ... }`) don't need them.
+
+**Typed errors instead of `new AdcpError(code, ...)`.** `AuthRequiredError`, `PermissionDeniedError(action)`, `RateLimitedError(retryAfterSeconds)`, `ServiceUnavailableError`, `UnsupportedFeatureError(feature)`, `GovernanceDeniedError`, `PolicyViolationError`, `IdempotencyConflictError`, `InvalidRequestError`, `InvalidStateError`, plus the not-found family (`AccountNotFoundError`, `MediaBuyNotFoundError`, `PackageNotFoundError`, `ProductNotFoundError`, `CreativeNotFoundError`) and the budget / state family. Each maps to its wire error code with `recovery` baked in. Throw from any platform method or `accounts.resolve`.
+
+**`composeMethod` cookbook.** To layer `before`/`after` hooks on a single platform method — short-circuit for caching, enrichment under `ext.*`, typed-error guards — use `composeMethod(inner, { before?, after? })` from `@adcp/sdk/server`. Stacking multiple guards: nest `composeMethod` calls (outer `before` runs first). Test patterns (mocking inner, asserting short-circuit, chained hooks, typed-error propagation): see [`docs/recipes/composeMethod-testing.md`](./recipes/composeMethod-testing.md). Pre-built `accounts.resolve` guards from the same package: `requireAccountMatch(predicate, opts)`, `requireAdvertiserMatch(getRoster, opts)`, `requireOrgScope(getAccountOrg, getCtxOrg, opts)`. Default deny returns `null` (indistinguishable from "not found"; guards against principal enumeration); opt in to `onDeny: 'throw'` for typed `PermissionDeniedError`.
+
+**Three reference `AccountStore` shapes.** Pick the one whose onboarding model matches yours. **Shape A — `InMemoryImplicitAccountStore`**: `resolution: 'implicit'`, buyer-driven `sync_accounts` populates the auth-principal → accounts map. **Shape B — `createOAuthPassthroughResolver`**: `resolution: 'explicit'`, returns just the `resolve` function for adapters fronting an upstream OAuth listing endpoint (Snap, Meta, TikTok, LinkedIn — `extract bearer → GET /me/adaccounts → match by id`). **Shape C — `createRosterAccountStore`**: `resolution: 'explicit'`, returns a complete `AccountStore` for adopters who own the roster (storefront table, admin-UI-managed JSON). All three live at `@adcp/sdk/server`.
+
+**Multi-tenant.** Two helpers, pick by deployment shape. **Host-routed**: `createTenantRegistry({...})` — one server per tenant, tenant-id keyed lookup with `registry.get(tenantId)`. **Account-routed**: `createTenantStore({...})` — one server, per-entry tenant-isolation gate built in (cross-tenant entries on `upsert` / `syncGovernance` rejected with `PERMISSION_DENIED` BEFORE adopter callbacks run; fail-closed when the auth principal can't be resolved). `createTenantStore` mitigates the canonical multi-tenant write-across-tenants bug class at the SDK layer rather than relying on adopter discipline.
+
+**`BuyerAgentRegistry`** — durable buyer-agent identity surface. `BuyerAgentRegistry.signingOnly({ resolveByAgentUrl })` (production target — only `http_sig` credentials route through), `bearerOnly({ resolveByCredential })` (pre-trust beta — bearer/api-key/oauth all route), `mixed(...)` (transition posture). Wrap with `BuyerAgentRegistry.cached(inner, { ttlSeconds })` for TTL + LRU + concurrent-resolve coalescing. The resolved `BuyerAgent` flows through `ctx.agent` to every `AccountStore` method (`resolve` / `upsert` / `list` / `syncGovernance` / `reportUsage` / `getAccountFinancials`) and to `tasks_get` polling. `BuyerAgent.status === 'suspended' | 'blocked'` triggers framework-level `PERMISSION_DENIED`. `BuyerAgent.sandbox_only: true` rejects requests against non-sandbox accounts. See [`docs/migration-buyer-agent-registry.md`](./migration-buyer-agent-registry.md) for the full surface.
+
+**Lifecycle helpers.** `MEDIA_BUY_TRANSITIONS` and `CREATIVE_ASSET_TRANSITIONS` (the canonical state-graph maps the storyboard runner uses), plus `isLegalMediaBuyTransition(from, to)` / `assertMediaBuyTransition(from, to)` and the creative pair. `assertMediaBuyTransition` throws `AdcpError` with the spec-correct code (`NOT_CANCELLABLE` for the cancel-idempotency path, `INVALID_STATE` everywhere else). Production sellers that enforce transitions with these helpers cannot drift from conformance enforcement. `createMediaBuyStore({ store })` opt-in framework wiring handles the `packages[].targeting_overlay` echo contract on `get_media_buys` (sellers claiming `property-lists` / `collection-lists` MUST echo the persisted list reference).
+
+**Breaking in 6.7 — audit before bumping.** (1) `accounts.resolution: 'implicit'` now actually refuses inline `{account_id}` references with `INVALID_REQUEST` (pre-6.7 the docstring claimed this but nothing checked it). Adopters whose callers passed inline `account_id` against an `'implicit'` platform must drop to `'explicit'` or fix callers to use `sync_accounts` first. (2) `SalesPlatform` is now structurally `SalesCorePlatform & SalesIngestionPlatform` with all methods individually optional. Adopters with `: SalesPlatform<Meta>` field annotations claiming `sales-non-guaranteed` / `-guaranteed` / `-broadcast-tv` / `-catalog-driven` need to switch the annotation to `: SalesCorePlatform<Meta> & SalesIngestionPlatform<Meta>` (or use `defineSalesCorePlatform` + `defineSalesIngestionPlatform` spread). Self-announcing under `tsc --noEmit`. Walled-garden CAPI specialisms (`sales-social`) drop ~40 LOC of stub-throw boilerplate. Full migration recipe at [`docs/migration-6.6-to-6.7.md`](./migration-6.6-to-6.7.md).
+
+**`Account<TCtxMeta>` v3 wire fields.** `Account` gained `billing_entity`, `rate_card`, `payment_terms`, `credit_limit`, `setup` (drives `pending_approval` → `active` lifecycle), `account_scope`, `governance_agents`, and `reporting_bucket` — all optional. `billing_entity.bank` and `governance_agents[i].authentication.credentials` are stripped on emit per spec; `Account.authInfo` is now optional. `AccountStore.upsert` / `list` / `syncGovernance` accept an optional `ResolveContext` second argument carrying `authInfo` / `toolName` / `agent` for principal-keyed gating.
+
+**`refAccountId(ref)`** narrows `AccountReference` to its `account_id` arm without casting (returns `undefined` for missing refs, `{brand, operator}` arms, sandbox arms). `narrowAccountRef(ref)` returns the typed arm or `null` for full discriminated-union narrowing. **`NoAccountCtx<TCtxMeta>`** is the request-context type for tools whose wire request doesn't carry an `account` field (`previewCreative`, `listCreativeFormats`, `providePerformanceFeedback`); `ctx.account` is `Account<TCtxMeta> | undefined` and adopters either return a singleton from `accounts.resolve(undefined)` or guard with `if (ctx.account == null) ...`.
+
+**Validation hints on every `VALIDATION_ERROR` envelope.** `ValidationIssue` carries `hint` (one-sentence curated recipe for known shape gotchas — `activation_key` discriminator nesting, `account` discriminator merging, `budget` shape, `format_id` object, VAST/DAAST `delivery_type`, missing `idempotency_key`, log_event/CAPI projection), `discriminator` (which `oneOf` branch the validator inferred), and `schemaId` (the `$id` of the rejecting schema). Buyer-side recovery order: `hint` first, then `discriminator`, then `variants`, then `pointer` + `keyword`. `oneOf` near-miss diagnostics now point at the Success-arm residuals when a Success-vs-Error envelope payload populates Success-only fields.
+
+**Other adopter-facing surfaces.** `DecisioningPlatform.instructions` accepts a function form (`(ctx: SessionContext) => string | undefined`) for per-session prose under `serve({ reuseAgent: false })`. `listCreativeFormats?` is now typed on `CreativeBuilderPlatform` and `CreativeAdServerPlatform` (drops the v5 `opts.creative.listCreativeFormats` escape hatch). `update_rights` is a first-class brand-rights tool with `creative_approval` webhook builders. `@adcp/sdk/upstream-recorder` is a sandbox-only producer-side middleware for the `query_upstream_traffic` storyboard check; `@adcp/sdk/mock-server` is a public sub-export for in-process integration tests. `runStoryboard({ agents })` routes per-specialism storyboard steps to multiple agents (matching `/sales`, `/signals`, `/governance`, `/creative`, `/brand` topology). `media_buy_ids[]` fan-out on `getMediaBuyDelivery` / `getCreativeDelivery` is platform-side pass-through (framework hands the array as-is); a dev-mode warning fires when handlers return fewer rows than requested.
+
+**Don't put credentials in `ctx_metadata`.** Wire-strip protects buyer responses but not server-side log lines, error envelopes, heap dumps, or adopter-generated strings. Re-derive bearers per request from `ctx.authInfo` + your token cache; embed only non-secret upstream IDs in `ctx_metadata`. See [`docs/guides/CTX-METADATA-SAFETY.md`](./guides/CTX-METADATA-SAFETY.md).
+
 ## Quick Start (Client)
 
 ```typescript
@@ -170,6 +200,16 @@ await client.createMediaBuy({ ...params, ...useIdempotencyKey(key) });
 
 **Crash-recovery cookbook.** For an end-to-end recipe (natural-key lookup after restart, `IdempotencyConflictError` / `IdempotencyExpiredError` handling, `metadata.replayed` as side-effect gate, Postgres schema), see [`docs/guides/idempotency-crash-recovery.md`](./guides/idempotency-crash-recovery.md).
 
+## ext.adcp Extension Namespace
+
+**`ext.adcp.*` namespace.** The SDK reserves keys under `ext.adcp.*` for read-by-agent extensions that don't yet warrant their own AdCP spec field. Agents that recognize a key act on it; agents that don't recognize it ignore it silently (per AdCP `ext` semantics: accepted-without-error). The namespace is transport-neutral — it travels in the `ext` envelope field on both MCP and A2A transports. Keys in this namespace are hints **inbound to seller/responder agents** from the SDK or test tooling; **buyer agents building production flows MUST NOT emit `ext.adcp.*` keys**.
+
+| Key | Stamped by | Purpose |
+|-----|-----------|---------|
+| `ext.adcp.disable_sandbox` | `adcp storyboard run --no-sandbox` | Hint (value: `true`) to bypass internal sandbox routing and exercise real adapter paths. Seller agents that honor this key serve production-shaped responses regardless of internal sandbox heuristics (env-var fallbacks, brand-domain detection, fixture substitutes). |
+
+Third-party extensions MUST use a distinct namespace (e.g. `ext.com.example.*`) to avoid collisions with future `ext.adcp.*` keys.
+
 ## Tools
 
 Every tool is an MCP tool called via `agent.<methodName>(params)`. Returns `TaskResult<T>` with `status`, `data`, `error`, `adcpError`, `correlationId`, `deferred`, or `submitted`.
@@ -1063,51 +1103,51 @@ Agents use the `recovery` classification to decide what to do: `transient` → r
 
 | Code | Recovery | Description |
 |------|----------|-------------|
-| `INVALID_REQUEST` | correctable | Request is malformed, missing required fields, or violates schema constraints |
-| `AUTH_REQUIRED` | correctable | Authentication is required to access this resource |
-| `RATE_LIMITED` | transient | Request rate exceeded; retry after the retry_after interval |
-| `SERVICE_UNAVAILABLE` | transient | Seller service is temporarily unavailable |
-| `POLICY_VIOLATION` | correctable | Request violates the seller's content or advertising policies |
-| `PRODUCT_NOT_FOUND` | correctable | One or more referenced product IDs are unknown or expired |
-| `PRODUCT_UNAVAILABLE` | correctable | The requested product is sold out or no longer available |
-| `PROPOSAL_EXPIRED` | correctable | A referenced proposal ID has passed its expires_at timestamp |
-| `BUDGET_TOO_LOW` | correctable | Budget is below the seller's minimum |
-| `CREATIVE_REJECTED` | correctable | Creative failed content policy review |
-| `UNSUPPORTED_FEATURE` | correctable | A requested feature or field is not supported by this seller |
-| `AUDIENCE_TOO_SMALL` | correctable | Audience segment is below the minimum required size for targeting |
-| `ACCOUNT_NOT_FOUND` | terminal | The account reference could not be resolved |
-| `ACCOUNT_SETUP_REQUIRED` | correctable | Natural key resolved but the account needs setup before use |
-| `ACCOUNT_AMBIGUOUS` | correctable | Natural key resolves to multiple accounts |
-| `ACCOUNT_PAYMENT_REQUIRED` | terminal | Account has an outstanding balance requiring payment before new buys |
-| `ACCOUNT_SUSPENDED` | terminal | Account has been suspended |
-| `COMPLIANCE_UNSATISFIED` | correctable | A required disclosure from the brief's compliance section cannot be satisfied by the target format |
-| `GOVERNANCE_DENIED` | correctable | A registered governance agent denied the transaction |
-| `BUDGET_EXHAUSTED` | terminal | Account or campaign budget has been fully spent |
-| `BUDGET_EXCEEDED` | correctable | Operation would exceed the allocated budget for the media buy or package |
-| `CONFLICT` | transient | Concurrent modification detected; the resource was modified between read and write |
-| `IDEMPOTENCY_CONFLICT` | correctable | An earlier request with the same idempotency_key was processed with a different canonical payload. Use a fresh UUID v4 for the new request, or resend the exact original payload to get the cached response. |
-| `IDEMPOTENCY_EXPIRED` | correctable | The idempotency_key is past the seller's replay window. If the prior call succeeded, look up the resource by natural key before retrying; otherwise mint a fresh UUID v4. |
-| `CREATIVE_DEADLINE_EXCEEDED` | correctable | Creative change submitted after the package's creative_deadline |
-| `INVALID_STATE` | correctable | Operation is not permitted for the resource's current status |
-| `MEDIA_BUY_NOT_FOUND` | correctable | Referenced media buy does not exist or is not accessible |
-| `NOT_CANCELLABLE` | correctable | The media buy or package cannot be canceled in its current state |
-| `PACKAGE_NOT_FOUND` | correctable | Referenced package does not exist within the specified media buy |
-| `CREATIVE_NOT_FOUND` | correctable | Referenced creative does not exist in the agent's creative library |
-| `SIGNAL_NOT_FOUND` | correctable | Referenced signal does not exist in the agent's catalog |
-| `SESSION_NOT_FOUND` | correctable | SI session ID is invalid, expired, or does not exist |
-| `PLAN_NOT_FOUND` | correctable | Referenced governance plan does not exist or is not accessible |
-| `REFERENCE_NOT_FOUND` | correctable | Generic fallback for a referenced identifier, grant, session, or other resource that does not exist or is not accessible by the caller |
-| `SESSION_TERMINATED` | correctable | SI session has already been terminated and cannot accept further messages |
-| `VALIDATION_ERROR` | correctable | Request contains invalid field values or violates business rules beyond schema validation |
-| `PRODUCT_EXPIRED` | correctable | One or more referenced products have passed their expires_at timestamp |
-| `PROPOSAL_NOT_COMMITTED` | correctable | The referenced proposal has proposal_status 'draft' and cannot be used to create a media buy |
-| `IO_REQUIRED` | correctable | The committed proposal requires a signed insertion order but no io_acceptance was provided |
-| `TERMS_REJECTED` | correctable | Buyer-proposed measurement_terms were rejected by the seller |
-| `REQUOTE_REQUIRED` | correctable | An update_media_buy request changes the parameter envelope (budget, flight dates, volume, targeting) the original quote was priced against |
-| `VERSION_UNSUPPORTED` | correctable | The declared adcp_major_version is not supported by this seller |
-| `CAMPAIGN_SUSPENDED` | transient | Campaign governance has been suspended pending human review |
-| `GOVERNANCE_UNAVAILABLE` | transient | A registered governance agent is unreachable and the seller cannot obtain a governance decision |
-| `PERMISSION_DENIED` | correctable | The authenticated caller is not authorized for the requested action under the seller's policies, or a required signed credential is missing or invalid |
+| `ACCOUNT_AMBIGUOUS` | correctable | Natural key resolves to multiple accounts. |
+| `ACCOUNT_NOT_FOUND` | terminal | The account reference could not be resolved. |
+| `ACCOUNT_PAYMENT_REQUIRED` | terminal | Account has an outstanding balance requiring payment before new buys. |
+| `ACCOUNT_SETUP_REQUIRED` | correctable | Natural key resolved but the account needs setup before use. |
+| `ACCOUNT_SUSPENDED` | terminal | Account has been suspended. |
+| `AUDIENCE_TOO_SMALL` | correctable | Audience segment is below the minimum required size for targeting. |
+| `AUTH_REQUIRED` | correctable | Authentication is required, or presented credentials were rejected. Two operational sub-cases share this code: (a) credentials missing — agent provides credentials and retries; (b) credentials presented but rejected (expired / revoked / malformed signature) — agent SHOULD NOT auto-retry, since re-presenting a rejected credential against an SSO endpoint creates retry-storm patterns indistinguishable from brute-force probes. In sub-case (b) the agent SHOULD escalate to operator for credential rotation rather than loop. A future minor release splits this code into AUTH_MISSING (correctable) and AUTH_INVALID (terminal); agents handling 3.0.x sellers SHOULD apply the same operational distinction at the application layer. |
+| `BUDGET_EXCEEDED` | correctable | Operation would exceed the allocated budget for the media buy or package. Distinct from BUDGET_EXHAUSTED (already spent) and BUDGET_TOO_LOW (below minimum). |
+| `BUDGET_EXHAUSTED` | terminal | Account or campaign budget has been fully spent. Distinct from BUDGET_TOO_LOW (rejected at submission). |
+| `BUDGET_TOO_LOW` | correctable | Budget is below the seller's minimum. |
+| `CAMPAIGN_SUSPENDED` | transient | Campaign governance has been suspended pending human review; the governance agent MUST reject `check_governance` and `report_plan_outcome` calls on the affected plan until the escalation is resolved. Distinct from `ACCOUNT_SUSPENDED` (account-wide) — this is scoped to a single plan/campaign. |
+| `COMPLIANCE_UNSATISFIED` | correctable | A required disclosure from the brief's compliance section cannot be satisfied by the target format — either the required position or the required persistence mode is not in the format's disclosure_capabilities. |
+| `CONFLICT` | transient | Concurrent modification detected. The resource was modified by another request between read and write. |
+| `CREATIVE_DEADLINE_EXCEEDED` | correctable | Creative change submitted after the package's creative_deadline. Distinct from CREATIVE_REJECTED (content policy failure). |
+| `CREATIVE_NOT_FOUND` | correctable | Referenced creative does not exist in the agent's creative library. Sellers MUST return this code uniformly for any creative_id not owned by the calling account — never distinguish 'exists in another tenant' from 'does not exist', which would enable cross-tenant enumeration. |
+| `CREATIVE_REJECTED` | correctable | Creative failed content policy review. For deadline violations, see CREATIVE_DEADLINE_EXCEEDED. |
+| `GOVERNANCE_DENIED` | correctable | A registered governance agent denied the transaction. The buyer may restructure the buy (e.g., reduce budget, split into smaller transactions), escalate to human spending authority, or contact the governance agent for details. |
+| `GOVERNANCE_UNAVAILABLE` | transient | A registered governance agent is unreachable (timeout, network error, or repeated failure) and the seller cannot obtain a governance decision for the spend-commit. Distinct from `GOVERNANCE_DENIED` (agent reachable and explicitly denied). |
+| `IDEMPOTENCY_CONFLICT` | correctable | An earlier request with the same idempotency_key was processed with a different canonical payload within the seller's replay window. Distinct from CONFLICT (concurrent write) — this indicates the client reused a key across semantically different requests. |
+| `IDEMPOTENCY_EXPIRED` | correctable | The idempotency_key was seen previously but its cached response has been evicted because it is past the seller's declared replay_ttl_seconds. Distinct from IDEMPOTENCY_CONFLICT (different payload within window) — this indicates the retry arrived too late for at-most-once guarantees. If the buyer has any evidence the prior call succeeded (partial response received before crash, entry in the buyer's own DB, a webhook fired), the buyer MUST do the natural-key check BEFORE minting a new key — minting a new key in that situation is exactly how double-creation happens. |
+| `INVALID_REQUEST` | correctable | Request is malformed, missing required fields, or violates schema constraints. |
+| `INVALID_STATE` | correctable | Operation is not permitted for the resource's current status (e.g., updating a completed or canceled media buy, or modifying a canceled package). |
+| `IO_REQUIRED` | correctable | The committed proposal requires a signed insertion order but no io_acceptance was provided. |
+| `MEDIA_BUY_NOT_FOUND` | correctable | Referenced media buy does not exist or is not accessible to the requesting agent. |
+| `NOT_CANCELLABLE` | correctable | The media buy or package cannot be canceled in its current state. The seller may have contractual or operational constraints that prevent cancellation. |
+| `PACKAGE_NOT_FOUND` | correctable | Referenced package does not exist within the specified media buy. |
+| `PERMISSION_DENIED` | correctable | The authenticated caller is not authorized for the requested action under the seller's own policies, or a required signed credential (e.g., a `governance_context` token on a spend-commit) is missing, fails verification, or was issued for a different plan, seller, or phase. Distinct from `AUTH_REQUIRED` (no credentials presented) and `GOVERNANCE_DENIED` (governance agent denied). |
+| `PLAN_NOT_FOUND` | correctable | Referenced governance plan does not exist or is not accessible to the requesting agent. Sellers MUST return this code uniformly for any plan_id not accessible to the calling account — never distinguish 'exists but unauthorized' from 'does not exist', which would enable cross-tenant enumeration of governance plans. |
+| `POLICY_VIOLATION` | correctable | Request violates the seller's content or advertising policies. |
+| `PRODUCT_EXPIRED` | correctable | One or more referenced products have passed their expires_at timestamp and are no longer available for purchase. |
+| `PRODUCT_NOT_FOUND` | correctable | One or more referenced product IDs are unknown or expired. |
+| `PRODUCT_UNAVAILABLE` | correctable | The requested product is sold out or no longer available. |
+| `PROPOSAL_EXPIRED` | correctable | A referenced proposal ID has passed its expires_at timestamp. |
+| `PROPOSAL_NOT_COMMITTED` | correctable | The referenced proposal has proposal_status 'draft' and cannot be used to create a media buy. |
+| `RATE_LIMITED` | transient | Request rate exceeded. Retry after the retry_after interval. |
+| `REFERENCE_NOT_FOUND` | correctable | Generic fallback for a referenced identifier, grant, session, or other resource that does not exist or is not accessible by the caller. Use when no resource-specific not-found code applies (e.g., property lists, content standards, rights grants, SI offerings, proposals, catalogs, event sources, collection lists, brands, individual properties). Typed parameters that lack a dedicated standard code MUST also use REFERENCE_NOT_FOUND rather than minting a custom *_NOT_FOUND code. See 'Uniform response for inaccessible references' in error-handling.mdx for the full MUST list. Summary of the uniform-response MUST: sellers MUST return the same response for 'exists but the caller lacks access' as for 'does not exist' across every observable channel — error.code/message/field/details (message MUST be generic; error.field MUST be identical across both cases on typed parameters); HTTP status, A2A task.status.state, and MCP isError; response headers (ETag, Cache-Control, per-type rate-limit buckets, CDN tags); side effects (webhook/audit writes, background-job enqueues, per-type quota counters, DB-shard routing); and observability (logs, APM spans, third-party error telemetry like Sentry/Datadog). Sellers MUST perform the same resolution-and-authorization work on both paths (resolve-then-authorize; on true-miss still run an authorization decision of equivalent shape against an empty principal set so authorizer latency is not a side channel). Cache population MUST NOT be gated on authorization. Polymorphism is evaluated against the tool-schema's declared parameter shape before any lookup, and a tool's declared shape MUST be identical across all callers. |
+| `REQUOTE_REQUIRED` | correctable | An update_media_buy request changes the parameter envelope (budget, flight dates, volume, targeting) the original quote was priced against. The pricing_option remains locked; the seller is declining the requested shape at that price. Distinct from TERMS_REJECTED (measurement) and POLICY_VIOLATION (content). Sellers SHOULD populate error.details.envelope_field with the field path(s) that breached the envelope (e.g., 'packages[0].budget', 'end_time') so the buyer's agent can autonomously re-discover. |
+| `SERVICE_UNAVAILABLE` | transient | Seller service is temporarily unavailable. Retry with exponential backoff. |
+| `SESSION_NOT_FOUND` | correctable | SI session ID is invalid, expired, or does not exist. |
+| `SESSION_TERMINATED` | correctable | SI session has already been terminated and cannot accept further messages. |
+| `SIGNAL_NOT_FOUND` | correctable | Referenced signal does not exist in the agent's catalog. Sellers MUST return this code uniformly for any signal_id not accessible to the calling account — never distinguish 'exists but unauthorized' from 'does not exist', which would enable cross-tenant enumeration. |
+| `TERMS_REJECTED` | correctable | Buyer-proposed measurement_terms were rejected by the seller. The error details SHOULD identify which specific term was rejected and the seller's acceptable range or supported vendors. |
+| `UNSUPPORTED_FEATURE` | correctable | A requested feature or field is not supported by this seller. |
+| `VALIDATION_ERROR` | correctable | Request contains invalid field values or violates business rules beyond schema validation. |
+| `VERSION_UNSUPPORTED` | correctable | The declared adcp_major_version is not supported by this seller. |
 
 Unknown codes: fall back to the HTTP status code (4xx = correctable, 5xx = transient).
 
@@ -1155,6 +1195,12 @@ Group A storyboards seed fixtures via `comply_test_controller.seed_product` (and
 
 Wire on `createAdcpServer({ testController: bridgeFromTestControllerStore(store, baseline) })`. See `skills/build-seller-agent/SKILL.md` for the full pattern alongside `createComplyController`.
 
+### Anti-façade upstream-traffic recording (`@adcp/sdk/upstream-recorder`)
+
+Storyboards declaring `check: upstream_traffic` (runner-output-contract v2.0.0, spec PR adcontextprotocol/adcp#3816) verify that an adapter actually called its upstream platform with the storyboard-supplied identifiers — distinguishing a real adapter from one returning shape-valid AdCP responses without touching upstream. Adopters opt in by advertising `query_upstream_traffic` on their `comply_test_controller`.
+
+`@adcp/sdk/upstream-recorder` is the producer-side reference middleware: a sandbox-only-by-default helper that wraps the adapter's HTTP layer with per-principal isolation, record-time secret redaction, ring-buffer + TTL eviction, and a `query()` method that maps onto the controller wire shape via `toQueryUpstreamTrafficResponse()`. Wire-up is four steps — boot recorder, wrap fetch, scope handlers in `runWithPrincipal`, return `toQueryUpstreamTrafficResponse(recorder.query(...))` from your `comply_test_controller`'s `query_upstream_traffic` scenario. Worked example at `examples/hello_signals_adapter_marketplace.ts`. See `skills/build-seller-agent/SKILL.md` § "Opting into `upstream_traffic`" for the full pattern, including multi-tenant principal resolution.
+
 ## Key Types
 
 See docs/TYPE-SUMMARY.md for field-level detail. Key types at a glance:
@@ -1204,6 +1250,14 @@ These docs are available locally in the repo and hosted at https://adcontextprot
 | Full type signatures | docs/TYPE-SUMMARY.md | [link](https://adcontextprotocol.github.io/adcp-client/TYPE-SUMMARY.md) |
 | Getting started / install | docs/getting-started.md | [link](https://adcontextprotocol.github.io/adcp-client/getting-started.md) |
 | Build a server-side agent | docs/guides/BUILD-AN-AGENT.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/BUILD-AN-AGENT.md) |
+| Migrating 6.6 → 6.7 (15 recipes; 2 breaking) | docs/migration-6.6-to-6.7.md | [link](https://adcontextprotocol.github.io/adcp-client/migration-6.6-to-6.7.md) |
+| Migrating 5.x → 6.x | docs/migration-5.x-to-6.x.md | [link](https://adcontextprotocol.github.io/adcp-client/migration-5.x-to-6.x.md) |
+| BuyerAgentRegistry adopter migration | docs/migration-buyer-agent-registry.md | [link](https://adcontextprotocol.github.io/adcp-client/migration-buyer-agent-registry.md) |
+| Account resolution: explicit / implicit / derived | docs/guides/account-resolution.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/account-resolution.md) |
+| ctx_metadata credential safety | docs/guides/CTX-METADATA-SAFETY.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/CTX-METADATA-SAFETY.md) |
+| Request signing (RFC 9421) + JWKS | docs/guides/SIGNING-GUIDE.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/SIGNING-GUIDE.md) |
+| Conformance (property-based fuzzing) | docs/guides/CONFORMANCE.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/CONFORMANCE.md) |
+| Validate your agent (5-command checklist) | docs/guides/VALIDATE-YOUR-AGENT.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/VALIDATE-YOUR-AGENT.md) |
 | Async patterns (polling, webhooks, deferred) | docs/guides/ASYNC-DEVELOPER-GUIDE.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/ASYNC-DEVELOPER-GUIDE.md) |
 | Async API reference | docs/guides/ASYNC-API-REFERENCE.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/ASYNC-API-REFERENCE.md) |
 | Input handler patterns | docs/guides/HANDLER-PATTERNS-GUIDE.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/HANDLER-PATTERNS-GUIDE.md) |
@@ -1212,6 +1266,7 @@ These docs are available locally in the repo and hosted at https://adcontextprot
 | CLI reference | docs/CLI.md | [link](https://adcontextprotocol.github.io/adcp-client/CLI.md) |
 | Zod runtime validation | docs/ZOD-SCHEMAS.md | [link](https://adcontextprotocol.github.io/adcp-client/ZOD-SCHEMAS.md) |
 | Testing strategy | docs/guides/TESTING-STRATEGY.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/TESTING-STRATEGY.md) |
+| Testing `composeMethod`-wrapped handlers | docs/recipes/composeMethod-testing.md | [link](https://adcontextprotocol.github.io/adcp-client/recipes/composeMethod-testing.md) |
 | Protocol differences (MCP vs A2A) | docs/development/PROTOCOL_DIFFERENCES.md | [link](https://adcontextprotocol.github.io/adcp-client/development/PROTOCOL_DIFFERENCES.md) |
 | TypeDoc API reference | docs/api/index.html | [link](https://adcontextprotocol.github.io/adcp-client/api/index.html) |
 

package/examples/CONTRIBUTING.md

@@ -0,0 +1,173 @@
+# Contributing to `examples/`
+
+The `examples/` directory ships **fork-target reference adapters**: working code that adopters clone, modify, and ship. They double as integration test surface (each `hello_*` adapter is paired with a CI gate). Adopter trust in this directory is load-bearing — a copy-paste anti-pattern landed here propagates across the ecosystem.
+
+This file documents the conventions that make the directory adopter-friendly. Apply them when adding or modifying any `hello_*_adapter_*.ts` file.
+
+## SWAP-marker convention
+
+Every place an adopter must replace something for production gets a `// SWAP:` marker. The convention is:
+
+```ts
+// SWAP: <one-line description of what to replace, in adopter terms>
+const OPERATOR_TO_TENANT = new Map([
+  /* ... */
+]);
+```
+
+Adopters grep for `// SWAP:` to find seams. The density is the convention — under-marking forces adopters to read the whole file; over-marking buries the structural seams.
+
+**Always mark:**
+
+- Routing tables (operator → tenant, user → workspace, brand → catalog) — the lookup that ties wire input to your backend
+- Upstream HTTP client construction (base URL, auth, header overrides) — the network seam
+- Per-handler write sites (`tenant.X.set(...)`, `db.insert(...)`) — where row-level transactions go
+- Auth-info → principal extraction (the bridge between transport credential and your user/account model)
+- Hardcoded sandbox/dev defaults that production must override (sandbox booleans, dev-mode flags, in-memory stores)
+
+**Optional but useful:**
+
+- Error message text that adopters might localize
+- Pricing/rate-card values that vary by deployment
+- Test-data seeds (clearly labeled as fixture-only)
+
+**Don't mark:**
+
+- Schema-driven response shapes (those follow the spec, not adopter taste)
+- Framework wiring (`createAdcpServerFromPlatform`, `serve()` calls) — adopters don't touch these
+- Type definitions and interfaces — adopters extend, not replace
+
+## "DO NOT DEPLOY AS-IS" banner
+
+Hello adapters seed credentials, sandbox-only flags, and in-memory stores in plaintext. Every adapter that ships any of these gets a top-of-file banner:
+
+```ts
+/**
+ * <adapter_name>
+ *
+ * ⚠️  DO NOT DEPLOY AS-IS. This file seeds <list-of-things> in plaintext
+ *    for local exploration. Production adopters: <one-line-fix-summary>.
+ *
+ * <rest of header doc>
+ */
+```
+
+Banner emphasis must scale to actual production risk:
+
+- **No credentials, no in-memory state** → no banner; adopter conventions in the file body suffice
+- **Hardcoded credentials OR in-memory state** → required banner with specific risks called out
+- **Multi-tenant data models** → required banner mentioning tenant-isolation specifically
+
+## File header doc
+
+Every `hello_*` adapter starts with a JSDoc block covering:
+
+1. **What it demonstrates** — the patterns this file teaches (e.g., "account-routed multi-tenant", "OAuth pass-through resolver", "creative-template build/preview")
+2. **What it doesn't** — patterns explicitly NOT in this file that adopters might mistakenly think are here (e.g., "host-routed tenancy lives in `decisioning-platform-multi-tenant.ts`")
+3. **How to run it** — `NODE_ENV=development npx tsx ...` plus any `adcp storyboard run` invocation that exercises it
+4. **What to swap for production** — the FORK CHECKLIST: routing tables, credentials, in-memory stores, sandbox flags
+
+Header verbosity earns its keep when the adapter introduces a non-obvious pattern (multi-tenancy, cross-specialism dispatch, OAuth pass-through). Don't trim header docs to look minimal — adopters cloning the file see the header before anything else.
+
+## Naming convention
+
+`hello_<role>_adapter_<specialism>.ts`
+
+- `<role>` — AdCP protocol layer: `seller` (media-buy), `creative`, `signals`, `governance`, `brand`
+- `<specialism>` — strips the role-implied prefix (`creative-template` → `_template`, `sales-guaranteed` → `_guaranteed`)
+
+Examples: `hello_seller_adapter_guaranteed.ts`, `hello_creative_adapter_template.ts`, `hello_signals_adapter_marketplace.ts`
+
+**Multi-role adapters** (e.g., the multi-tenant holdco adapter spans governance + brand-rights + property-lists) sit outside the convention. Name them after the deployment shape: `hello_seller_adapter_multi_tenant.ts`, `hello_<deployment>_adapter_<shape>.ts`. Note the exception in the README naming-convention paragraph.
+
+## Cross-specialism dispatch
+
+When an adapter hosts multiple specialisms (e.g., the multi-tenant holdco adapter), one specialism's handler may need to call another's. The canonical pattern is a private helper extracted from the calling specialism, not a direct sibling-method call:
+
+```ts
+class MyAdapter implements DecisioningPlatform {
+  brandRights = defineBrandRightsPlatform({
+    acquireRights: async (req, ctx) => {
+      const denial = await this.enforceGovernance(tenant, ctx, offering, req);
+      if (denial) return denial;
+      // ... rest of acquire flow
+    },
+  });
+
+  campaignGovernance = defineCampaignGovernancePlatform({
+    checkGovernance: async (req, ctx) => {
+      /* ... */
+    },
+  });
+
+  private async enforceGovernance(tenant, ctx, offering, req): Promise<AcquireRightsRejected | null> {
+    // Calls this.campaignGovernance.checkGovernance internally.
+    // Documents the same-tenant invariant + the "do not copy into
+    // single-specialism agents" warning.
+  }
+}
+```
+
+The helper extraction:
+
+- Makes the data flow visible at the call site (no reading 30 lines of inline logic)
+- Gives single-specialism adopters a clean copy target (they can lift just the helper they need)
+- Forces an explicit place to document the in-process-call assumption (so adopters who copy into a single-specialism file see the warning)
+
+Always include a "DO NOT copy into a single-specialism agent" warning on cross-specialism helpers.
+
+## Tenant-isolation gates (multi-tenant adapters)
+
+Multi-tenant adapters must fail-closed, not fail-open. The pattern:
+
+```ts
+// FAIL-CLOSED: reject when home tenant can't be resolved OR when wire
+// operator maps to a different tenant than the buyer's authenticated home.
+if (!homeTenantId || tenantId !== homeTenantId) {
+  return {
+    /* PERMISSION_DENIED */
+  };
+}
+```
+
+NOT this:
+
+```ts
+// FAIL-OPEN: skips the check entirely when homeTenantId is undefined.
+// An adopter who forks and adds a credential without populating the
+// home-tenant lookup silently disables tenant isolation.
+if (homeTenantId && tenantId !== homeTenantId) {
+  return {
+    /* PERMISSION_DENIED */
+  };
+}
+```
+
+The canonical security review (`bokelley/hello-adapters-gov-rights` PR #1390 round 2) caught this exact pattern. Adopters WILL copy fail-open gates if you ship them.
+
+## CI gate
+
+Each `hello_*_adapter_*.ts` is paired with a three-gate CI test:
+
+1. **Strict tsc** — file compiles against the published `dist/` types (matches what an external adopter sees)
+2. **Storyboard** — boots the adapter, runs the matching specialism storyboard, asserts pass
+3. **Upstream-traffic** — replays a recorded upstream-fixture trace and asserts the adapter's HTTP-out shape matches
+
+A regression in any of these fails CI. When adding an adapter, add the three CI hooks; when modifying an adapter, run all three locally before pushing (`npm run typecheck`, `npx adcp storyboard run`, the upstream-recorder verify).
+
+## Format check
+
+`npm run format:check` is a hard CI gate. Run `npm run format:write` before pushing.
+
+## Changeset
+
+Every example change that ships as part of an adapter (file rename, new adapter, breaking change to an adapter's exported types) needs a changeset. Pure documentation changes (this file, README) don't.
+
+## See also
+
+- Repo-root [`CONTRIBUTING.md`](../CONTRIBUTING.md) — general dev process, IPR, commit conventions; this file scopes to `examples/` conventions only
+- `examples/README.md` — the adopter-facing matrix of "if you're claiming X, fork Y"
+- `skills/triage-storyboard-failure/SKILL.md` — when a storyboard fails on your fork
+- `skills/build-holdco-agent/SKILL.md` — multi-tenant + multi-specialism adopter pattern (cross-references the FAIL-CLOSED gate convention from this file)
+- `skills/build-seller-agent/`, `skills/build-creative-agent/`, etc. — per-specialism teaching surface adopters read alongside the example file
+- CLAUDE.md (repo root) — protocol-wide conventions and the storyboard-triage rubric this skill expands

package/examples/README.md

@@ -2,6 +2,27 @@
 
 This directory contains practical examples of how to use the `@adcp/sdk` library.
 
+## Building an AdCP agent — fork-target reference adapters
+
+Pick the example whose AdCP role and specialism most closely match what you're building, fork the file, replace the `// SWAP:` markers, and follow the `FORK CHECKLIST` block at the top of each adapter for the unmarked but load-bearing constants. Each adapter is paired with a three-gate CI test (strict tsc / storyboard / upstream-traffic) so a regression in your fork fails CI before it ships.
+
+| If you're claiming…                | Fork                                              | Then…                                                                                                                                          |
+| ---------------------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `signal-marketplace` / `signal-owned` | `hello_signals_adapter_marketplace.ts`         | as-is for marketplace; `signal-owned` adopters drop the marketplace-specific tax/rev-share fields                                              |
+| `creative-template`                | `hello_creative_adapter_template.ts`              | as-is — single-tenant; production adopters add per-tenant workspace binding (see SWAP markers)                                                 |
+| `creative-generative`              | `hello_creative_adapter_template.ts`              | replace template-driven `buildCreative` with brief-driven generation; keep the `previewCreative` shape                                         |
+| `creative-ad-server`               | `hello_creative_adapter_template.ts`              | promote to `CreativeAdServerPlatform`, add `syncCreatives` library + `listCreatives` query + tag-rendering on `buildCreative`                  |
+| `sales-non-guaranteed`             | `hello_seller_adapter_social.ts`                  | drop OAuth (use static Bearer or your auth), add `getProducts` + `createMediaBuy` + `updateMediaBuy` + `getMediaBuyDelivery` + `getMediaBuys`  |
+| `sales-guaranteed`                 | `hello_seller_adapter_guaranteed.ts`              | as-is — covers the HITL flow                                                                                                                   |
+| `sales-broadcast-tv`               | `hello_seller_adapter_guaranteed.ts`              | replace `audience_targeting` with broadcast-DMA targeting; replace `Product.channels` with `linear_tv`                                         |
+| `sales-streaming-tv`               | `hello_seller_adapter_guaranteed.ts`              | adjust `Product.channels` to `ctv`                                                                                                             |
+| `sales-social`                     | `hello_seller_adapter_social.ts`                  | as-is                                                                                                                                          |
+| `sales-catalog-driven`             | `hello_seller_adapter_social.ts`                  | promote `syncCatalogs` to a real catalog ingestion + `getProducts` reads from the catalog                                                      |
+| `audience-sync`                    | `hello_seller_adapter_social.ts`                  | strip everything except `syncAudiences` + `pollAudienceStatuses`; this is the standalone audience-sync seller pattern                          |
+| `governance-spend-authority` / `property-lists` / `brand-rights` | `hello_seller_adapter_multi_tenant.ts` | as-is — multi-specialism + multi-tenant agency / holdco shape; closes adcp-client#1332 (governance) and adcp-client#1334 (brand-rights). Single-specialism adopters fork the relevant handler block out of the same file. |
+
+Naming convention: `hello_<role>_adapter_<specialism>.ts` where `<role>` is the AdCP protocol layer (`seller` for `media-buy`, `creative` for `creative`, `signals` for `signals`, `governance` for `governance`, `brand` for `brand`). `<specialism>` strips the role-implied prefix (so `creative-template` → `_template`, `sales-guaranteed` → `_guaranteed`). The multi-tenant holdco adapter sits outside this convention because it spans multiple roles (governance + brand-rights + property-lists) — naming follows the deployment shape rather than a single role.
+
 ## Examples
 
 ### Basic Usage
@@ -11,6 +32,17 @@ This directory contains practical examples of how to use the `@adcp/sdk` library
 - **`env-config.ts`** - Loading agent configuration from environment variables
 - **`conversation-client.ts`** - Conversation-aware client with input handlers
 
+### Multi-specialism + multi-tenant (account-routed)
+
+`hello_seller_adapter_multi_tenant.ts` demonstrates the **account-routed** multi-tenant model: one server hosts `governance-spend-authority`, `property-lists`, and `brand-rights` for two distinct tenants whose data never crosses. The agency / holdco hub shape. Two resolution paths:
+
+- Tools that carry `account` (governance, property-lists, sync_accounts, sync_governance) → `accounts.resolve(ref)` reads `ref.operator` and routes to the matching tenant. Same buyer credential can hit different tenants by varying `account.operator`.
+- Tools without `account` (`get_brand_identity`, `get_rights`) → `accounts.resolve(undefined, ctx)` reads the resolved buyer agent's home tenant from `ctx.agent`. Different credentials → different views of the catalog without any account field on the wire.
+
+Cross-specialism dispatch: `brandRights.acquireRights` consults `campaignGovernance.checkGovernance` directly (in-process, no HTTP roundtrip) when the buyer has registered a governance binding via `sync_governance`. Returns the spec-correct `AcquireRightsRejected` arm with `reason` + `suggestions` on denial.
+
+This is distinct from `decisioning-platform-multi-tenant.ts` which uses **host-routed** tenancy via `TenantRegistry` (different agentUrls per tenant). Both are valid; pick by deployment shape.
+
 ### Agent testing (`comply_test_controller`)
 
 Start with `createComplyController` (`comply-controller-seller.ts`). Switch to `registerTestController` (`seller-test-controller.ts`) only when your domain state has internal structure that multiple production tools read from — i.e., when the adapter surface's one-method-per-scenario shape starts fighting the code you already have.

package/examples/comply-controller-seller.ts

@@ -34,7 +34,7 @@
  *     --params '{"creative_id":"cr-1","status":"rejected","rejection_reason":"Brand safety"}'
  */
 
-import { createTaskCapableServer, serve, type ServeContext } from '@adcp/sdk';
+import { createTaskCapableServer, isLegalCreativeTransition, serve, type ServeContext } from '@adcp/sdk';
 import { createComplyController, TestControllerError, type CreativeStatus } from '@adcp/sdk/testing';
 
 // ---------------------------------------------------------------------------
@@ -58,23 +58,15 @@ interface CreativeRecord {
 const products = new Map<string, ProductFixture>();
 const creatives = new Map<string, CreativeRecord>();
 
-// DEMO POLICY — do not copy this table into a production state machine.
-// It is permissive enough to run the example storyboards; a real seller
-// encodes their approval workflow here (and in production the controller
-// itself is never registered). The point of this table is to show WHERE
-// transition enforcement lives — the controller routes through the same
-// guard as the production path.
-const CREATIVE_TRANSITIONS: Record<CreativeStatus, CreativeStatus[]> = {
-  processing: ['pending_review', 'approved', 'rejected'],
-  pending_review: ['approved', 'rejected'],
-  approved: ['rejected', 'archived'],
-  rejected: ['approved', 'archived'],
-  archived: [],
-};
-
+// Transition enforcement uses the SDK's canonical graph
+// (`isLegalCreativeTransition` / `CREATIVE_ASSET_TRANSITIONS`) — the same
+// edges the storyboard runner's `status.monotonic` invariant enforces.
+// Wrapping the boolean predicate in a `TestControllerError` keeps the
+// controller's force_* error shape; production wire-facing code should
+// call `assertCreativeTransition` instead and let the framework project
+// the thrown `AdcpError` onto the wire envelope.
 function assertCreativeTransition(from: CreativeStatus, to: CreativeStatus): void {
-  const allowed = CREATIVE_TRANSITIONS[from] ?? [];
-  if (!allowed.includes(to)) {
+  if (!isLegalCreativeTransition(from, to)) {
     throw new TestControllerError('INVALID_TRANSITION', `Creative cannot move from ${from} to ${to}`, from);
   }
 }

package/examples/decisioning-platform-broadcast-tv.ts

@@ -31,7 +31,8 @@ import {
   DEFAULT_REPORTING_CAPABILITIES,
   publishStatusChange,
   type DecisioningPlatform,
-  type SalesPlatform,
+  type SalesCorePlatform,
+  type SalesIngestionPlatform,
   type AccountStore,
   type SyncCreativesRow,
 } from '@adcp/sdk/server';
@@ -107,7 +108,7 @@ export class BroadcastTvSeller implements DecisioningPlatform<BroadcastTvConfig,
     },
   };
 
-  sales: SalesPlatform<BroadcastTvMeta> = {
+  sales: SalesCorePlatform<BroadcastTvMeta> & SalesIngestionPlatform<BroadcastTvMeta> = {
     /**
      * Sync catalog read. Returns the affiliate's standing packages —
      * primetime daypart, sports tentpoles, etc. Brief-based proposal