@adcp/sdk 5.23.0

package/dist/lib/testing/comply-controller.d.ts

@@ -0,0 +1,193 @@
+/**
+ * Seller-side scaffold for the `comply_test_controller` tool.
+ *
+ * `createComplyController` turns a set of domain-grouped adapters into the
+ * pieces needed to register the tool on an MCP server: a tool definition, a
+ * raw handler, an MCP-envelope handler, and a one-call `register(server)`.
+ *
+ * The helper owns:
+ *   - Dispatching `scenario` to the correct adapter
+ *   - Param validation + typed error envelopes (`UNKNOWN_SCENARIO`,
+ *     `INVALID_PARAMS`, `NOT_FOUND`, `INVALID_TRANSITION`, `FORBIDDEN`)
+ *   - Seed re-seed idempotency (same id + equivalent fixture =
+ *     `SeedSuccess` with `message: "Fixture re-seeded (equivalent)"`;
+ *     divergent fixture = `INVALID_PARAMS`)
+ *   - Optional sandbox gating at both `tools/list` and per-request level
+ *
+ * The helper does NOT own the state machine. Transition enforcement lives
+ * inside your adapters so production and compliance testing share one source
+ * of truth — throw `TestControllerError('INVALID_TRANSITION', …)` from the
+ * adapter when a transition is disallowed.
+ *
+ * For custom MCP wrappers that need AsyncLocalStorage, sandbox gating at the
+ * transport layer, or a session-backed store factory, compose
+ * `handleTestControllerRequest`, `toMcpResponse`, and `TOOL_INPUT_SHAPE` from
+ * `@adcp/sdk/server` directly — the flat-store surface documented there.
+ *
+ * @example
+ * ```ts
+ * import { createComplyController } from '@adcp/sdk/testing';
+ *
+ * const controller = createComplyController({
+ *   sandboxGate: input => input.auth?.sandbox === true,
+ *   seed: {
+ *     product: (params) => productRepo.upsert(params.product_id, params.fixture),
+ *     creative: (params) => creativeRepo.upsert(params.creative_id, params.fixture),
+ *   },
+ *   force: {
+ *     creative_status: (params) => creativeRepo.transition(params.creative_id, params.status),
+ *   },
+ * });
+ *
+ * controller.register(server);
+ * ```
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { TOOL_INPUT_SHAPE, type SeedFixtureCache } from '../server/test-controller';
+import { type AdcpServer } from '../server/adcp-server';
+import type { ComplyTestControllerResponse, SimulationSuccess, StateTransitionSuccess } from '../types/tools.generated';
+import type { AccountStatus, CreativeStatus, MediaBuyStatus } from '../types/core.generated';
+import type { McpToolResponse } from '../server/responses';
+/** Common second argument every adapter receives: the raw tool input so
+ * adapters can read `context.session_id`, `ext`, or vendor-specific fields. */
+export interface ComplyControllerContext {
+    /** The tool input as received over the wire, pre-validation. */
+    input: Record<string, unknown>;
+}
+/** Params for `seed_product`. `fixture` mirrors the persisted product shape
+ * (delivery_type, channels, pricing_options, …). Kept permissive — the spec
+ * lets storyboards declare only the fields each test needs. */
+export interface SeedProductParams {
+    product_id: string;
+    fixture: Record<string, unknown>;
+}
+export interface SeedPricingOptionParams {
+    product_id: string;
+    pricing_option_id: string;
+    fixture: Record<string, unknown>;
+}
+export interface SeedCreativeParams {
+    creative_id: string;
+    fixture: Record<string, unknown>;
+}
+export interface SeedPlanParams {
+    plan_id: string;
+    fixture: Record<string, unknown>;
+}
+export interface SeedMediaBuyParams {
+    media_buy_id: string;
+    fixture: Record<string, unknown>;
+}
+export interface ForceCreativeStatusParams {
+    creative_id: string;
+    status: CreativeStatus;
+    rejection_reason?: string;
+}
+export interface ForceAccountStatusParams {
+    account_id: string;
+    status: AccountStatus;
+}
+export interface ForceMediaBuyStatusParams {
+    media_buy_id: string;
+    status: MediaBuyStatus;
+    rejection_reason?: string;
+}
+export interface ForceSessionStatusParams {
+    session_id: string;
+    status: 'complete' | 'terminated';
+    termination_reason?: string;
+}
+export interface SimulateDeliveryParams {
+    media_buy_id: string;
+    impressions?: number;
+    clicks?: number;
+    conversions?: number;
+    reported_spend?: {
+        amount: number;
+        currency: string;
+    };
+}
+export interface SimulateBudgetSpendParams {
+    account_id?: string;
+    media_buy_id?: string;
+    spend_percentage: number;
+}
+/** Seed adapters persist the fixture to the seller's data layer. Return
+ * value is ignored — the helper builds the `SeedSuccess` envelope (the
+ * 3.0.1+ message-only seed arm) from its own idempotency cache. Throw
+ * {@link TestControllerError} for typed errors (`INVALID_PARAMS`,
+ * `FORBIDDEN`). */
+export type SeedAdapter<P> = (params: P, ctx: ComplyControllerContext) => Promise<void> | void;
+/** Force adapters return a {@link StateTransitionSuccess}. Throw
+ * `TestControllerError('INVALID_TRANSITION', msg, currentState)` when the
+ * state machine disallows the transition. */
+export type ForceAdapter<P> = (params: P, ctx: ComplyControllerContext) => Promise<StateTransitionSuccess> | StateTransitionSuccess;
+/** Simulate adapters return a {@link SimulationSuccess}. */
+export type SimulateAdapter<P> = (params: P, ctx: ComplyControllerContext) => Promise<SimulationSuccess> | SimulationSuccess;
+export interface ComplyControllerConfig {
+    /** Per-request gate. Return `false` to reject with `FORBIDDEN` — suitable
+     * for tenants flagged as production, accounts not marked sandbox, or
+     * missing sandbox headers. When omitted, every request is allowed.
+     *
+     * MCP tools/list visibility is controlled by *whether you call*
+     * {@link ComplyController.register}. Wrap registration with your own
+     * environment check if you need to hide the tool outside sandbox:
+     *
+     * ```ts
+     * if (process.env.ADCP_SANDBOX === '1') controller.register(server);
+     * ```
+     *
+     * Called for every request; the helper does NOT invoke adapters when the
+     * gate returns false. Errors thrown from the gate are treated as denials
+     * so a broken gate fails closed.
+     */
+    sandboxGate?: (input: Record<string, unknown>) => boolean | Promise<boolean>;
+    /** Seed adapters. Each registered method advertises its scenario as
+     * implemented; omitted methods return `UNKNOWN_SCENARIO` when called. */
+    seed?: {
+        product?: SeedAdapter<SeedProductParams>;
+        pricing_option?: SeedAdapter<SeedPricingOptionParams>;
+        creative?: SeedAdapter<SeedCreativeParams>;
+        plan?: SeedAdapter<SeedPlanParams>;
+        media_buy?: SeedAdapter<SeedMediaBuyParams>;
+    };
+    /** Force adapters (state transitions). */
+    force?: {
+        creative_status?: ForceAdapter<ForceCreativeStatusParams>;
+        account_status?: ForceAdapter<ForceAccountStatusParams>;
+        media_buy_status?: ForceAdapter<ForceMediaBuyStatusParams>;
+        session_status?: ForceAdapter<ForceSessionStatusParams>;
+    };
+    /** Simulation adapters (synthetic delivery/budget data). */
+    simulate?: {
+        delivery?: SimulateAdapter<SimulateDeliveryParams>;
+        budget_spend?: SimulateAdapter<SimulateBudgetSpendParams>;
+    };
+    /** Override the seed idempotency cache (e.g., to scope by tenant or
+     * persist across restarts). Defaults to an unbounded in-memory cache. */
+    seedCache?: SeedFixtureCache;
+}
+export interface ComplyControllerToolDefinition {
+    name: 'comply_test_controller';
+    description: string;
+    inputSchema: typeof TOOL_INPUT_SHAPE;
+}
+export interface ComplyController {
+    /** MCP tool definition — pass to `server.registerTool(name, { description, inputSchema }, handle)`
+     * manually, or use {@link ComplyController.register} to do it for you. */
+    readonly toolDefinition: ComplyControllerToolDefinition;
+    /** Protocol-level handler. Returns a {@link ComplyTestControllerResponse}
+     * without the MCP envelope — useful for A2A adaptation or custom transports. */
+    handleRaw(input: Record<string, unknown>): Promise<ComplyTestControllerResponse>;
+    /** MCP-envelope handler. Wraps {@link ComplyController.handleRaw} with
+     * `content` + `structuredContent` + `isError`. */
+    handle(input: Record<string, unknown>): Promise<McpToolResponse & {
+        isError?: true;
+    }>;
+    /** Register the tool on an `AdcpServer` or raw `McpServer`. Equivalent to
+     * calling `server.registerTool(name, { description, inputSchema }, handle)`. */
+    register(server: AdcpServer | McpServer): void;
+}
+/** Create a comply_test_controller scaffold from domain-grouped adapters. */
+export declare function createComplyController(config: ComplyControllerConfig): ComplyController;
+//# sourceMappingURL=comply-controller.d.ts.map

