@adcp/sdk 6.5.0 → 6.7.0

package/examples/hello_signals_adapter_marketplace.ts

@@ -0,0 +1,532 @@
+/**
+ * hello_signals_adapter_marketplace — worked starting point for an
+ * AdCP signals adapter that wraps an upstream signal-marketplace platform.
+ *
+ * Fork this. Replace `UpstreamClient` with your real backend's HTTP/SDK
+ * client. The AdCP-facing platform methods stay the same.
+ *
+ * Demo:
+ *   npx @adcp/sdk@latest mock-server signal-marketplace --port 4150
+ *   UPSTREAM_URL=http://127.0.0.1:4150 \
+ *     npx tsx examples/hello_signals_adapter_marketplace.ts
+ *   adcp storyboard run http://127.0.0.1:3001/mcp signal_marketplace \
+ *     --auth sk_harness_do_not_use_in_prod
+ *   curl http://127.0.0.1:4150/_debug/traffic
+ *
+ * Production:
+ *   UPSTREAM_URL=https://my-platform.example/api UPSTREAM_API_KEY=… \
+ *     npx tsx examples/hello_signals_adapter_marketplace.ts
+ */
+
+import {
+  createAdcpServerFromPlatform,
+  serve,
+  verifyApiKey,
+  createIdempotencyStore,
+  createUpstreamHttpClient,
+  memoryBackend,
+  AdcpError,
+  BuyerAgentRegistry,
+  defineSignalsPlatform,
+  registerTestController,
+  type DecisioningPlatform,
+  type SignalsPlatform,
+  type AccountStore,
+  type Account,
+  type BuyerAgent,
+  type CachedBuyerAgentRegistry,
+} from '@adcp/sdk/server';
+import type { GetSignalsResponse, ActivateSignalRequest, ActivateSignalSuccess } from '@adcp/sdk/types';
+import { createUpstreamRecorder, toQueryUpstreamTrafficResponse } from '@adcp/sdk/upstream-recorder';
+import { createHash, randomUUID } from 'node:crypto';
+
+const UPSTREAM_URL = process.env['UPSTREAM_URL'] ?? 'http://127.0.0.1:4150';
+const UPSTREAM_API_KEY = process.env['UPSTREAM_API_KEY'] ?? 'mock_signal_market_key_do_not_use_in_prod';
+const PORT = Number(process.env['PORT'] ?? 3001);
+const ADCP_AUTH_TOKEN = process.env['ADCP_AUTH_TOKEN'] ?? 'sk_harness_do_not_use_in_prod';
+
+// ---------------------------------------------------------------------------
+// Upstream client — SWAP for production.
+// `createUpstreamHttpClient` from @adcp/sdk/server handles auth injection,
+// 404→null, and JSON parse. Five typed wrappers below are the seams to
+// swap when wiring to your real backend.
+// ---------------------------------------------------------------------------
+
+interface UpstreamCohort {
+  cohort_id: string;
+  name: string;
+  description: string;
+  member_count: number;
+  total_universe: number;
+  data_provider_domain: string;
+  data_provider_id: string;
+  data_provider_name: string;
+  value_type: 'binary' | 'numeric' | 'categorical';
+  range?: { min: number; max: number };
+  categories?: string[];
+  pricing: Array<{ pricing_id: string; model: 'cpm'; cpm_amount: number; currency: string }>;
+}
+interface UpstreamDestination {
+  destination_id: string;
+  platform_type: 'dsp' | 'ssp' | 'social' | 'ctv' | 'retail' | 'agent';
+  platform_code?: string;
+  agent_url?: string;
+}
+interface UpstreamActivation {
+  activation_id: string;
+  segment_id?: string;
+  /** Mock returns `{ agent_segment: <string> }` — production platforms vary. */
+  agent_activation_key?: { agent_segment?: string };
+}
+
+// ---------------------------------------------------------------------------
+// Upstream-traffic recorder (sandbox-only, opts into `upstream_traffic` storyboard checks)
+// ---------------------------------------------------------------------------
+//
+// Wires `@adcp/sdk/upstream-recorder` so the runner-output-contract v2.0.0
+// `upstream_traffic` storyboard validation grades against real outbound calls
+// rather than the AdCP-shaped response. The recorder is sandbox-only; in
+// production builds set `enabled: false` (or run with NODE_ENV=production
+// + the explicit ADCP_RECORDER_PRODUCTION_ACK=1 escape hatch).
+//
+// Strict mode here so `record()` outside scope throws instead of silently
+// dropping — adopters debugging integration runs see the unwrapped call
+// site as a stack trace, not a mysterious "controller present, observed
+// nothing" storyboard failure.
+const recorder = createUpstreamRecorder({
+  enabled: process.env['NODE_ENV'] !== 'production',
+  strict: process.env['ADCP_RECORDER_STRICT'] === '1',
+});
+
+// Record-time and query-time MUST use the same principal string. This
+// example uses a single static API key, so we hardcode the auth
+// principal and use it both inside `runWithPrincipal` (per handler) and
+// when the controller's `query_upstream_traffic` scenario fires. Multi-
+// tenant adopters resolve this per request from their auth context (the
+// `verifyApiKey({ keys: { ... principal } })` value, an OAuth client_id,
+// or the resolved account.id) and pass it via the registerTestController
+// factory shape (`createStore: async input => ...`).
+const RECORDER_PRINCIPAL = 'compliance-runner';
+
+// Pass the recorder-wrapped fetch into `createUpstreamHttpClient` so every
+// outbound call flows through `runWithPrincipal`-scoped recording. With the
+// recorder disabled (production builds), `wrapFetch` returns the input
+// unchanged — zero per-call overhead.
+const http = createUpstreamHttpClient({
+  baseUrl: UPSTREAM_URL,
+  auth: { kind: 'static_bearer', token: UPSTREAM_API_KEY },
+  fetch: recorder.wrapFetch(fetch),
+});
+
+const tenantHeader = (operatorId: string) => ({ 'X-Operator-Id': operatorId });
+
+const upstream = {
+  // SWAP: tenant lookup. Mock exposes /_lookup; production typically a
+  // directory service or config registry.
+  async lookupOperator(adcpOperator: string): Promise<string | null> {
+    const { body } = await http.get<{ operator_id?: string }>('/_lookup/operator', {
+      adcp_operator: adcpOperator,
+    });
+    return body?.operator_id ?? null;
+  },
+
+  // SWAP: catalog list.
+  async listCohorts(operatorId: string): Promise<UpstreamCohort[]> {
+    const { body } = await http.get<{ cohorts: UpstreamCohort[] }>('/v2/cohorts', undefined, tenantHeader(operatorId));
+    return body?.cohorts ?? [];
+  },
+
+  // SWAP: single cohort.
+  async getCohort(operatorId: string, cohortId: string): Promise<UpstreamCohort | null> {
+    const { body } = await http.get<UpstreamCohort>(
+      `/v2/cohorts/${encodeURIComponent(cohortId)}`,
+      undefined,
+      tenantHeader(operatorId)
+    );
+    return body;
+  },
+
+  // SWAP: destinations available to this operator.
+  async listDestinations(operatorId: string): Promise<UpstreamDestination[]> {
+    const { body } = await http.get<{ destinations: UpstreamDestination[] }>(
+      '/v2/destinations',
+      undefined,
+      tenantHeader(operatorId)
+    );
+    return body?.destinations ?? [];
+  },
+
+  // SWAP: post an activation.
+  async activate(
+    operatorId: string,
+    body: { cohort_id: string; destination_id: string; pricing_id: string; client_request_id: string }
+  ): Promise<UpstreamActivation> {
+    const r = await http.post<UpstreamActivation>('/v2/activations', body, tenantHeader(operatorId));
+    if (r.body === null) {
+      throw new AdcpError('SIGNAL_NOT_FOUND', { message: 'cohort or destination not found' });
+    }
+    return r.body;
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Buyer-agent registry — every seller needs one.
+//
+// The registry models the seller's commercial relationship with each buyer
+// agent it accepts traffic from: who they are, what their status is
+// (active / suspended / blocked), what billing modes they're permitted to
+// request, and any default account terms applied during onboarding. Distinct
+// from the per-request credential — the credential proves "who is calling
+// right now"; the registry record says "who they are to us."
+//
+// SWAP: replace the in-memory map with your seller's onboarding-ledger DB
+// query. The shape stays the same; only the storage changes.
+//
+// HOW CREDENTIALS GET ISSUED (this is adopter-side admin work, NOT modeled
+// here — but every adopter needs to build it):
+//
+//   1. Seller's admin UI / API generates a fresh bearer token (32+ bytes
+//      of CSPRNG entropy is sufficient).
+//   2. Seller computes `hashApiKey(token)` to get the `key_id` that
+//      `verifyApiKey` will stamp on every request from this caller.
+//   3. Seller inserts a `BuyerAgent` row into the ledger keyed by that
+//      `key_id`, populated with the agent's onboarded relationship state.
+//   4. Seller hands the raw token to the buyer agent OUT-OF-BAND (signed
+//      contract, secure delivery, etc.) — the token is the credential;
+//      the ledger only stores the hash so a leak of the ledger doesn't
+//      yield a usable credential.
+//   5. Subsequent requests from the buyer carry `Authorization: Bearer
+//      <token>`; the framework hashes, looks up the row, and threads the
+//      resolved `BuyerAgent` through `ctx.agent`.
+//
+// Real implementations also support invalidation (`registry.invalidate(...)`
+// when the row mutates) and rotation (issue new token, leave old one valid
+// for a grace window, then drop the old `key_id` from the ledger).
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute the same `credential.key_id` value `verifyApiKey` will stamp.
+ * The seller stores this hash (NOT the raw token) in their onboarding
+ * ledger so an attacker who reads the ledger can't extract a usable
+ * credential.
+ */
+function hashApiKey(token: string): string {
+  return createHash('sha256').update(token).digest('hex').slice(0, 32);
+}
+
+/**
+ * In-memory onboarding ledger. Production sellers replace this with a
+ * Postgres table keyed by `key_id`. The cached decorator below makes the
+ * per-request lookup cheap regardless of backing store.
+ *
+ * The seed entry is `Addie` — the canonical AdCP buyer-agent persona used
+ * by the storyboard runner and signing docs. Storyboards driving this
+ * adapter authenticate with the harness token, hash to this `key_id`, and
+ * resolve to this record. Real adopters add real buyer agents (their
+ * partner DSPs, internal test agents, etc.) keyed off the tokens they
+ * issue.
+ *
+ * **Why Addie is `sandbox_only: true`.** The storyboard runner is a test
+ * agent — it should never have production reach. If the harness token
+ * leaks (it's literally `sk_harness_do_not_use_in_prod` in this example),
+ * blast radius is bounded to sandbox accounts. Production buyer agents
+ * leave `sandbox_only` unset (or `false`); test agents set it to `true`.
+ * This is the right default for any agent registered for testing —
+ * adopters cloning this example get the safe baseline rather than
+ * discovering the gap later. (The field is enforced by the framework
+ * after `accounts.resolve`: a sandbox-only agent hitting a non-sandbox
+ * account → PERMISSION_DENIED with `details.reason: 'sandbox-only'`.)
+ */
+const ONBOARDING_LEDGER = new Map<string, BuyerAgent>([
+  [
+    hashApiKey(ADCP_AUTH_TOKEN),
+    {
+      agent_url: 'https://addie.example.com',
+      display_name: 'Addie (storyboard runner)',
+      status: 'active',
+      // Set-valued: this agent is allowed to request operator-billed
+      // accounts only. A real holdco might be `new Set(['operator',
+      // 'agent', 'advertiser'])`. The framework will gain enforcement of
+      // these capabilities; today the field documents commercial intent.
+      billing_capabilities: new Set(['operator']),
+      // Test-agent default. Framework rejects any request from this
+      // agent whose resolved Account.sandbox !== true. Production
+      // buyer agents leave this unset.
+      sandbox_only: true,
+    },
+  ],
+]);
+
+/**
+ * `bearerOnly` because this example authenticates via `verifyApiKey`.
+ * Sellers wiring `verifySignatureAsAuthenticator` swap to `signingOnly`
+ * (or `mixed` during the bearer→signed migration); the resolver shape
+ * adapts accordingly.
+ *
+ * Wrapped in `cached` so a buyer's traffic burst doesn't spam the
+ * onboarding ledger. `invalidate(credential)` purges a stale entry when
+ * the seller mutates an agent's record (status flip, etc.).
+ */
+const agentRegistry: CachedBuyerAgentRegistry = BuyerAgentRegistry.cached(
+  BuyerAgentRegistry.bearerOnly({
+    resolveByCredential: async credential => {
+      // bearerOnly receives every credential kind; MUST kind-discriminate
+      // and reject anything you don't recognize.
+      if (credential.kind !== 'api_key') return null;
+      return ONBOARDING_LEDGER.get(credential.key_id) ?? null;
+    },
+  }),
+  { ttlSeconds: 60 }
+);
+
+// ---------------------------------------------------------------------------
+// AdCP-side adapter — typed against SignalsPlatform.
+// ---------------------------------------------------------------------------
+
+interface OperatorMeta {
+  /** Resolved upstream tenant id, cached on the Account by accounts.resolve. */
+  operator_id: string;
+  [key: string]: unknown;
+}
+
+function toAdcpSignal(c: UpstreamCohort): GetSignalsResponse['signals'][number] {
+  const coverage = c.total_universe > 0 ? Math.round((c.member_count / c.total_universe) * 100) : 0;
+  return {
+    signal_agent_segment_id: c.cohort_id,
+    signal_id: {
+      source: 'catalog',
+      data_provider_domain: c.data_provider_domain,
+      id: c.data_provider_id,
+    },
+    name: c.name,
+    description: c.description,
+    value_type: c.value_type,
+    signal_type: 'marketplace',
+    data_provider: c.data_provider_name,
+    coverage_percentage: coverage,
+    deployments: [],
+    pricing_options: c.pricing.map(p => ({
+      pricing_option_id: p.pricing_id,
+      model: p.model,
+      currency: p.currency,
+      cpm: p.cpm_amount,
+    })),
+    ...(c.range ? { range: c.range } : {}),
+    ...(c.categories ? { categories: c.categories } : {}),
+  };
+}
+
+class SignalMarketplaceAdapter implements DecisioningPlatform<Record<string, never>, OperatorMeta> {
+  capabilities = {
+    specialisms: ['signal-marketplace'] as const,
+    config: {},
+  };
+
+  /**
+   * Buyer-agent registry — framework runs `agentRegistry.resolve(authInfo)`
+   * once per request and threads the resolved record through `ctx.agent`
+   * to specialism handlers AND to `accounts.resolve` (below). When the
+   * resolved agent's `status` is `suspended` / `blocked`, the framework
+   * rejects the request with PERMISSION_DENIED before invoking any
+   * handler — adopters don't reimplement that gate.
+   */
+  agentRegistry = agentRegistry;
+
+  accounts: AccountStore<OperatorMeta> = {
+    /** Translate AdCP `account.operator` → upstream `operator_id`, cache on
+     *  the Account so handlers read from `ctx.account.ctx_metadata`. The
+     *  resolved buyer agent (if any) is on `ctx.agent` — adopters route
+     *  tenant resolution against the durable buyer-agent identity here
+     *  rather than re-deriving from the credential. */
+    resolve: async (ref, ctx) => {
+      if (!ref) return null;
+      // AccountReference discriminated union: `{ account_id }` post-sync,
+      // or `{ brand, operator, sandbox? }` on initial discovery. Mock has
+      // no account_id index; SWAP: production keeps an account_id →
+      // operator_id index populated during list_accounts.
+      if ('account_id' in ref) return null;
+      const adcpOperator = ref.operator;
+      if (!adcpOperator) return null;
+      // Optional: gate the operator on the buyer agent's allowed_brands /
+      // billing_capabilities. Sellers who don't cross-check operator vs.
+      // agent here let any onboarded agent operate on any operator —
+      // legitimate for some marketplaces, a leak for others.
+      const buyerAgent = ctx?.agent;
+      void buyerAgent; // demonstration site — wire your own checks here.
+      const operatorId = await upstream.lookupOperator(adcpOperator);
+      if (!operatorId) return null;
+      return {
+        id: operatorId,
+        name: adcpOperator,
+        status: 'active',
+        operator: adcpOperator,
+        ctx_metadata: { operator_id: operatorId },
+        // The upstream here is the AdCP mock-server. Every account it
+        // returns is a sandbox account by definition. Production
+        // adapters set `sandbox: true` only when they actually
+        // resolved a sandbox-flagged account from their backing store.
+        // This pairs with Addie's `sandbox_only: true` above — the
+        // framework's sandbox-only gate composes `agent.sandbox_only
+        // && account.sandbox !== true → reject`, so production
+        // accounts on a sandbox-only agent fail.
+        sandbox: true, // FIXME(adopter): replace with your real sandbox flag from backing store
+      };
+    },
+  };
+
+  signals: SignalsPlatform<OperatorMeta> = defineSignalsPlatform<OperatorMeta>({
+    getSignals: (req, ctx) =>
+      // `recorder.runWithPrincipal` scopes every outbound call inside `fn`
+      // to `ctx.account.id` for `upstream_traffic` storyboard checks. The
+      // SAME principal MUST be passed at query time in the
+      // comply_test_controller handler below — mismatch returns zero.
+      recorder.runWithPrincipal(RECORDER_PRINCIPAL, async () => {
+        const operatorId = ctx.account.ctx_metadata.operator_id;
+        // `signal_spec` is a semantic brief, not a substring keyword. A real
+        // semantic-search backend would consume it; the published mock does
+        // literal substring filtering on /v2/cohorts?q=. Fetch the full
+        // catalog and filter client-side via signal_ids.
+        const cohorts = await upstream.listCohorts(operatorId);
+        const filtered = cohorts.filter(c => {
+          if (!Array.isArray(req.signal_ids) || req.signal_ids.length === 0) return true;
+          // signal_ids is signal_id[] — provenance objects, not strings.
+          // Narrow on the catalog variant before reading data_provider_domain.
+          // See skills/SHAPE-GOTCHAS.md §2.
+          return req.signal_ids.some(
+            sid =>
+              sid.source === 'catalog' &&
+              sid.data_provider_domain === c.data_provider_domain &&
+              sid.id === c.data_provider_id
+          );
+        });
+        return { signals: filtered.map(toAdcpSignal) } satisfies GetSignalsResponse;
+      }),
+
+    activateSignal: (req: ActivateSignalRequest, ctx): Promise<ActivateSignalSuccess> =>
+      recorder.runWithPrincipal(RECORDER_PRINCIPAL, async () => {
+        const operatorId = ctx.account.ctx_metadata.operator_id;
+        const cohortId = req.signal_agent_segment_id;
+        const cohort = await upstream.getCohort(operatorId, cohortId);
+        if (!cohort) {
+          throw new AdcpError('SIGNAL_NOT_FOUND', {
+            message: `Unknown signal: ${cohortId}`,
+            field: 'signal_agent_segment_id',
+          });
+        }
+        const upstreamDests = await upstream.listDestinations(operatorId);
+        const pricingId = req.pricing_option_id ?? cohort.pricing[0]?.pricing_id;
+        if (!pricingId) {
+          throw new AdcpError('INVALID_REQUEST', {
+            message: 'pricing_option_id required and no default pricing on signal',
+            field: 'pricing_option_id',
+          });
+        }
+        const idempotency = req.idempotency_key ?? randomUUID();
+
+        const deployments = await Promise.all(
+          req.destinations.map(async (dest, i) => {
+            const matched =
+              dest.type === 'platform'
+                ? upstreamDests.find(d => d.platform_type !== 'agent' && d.platform_code === dest.platform)
+                : upstreamDests.find(d => d.platform_type === 'agent' && d.agent_url === dest.agent_url);
+            if (!matched) {
+              const target = dest.type === 'platform' ? dest.platform : dest.agent_url;
+              throw new AdcpError('INVALID_REQUEST', {
+                message: `No upstream destination matches ${target}`,
+                field: 'destinations',
+              });
+            }
+            const activation = await upstream.activate(operatorId, {
+              cohort_id: cohort.cohort_id,
+              destination_id: matched.destination_id,
+              pricing_id: pricingId,
+              client_request_id: `${idempotency}.${i}`,
+            });
+            if (dest.type === 'agent') {
+              // ActivationKey oneOf — for `type: 'key_value'`, `key` and `value`
+              // sit at the TOP level (not nested under a `key_value` field).
+              // `value` MUST be string. See skills/SHAPE-GOTCHAS.md §1.
+              return {
+                type: 'agent' as const,
+                agent_url: dest.agent_url,
+                is_live: true,
+                activation_key: {
+                  type: 'key_value' as const,
+                  key: 'agent_segment',
+                  value: activation.agent_activation_key?.agent_segment ?? activation.activation_id,
+                },
+                deployed_at: new Date().toISOString(),
+              };
+            }
+            return {
+              type: 'platform' as const,
+              platform: dest.platform,
+              is_live: false,
+              activation_key: {
+                type: 'segment_id' as const,
+                segment_id: activation.segment_id ?? activation.activation_id,
+              },
+              estimated_activation_duration_minutes: 30,
+            };
+          })
+        );
+        return { deployments } satisfies ActivateSignalSuccess;
+      }),
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Boot
+// ---------------------------------------------------------------------------
+
+const platform = new SignalMarketplaceAdapter();
+const idempotencyStore = createIdempotencyStore({ backend: memoryBackend(), ttlSeconds: 86_400 });
+
+serve(
+  ({ taskStore }) => {
+    const adcpServer = createAdcpServerFromPlatform(platform, {
+      name: 'hello-signals-adapter-marketplace',
+      version: '1.0.0',
+      taskStore,
+      idempotency: idempotencyStore,
+      resolveSessionKey: ctx => {
+        // ctx.account is typed as Account<OperatorMeta> | undefined here.
+        const acct = ctx.account as Account<OperatorMeta> | undefined;
+        return acct?.id ?? 'anonymous';
+      },
+    });
+
+    // Register `comply_test_controller` with the recorder-backed
+    // `query_upstream_traffic` scenario. The runner queries this after
+    // each step that declares a `check: upstream_traffic` validation;
+    // adopters who don't advertise the scenario grade `not_applicable`.
+    //
+    // Sandbox-only — production builds 404 the controller entirely
+    // (gate via the `if (process.env.ADCP_SANDBOX === '1')` pattern from
+    // the SKILL). For this example adapter we always register since the
+    // example is itself a fixture for the matrix harness.
+    registerTestController(adcpServer, {
+      // Adapter resolves principal from auth context. The same string
+      // MUST be returned by both record-time (runWithPrincipal) and
+      // query-time — mismatch returns zero per cross-tenant isolation.
+      queryUpstreamTraffic: async params => {
+        const result = recorder.query({
+          principal: RECORDER_PRINCIPAL,
+          ...(params.since_timestamp !== undefined && { sinceTimestamp: params.since_timestamp }),
+          ...(params.endpoint_pattern !== undefined && { endpointPattern: params.endpoint_pattern }),
+          ...(params.limit !== undefined && { limit: params.limit }),
+        });
+        return toQueryUpstreamTrafficResponse(result);
+      },
+    });
+    return adcpServer;
+  },
+  {
+    port: PORT,
+    authenticate: verifyApiKey({
+      keys: { [ADCP_AUTH_TOKEN]: { principal: 'compliance-runner' } },
+    }),
+  }
+);
+
+console.log(`signals adapter on http://127.0.0.1:${PORT}/mcp · upstream: ${UPSTREAM_URL}`);

package/examples/seller-test-controller.ts

@@ -31,7 +31,15 @@ import {
   type TestControllerStore,
   type TestControllerStoreFactory,
 } from '@adcp/sdk/testing';
-import { createTaskCapableServer, serve, type ServeContext } from '@adcp/sdk';
+import {
+  CREATIVE_ASSET_TRANSITIONS,
+  createTaskCapableServer,
+  isLegalCreativeTransition,
+  isLegalMediaBuyTransition,
+  MEDIA_BUY_TRANSITIONS,
+  serve,
+  type ServeContext,
+} from '@adcp/sdk';
 
 // ---------------------------------------------------------------------------
 // Typed domain state.
@@ -127,39 +135,25 @@ function resolveSessionId(input: Record<string, unknown>): string {
 }
 
 // ---------------------------------------------------------------------------
-// State-machine guards live HERE, in the same module your production tools
-// import. The controller routes through the same guards — one source of
-// truth for what transitions are legal. The tables cover every state in
-// the AdCP 3.0.0 status enums; TypeScript will catch a missing state if
-// you swap the `Partial<Record<...>>` signature for `Record<...>`.
+// State-machine guards. The transition graphs come straight from the SDK —
+// `MEDIA_BUY_TRANSITIONS` / `CREATIVE_ASSET_TRANSITIONS` are the same maps
+// the storyboard runner's `status.monotonic` invariant uses, so production
+// tools and the controller cannot drift from conformance enforcement.
+// We wrap the boolean predicates in `TestControllerError('INVALID_TRANSITION')`
+// here because this is the controller's force_* path, not a buyer-facing
+// wire response — production seller code should call `assertMediaBuyTransition`
+// / `assertCreativeTransition` instead and let the framework project the
+// thrown `AdcpError` onto the wire `adcp_error` envelope.
 // ---------------------------------------------------------------------------
 
-const MEDIA_BUY_TRANSITIONS: Record<MediaBuyStatus, MediaBuyStatus[]> = {
-  pending_creatives: ['pending_start', 'active', 'paused', 'rejected', 'canceled'],
-  pending_start: ['active', 'paused', 'canceled'],
-  active: ['paused', 'completed', 'canceled'],
-  paused: ['active', 'completed', 'canceled'],
-  completed: [],
-  rejected: [],
-  canceled: [],
-};
-
-const CREATIVE_TRANSITIONS: Record<CreativeStatus, CreativeStatus[]> = {
-  processing: ['pending_review', 'approved', 'rejected', 'archived'],
-  pending_review: ['approved', 'rejected', 'archived'],
-  approved: ['rejected', 'archived'],
-  rejected: ['approved', 'archived'],
-  archived: [],
-};
-
 function assertMediaBuyTransition(from: MediaBuyStatus, to: MediaBuyStatus): void {
-  if (!MEDIA_BUY_TRANSITIONS[from].includes(to)) {
+  if (!isLegalMediaBuyTransition(from, to)) {
     throw new TestControllerError('INVALID_TRANSITION', `media buy cannot move from ${from} to ${to}`, from);
   }
 }
 
 function assertCreativeTransition(from: CreativeStatus, to: CreativeStatus): void {
-  if (!CREATIVE_TRANSITIONS[from].includes(to)) {
+  if (!isLegalCreativeTransition(from, to)) {
     throw new TestControllerError('INVALID_TRANSITION', `creative cannot move from ${from} to ${to}`, from);
   }
 }
@@ -270,11 +264,11 @@ const storeFactory: TestControllerStoreFactory = {
 };
 
 function isMediaBuyStatus(value: unknown): value is MediaBuyStatus {
-  return typeof value === 'string' && value in MEDIA_BUY_TRANSITIONS;
+  return typeof value === 'string' && MEDIA_BUY_TRANSITIONS.has(value as MediaBuyStatus);
 }
 
 function isCreativeStatus(value: unknown): value is CreativeStatus {
-  return typeof value === 'string' && value in CREATIVE_TRANSITIONS;
+  return typeof value === 'string' && CREATIVE_ASSET_TRANSITIONS.has(value as CreativeStatus);
 }
 
 // ---------------------------------------------------------------------------