@adcp/sdk 5.23.0

package/dist/lib/server/test-controller.js

@@ -0,0 +1,735 @@
+"use strict";
+/**
+ * Server-side comply_test_controller implementation.
+ *
+ * Most new code should use {@link createComplyController} from
+ * `@adcp/sdk/testing` — it wraps this module with a domain-grouped
+ * (`seed` / `force` / `simulate`) adapter surface, typed params, sandbox
+ * gating, and built-in seed idempotency. The functions below remain
+ * supported for existing integrations and for custom wrappers that need
+ * access to the underlying request handler / MCP envelope helpers.
+ *
+ * Sellers typically call `registerTestController(server, store)` to add the
+ * `comply_test_controller` tool to their MCP server. The TestControllerStore
+ * interface lets sellers wire up their own state management while the SDK
+ * handles request parsing, scenario dispatch, and response formatting.
+ *
+ * @example Basic usage — single in-memory store
+ * ```typescript
+ * import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+ * import { registerTestController, TestControllerError } from '@adcp/sdk';
+ *
+ * const accounts = new Map<string, string>();
+ *
+ * registerTestController(server, {
+ *   async forceAccountStatus(accountId, status) {
+ *     const prev = accounts.get(accountId);
+ *     if (!prev) throw new TestControllerError('NOT_FOUND', `Account ${accountId} not found`);
+ *     accounts.set(accountId, status);
+ *     return { success: true, previous_state: prev, current_state: status };
+ *   },
+ * });
+ * ```
+ *
+ * @example Session-backed store (factory shape)
+ *
+ * If your session state is persisted (Postgres/Redis/JSONB) and rehydrated into
+ * a *new* object per request, closures over module-level state will silently
+ * lose data between calls. Pass a factory object: `scenarios` declares the
+ * static capability set (answered without invoking your factory), and
+ * `createStore` runs per request so the returned store closes over the live
+ * session.
+ *
+ * ```typescript
+ * import { registerTestController, CONTROLLER_SCENARIOS, enforceMapCap } from '@adcp/sdk';
+ *
+ * registerTestController(server, {
+ *   scenarios: [CONTROLLER_SCENARIOS.FORCE_ACCOUNT_STATUS, CONTROLLER_SCENARIOS.FORCE_MEDIA_BUY_STATUS],
+ *   async createStore(input) {
+ *     const session = await loadSession((input.context as { session_id?: string })?.session_id);
+ *     return {
+ *       async forceAccountStatus(accountId, status) {
+ *         enforceMapCap(session.accountStatuses, accountId, 'account statuses');
+ *         const prev = session.accountStatuses.get(accountId) ?? 'active';
+ *         session.accountStatuses.set(accountId, status);
+ *         await saveSession(session);
+ *         return { success: true, previous_state: prev, current_state: status };
+ *       },
+ *     };
+ *   },
+ * });
+ * ```
+ *
+ * @example Custom MCP wrapper
+ *
+ * For wrappers that need `AsyncLocalStorage`, sandbox gating, or a custom task
+ * store, bypass `registerTestController` and compose the exported building
+ * blocks directly. `TOOL_INPUT_SHAPE` is the canonical Zod shape;
+ * `toMcpResponse` produces the same envelope the default registration does.
+ *
+ * ```typescript
+ * import { AsyncLocalStorage } from 'node:async_hooks';
+ * import {
+ *   handleTestControllerRequest,
+ *   toMcpResponse,
+ *   TOOL_INPUT_SHAPE,
+ * } from '@adcp/sdk';
+ *
+ * const sessionContext = new AsyncLocalStorage<{ sessionId: string }>();
+ * const store = { async forceAccountStatus() { ... } };
+ *
+ * server.registerTool(
+ *   'comply_test_controller',
+ *   { description: 'Sandbox only.', inputSchema: TOOL_INPUT_SHAPE },
+ *   async input => {
+ *     if (!sandboxEnabled()) {
+ *       return toMcpResponse({ success: false, error: 'FORBIDDEN', error_detail: 'Sandbox disabled' });
+ *     }
+ *     return sessionContext.run({ sessionId: (input.context as { session_id: string }).session_id }, async () => {
+ *       const response = await handleTestControllerRequest(store, input as Record<string, unknown>);
+ *       return toMcpResponse(response);
+ *     });
+ *   }
+ * );
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TOOL_INPUT_SHAPE = exports.SESSION_ENTRY_CAP = exports.TestControllerError = exports.SEED_MESSAGES = exports.SEED_SCENARIOS = exports.CONTROLLER_SCENARIOS = void 0;
+exports.enforceMapCap = enforceMapCap;
+exports.createSeedFixtureCache = createSeedFixtureCache;
+exports.handleTestControllerRequest = handleTestControllerRequest;
+exports.toMcpResponse = toMcpResponse;
+exports.registerTestController = registerTestController;
+const zod_1 = require("zod");
+const adcp_server_1 = require("./adcp-server");
+const schemas_generated_1 = require("../types/schemas.generated");
+const responses_1 = require("./responses");
+/**
+ * Scenario name constants for force_* and simulate_* (the advertised set).
+ * Use in place of string literals for type-safe dispatch in custom wrappers,
+ * tests, and factory `scenarios` declarations.
+ *
+ * ```ts
+ * if (input.scenario === CONTROLLER_SCENARIOS.FORCE_ACCOUNT_STATUS) { ... }
+ * ```
+ */
+exports.CONTROLLER_SCENARIOS = {
+    FORCE_CREATIVE_STATUS: 'force_creative_status',
+    FORCE_ACCOUNT_STATUS: 'force_account_status',
+    FORCE_MEDIA_BUY_STATUS: 'force_media_buy_status',
+    FORCE_SESSION_STATUS: 'force_session_status',
+    FORCE_CREATE_MEDIA_BUY_ARM: 'force_create_media_buy_arm',
+    FORCE_TASK_COMPLETION: 'force_task_completion',
+    SIMULATE_DELIVERY: 'simulate_delivery',
+    SIMULATE_BUDGET_SPEND: 'simulate_budget_spend',
+};
+/**
+ * Seed scenario name constants. Used by seed dispatch and the
+ * {@link createComplyController} domain-grouped façade. Seeds are not
+ * advertised via `list_scenarios`.
+ */
+exports.SEED_SCENARIOS = {
+    SEED_PRODUCT: 'seed_product',
+    SEED_PRICING_OPTION: 'seed_pricing_option',
+    SEED_CREATIVE: 'seed_creative',
+    SEED_PLAN: 'seed_plan',
+    SEED_MEDIA_BUY: 'seed_media_buy',
+    SEED_CREATIVE_FORMAT: 'seed_creative_format',
+};
+/**
+ * Stable `SeedSuccess.message` strings the SDK's `dispatchSeed` emits.
+ * Adopters who want to detect first-seed vs idempotent-replay can match
+ * on these constants instead of grepping for the literal prose.
+ *
+ * Third-party sellers MAY emit any string the spec allows (the spec only
+ * requires `success: true`); these constants are SDK-specific contracts
+ * and not portable across implementations. For cross-implementation
+ * replay detection, do not rely on `message`.
+ */
+exports.SEED_MESSAGES = {
+    fresh: 'Fixture seeded',
+    replay: 'Fixture re-seeded (equivalent)',
+};
+const _scenarioExhaustivenessGuard = true;
+void _scenarioExhaustivenessGuard;
+function isFactory(x) {
+    return typeof x.createStore === 'function';
+}
+// ────────────────────────────────────────────────────────────
+// Error class for sellers
+// ────────────────────────────────────────────────────────────
+/**
+ * Throw from TestControllerStore methods to return a typed controller error.
+ *
+ * @example
+ * ```typescript
+ * throw new TestControllerError('NOT_FOUND', `Account ${id} not found`);
+ * throw new TestControllerError('INVALID_TRANSITION', 'Cannot pause a completed buy', 'completed');
+ * ```
+ */
+class TestControllerError extends Error {
+    code;
+    currentState;
+    constructor(code, message, currentState) {
+        super(message);
+        this.code = code;
+        this.currentState = currentState;
+        this.name = 'TestControllerError';
+    }
+}
+exports.TestControllerError = TestControllerError;
+// ────────────────────────────────────────────────────────────
+// Quota guard
+// ────────────────────────────────────────────────────────────
+/**
+ * Default cap on the number of entries a single session-scoped Map may hold
+ * before {@link enforceMapCap} rejects further inserts. Tuned for compliance
+ * testing workloads — raise the cap explicitly if you need a higher ceiling.
+ */
+exports.SESSION_ENTRY_CAP = 1000;
+/** Max chars of `label` echoed into `enforceMapCap`'s error message. */
+const MAX_LABEL_LENGTH = 64;
+/** Clamp `label` before interpolating into error messages — attacker-controlled
+ * input could otherwise spam logs or derail structured detail parsing. */
+function sanitizeLabel(label) {
+    const trimmed = typeof label === 'string' ? label : String(label);
+    return trimmed.slice(0, MAX_LABEL_LENGTH).replace(/[^\x20-\x7E]/g, '?');
+}
+/**
+ * Reject new entries when `map` has reached `cap`. Use inside
+ * {@link TestControllerStore} methods before `.set()` on any Map that
+ * accumulates per-session state (account statuses, media-buy states,
+ * simulated deliveries). Existing keys are allowed to overwrite — only
+ * *net-new* keys are rejected at the cap.
+ *
+ * Rejects via {@link TestControllerError} with code `INVALID_STATE`, which the
+ * dispatcher converts to a typed `ControllerError` response. The caller gets
+ * a clear "clear the session or reuse an existing id" error rather than silent
+ * LRU eviction that would make compliance tests nondeterministic.
+ *
+ * @param label - Human-readable plural noun used in the error message
+ *   (`"account statuses"`, `"media buy states"`). Intended to be a
+ *   caller-controlled string literal; defensively truncated to 64 chars and
+ *   stripped of non-printable characters before interpolation so user-controlled
+ *   input can't spam logs.
+ *
+ * @example
+ * ```ts
+ * async forceAccountStatus(accountId, status) {
+ *   enforceMapCap(session.accountStatuses, accountId, 'account statuses');
+ *   const prev = session.accountStatuses.get(accountId) ?? 'active';
+ *   session.accountStatuses.set(accountId, status);
+ *   return { success: true, previous_state: prev, current_state: status };
+ * }
+ * ```
+ */
+function enforceMapCap(map, key, label, cap = exports.SESSION_ENTRY_CAP) {
+    if (!map.has(key) && map.size >= cap) {
+        throw new TestControllerError('INVALID_STATE', `Too many ${sanitizeLabel(label)} entries (limit ${cap}). Clear the session or reuse an existing id.`);
+    }
+}
+// ────────────────────────────────────────────────────────────
+// Request handler
+// ────────────────────────────────────────────────────────────
+/** Map store method presence to scenario names. */
+const SCENARIO_MAP = [
+    ['forceCreativeStatus', exports.CONTROLLER_SCENARIOS.FORCE_CREATIVE_STATUS],
+    ['forceAccountStatus', exports.CONTROLLER_SCENARIOS.FORCE_ACCOUNT_STATUS],
+    ['forceMediaBuyStatus', exports.CONTROLLER_SCENARIOS.FORCE_MEDIA_BUY_STATUS],
+    ['forceSessionStatus', exports.CONTROLLER_SCENARIOS.FORCE_SESSION_STATUS],
+    ['forceCreateMediaBuyArm', exports.CONTROLLER_SCENARIOS.FORCE_CREATE_MEDIA_BUY_ARM],
+    ['forceTaskCompletion', exports.CONTROLLER_SCENARIOS.FORCE_TASK_COMPLETION],
+    ['simulateDelivery', exports.CONTROLLER_SCENARIOS.SIMULATE_DELIVERY],
+    ['simulateBudgetSpend', exports.CONTROLLER_SCENARIOS.SIMULATE_BUDGET_SPEND],
+];
+function scenariosFromStore(store) {
+    return SCENARIO_MAP.filter(([method]) => typeof store[method] === 'function').map(([, scenario]) => scenario);
+}
+function controllerError(code, detail, currentState) {
+    return {
+        success: false,
+        error: code,
+        error_detail: detail,
+        ...(currentState !== undefined && { current_state: currentState }),
+    };
+}
+/** Build an in-memory {@link SeedFixtureCache}. Capped at {@link SESSION_ENTRY_CAP}
+ * net-new keys to bound memory from a sandbox-authed caller that keeps seeding
+ * fresh IDs. Existing keys are always writable so re-seeds continue to work at
+ * the cap. Raise the cap explicitly for high-volume test runs. */
+function createSeedFixtureCache(cap = exports.SESSION_ENTRY_CAP) {
+    const map = new Map();
+    return {
+        get: k => map.get(k),
+        set: (k, v) => {
+            if (!map.has(k) && map.size >= cap) {
+                throw new TestControllerError('INVALID_STATE', `Seed fixture cache full (limit ${cap}). Clear the session or reuse an existing id.`);
+            }
+            map.set(k, v);
+        },
+        has: k => map.has(k),
+    };
+}
+/** Canonical JSON for equivalence checks. Sorts object keys recursively so
+ * `{a:1,b:2}` matches `{b:2,a:1}`. Arrays remain order-sensitive. Uses a
+ * seen-set to short-circuit circular references rather than stack-overflowing. */
+function canonicalJson(value, seen = new WeakSet()) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (seen.has(value))
+        return '"__cycle__"';
+    seen.add(value);
+    if (Array.isArray(value))
+        return `[${value.map(v => canonicalJson(v, seen)).join(',')}]`;
+    const entries = Object.keys(value)
+        .sort()
+        .map(k => `${JSON.stringify(k)}:${canonicalJson(value[k], seen)}`);
+    return `{${entries.join(',')}}`;
+}
+function fixturesEquivalent(a, b) {
+    try {
+        return canonicalJson(a) === canonicalJson(b);
+    }
+    catch {
+        // BigInt, symbols, or other non-JSON-safe values — treat as divergent so
+        // the caller gets a clear INVALID_PARAMS instead of an INTERNAL_ERROR.
+        return false;
+    }
+}
+/** Dispatch a seed scenario through the correct adapter method, honoring the
+ * spec idempotency rules when a {@link SeedFixtureCache} is provided. */
+async function dispatchSeed(store, scenario, params, cache) {
+    // Validate fixture is a plain object (not null, array, or primitive) before
+    // casting — the adapter signature promises Record<string, unknown>.
+    const rawFixture = params?.fixture;
+    if (rawFixture !== undefined &&
+        (typeof rawFixture !== 'object' || Array.isArray(rawFixture) || rawFixture === null)) {
+        return controllerError('INVALID_PARAMS', `${scenario} requires params.fixture to be an object (got ${Array.isArray(rawFixture) ? 'array' : typeof rawFixture})`);
+    }
+    const fixture = rawFixture ?? {};
+    // Reject keys that can pollute prototypes when adapters spread the fixture
+    // into plain objects. Checked only at the top level — nested uses
+    // `Object.hasOwn` or similar in the adapter's own data layer.
+    for (const key of Object.keys(fixture)) {
+        if (key === '__proto__' || key === 'constructor' || key === 'prototype') {
+            return controllerError('INVALID_PARAMS', `${scenario} fixture key ${JSON.stringify(key)} is reserved and rejected to prevent prototype pollution`);
+        }
+    }
+    let dispatch = null;
+    let missingParam = null;
+    switch (scenario) {
+        case exports.SEED_SCENARIOS.SEED_PRODUCT: {
+            if (!params?.product_id) {
+                missingParam = 'seed_product requires params.product_id';
+                break;
+            }
+            if (!store.seedProduct)
+                return controllerError('UNKNOWN_SCENARIO', `Scenario not supported: ${scenario}`);
+            const productId = params.product_id;
+            dispatch = {
+                key: `seed_product:${productId}`,
+                invoke: () => store.seedProduct(productId, fixture),
+            };
+            break;
+        }
+        case exports.SEED_SCENARIOS.SEED_PRICING_OPTION: {
+            if (!params?.product_id || !params?.pricing_option_id) {
+                missingParam = 'seed_pricing_option requires params.product_id and params.pricing_option_id';
+                break;
+            }
+            if (!store.seedPricingOption)
+                return controllerError('UNKNOWN_SCENARIO', `Scenario not supported: ${scenario}`);
+            const productId = params.product_id;
+            const pricingOptionId = params.pricing_option_id;
+            dispatch = {
+                key: `seed_pricing_option:${productId}:${pricingOptionId}`,
+                invoke: () => store.seedPricingOption(productId, pricingOptionId, fixture),
+            };
+            break;
+        }
+        case exports.SEED_SCENARIOS.SEED_CREATIVE: {
+            if (!params?.creative_id) {
+                missingParam = 'seed_creative requires params.creative_id';
+                break;
+            }
+            if (!store.seedCreative)
+                return controllerError('UNKNOWN_SCENARIO', `Scenario not supported: ${scenario}`);
+            const creativeId = params.creative_id;
+            dispatch = {
+                key: `seed_creative:${creativeId}`,
+                invoke: () => store.seedCreative(creativeId, fixture),
+            };
+            break;
+        }
+        case exports.SEED_SCENARIOS.SEED_PLAN: {
+            if (!params?.plan_id) {
+                missingParam = 'seed_plan requires params.plan_id';
+                break;
+            }
+            if (!store.seedPlan)
+                return controllerError('UNKNOWN_SCENARIO', `Scenario not supported: ${scenario}`);
+            const planId = params.plan_id;
+            dispatch = {
+                key: `seed_plan:${planId}`,
+                invoke: () => store.seedPlan(planId, fixture),
+            };
+            break;
+        }
+        case exports.SEED_SCENARIOS.SEED_MEDIA_BUY: {
+            if (!params?.media_buy_id) {
+                missingParam = 'seed_media_buy requires params.media_buy_id';
+                break;
+            }
+            if (!store.seedMediaBuy)
+                return controllerError('UNKNOWN_SCENARIO', `Scenario not supported: ${scenario}`);
+            const mediaBuyId = params.media_buy_id;
+            dispatch = {
+                key: `seed_media_buy:${mediaBuyId}`,
+                invoke: () => store.seedMediaBuy(mediaBuyId, fixture),
+            };
+            break;
+        }
+        case exports.SEED_SCENARIOS.SEED_CREATIVE_FORMAT: {
+            if (!params?.format_id) {
+                missingParam = 'seed_creative_format requires params.format_id';
+                break;
+            }
+            if (!store.seedCreativeFormat)
+                return controllerError('UNKNOWN_SCENARIO', `Scenario not supported: ${scenario}`);
+            const formatId = params.format_id;
+            dispatch = {
+                key: `seed_creative_format:${formatId}`,
+                invoke: () => store.seedCreativeFormat(formatId, fixture),
+            };
+            break;
+        }
+    }
+    if (missingParam)
+        return controllerError('INVALID_PARAMS', missingParam);
+    if (!dispatch)
+        return controllerError('UNKNOWN_SCENARIO', `Scenario not supported: ${scenario}`);
+    // Spec idempotency: same ID + equivalent fixture = existing; divergent = INVALID_PARAMS.
+    // We also handle caches where has() can race with get() (TTL/LRU eviction) —
+    // a missing prior entry is treated as a fresh seed rather than a crash.
+    const prior = cache?.has(dispatch.key) ? cache.get(dispatch.key) : undefined;
+    if (prior !== undefined) {
+        if (!fixturesEquivalent(prior, fixture)) {
+            return controllerError('INVALID_PARAMS', `Fixture for ${sanitizeLabel(dispatch.key)} diverges from the previously seeded fixture. ` +
+                'Seed replays must carry an equivalent fixture or choose a new id.');
+        }
+        await dispatch.invoke();
+        // SeedSuccess (3.0.1+): message-only arm. The schema's `oneOf` excludes
+        // `previous_state`/`current_state` from this branch — seeds are
+        // pre-population, not entity transitions. {@link SEED_MESSAGES} carries
+        // the SDK-specific replay-detection token.
+        return { success: true, message: exports.SEED_MESSAGES.replay };
+    }
+    await dispatch.invoke();
+    cache?.set(dispatch.key, fixture);
+    return { success: true, message: exports.SEED_MESSAGES.fresh };
+}
+/**
+ * Handle a `comply_test_controller` request. Exported so custom MCP wrappers
+ * can compose it with their own middleware (AsyncLocalStorage, sandbox gating,
+ * logging) without going through {@link registerTestController}.
+ *
+ * `list_scenarios` is answered from the static capability set (store method
+ * presence for plain stores, `factory.scenarios` for factories) and never
+ * invokes `factory.createStore`. Session-backed factories can therefore load
+ * real session state unconditionally.
+ */
+async function handleTestControllerRequest(storeOrFactory, input, options) {
+    const scenario = input.scenario;
+    if (!scenario) {
+        return controllerError('INVALID_PARAMS', 'Missing required field: scenario');
+    }
+    // list_scenarios is a stateless capability probe — answer it without
+    // invoking the factory so session-backed factories don't need to tolerate
+    // sessionless probes.
+    if (scenario === 'list_scenarios') {
+        const scenarios = isFactory(storeOrFactory) ? [...storeOrFactory.scenarios] : scenariosFromStore(storeOrFactory);
+        return { success: true, scenarios };
+    }
+    let store;
+    try {
+        store = isFactory(storeOrFactory) ? await storeOrFactory.createStore(input) : storeOrFactory;
+    }
+    catch (err) {
+        if (err instanceof TestControllerError) {
+            return controllerError(err.code, err.message, err.currentState);
+        }
+        return controllerError('INTERNAL_ERROR', `Failed to resolve test controller store for scenario ${sanitizeLabel(scenario)}`);
+    }
+    const params = input.params;
+    try {
+        switch (scenario) {
+            case exports.CONTROLLER_SCENARIOS.FORCE_CREATIVE_STATUS: {
+                if (!store.forceCreativeStatus) {
+                    return controllerError('UNKNOWN_SCENARIO', `Scenario not supported: ${scenario}`);
+                }
+                if (!params?.creative_id || !params?.status) {
+                    return controllerError('INVALID_PARAMS', 'force_creative_status requires params.creative_id and params.status');
+                }
+                const creativeStatus = schemas_generated_1.CreativeStatusSchema.safeParse(params.status);
+                if (!creativeStatus.success) {
+                    return controllerError('INVALID_PARAMS', `Invalid creative status: ${params.status}`);
+                }
+                return await store.forceCreativeStatus(params.creative_id, creativeStatus.data, params.rejection_reason);
+            }
+            case exports.CONTROLLER_SCENARIOS.FORCE_ACCOUNT_STATUS: {
+                if (!store.forceAccountStatus) {
+                    return controllerError('UNKNOWN_SCENARIO', `Scenario not supported: ${scenario}`);
+                }
+                if (!params?.account_id || !params?.status) {
+                    return controllerError('INVALID_PARAMS', 'force_account_status requires params.account_id and params.status');
+                }
+                const accountStatus = schemas_generated_1.AccountStatusSchema.safeParse(params.status);
+                if (!accountStatus.success) {
+                    return controllerError('INVALID_PARAMS', `Invalid account status: ${params.status}`);
+                }
+                return await store.forceAccountStatus(params.account_id, accountStatus.data);
+            }
+            case exports.CONTROLLER_SCENARIOS.FORCE_MEDIA_BUY_STATUS: {
+                if (!store.forceMediaBuyStatus) {
+                    return controllerError('UNKNOWN_SCENARIO', `Scenario not supported: ${scenario}`);
+                }
+                if (!params?.media_buy_id || !params?.status) {
+                    return controllerError('INVALID_PARAMS', 'force_media_buy_status requires params.media_buy_id and params.status');
+                }
+                const mediaBuyStatus = schemas_generated_1.MediaBuyStatusSchema.safeParse(params.status);
+                if (!mediaBuyStatus.success) {
+                    return controllerError('INVALID_PARAMS', `Invalid media buy status: ${params.status}`);
+                }
+                return await store.forceMediaBuyStatus(params.media_buy_id, mediaBuyStatus.data, params.rejection_reason);
+            }
+            case exports.CONTROLLER_SCENARIOS.FORCE_SESSION_STATUS: {
+                if (!store.forceSessionStatus) {
+                    return controllerError('UNKNOWN_SCENARIO', `Scenario not supported: ${scenario}`);
+                }
+                if (!params?.session_id || !params?.status) {
+                    return controllerError('INVALID_PARAMS', 'force_session_status requires params.session_id and params.status');
+                }
+                const validSessionStatuses = ['complete', 'terminated'];
+                if (!validSessionStatuses.includes(params.status)) {
+                    return controllerError('INVALID_PARAMS', `Invalid session status: ${params.status}`);
+                }
+                return await store.forceSessionStatus(params.session_id, params.status, params.termination_reason);
+            }
+            case exports.CONTROLLER_SCENARIOS.SIMULATE_DELIVERY: {
+                if (!store.simulateDelivery) {
+                    return controllerError('UNKNOWN_SCENARIO', `Scenario not supported: ${scenario}`);
+                }
+                if (!params?.media_buy_id) {
+                    return controllerError('INVALID_PARAMS', 'simulate_delivery requires params.media_buy_id');
+                }
+                return await store.simulateDelivery(params.media_buy_id, {
+                    impressions: params.impressions,
+                    clicks: params.clicks,
+                    reported_spend: params.reported_spend,
+                    conversions: params.conversions,
+                });
+            }
+            case exports.CONTROLLER_SCENARIOS.SIMULATE_BUDGET_SPEND: {
+                if (!store.simulateBudgetSpend) {
+                    return controllerError('UNKNOWN_SCENARIO', `Scenario not supported: ${scenario}`);
+                }
+                if (params?.spend_percentage === undefined || params?.spend_percentage === null) {
+                    return controllerError('INVALID_PARAMS', 'simulate_budget_spend requires params.spend_percentage');
+                }
+                if (!params?.account_id && !params?.media_buy_id) {
+                    return controllerError('INVALID_PARAMS', 'simulate_budget_spend requires params.account_id or params.media_buy_id');
+                }
+                return await store.simulateBudgetSpend({
+                    account_id: params.account_id,
+                    media_buy_id: params.media_buy_id,
+                    spend_percentage: params.spend_percentage,
+                });
+            }
+            case exports.CONTROLLER_SCENARIOS.FORCE_CREATE_MEDIA_BUY_ARM: {
+                if (!store.forceCreateMediaBuyArm) {
+                    return controllerError('UNKNOWN_SCENARIO', `Scenario not supported: ${scenario}`);
+                }
+                const arm = params?.arm;
+                if (arm !== 'submitted' && arm !== 'input-required') {
+                    return controllerError('INVALID_PARAMS', "force_create_media_buy_arm requires params.arm = 'submitted' or 'input-required'");
+                }
+                if (arm === 'submitted' && !params?.task_id) {
+                    return controllerError('INVALID_PARAMS', "force_create_media_buy_arm with arm='submitted' requires params.task_id");
+                }
+                // Spec: task_id is "Present only when arm is 'submitted'" — reject
+                // it on the input-required arm so sellers can rely on the field's
+                // presence as a discriminator.
+                if (arm === 'input-required' && params?.task_id !== undefined) {
+                    return controllerError('INVALID_PARAMS', "force_create_media_buy_arm with arm='input-required' must not include params.task_id");
+                }
+                return await store.forceCreateMediaBuyArm({
+                    arm,
+                    task_id: params?.task_id,
+                    message: params?.message,
+                });
+            }
+            case exports.CONTROLLER_SCENARIOS.FORCE_TASK_COMPLETION: {
+                if (!store.forceTaskCompletion) {
+                    return controllerError('UNKNOWN_SCENARIO', `Scenario not supported: ${scenario}`);
+                }
+                if (!params?.task_id) {
+                    return controllerError('INVALID_PARAMS', 'force_task_completion requires params.task_id');
+                }
+                // Reject arrays explicitly — `typeof [] === 'object'` would let an
+                // array slip past the object check, but `result` is a structured
+                // completion payload (validates against async-response-data.json),
+                // never an array.
+                if (!params?.result || typeof params.result !== 'object' || Array.isArray(params.result)) {
+                    return controllerError('INVALID_PARAMS', 'force_task_completion requires params.result (completion payload object)');
+                }
+                return await store.forceTaskCompletion(params.task_id, params.result);
+            }
+            case exports.SEED_SCENARIOS.SEED_PRODUCT:
+            case exports.SEED_SCENARIOS.SEED_PRICING_OPTION:
+            case exports.SEED_SCENARIOS.SEED_CREATIVE:
+            case exports.SEED_SCENARIOS.SEED_PLAN:
+            case exports.SEED_SCENARIOS.SEED_MEDIA_BUY:
+            case exports.SEED_SCENARIOS.SEED_CREATIVE_FORMAT:
+                return await dispatchSeed(store, scenario, params, options?.seedCache);
+            default:
+                return controllerError('UNKNOWN_SCENARIO', 'Unrecognized scenario name');
+        }
+    }
+    catch (err) {
+        if (err instanceof TestControllerError) {
+            return controllerError(err.code, err.message, err.currentState);
+        }
+        return controllerError('INTERNAL_ERROR', 'An unexpected error occurred in the test controller store');
+    }
+}
+// ────────────────────────────────────────────────────────────
+// MCP envelope helpers
+// ────────────────────────────────────────────────────────────
+function summarize(data) {
+    if (data.success === false)
+        return `Controller error: ${data.error}`;
+    if ('scenarios' in data)
+        return `Supported scenarios: ${data.scenarios.join(', ')}`;
+    if ('previous_state' in data) {
+        return `Transitioned from ${data.previous_state} to ${data.current_state}`;
+    }
+    if ('simulated' in data)
+        return `Simulation complete: ${JSON.stringify(data.simulated)}`;
+    if ('forced' in data)
+        return `Directive registered: arm=${data.forced.arm}`;
+    // SeedSuccess (3.0.1+): message-only arm. dispatchSeed sets the message
+    // to 'Fixture seeded' / 'Fixture re-seeded (equivalent)'; third-party
+    // sellers may emit other strings (or none — the spec only requires
+    // success).
+    return data.message ?? 'Scenario succeeded';
+}
+/**
+ * Wrap a {@link ComplyTestControllerResponse} in an MCP tool response envelope
+ * (`content` + `structuredContent` + `isError`). Exported so custom wrappers
+ * can reuse the same summary/error shape as {@link registerTestController}.
+ */
+function toMcpResponse(data) {
+    const isError = data.success === false;
+    return {
+        content: [{ type: 'text', text: summarize(data) }],
+        structuredContent: (0, responses_1.toStructuredContent)(data),
+        ...(isError && { isError: true }),
+    };
+}
+/**
+ * Canonical Zod input schema for the `comply_test_controller` tool. Pass as
+ * the `inputSchema` argument to `server.registerTool(...)` in custom wrappers
+ * so the request shape stays in sync with {@link registerTestController}.
+ *
+ * Matches `ComplyTestControllerRequest` from the generated schema: `scenario`
+ * (required), `params` (scenario-specific), and the universal `context` / `ext`
+ * envelope fields. No top-level `account` — AdCP routes account context
+ * through `context` on this tool.
+ *
+ * **Extending for vendor fields.** Custom wrappers that route sandbox gating
+ * or tenant scoping on top-level fields can extend the shape locally:
+ *
+ * ```ts
+ * const MY_SHAPE = {
+ *   ...TOOL_INPUT_SHAPE,
+ *   account: z.object({ sandbox: z.boolean() }).passthrough().optional(),
+ * };
+ * server.registerTool(
+ *   'comply_test_controller',
+ *   { description: 'Sandbox only.', inputSchema: MY_SHAPE },
+ *   async input => {
+ *     if (input.account?.sandbox !== true) return toMcpResponse({ ... });
+ *     return toMcpResponse(await handleTestControllerRequest(store, input as Record<string, unknown>));
+ *   }
+ * );
+ * ```
+ *
+ * This keeps the default registration protocol-compliant while giving
+ * wrapper authors a documented extension point.
+ */
+exports.TOOL_INPUT_SHAPE = {
+    scenario: zod_1.z.string().describe('Scenario to execute (e.g., list_scenarios, force_account_status)'),
+    params: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional().describe('Scenario-specific parameters'),
+    context: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional().describe('AdCP context object'),
+    ext: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional().describe('AdCP extension object'),
+};
+// ────────────────────────────────────────────────────────────
+// MCP tool registration
+// ────────────────────────────────────────────────────────────
+/**
+ * Register the `comply_test_controller` tool on an MCP server.
+ *
+ * Accepts a plain {@link TestControllerStore} (scenarios inferred from
+ * implemented methods) or a {@link TestControllerStoreFactory} (scenarios
+ * declared explicitly; `createStore` runs per request for session-backed
+ * state). See the module-level examples for both patterns.
+ *
+ * The `server` argument takes either an `AdcpServer` from
+ * `createAdcpServer()` or a raw SDK `McpServer` from
+ * `createTaskCapableServer()` — the helper unwraps the opaque handle
+ * when needed so tool registration reaches the underlying SDK server.
+ */
+function registerTestController(server, storeOrFactory, options) {
+    const mcp = (0, adcp_server_1.getSdkServer)(server) ?? server;
+    // Per-registration cache so seed idempotency holds across all requests on
+    // this server instance. Callers can supply their own cache to scope by
+    // session or tenant.
+    const seedCache = options?.seedCache ?? createSeedFixtureCache();
+    // Per AdCP 3.0, comply_test_controller support is declared via the
+    // top-level `compliance_testing` capability block — NOT as an entry in
+    // `supported_protocols`. When we've been given an AdcpServer produced by
+    // createAdcpServer, auto-populate that block. The scenarios list comes
+    // from the factory's static `scenarios` (factory shape) or is inferred
+    // from the plain store's method presence.
+    const capsBag = server[adcp_server_1.ADCP_CAPABILITIES];
+    if (capsBag) {
+        const incoming = isFactory(storeOrFactory) ? [...storeOrFactory.scenarios] : scenariosFromStore(storeOrFactory);
+        if (incoming.length > 0) {
+            // Merge with any previously-declared scenarios rather than silently
+            // dropping them. A server can wire more than one controller (e.g.
+            // media-buy + governance) and each call should contribute its
+            // scenarios to the advertised set.
+            const existing = (capsBag.compliance_testing?.scenarios ?? []);
+            const merged = Array.from(new Set([...existing, ...incoming]));
+            capsBag.compliance_testing = { scenarios: merged };
+        }
+    }
+    mcp.registerTool('comply_test_controller', {
+        description: 'Triggers seller-side state transitions for compliance testing. Sandbox only.',
+        inputSchema: exports.TOOL_INPUT_SHAPE,
+    }, (async (input) => {
+        const response = await handleTestControllerRequest(storeOrFactory, input, {
+            seedCache,
+        });
+        // Echo request context back into the response envelope so callers see
+        // their correlation data round-trip (matches the auto-echo createAdcpServer
+        // does for domain tools). Only attaches when the handler didn't place a
+        // context itself — handler-supplied context wins.
+        const ctx = input.context;
+        const withContext = ctx && typeof ctx === 'object' && response.context === undefined
+            ? { ...response, context: ctx }
+            : response;
+        return toMcpResponse(withContext);
+    }));
+}
+//# sourceMappingURL=test-controller.js.map