package/dist/lib/testing/comply-controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"comply-controller.d.ts","sourceRoot":"","sources":["../../../src/lib/testing/comply-controller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,EAEL,gBAAgB,EAKhB,KAAK,gBAAgB,EAEtB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACtE,OAAO,KAAK,EACV,4BAA4B,EAE5B,iBAAiB,EACjB,sBAAsB,EACvB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAC7F,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAM3D;+EAC+E;AAC/E,MAAM,WAAW,uBAAuB;IACtC,gEAAgE;IAChE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED;;+DAE+D;AAC/D,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,uBAAuB;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,kBAAkB;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,yBAAyB;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,cAAc,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,wBAAwB;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,aAAa,CAAC;CACvB;AAED,MAAM,WAAW,yBAAyB;IACxC,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,cAAc,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,wBAAwB;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,UAAU,GAAG,YAAY,CAAC;IAClC,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,sBAAsB;IACrC,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;CACvD;AAED,MAAM,WAAW,yBAAyB;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAMD;;;;mBAImB;AACnB,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,GAAG,EAAE,uBAAuB,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAE/F;;6CAE6C;AAC7C,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAC5B,MAAM,EAAE,CAAC,EACT,GAAG,EAAE,uBAAuB,KACzB,OAAO,CAAC,sBAAsB,CAAC,GAAG,sBAAsB,CAAC;AAE9D,4DAA4D;AAC5D,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI,CAC/B,MAAM,EAAE,CAAC,EACT,GAAG,EAAE,uBAAuB,KACzB,OAAO,CAAC,iBAAiB,CAAC,GAAG,iBAAiB,CAAC;AAMpD,MAAM,WAAW,sBAAsB;IACrC;;;;;;;;;;;;;;;OAeG;IACH,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAE7E;6EACyE;IACzE,IAAI,CAAC,EAAE;QACL,OAAO,CAAC,EAAE,WAAW,CAAC,iBAAiB,CAAC,CAAC;QACzC,cAAc,CAAC,EAAE,WAAW,CAAC,uBAAuB,CAAC,CAAC;QACtD,QAAQ,CAAC,EAAE,WAAW,CAAC,kBAAkB,CAAC,CAAC;QAC3C,IAAI,CAAC,EAAE,WAAW,CAAC,cAAc,CAAC,CAAC;QACnC,SAAS,CAAC,EAAE,WAAW,CAAC,kBAAkB,CAAC,CAAC;KAC7C,CAAC;IAEF,0CAA0C;IAC1C,KAAK,CAAC,EAAE;QACN,eAAe,CAAC,EAAE,YAAY,CAAC,yBAAyB,CAAC,CAAC;QAC1D,cAAc,CAAC,EAAE,YAAY,CAAC,wBAAwB,CAAC,CAAC;QACxD,gBAAgB,CAAC,EAAE,YAAY,CAAC,yBAAyB,CAAC,CAAC;QAC3D,cAAc,CAAC,EAAE,YAAY,CAAC,wBAAwB,CAAC,CAAC;KACzD,CAAC;IAEF,4DAA4D;IAC5D,QAAQ,CAAC,EAAE;QACT,QAAQ,CAAC,EAAE,eAAe,CAAC,sBAAsB,CAAC,CAAC;QACnD,YAAY,CAAC,EAAE,eAAe,CAAC,yBAAyB,CAAC,CAAC;KAC3D,CAAC;IAEF;6EACyE;IACzE,SAAS,CAAC,EAAE,gBAAgB,CAAC;CAC9B;AAMD,MAAM,WAAW,8BAA8B;IAC7C,IAAI,EAAE,wBAAwB,CAAC;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,OAAO,gBAAgB,CAAC;CACtC;AAED,MAAM,WAAW,gBAAgB;IAC/B;8EAC0E;IAC1E,QAAQ,CAAC,cAAc,EAAE,8BAA8B,CAAC;IAExD;oFACgF;IAChF,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,4BAA4B,CAAC,CAAC;IAEjF;sDACkD;IAClD,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,eAAe,GAAG;QAAE,OAAO,CAAC,EAAE,IAAI,CAAA;KAAE,CAAC,CAAC;IAEtF;oFACgF;IAChF,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,SAAS,GAAG,IAAI,CAAC;CAChD;AAuFD,6EAA6E;AAC7E,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,sBAAsB,GAAG,gBAAgB,CA2FvF"}

package/dist/lib/testing/comply-controller.js

@@ -0,0 +1,199 @@
+"use strict";
+/**
+ * Seller-side scaffold for the `comply_test_controller` tool.
+ *
+ * `createComplyController` turns a set of domain-grouped adapters into the
+ * pieces needed to register the tool on an MCP server: a tool definition, a
+ * raw handler, an MCP-envelope handler, and a one-call `register(server)`.
+ *
+ * The helper owns:
+ *   - Dispatching `scenario` to the correct adapter
+ *   - Param validation + typed error envelopes (`UNKNOWN_SCENARIO`,
+ *     `INVALID_PARAMS`, `NOT_FOUND`, `INVALID_TRANSITION`, `FORBIDDEN`)
+ *   - Seed re-seed idempotency (same id + equivalent fixture =
+ *     `SeedSuccess` with `message: "Fixture re-seeded (equivalent)"`;
+ *     divergent fixture = `INVALID_PARAMS`)
+ *   - Optional sandbox gating at both `tools/list` and per-request level
+ *
+ * The helper does NOT own the state machine. Transition enforcement lives
+ * inside your adapters so production and compliance testing share one source
+ * of truth — throw `TestControllerError('INVALID_TRANSITION', …)` from the
+ * adapter when a transition is disallowed.
+ *
+ * For custom MCP wrappers that need AsyncLocalStorage, sandbox gating at the
+ * transport layer, or a session-backed store factory, compose
+ * `handleTestControllerRequest`, `toMcpResponse`, and `TOOL_INPUT_SHAPE` from
+ * `@adcp/sdk/server` directly — the flat-store surface documented there.
+ *
+ * @example
+ * ```ts
+ * import { createComplyController } from '@adcp/sdk/testing';
+ *
+ * const controller = createComplyController({
+ *   sandboxGate: input => input.auth?.sandbox === true,
+ *   seed: {
+ *     product: (params) => productRepo.upsert(params.product_id, params.fixture),
+ *     creative: (params) => creativeRepo.upsert(params.creative_id, params.fixture),
+ *   },
+ *   force: {
+ *     creative_status: (params) => creativeRepo.transition(params.creative_id, params.status),
+ *   },
+ * });
+ *
+ * controller.register(server);
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createComplyController = createComplyController;
+const test_controller_1 = require("../server/test-controller");
+const adcp_server_1 = require("../server/adcp-server");
+// ────────────────────────────────────────────────────────────
+// Implementation
+// ────────────────────────────────────────────────────────────
+function controllerError(code, detail) {
+    return { success: false, error: code, error_detail: detail };
+}
+/** Build a {@link TestControllerStore} that delegates to the domain-grouped
+ * adapters. Only methods for registered adapters are set, so
+ * `handleTestControllerRequest` returns `UNKNOWN_SCENARIO` for the rest. */
+function buildStore(config, ctx) {
+    const store = {};
+    const { seed, force, simulate } = config;
+    if (seed?.product) {
+        store.seedProduct = async (productId, fixture) => {
+            await seed.product({ product_id: productId, fixture: fixture ?? {} }, ctx);
+        };
+    }
+    if (seed?.pricing_option) {
+        store.seedPricingOption = async (productId, pricingOptionId, fixture) => {
+            await seed.pricing_option({ product_id: productId, pricing_option_id: pricingOptionId, fixture: fixture ?? {} }, ctx);
+        };
+    }
+    if (seed?.creative) {
+        store.seedCreative = async (creativeId, fixture) => {
+            await seed.creative({ creative_id: creativeId, fixture: fixture ?? {} }, ctx);
+        };
+    }
+    if (seed?.plan) {
+        store.seedPlan = async (planId, fixture) => {
+            await seed.plan({ plan_id: planId, fixture: fixture ?? {} }, ctx);
+        };
+    }
+    if (seed?.media_buy) {
+        store.seedMediaBuy = async (mediaBuyId, fixture) => {
+            await seed.media_buy({ media_buy_id: mediaBuyId, fixture: fixture ?? {} }, ctx);
+        };
+    }
+    if (force?.creative_status) {
+        store.forceCreativeStatus = (creativeId, status, rejection_reason) => Promise.resolve(force.creative_status({ creative_id: creativeId, status, rejection_reason }, ctx));
+    }
+    if (force?.account_status) {
+        store.forceAccountStatus = (accountId, status) => Promise.resolve(force.account_status({ account_id: accountId, status }, ctx));
+    }
+    if (force?.media_buy_status) {
+        store.forceMediaBuyStatus = (mediaBuyId, status, rejection_reason) => Promise.resolve(force.media_buy_status({ media_buy_id: mediaBuyId, status, rejection_reason }, ctx));
+    }
+    if (force?.session_status) {
+        store.forceSessionStatus = (sessionId, status, termination_reason) => Promise.resolve(force.session_status({ session_id: sessionId, status, termination_reason }, ctx));
+    }
+    if (simulate?.delivery) {
+        store.simulateDelivery = (mediaBuyId, params) => Promise.resolve(simulate.delivery({ media_buy_id: mediaBuyId, ...params }, ctx));
+    }
+    if (simulate?.budget_spend) {
+        store.simulateBudgetSpend = params => Promise.resolve(simulate.budget_spend(params, ctx));
+    }
+    return store;
+}
+/** The set of force_* / simulate_* scenarios a config advertises via
+ * `list_scenarios`. Seeds are intentionally NOT advertised per the spec. */
+function advertisedScenarios(config) {
+    const out = [];
+    if (config.force?.creative_status)
+        out.push(test_controller_1.CONTROLLER_SCENARIOS.FORCE_CREATIVE_STATUS);
+    if (config.force?.account_status)
+        out.push(test_controller_1.CONTROLLER_SCENARIOS.FORCE_ACCOUNT_STATUS);
+    if (config.force?.media_buy_status)
+        out.push(test_controller_1.CONTROLLER_SCENARIOS.FORCE_MEDIA_BUY_STATUS);
+    if (config.force?.session_status)
+        out.push(test_controller_1.CONTROLLER_SCENARIOS.FORCE_SESSION_STATUS);
+    if (config.simulate?.delivery)
+        out.push(test_controller_1.CONTROLLER_SCENARIOS.SIMULATE_DELIVERY);
+    if (config.simulate?.budget_spend)
+        out.push(test_controller_1.CONTROLLER_SCENARIOS.SIMULATE_BUDGET_SPEND);
+    return out;
+}
+/** Create a comply_test_controller scaffold from domain-grouped adapters. */
+function createComplyController(config) {
+    const seedCache = config.seedCache ?? (0, test_controller_1.createSeedFixtureCache)();
+    const scenarios = advertisedScenarios(config);
+    // Stable reference so factory answers list_scenarios without invoking
+    // createStore — handleTestControllerRequest inspects the `scenarios` field.
+    const factoryScenarios = Object.freeze([...scenarios]);
+    async function handleRaw(input) {
+        // `list_scenarios` is a capability probe — answer it without consulting
+        // the gate so buyer tooling can distinguish "controller exists but
+        // locked" from "controller missing entirely". State-mutating scenarios
+        // still go through the gate below.
+        const isListScenariosProbe = input.scenario === 'list_scenarios';
+        if (config.sandboxGate && !isListScenariosProbe) {
+            let allowed;
+            try {
+                allowed = await config.sandboxGate(input);
+            }
+            catch (err) {
+                // Don't leak gate-internal errors. Treat as denial — matches how a
+                // sandbox would fail closed if its auth layer threw.
+                void err;
+                return controllerError('FORBIDDEN', 'Sandbox gate check failed');
+            }
+            // Strict equality: anything that is not literally `true` is a denial.
+            // Guards against gates that accidentally return a reason string, a
+            // number, or a truthy object.
+            if (allowed !== true) {
+                return controllerError('FORBIDDEN', 'comply_test_controller is disabled in this environment (non-sandbox or gate denied)');
+            }
+        }
+        const ctx = { input };
+        const store = buildStore(config, ctx);
+        return (0, test_controller_1.handleTestControllerRequest)({ scenarios: factoryScenarios, createStore: () => store }, input, { seedCache });
+    }
+    async function handle(input) {
+        return (0, test_controller_1.toMcpResponse)(await handleRaw(input));
+    }
+    // Shallow-copy the shape so a caller who mutates toolDefinition.inputSchema
+    // doesn't poison subsequent registrations. Zod schema values inside are
+    // themselves immutable, so a one-level copy is enough.
+    const toolDefinition = Object.freeze({
+        name: 'comply_test_controller',
+        description: 'Triggers seller-side state transitions for compliance testing. Sandbox only.',
+        inputSchema: { ...test_controller_1.TOOL_INPUT_SHAPE },
+    });
+    // Per-controller latch so the "ungated controller" warning fires once even
+    // when serve() invokes the factory (and therefore register) per request.
+    let hasWarnedOnRegister = false;
+    function register(server) {
+        // Loud warning when the tool is about to be exposed without any explicit
+        // gate. Sellers who intentionally gate at the transport layer can silence
+        // this by setting ADCP_SANDBOX=1 (or ADCP_COMPLY_CONTROLLER_UNGATED=1 to
+        // opt out entirely). Prevents silent fail-open misuse without breaking
+        // the API's "gate is optional" shape.
+        if (!hasWarnedOnRegister &&
+            !config.sandboxGate &&
+            process.env.ADCP_SANDBOX !== '1' &&
+            process.env.ADCP_COMPLY_CONTROLLER_UNGATED !== '1') {
+            hasWarnedOnRegister = true;
+            // eslint-disable-next-line no-console
+            console.warn('[comply_test_controller] Registered with no sandboxGate and no ' +
+                'ADCP_SANDBOX / ADCP_COMPLY_CONTROLLER_UNGATED env flag. The tool ' +
+                'will accept every request — only correct if your transport layer ' +
+                'enforces sandbox isolation. See createComplyController docs.');
+        }
+        const mcp = (0, adcp_server_1.getSdkServer)(server) ?? server;
+        mcp.registerTool(toolDefinition.name, {
+            description: toolDefinition.description,
+            inputSchema: toolDefinition.inputSchema,
+        }, (async (input) => handle(input)));
+    }
+    return { toolDefinition, handleRaw, handle, register };
+}
+//# sourceMappingURL=comply-controller.js.map

package/dist/lib/testing/comply-controller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"comply-controller.js","sourceRoot":"","sources":["../../../src/lib/testing/comply-controller.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;;AAmSH,wDA2FC;AA3XD,+DASmC;AACnC,uDAAsE;AAgMtE,+DAA+D;AAC/D,iBAAiB;AACjB,+DAA+D;AAE/D,SAAS,eAAe,CAAC,IAA8B,EAAE,MAAc;IACrE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,EAAE,CAAC;AAC/D,CAAC;AAED;;4EAE4E;AAC5E,SAAS,UAAU,CAAC,MAA8B,EAAE,GAA4B;IAC9E,MAAM,KAAK,GAAwB,EAAE,CAAC;IACtC,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,MAAM,CAAC;IAEzC,IAAI,IAAI,EAAE,OAAO,EAAE,CAAC;QAClB,KAAK,CAAC,WAAW,GAAG,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,EAAE;YAC/C,MAAM,IAAI,CAAC,OAAQ,CAAC,EAAE,UAAU,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,IAAI,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC;QAC9E,CAAC,CAAC;IACJ,CAAC;IACD,IAAI,IAAI,EAAE,cAAc,EAAE,CAAC;QACzB,KAAK,CAAC,iBAAiB,GAAG,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,OAAO,EAAE,EAAE;YACtE,MAAM,IAAI,CAAC,cAAe,CACxB,EAAE,UAAU,EAAE,SAAS,EAAE,iBAAiB,EAAE,eAAe,EAAE,OAAO,EAAE,OAAO,IAAI,EAAE,EAAE,EACrF,GAAG,CACJ,CAAC;QACJ,CAAC,CAAC;IACJ,CAAC;IACD,IAAI,IAAI,EAAE,QAAQ,EAAE,CAAC;QACnB,KAAK,CAAC,YAAY,GAAG,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,EAAE;YACjD,MAAM,IAAI,CAAC,QAAS,CAAC,EAAE,WAAW,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,IAAI,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC;QACjF,CAAC,CAAC;IACJ,CAAC;IACD,IAAI,IAAI,EAAE,IAAI,EAAE,CAAC;QACf,KAAK,CAAC,QAAQ,GAAG,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE;YACzC,MAAM,IAAI,CAAC,IAAK,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,IAAI,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC;QACrE,CAAC,CAAC;IACJ,CAAC;IACD,IAAI,IAAI,EAAE,SAAS,EAAE,CAAC;QACpB,KAAK,CAAC,YAAY,GAAG,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,EAAE;YACjD,MAAM,IAAI,CAAC,SAAU,CAAC,EAAE,YAAY,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,IAAI,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC;QACnF,CAAC,CAAC;IACJ,CAAC;IAED,IAAI,KAAK,EAAE,eAAe,EAAE,CAAC;QAC3B,KAAK,CAAC,mBAAmB,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,gBAAgB,EAAE,EAAE,CACnE,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,eAAgB,CAAC,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,EAAE,gBAAgB,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC;IACxG,CAAC;IACD,IAAI,KAAK,EAAE,cAAc,EAAE,CAAC;QAC1B,KAAK,CAAC,kBAAkB,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,CAC/C,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,cAAe,CAAC,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC;IACnF,CAAC;IACD,IAAI,KAAK,EAAE,gBAAgB,EAAE,CAAC;QAC5B,KAAK,CAAC,mBAAmB,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,gBAAgB,EAAE,EAAE,CACnE,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,gBAAiB,CAAC,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,gBAAgB,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC;IAC1G,CAAC;IACD,IAAI,KAAK,EAAE,cAAc,EAAE,CAAC;QAC1B,KAAK,CAAC,kBAAkB,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,kBAAkB,EAAE,EAAE,CACnE,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,cAAe,CAAC,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,kBAAkB,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC;IACvG,CAAC;IAED,IAAI,QAAQ,EAAE,QAAQ,EAAE,CAAC;QACvB,KAAK,CAAC,gBAAgB,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,CAC9C,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,QAAS,CAAC,EAAE,YAAY,EAAE,UAAU,EAAE,GAAG,MAAM,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC;IACtF,CAAC;IACD,IAAI,QAAQ,EAAE,YAAY,EAAE,CAAC;QAC3B,KAAK,CAAC,mBAAmB,GAAG,MAAM,CAAC,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,YAAa,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;IAC7F,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED;4EAC4E;AAC5E,SAAS,mBAAmB,CAAC,MAA8B;IACzD,MAAM,GAAG,GAAyB,EAAE,CAAC;IACrC,IAAI,MAAM,CAAC,KAAK,EAAE,eAAe;QAAE,GAAG,CAAC,IAAI,CAAC,sCAAoB,CAAC,qBAAqB,CAAC,CAAC;IACxF,IAAI,MAAM,CAAC,KAAK,EAAE,cAAc;QAAE,GAAG,CAAC,IAAI,CAAC,sCAAoB,CAAC,oBAAoB,CAAC,CAAC;IACtF,IAAI,MAAM,CAAC,KAAK,EAAE,gBAAgB;QAAE,GAAG,CAAC,IAAI,CAAC,sCAAoB,CAAC,sBAAsB,CAAC,CAAC;IAC1F,IAAI,MAAM,CAAC,KAAK,EAAE,cAAc;QAAE,GAAG,CAAC,IAAI,CAAC,sCAAoB,CAAC,oBAAoB,CAAC,CAAC;IACtF,IAAI,MAAM,CAAC,QAAQ,EAAE,QAAQ;QAAE,GAAG,CAAC,IAAI,CAAC,sCAAoB,CAAC,iBAAiB,CAAC,CAAC;IAChF,IAAI,MAAM,CAAC,QAAQ,EAAE,YAAY;QAAE,GAAG,CAAC,IAAI,CAAC,sCAAoB,CAAC,qBAAqB,CAAC,CAAC;IACxF,OAAO,GAAG,CAAC;AACb,CAAC;AAED,6EAA6E;AAC7E,SAAgB,sBAAsB,CAAC,MAA8B;IACnE,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,IAAI,IAAA,wCAAsB,GAAE,CAAC;IAC/D,MAAM,SAAS,GAAG,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAC9C,sEAAsE;IACtE,4EAA4E;IAC5E,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,SAAS,CAAC,CAAkC,CAAC;IAExF,KAAK,UAAU,SAAS,CAAC,KAA8B;QACrD,wEAAwE;QACxE,mEAAmE;QACnE,uEAAuE;QACvE,mCAAmC;QACnC,MAAM,oBAAoB,GAAG,KAAK,CAAC,QAAQ,KAAK,gBAAgB,CAAC;QAEjE,IAAI,MAAM,CAAC,WAAW,IAAI,CAAC,oBAAoB,EAAE,CAAC;YAChD,IAAI,OAAgB,CAAC;YACrB,IAAI,CAAC;gBACH,OAAO,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;YAC5C,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,mEAAmE;gBACnE,qDAAqD;gBACrD,KAAK,GAAG,CAAC;gBACT,OAAO,eAAe,CAAC,WAAW,EAAE,2BAA2B,CAAC,CAAC;YACnE,CAAC;YACD,sEAAsE;YACtE,mEAAmE;YACnE,8BAA8B;YAC9B,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;gBACrB,OAAO,eAAe,CACpB,WAAW,EACX,qFAAqF,CACtF,CAAC;YACJ,CAAC;QACH,CAAC;QAED,MAAM,GAAG,GAA4B,EAAE,KAAK,EAAE,CAAC;QAC/C,MAAM,KAAK,GAAG,UAAU,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAEtC,OAAO,IAAA,6CAA2B,EAAC,EAAE,SAAS,EAAE,gBAAgB,EAAE,WAAW,EAAE,GAAG,EAAE,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;IACtH,CAAC;IAED,KAAK,UAAU,MAAM,CAAC,KAA8B;QAClD,OAAO,IAAA,+BAAa,EAAC,MAAM,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;IAC/C,CAAC;IAED,4EAA4E;IAC5E,wEAAwE;IACxE,uDAAuD;IACvD,MAAM,cAAc,GAAmC,MAAM,CAAC,MAAM,CAAC;QACnE,IAAI,EAAE,wBAAwB;QAC9B,WAAW,EAAE,8EAA8E;QAC3F,WAAW,EAAE,EAAE,GAAG,kCAAgB,EAAE;KACrC,CAAC,CAAC;IAEH,2EAA2E;IAC3E,yEAAyE;IACzE,IAAI,mBAAmB,GAAG,KAAK,CAAC;IAEhC,SAAS,QAAQ,CAAC,MAA8B;QAC9C,yEAAyE;QACzE,0EAA0E;QAC1E,yEAAyE;QACzE,uEAAuE;QACvE,sCAAsC;QACtC,IACE,CAAC,mBAAmB;YACpB,CAAC,MAAM,CAAC,WAAW;YACnB,OAAO,CAAC,GAAG,CAAC,YAAY,KAAK,GAAG;YAChC,OAAO,CAAC,GAAG,CAAC,8BAA8B,KAAK,GAAG,EAClD,CAAC;YACD,mBAAmB,GAAG,IAAI,CAAC;YAC3B,sCAAsC;YACtC,OAAO,CAAC,IAAI,CACV,iEAAiE;gBAC/D,mEAAmE;gBACnE,mEAAmE;gBACnE,8DAA8D,CACjE,CAAC;QACJ,CAAC;QACD,MAAM,GAAG,GAAG,IAAA,0BAAY,EAAC,MAAoB,CAAC,IAAK,MAAoB,CAAC;QACxE,GAAG,CAAC,YAAY,CACd,cAAc,CAAC,IAAI,EACnB;YACE,WAAW,EAAE,cAAc,CAAC,WAAW;YACvC,WAAW,EAAE,cAAc,CAAC,WAAW;SACxC,EACD,CAAC,KAAK,EAAE,KAA8B,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAA2C,CACpG,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;AACzD,CAAC"}

package/dist/lib/testing/controller-assertions.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Assertion helpers for unit tests that exercise
+ * {@link handleTestControllerRequest} directly.
+ */
+import type { ComplyTestControllerResponse, ControllerError, ListScenariosSuccess, StateTransitionSuccess, SimulationSuccess, ForcedDirectiveSuccess, SeedSuccess } from '../types/tools.generated';
+type AnyControllerSuccess = ListScenariosSuccess | StateTransitionSuccess | SimulationSuccess | ForcedDirectiveSuccess | SeedSuccess;
+/**
+ * `ControllerError` with `error_detail` guaranteed to be present. The SDK's
+ * internal `controllerError` constructor always populates it, so in practice
+ * every error returned by the dispatcher satisfies this narrower type —
+ * returning it lets callers assert on detail without `!` or `?.`.
+ */
+export type ControllerErrorWithDetail = ControllerError & {
+    error_detail: string;
+};
+/**
+ * Narrow a `ComplyTestControllerResponse` to the `ControllerError` arm and
+ * assert its `error` code. Throws an `Error` with a descriptive message when
+ * the response is success-shaped or when the code does not match.
+ *
+ * Returns the narrowed error so callers can make further assertions on
+ * `error_detail` / `current_state` without re-casting.
+ *
+ * ```ts
+ * const result = await handleTestControllerRequest(store, {
+ *   scenario: 'force_account_status',
+ *   params: {},
+ * });
+ * const err = expectControllerError(result, 'INVALID_PARAMS');
+ * assert.match(err.error_detail, /account_id/);
+ * ```
+ */
+export declare function expectControllerError(result: ComplyTestControllerResponse, code: ControllerError['error']): ControllerErrorWithDetail;
+/**
+ * Narrow a `ComplyTestControllerResponse` to its success arm and optionally
+ * assert which success shape it is (`'list'`, `'transition'`, or `'simulation'`).
+ * Throws when the response is an error or when the arm doesn't match.
+ *
+ * Returns the narrowed success value so callers skip the `if (result.success)`
+ * boilerplate and access arm-specific fields directly.
+ *
+ * ```ts
+ * const result = await handleTestControllerRequest(store, {
+ *   scenario: 'force_account_status',
+ *   params: { account_id: 'acct-1', status: 'suspended' },
+ * });
+ * const ok = expectControllerSuccess(result, 'transition');
+ * assert.strictEqual(ok.current_state, 'suspended');
+ * ```
+ */
+export declare function expectControllerSuccess(result: ComplyTestControllerResponse, kind?: 'list'): ListScenariosSuccess;
+export declare function expectControllerSuccess(result: ComplyTestControllerResponse, kind: 'transition'): StateTransitionSuccess;
+export declare function expectControllerSuccess(result: ComplyTestControllerResponse, kind: 'simulation'): SimulationSuccess;
+export declare function expectControllerSuccess(result: ComplyTestControllerResponse, kind: 'forced'): ForcedDirectiveSuccess;
+/**
+ * Narrow to the `SeedSuccess` arm (3.0.1+ message-only seed acknowledgement).
+ *
+ * Every `seed_*` scenario returns `SeedSuccess` (`{ success: true, message? }`)
+ * — both responses produced by the SDK's own `dispatchSeed` and responses
+ * from third-party sellers. Force_* scenarios continue to return
+ * `StateTransitionSuccess` (`previous_state` / `current_state`) under
+ * `kind: 'transition'`.
+ */
+export declare function expectControllerSuccess(result: ComplyTestControllerResponse, kind: 'seed'): SeedSuccess;
+export declare function expectControllerSuccess(result: ComplyTestControllerResponse): AnyControllerSuccess;
+export {};
+//# sourceMappingURL=controller-assertions.d.ts.map

package/dist/lib/testing/controller-assertions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller-assertions.d.ts","sourceRoot":"","sources":["../../../src/lib/testing/controller-assertions.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,4BAA4B,EAC5B,eAAe,EACf,oBAAoB,EACpB,sBAAsB,EACtB,iBAAiB,EACjB,sBAAsB,EACtB,WAAW,EACZ,MAAM,0BAA0B,CAAC;AAElC,KAAK,oBAAoB,GACrB,oBAAoB,GACpB,sBAAsB,GACtB,iBAAiB,GACjB,sBAAsB,GACtB,WAAW,CAAC;AAEhB;;;;;GAKG;AACH,MAAM,MAAM,yBAAyB,GAAG,eAAe,GAAG;IAAE,YAAY,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,4BAA4B,EACpC,IAAI,EAAE,eAAe,CAAC,OAAO,CAAC,GAC7B,yBAAyB,CAiB3B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,4BAA4B,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,oBAAoB,CAAC;AACnH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,4BAA4B,EACpC,IAAI,EAAE,YAAY,GACjB,sBAAsB,CAAC;AAC1B,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,4BAA4B,EAAE,IAAI,EAAE,YAAY,GAAG,iBAAiB,CAAC;AACrH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,4BAA4B,EAAE,IAAI,EAAE,QAAQ,GAAG,sBAAsB,CAAC;AACtH;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,4BAA4B,EAAE,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;AACzG,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,4BAA4B,GAAG,oBAAoB,CAAC"}

package/dist/lib/testing/controller-assertions.js

@@ -0,0 +1,60 @@
+"use strict";
+/**
+ * Assertion helpers for unit tests that exercise
+ * {@link handleTestControllerRequest} directly.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.expectControllerError = expectControllerError;
+exports.expectControllerSuccess = expectControllerSuccess;
+/**
+ * Narrow a `ComplyTestControllerResponse` to the `ControllerError` arm and
+ * assert its `error` code. Throws an `Error` with a descriptive message when
+ * the response is success-shaped or when the code does not match.
+ *
+ * Returns the narrowed error so callers can make further assertions on
+ * `error_detail` / `current_state` without re-casting.
+ *
+ * ```ts
+ * const result = await handleTestControllerRequest(store, {
+ *   scenario: 'force_account_status',
+ *   params: {},
+ * });
+ * const err = expectControllerError(result, 'INVALID_PARAMS');
+ * assert.match(err.error_detail, /account_id/);
+ * ```
+ */
+function expectControllerError(result, code) {
+    if (result.success !== false) {
+        throw new Error(`expectControllerError(${code}): expected a ControllerError response but got success-shaped result: ${JSON.stringify(result)}`);
+    }
+    if (result.error !== code) {
+        throw new Error(`expectControllerError(${code}): expected error code "${code}" but got "${result.error}" (detail: ${result.error_detail ?? 'n/a'})`);
+    }
+    // error_detail is always populated by the SDK's controllerError() constructor.
+    return result;
+}
+function expectControllerSuccess(result, kind) {
+    if (result.success !== true) {
+        throw new Error(`expectControllerSuccess: expected a success response but got ControllerError ${result.error}${result.error_detail ? ` (${result.error_detail})` : ''}`);
+    }
+    if (kind === undefined) {
+        return result;
+    }
+    // Discriminate by required field — every success arm has exactly one
+    // distinguishing key. `seed` is the message-only fallback when no other
+    // arm's required field is present.
+    const actual = 'scenarios' in result
+        ? 'list'
+        : 'previous_state' in result
+            ? 'transition'
+            : 'simulated' in result
+                ? 'simulation'
+                : 'forced' in result
+                    ? 'forced'
+                    : 'seed';
+    if (actual !== kind) {
+        throw new Error(`expectControllerSuccess(${kind}): expected "${kind}" arm but got "${actual}"`);
+    }
+    return result;
+}
+//# sourceMappingURL=controller-assertions.js.map

package/dist/lib/testing/controller-assertions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller-assertions.js","sourceRoot":"","sources":["../../../src/lib/testing/controller-assertions.ts"],"names":[],"mappings":";AAAA;;;GAGG;;AA4CH,sDAoBC;AAqCD,0DAiCC;AA3GD;;;;;;;;;;;;;;;;GAgBG;AACH,SAAgB,qBAAqB,CACnC,MAAoC,EACpC,IAA8B;IAE9B,IAAI,MAAM,CAAC,OAAO,KAAK,KAAK,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CACb,yBAAyB,IAAI,yEAAyE,IAAI,CAAC,SAAS,CAClH,MAAM,CACP,EAAE,CACJ,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CACb,yBAAyB,IAAI,2BAA2B,IAAI,cAAc,MAAM,CAAC,KAAK,cACpF,MAAM,CAAC,YAAY,IAAI,KACzB,GAAG,CACJ,CAAC;IACJ,CAAC;IACD,+EAA+E;IAC/E,OAAO,MAAmC,CAAC;AAC7C,CAAC;AAqCD,SAAgB,uBAAuB,CACrC,MAAoC,EACpC,IAA+D;IAE/D,IAAI,MAAM,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CACb,gFAAgF,MAAM,CAAC,KAAK,GAC1F,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,YAAY,GAAG,CAAC,CAAC,CAAC,EACtD,EAAE,CACH,CAAC;IACJ,CAAC;IAED,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,qEAAqE;IACrE,wEAAwE;IACxE,mCAAmC;IACnC,MAAM,MAAM,GACV,WAAW,IAAI,MAAM;QACnB,CAAC,CAAC,MAAM;QACR,CAAC,CAAC,gBAAgB,IAAI,MAAM;YAC1B,CAAC,CAAC,YAAY;YACd,CAAC,CAAC,WAAW,IAAI,MAAM;gBACrB,CAAC,CAAC,YAAY;gBACd,CAAC,CAAC,QAAQ,IAAI,MAAM;oBAClB,CAAC,CAAC,QAAQ;oBACV,CAAC,CAAC,MAAM,CAAC;IACnB,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CAAC,2BAA2B,IAAI,gBAAgB,IAAI,kBAAkB,MAAM,GAAG,CAAC,CAAC;IAClG,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/lib/testing/formatter.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Test result formatting for AdCP Agent E2E Testing
+ */
+import type { TestResult } from './types';
+/**
+ * Format test results for display in Slack/chat
+ */
+export declare function formatTestResults(result: TestResult): string;
+/**
+ * Format test results as JSON for programmatic use
+ */
+export declare function formatTestResultsJSON(result: TestResult): string;
+/**
+ * Format test results as a compact summary
+ */
+export declare function formatTestResultsSummary(result: TestResult): string;
+//# sourceMappingURL=formatter.d.ts.map

package/dist/lib/testing/formatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatter.d.ts","sourceRoot":"","sources":["../../../src/lib/testing/formatter.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1C;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAiE5D;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAEhE;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAenE"}