@adcp/sdk 5.23.0

package/dist/lib/server/create-adcp-server.js

@@ -0,0 +1,1831 @@
+"use strict";
+/**
+ * Declarative AdCP server builder.
+ *
+ * `createAdcpServer` wires domain-grouped handler functions to Zod input
+ * schemas, response builders, and account resolution.
+ * Handlers only run when preconditions pass. `get_adcp_capabilities` is
+ * auto-generated from the tools you register.
+ *
+ * For governance on financial tools (create_media_buy, update_media_buy,
+ * activate_signal), use the composable `checkGovernance()` helper inside
+ * your handler — see `governance.ts`.
+ *
+ * @example
+ * ```typescript
+ * import { createAdcpServer, serve } from '@adcp/sdk/server';
+ *
+ * serve(() => createAdcpServer({
+ *   name: 'My Publisher',
+ *   version: '1.0.0',
+ *
+ *   // Second argument carries `toolName` and (when `authenticate` is wired
+ *   // on `serve()`) the caller's `authInfo`. Adapters that front an
+ *   // upstream platform API can use the caller's token here to resolve
+ *   // the platform account in one pass.
+ *   resolveAccount: async (ref, { authInfo }) => db.findAccount(ref, authInfo),
+ *
+ *   mediaBuy: {
+ *     getProducts: async (params, ctx) => ({ products: catalog.search(params) }),
+ *     createMediaBuy: async (params, ctx) => ({
+ *       media_buy_id: `mb_${Date.now()}`,
+ *       packages: [],
+ *     }),
+ *   },
+ * }));
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ADCP_SIGNED_REQUESTS_STATE = exports.ADCP_PRE_TRANSPORT = void 0;
+exports.requireSessionKey = requireSessionKey;
+exports.createAdcpServer = createAdcpServer;
+const zod_1 = require("zod");
+const adcp_version_config_1 = require("../utils/adcp-version-config");
+const adcp_server_1 = require("./adcp-server");
+const tasks_1 = require("./tasks");
+const errors_1 = require("./errors");
+const envelope_allowlist_1 = require("./envelope-allowlist");
+const state_store_1 = require("./state-store");
+const responses_1 = require("./responses");
+const tool_request_schemas_1 = require("../utils/tool-request-schemas");
+// NOTE on `outputSchema`: the MCP SDK's client-side `callTool` validates
+// `result.structuredContent` against the registered `outputSchema`
+// whenever structuredContent is present — regardless of `isError`. See
+// `node_modules/@modelcontextprotocol/sdk/dist/esm/client/index.js` line
+// 504. AdCP's `adcpError()` envelope carries
+// `structuredContent: { adcp_error: {...} }` with `isError: true`, which
+// would fail every client-side outputSchema check (the error shape
+// doesn't match the success schema). Until the SDK gates that client
+// check on `!isError` too, we do not declare `outputSchema` on
+// framework-registered tools — response drift is caught by the
+// dispatcher's AJV validator (#727) instead, and custom tools opt in
+// explicitly via `customTools[*].outputSchema`.
+function hasIdempotencyClearAll(store) {
+    // `clearAll` is optional on `IdempotencyStore` — only present when the
+    // configured backend opts in (memory backend does; pg backend does not).
+    return typeof store.clearAll === 'function';
+}
+const idempotency_1 = require("../utils/idempotency");
+const schema_validator_1 = require("../validation/schema-validator");
+const schema_errors_1 = require("../validation/schema-errors");
+const webhook_emitter_1 = require("./webhook-emitter");
+const middleware_1 = require("../signing/middleware");
+const test_controller_bridge_1 = require("./test-controller-bridge");
+const version_1 = require("../version");
+const capabilities_1 = require("../utils/capabilities");
+const noopLogger = {
+    debug() { },
+    info() { },
+    warn() { },
+    error() { },
+};
+/**
+ * Narrow `ctx.sessionKey` from `string | undefined` to `string`. Use this in
+ * handlers that require session scoping so you don't litter `!` assertions:
+ *
+ * ```ts
+ * const sessionKey = requireSessionKey(ctx);
+ * const sessionStore = scopedStore(ctx.store, sessionKey);
+ * ```
+ *
+ * Throws a `SERVICE_UNAVAILABLE`-style error if `sessionKey` is missing — typically
+ * meaning `resolveSessionKey` isn't configured or returned `undefined` for this tool.
+ */
+function requireSessionKey(ctx) {
+    if (ctx.sessionKey == null) {
+        throw new Error('ctx.sessionKey is undefined. Configure resolveSessionKey on createAdcpServer, or guard per-tool before calling requireSessionKey.');
+    }
+    return ctx.sessionKey;
+}
+/**
+ * Symbol under which `createAdcpServer` attaches the auto-wired `preTransport`
+ * function to the returned `McpServer`. `serve()` reads this symbol to mount
+ * the verifier. Consumers typically don't need to touch it; it's exported for
+ * tests and for downstream frameworks that want the same wiring.
+ */
+exports.ADCP_PRE_TRANSPORT = Symbol.for('@adcp/client.preTransport');
+/**
+ * Symbol under which `createAdcpServer` attaches the `AdcpSignedRequestsState`
+ * snapshot. Use `server[ADCP_SIGNED_REQUESTS_STATE]` to inspect wiring from
+ * tests or boot diagnostics.
+ */
+exports.ADCP_SIGNED_REQUESTS_STATE = Symbol.for('@adcp/client.signedRequestsState');
+/**
+ * Clamp idempotency replay TTL to spec bounds (1h–7d).
+ */
+function clampReplayTtl(seconds) {
+    const MIN = 3600;
+    const MAX = 604800;
+    if (!Number.isFinite(seconds) || seconds < MIN)
+        return MIN;
+    if (seconds > MAX)
+        return MAX;
+    return Math.floor(seconds);
+}
+/**
+ * Deep-merge the per-domain blocks from `overrides` onto `target`. Nested
+ * objects merge recursively; arrays and primitives replace. `null` at the
+ * top-level field explicitly drops the block; `undefined` is a no-op.
+ */
+function applyCapabilityOverrides(target, overrides) {
+    const targetAny = target;
+    for (const [key, value] of Object.entries(overrides)) {
+        if (value === undefined)
+            continue;
+        if (value === null) {
+            delete targetAny[key];
+            continue;
+        }
+        targetAny[key] = deepMergePlainObjects(targetAny[key], value);
+    }
+}
+function isPlainObject(v) {
+    if (v === null || typeof v !== 'object')
+        return false;
+    if (Array.isArray(v))
+        return false;
+    const proto = Object.getPrototypeOf(v);
+    return proto === Object.prototype || proto === null;
+}
+function deepMergePlainObjects(target, source) {
+    if (source === undefined)
+        return target;
+    if (source === null)
+        return null;
+    if (!isPlainObject(source))
+        return source;
+    if (!isPlainObject(target))
+        return { ...source };
+    const out = { ...target };
+    for (const [k, v] of Object.entries(source)) {
+        if (v === undefined)
+            continue;
+        if (v === null) {
+            delete out[k];
+            continue;
+        }
+        out[k] = deepMergePlainObjects(out[k], v);
+    }
+    return out;
+}
+/**
+ * Stamp `replayed: true` on the response envelope for replay paths only.
+ * `protocol-envelope.json` permits the field to be "omitted when the
+ * request was executed fresh" — fresh-path responses therefore carry no
+ * `replayed` field, and the field's presence implies `true`. Buyers read
+ * the field to distinguish cached replays from new executions for billing
+ * and audit.
+ *
+ * Mirrors the marker into both L3 `structuredContent` and the L2
+ * `content[0].text` JSON fallback so A2A/REST adapters that consume the
+ * text body see the same envelope MCP does — matching the lockstep
+ * pattern in `injectContextIntoResponse` / `sanitizeAdcpErrorEnvelope`.
+ */
+function stampReplayed(response) {
+    if (!response.structuredContent || typeof response.structuredContent !== 'object')
+        return;
+    const sc = response.structuredContent;
+    sc.replayed = true;
+    if (Array.isArray(response.content)) {
+        const first = response.content[0];
+        if (first && first.type === 'text' && typeof first.text === 'string') {
+            try {
+                const parsed = JSON.parse(first.text);
+                if (parsed && typeof parsed === 'object') {
+                    parsed.replayed = true;
+                    first.text = JSON.stringify(parsed);
+                }
+            }
+            catch {
+                // Text isn't JSON — leave it alone (implausible for AdCP responses).
+            }
+        }
+    }
+}
+/**
+ * Remove per-request echo fields (`context`) from a formatted MCP response
+ * before caching. The buyer's `correlation_id` is scoped to the individual
+ * retry attempt and must not be baked into the cached envelope — replays
+ * need to echo back the CURRENT retry's context, not the first caller's.
+ * Other fields (media_buy_id, status, timestamps) are part of the pinned
+ * response and stay put.
+ */
+function stripEnvelopeEcho(response) {
+    const cloned = cloneFormattedResponse(response);
+    if (cloned.structuredContent && typeof cloned.structuredContent === 'object') {
+        const sc = cloned.structuredContent;
+        delete sc.context;
+    }
+    if (Array.isArray(cloned.content)) {
+        for (const item of cloned.content) {
+            if (item && item.type === 'text' && typeof item.text === 'string') {
+                try {
+                    const parsed = JSON.parse(item.text);
+                    if (parsed && typeof parsed === 'object') {
+                        delete parsed.context;
+                        item.text = JSON.stringify(parsed);
+                    }
+                }
+                catch {
+                    // Text isn't JSON — leave it alone
+                }
+            }
+        }
+    }
+    return cloned;
+}
+/**
+ * Shallow-clone a formatted MCP response so callers can mutate envelope
+ * fields (`replayed`, echo-back `context`) without stomping on the cache
+ * entry. The backend returns a fresh object (memory clones, pg
+ * serializes) but re-wrapping via `wrap()` can still alias pieces of the
+ * handler's return value — belt-and-suspenders against mutation leaks.
+ */
+function cloneFormattedResponse(response) {
+    const cloned = { ...response };
+    if (cloned.structuredContent && typeof cloned.structuredContent === 'object') {
+        cloned.structuredContent = { ...cloned.structuredContent };
+    }
+    if (Array.isArray(cloned.content)) {
+        cloned.content = cloned.content.map(item => ({ ...item }));
+    }
+    return cloned;
+}
+/**
+ * Detect whether a formatted MCP response represents a failure. Failures
+ * are NOT cached — a retry should re-execute rather than replay a
+ * transient error. Checks all three shapes the framework emits:
+ * `isError: true`, `structuredContent.adcp_error`, or envelope
+ * `status: 'failed'` (the envelope example in the spec for failed async
+ * tasks doesn't always include `adcp_error`).
+ */
+function isErrorResponse(response) {
+    if (response.isError === true)
+        return true;
+    const sc = response.structuredContent;
+    if (sc && typeof sc === 'object') {
+        if ('adcp_error' in sc)
+            return true;
+        const status = sc.status;
+        if (status === 'failed' || status === 'canceled' || status === 'rejected')
+            return true;
+    }
+    return false;
+}
+/**
+ * Detect a thrown `adcpError(...)` envelope. Handlers that `throw` an
+ * envelope (instead of `return`-ing it) would otherwise surface as
+ * `[object Object]` inside a SERVICE_UNAVAILABLE wrapper — the dispatcher
+ * unwraps and returns the envelope directly when the shape matches.
+ */
+function isThrownAdcpError(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const sc = value.structuredContent;
+    if (!sc || typeof sc !== 'object')
+        return false;
+    const env = sc.adcp_error;
+    if (!env || typeof env !== 'object')
+        return false;
+    // `adcpError()` guarantees both `code` and `message` as strings — assert
+    // both so a malformed envelope throw doesn't produce a half-formed
+    // response. Also rules out MCP SDK `McpError` (numeric `code`) and any
+    // other thrown object with a coincidentally-shaped sub-tree.
+    if (typeof env.code !== 'string')
+        return false;
+    if (typeof env.message !== 'string')
+        return false;
+    return Array.isArray(value.content) && value.isError === true;
+}
+/**
+ * Resolve the extra scope segment for tools with per-session semantics.
+ *
+ * For `si_send_message`, the request `session_id` enters the scope so
+ * the same idempotency_key used across two sessions doesn't false-replay
+ * (or false-conflict) across them. Other tools return `undefined` and
+ * use the default `(principal, key)` scope.
+ */
+function resolveExtraScope(toolName, params) {
+    if (toolName === 'si_send_message') {
+        const sessionId = params.session_id;
+        return typeof sessionId === 'string' && sessionId.length > 0 ? sessionId : undefined;
+    }
+    return undefined;
+}
+function genericResponse(toolName, data, summary) {
+    return {
+        content: [{ type: 'text', text: summary ?? `${toolName} completed` }],
+        structuredContent: (0, responses_1.toStructuredContent)(data),
+    };
+}
+function wrapBuildCreative(data, summary) {
+    if ('creative_manifests' in data) {
+        return (0, responses_1.buildCreativeMultiResponse)(data, summary);
+    }
+    return (0, responses_1.buildCreativeResponse)(data, summary);
+}
+// Shorthand annotation constants
+const RO = { readOnlyHint: true };
+const MUT = { readOnlyHint: false, destructiveHint: false };
+const DEST = { readOnlyHint: false, destructiveHint: true };
+const IDEMP = { readOnlyHint: false, idempotentHint: true };
+// Passthrough schema for every framework-registered tool (#909). See
+// the comment at the registerTool call sites for rationale — short
+// version: makes our AJV validator authoritative on both transports
+// without destroying args on MCP when the SDK's tool dispatcher would
+// otherwise coerce `undefined` into the handler for schemaless tools.
+// This also keeps `tools/list` payloads small for LLM consumers (full
+// schemas live in `docs/llms.txt`, SKILL.md files, and `schemas/cache/`).
+const PASSTHROUGH_INPUT_SCHEMA = zod_1.z.object({}).passthrough();
+const TOOL_META = {
+    // Media Buy
+    get_products: { wrap: responses_1.productsResponse, annotations: RO },
+    create_media_buy: { wrap: responses_1.mediaBuyResponse, annotations: MUT },
+    update_media_buy: { wrap: responses_1.updateMediaBuyResponse, annotations: MUT },
+    get_media_buys: { wrap: responses_1.getMediaBuysResponse, annotations: RO },
+    get_media_buy_delivery: { wrap: responses_1.deliveryResponse, annotations: RO },
+    provide_performance_feedback: { wrap: responses_1.performanceFeedbackResponse, annotations: MUT },
+    // Creative
+    list_creative_formats: { wrap: responses_1.listCreativeFormatsResponse, annotations: RO },
+    build_creative: { wrap: wrapBuildCreative, annotations: MUT },
+    preview_creative: { wrap: null, annotations: RO },
+    get_creative_delivery: { wrap: responses_1.creativeDeliveryResponse, annotations: RO },
+    list_creatives: { wrap: responses_1.listCreativesResponse, annotations: RO },
+    sync_creatives: { wrap: responses_1.syncCreativesResponse, annotations: IDEMP },
+    // Signals
+    get_signals: { wrap: responses_1.getSignalsResponse, annotations: RO },
+    activate_signal: { wrap: responses_1.activateSignalResponse, annotations: MUT },
+    // Accounts
+    list_accounts: { wrap: responses_1.listAccountsResponse, annotations: RO },
+    sync_accounts: { wrap: responses_1.syncAccountsResponse, annotations: IDEMP },
+    sync_governance: { wrap: responses_1.syncGovernanceResponse, annotations: IDEMP },
+    get_account_financials: { wrap: null, annotations: RO },
+    report_usage: { wrap: responses_1.reportUsageResponse, annotations: MUT },
+    // Event Tracking
+    sync_event_sources: { wrap: null, annotations: IDEMP },
+    log_event: { wrap: null, annotations: MUT },
+    // Audiences & Catalogs
+    sync_audiences: { wrap: null, annotations: IDEMP },
+    sync_catalogs: { wrap: null, annotations: IDEMP },
+    // Governance - Property Lists
+    create_property_list: { wrap: null, annotations: MUT },
+    update_property_list: { wrap: null, annotations: MUT },
+    get_property_list: { wrap: null, annotations: RO },
+    list_property_lists: { wrap: null, annotations: RO },
+    delete_property_list: { wrap: null, annotations: DEST },
+    // Governance - Content Standards
+    list_content_standards: { wrap: null, annotations: RO },
+    get_content_standards: { wrap: null, annotations: RO },
+    create_content_standards: { wrap: null, annotations: MUT },
+    update_content_standards: { wrap: null, annotations: MUT },
+    calibrate_content: { wrap: null, annotations: MUT },
+    validate_content_delivery: { wrap: null, annotations: RO },
+    get_media_buy_artifacts: { wrap: null, annotations: RO },
+    // Governance - Campaign
+    get_creative_features: { wrap: null, annotations: RO },
+    sync_plans: { wrap: null, annotations: IDEMP },
+    check_governance: { wrap: null, annotations: RO },
+    report_plan_outcome: { wrap: null, annotations: MUT },
+    get_plan_audit_logs: { wrap: null, annotations: RO },
+    // Sponsored Intelligence
+    si_get_offering: { wrap: null, annotations: RO },
+    si_initiate_session: { wrap: null, annotations: MUT },
+    si_send_message: { wrap: null, annotations: MUT },
+    si_terminate_session: { wrap: null, annotations: DEST },
+    // Brand Rights
+    get_brand_identity: { wrap: null, annotations: RO },
+    get_rights: { wrap: null, annotations: RO },
+    acquire_rights: { wrap: responses_1.acquireRightsResponse, annotations: MUT },
+};
+const MEDIA_BUY_ENTRIES = [
+    { handlerKey: 'getProducts', toolName: 'get_products' },
+    { handlerKey: 'createMediaBuy', toolName: 'create_media_buy' },
+    { handlerKey: 'updateMediaBuy', toolName: 'update_media_buy' },
+    { handlerKey: 'getMediaBuys', toolName: 'get_media_buys' },
+    { handlerKey: 'getMediaBuyDelivery', toolName: 'get_media_buy_delivery' },
+    { handlerKey: 'providePerformanceFeedback', toolName: 'provide_performance_feedback' },
+    { handlerKey: 'listCreativeFormats', toolName: 'list_creative_formats' },
+    { handlerKey: 'syncCreatives', toolName: 'sync_creatives' },
+    { handlerKey: 'listCreatives', toolName: 'list_creatives' },
+];
+const EVENT_TRACKING_ENTRIES = [
+    { handlerKey: 'syncEventSources', toolName: 'sync_event_sources' },
+    { handlerKey: 'logEvent', toolName: 'log_event' },
+    { handlerKey: 'syncAudiences', toolName: 'sync_audiences' },
+    { handlerKey: 'syncCatalogs', toolName: 'sync_catalogs' },
+];
+const SIGNALS_ENTRIES = [
+    { handlerKey: 'getSignals', toolName: 'get_signals' },
+    { handlerKey: 'activateSignal', toolName: 'activate_signal' },
+];
+const CREATIVE_ENTRIES = [
+    { handlerKey: 'listCreativeFormats', toolName: 'list_creative_formats' },
+    { handlerKey: 'buildCreative', toolName: 'build_creative' },
+    { handlerKey: 'previewCreative', toolName: 'preview_creative' },
+    { handlerKey: 'listCreatives', toolName: 'list_creatives' },
+    { handlerKey: 'syncCreatives', toolName: 'sync_creatives' },
+    { handlerKey: 'getCreativeDelivery', toolName: 'get_creative_delivery' },
+];
+const GOVERNANCE_ENTRIES = [
+    { handlerKey: 'createPropertyList', toolName: 'create_property_list' },
+    { handlerKey: 'updatePropertyList', toolName: 'update_property_list' },
+    { handlerKey: 'getPropertyList', toolName: 'get_property_list' },
+    { handlerKey: 'listPropertyLists', toolName: 'list_property_lists' },
+    { handlerKey: 'deletePropertyList', toolName: 'delete_property_list' },
+    { handlerKey: 'listContentStandards', toolName: 'list_content_standards' },
+    { handlerKey: 'getContentStandards', toolName: 'get_content_standards' },
+    { handlerKey: 'createContentStandards', toolName: 'create_content_standards' },
+    { handlerKey: 'updateContentStandards', toolName: 'update_content_standards' },
+    { handlerKey: 'calibrateContent', toolName: 'calibrate_content' },
+    { handlerKey: 'validateContentDelivery', toolName: 'validate_content_delivery' },
+    { handlerKey: 'getMediaBuyArtifacts', toolName: 'get_media_buy_artifacts' },
+    { handlerKey: 'getCreativeFeatures', toolName: 'get_creative_features' },
+    { handlerKey: 'syncPlans', toolName: 'sync_plans' },
+    { handlerKey: 'checkGovernance', toolName: 'check_governance' },
+    { handlerKey: 'reportPlanOutcome', toolName: 'report_plan_outcome' },
+    { handlerKey: 'getPlanAuditLogs', toolName: 'get_plan_audit_logs' },
+];
+const ACCOUNT_ENTRIES = [
+    { handlerKey: 'listAccounts', toolName: 'list_accounts' },
+    { handlerKey: 'syncAccounts', toolName: 'sync_accounts' },
+    { handlerKey: 'syncGovernance', toolName: 'sync_governance' },
+    { handlerKey: 'getAccountFinancials', toolName: 'get_account_financials' },
+    { handlerKey: 'reportUsage', toolName: 'report_usage' },
+];
+const SI_ENTRIES = [
+    { handlerKey: 'getOffering', toolName: 'si_get_offering' },
+    { handlerKey: 'initiateSession', toolName: 'si_initiate_session' },
+    { handlerKey: 'sendMessage', toolName: 'si_send_message' },
+    { handlerKey: 'terminateSession', toolName: 'si_terminate_session' },
+];
+const BRAND_RIGHTS_ENTRIES = [
+    { handlerKey: 'getBrandIdentity', toolName: 'get_brand_identity' },
+    { handlerKey: 'getRights', toolName: 'get_rights' },
+    { handlerKey: 'acquireRights', toolName: 'acquire_rights' },
+];
+// ---------------------------------------------------------------------------
+// Protocol detection
+// ---------------------------------------------------------------------------
+const TOOL_PROTOCOL_MAP = [
+    [capabilities_1.MEDIA_BUY_TOOLS, 'media_buy'],
+    [capabilities_1.SIGNALS_TOOLS, 'signals'],
+    [capabilities_1.GOVERNANCE_TOOLS, 'governance'],
+    [capabilities_1.CREATIVE_TOOLS, 'creative'],
+    [capabilities_1.SPONSORED_INTELLIGENCE_TOOLS, 'sponsored_intelligence'],
+    [capabilities_1.BRAND_RIGHTS_TOOLS, 'brand'],
+];
+function detectProtocols(toolNames) {
+    const nameSet = new Set(toolNames);
+    const protocols = [];
+    for (const [tools, protocol] of TOOL_PROTOCOL_MAP) {
+        if (tools.some(t => nameSet.has(t))) {
+            protocols.push(protocol);
+        }
+    }
+    return protocols;
+}
+// ---------------------------------------------------------------------------
+// Tool coherence warnings
+// ---------------------------------------------------------------------------
+const COHERENCE_RULES = [
+    [
+        'create_media_buy',
+        'get_products',
+        'create_media_buy without get_products — buyers cannot discover products before purchasing',
+    ],
+    [
+        'update_media_buy',
+        'get_media_buys',
+        'update_media_buy without get_media_buys — buyers cannot look up what to modify',
+    ],
+    [
+        'activate_signal',
+        'get_signals',
+        'activate_signal without get_signals — buyers cannot discover signals before activating',
+    ],
+    [
+        'sync_creatives',
+        'list_creative_formats',
+        'sync_creatives without list_creative_formats — buyers cannot discover valid formats',
+    ],
+];
+function checkCoherence(toolNames, logger) {
+    for (const [tool, requires, message] of COHERENCE_RULES) {
+        if (toolNames.has(tool) && !toolNames.has(requires)) {
+            logger.warn(message);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Response detection
+// ---------------------------------------------------------------------------
+function isFormattedResponse(value) {
+    if (value == null || typeof value !== 'object')
+        return false;
+    const obj = value;
+    return Array.isArray(obj.content) && 'structuredContent' in obj;
+}
+/**
+ * Detect an AdCP Submitted envelope (async task acknowledgement).
+ *
+ * Every *Submitted arm in the generated types has `status: 'submitted'`
+ * plus a required `task_id: string`. The discriminant is stable enough
+ * to use for routing at dispatch time without per-tool knowledge.
+ */
+function isSubmittedEnvelope(value) {
+    if (value == null || typeof value !== 'object')
+        return false;
+    const obj = value;
+    return obj.status === 'submitted' && typeof obj.task_id === 'string';
+}
+/**
+ * Detect an AdCP *Error arm (union member, not the framework `adcp_error`
+ * envelope). Every *Error interface in the generated types carries a
+ * required `errors: Error[]` and a narrow set of allowed siblings
+ * (`context`, `ext`, plus a couple of tool-specific extras). Success
+ * arms may have optional advisory fields but never a required `errors`
+ * array — the `status === 'submitted'` exclusion keeps us from
+ * confusing a Submitted envelope that advisory-echoes errors as an
+ * Error arm. The set of allowed sibling keys is intentionally narrow:
+ * any other top-level key means the payload carries Success-only fields
+ * (`media_buy_id`, `creatives`, `signal_id`, ...) and should fall
+ * through to the response builder.
+ */
+const ERROR_ARM_ALLOWED_KEYS = new Set(['errors', 'context', 'ext', 'success', 'conflicting_standards_id']);
+function isErrorArm(value) {
+    if (value == null || typeof value !== 'object')
+        return false;
+    const obj = value;
+    if (!Array.isArray(obj.errors))
+        return false;
+    if ('status' in obj)
+        return false;
+    for (const key of Object.keys(obj)) {
+        if (!ERROR_ARM_ALLOWED_KEYS.has(key))
+            return false;
+    }
+    return true;
+}
+/**
+ * Wrap a Submitted envelope returned directly by a handler. Skips the
+ * Success-builder defaults (`revision`, `confirmed_at`, `valid_actions`)
+ * — those fields are specific to `CreateMediaBuySuccess` and would
+ * corrupt the async-task shape if applied.
+ */
+function wrapSubmittedEnvelope(value) {
+    const summary = value.message ?? `Task ${value.task_id} submitted`;
+    return {
+        content: [{ type: 'text', text: summary }],
+        structuredContent: value,
+    };
+}
+/**
+ * Wrap an *Error arm returned directly by a handler. Preserves the
+ * generated-type shape (`errors: Error[]`) on `structuredContent` so
+ * buyers reading the typed response union see the exact branch the
+ * spec defines; also sets `isError: true` so the MCP-level signal
+ * matches `adcp_error` envelopes, which keeps `isErrorResponse()` and
+ * `response-validation: strict` consistent across both error paths.
+ */
+function wrapErrorArm(value) {
+    const firstError = value.errors[0];
+    const summary = firstError && typeof firstError === 'object'
+        ? `${typeof firstError.code === 'string' ? firstError.code : 'ERROR'}: ${typeof firstError.message === 'string' ? firstError.message : 'operation failed'}`
+        : 'operation failed';
+    return {
+        content: [{ type: 'text', text: summary }],
+        isError: true,
+        structuredContent: value,
+    };
+}
+/**
+ * Defence-in-depth sanitizer for handler-returned error envelopes.
+ *
+ * `adcpError()` filters its own output against `ADCP_ERROR_FIELD_ALLOWLIST`,
+ * but a handler that hand-rolls `{ isError: true, structuredContent: {
+ * adcp_error: {...} } }` (or constructs the envelope through a different
+ * builder) bypasses that sanitizer. The storyboard invariant
+ * `idempotency.conflict_no_payload_leak` catches this at conformance-test
+ * time, but production traffic would be unprotected — so we re-apply the
+ * allowlist here too. Silent no-op when the code has no registered entry,
+ * or when `structuredContent.adcp_error` is missing its `code` field.
+ *
+ * Keeps L2 (`content[0].text`) and L3 (`structuredContent`) in lockstep —
+ * both transport layers get the same filtered payload.
+ */
+function sanitizeAdcpErrorEnvelope(response) {
+    const sc = response.structuredContent;
+    if (!sc || typeof sc !== 'object')
+        return;
+    const err = sc.adcp_error;
+    if (!err || typeof err !== 'object')
+        return;
+    const code = err.code;
+    if (typeof code !== 'string')
+        return;
+    const allow = envelope_allowlist_1.ADCP_ERROR_FIELD_ALLOWLIST[code];
+    if (!allow)
+        return;
+    const filtered = {};
+    let droppedAny = false;
+    for (const [k, v] of Object.entries(err)) {
+        if (allow.has(k)) {
+            filtered[k] = v;
+        }
+        else {
+            droppedAny = true;
+        }
+    }
+    if (!droppedAny)
+        return;
+    sc.adcp_error = filtered;
+    if (Array.isArray(response.content)) {
+        const first = response.content[0];
+        if (first && first.type === 'text' && typeof first.text === 'string') {
+            try {
+                const parsed = JSON.parse(first.text);
+                if (parsed && typeof parsed === 'object') {
+                    parsed.adcp_error = filtered;
+                    first.text = JSON.stringify(parsed);
+                }
+            }
+            catch {
+                // Text isn't JSON — leave it alone. adcpError()-emitted envelopes
+                // always serialize to JSON, so the only hit here would be a seller
+                // who hand-rolled a non-JSON content[0] (implausible for AdCP).
+            }
+        }
+    }
+}
+// Echo the request context into a formatted MCP tool response so buyers can
+// trace correlation_id across both success and error responses. Only plain
+// objects are echoed: `si_get_offering` and `si_initiate_session` override
+// the request schema's `context` to a domain-specific string, while the
+// response schema still requires the protocol echo object — copying a
+// string there would fail response validation.
+function injectContextIntoResponse(response, context) {
+    if (context === null || typeof context !== 'object' || Array.isArray(context))
+        return;
+    const sc = response.structuredContent;
+    if (sc && typeof sc === 'object' && !('context' in sc)) {
+        sc.context = context;
+        // Keep the L2 text fallback (JSON body) in sync with structuredContent
+        if (Array.isArray(response.content)) {
+            const first = response.content[0];
+            if (first && first.type === 'text' && typeof first.text === 'string') {
+                try {
+                    const parsed = JSON.parse(first.text);
+                    if (parsed && typeof parsed === 'object' && !('context' in parsed)) {
+                        parsed.context = context;
+                        first.text = JSON.stringify(parsed);
+                    }
+                }
+                catch {
+                    // Text isn't JSON — leave it alone
+                }
+            }
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Signed-requests preTransport builder
+// ---------------------------------------------------------------------------
+/**
+ * Build a `preTransport` middleware that runs `createExpressVerifier` against
+ * the incoming Node request/response. The returned function matches the shape
+ * `serve({ preTransport })` expects: it resolves to `true` when the verifier
+ * has already written a 401 (headers sent), `false` otherwise.
+ *
+ * `serve()` buffers the request body into `req.rawBody` before invoking the
+ * preTransport hook, so the verifier sees the exact bytes the signer hashed
+ * for Content-Digest. For MCP the operation name comes from the JSON-RPC
+ * `params.name`; the resolver below falls back to `undefined` for non-JSON or
+ * non-`tools/call` bodies, which makes the verifier treat them as not-in-
+ * `required_for` rather than rejecting (discovery probes, health checks).
+ */
+function buildSignedRequestsPreTransport(signedRequests, capabilityRequiredFor) {
+    // Precedence: explicit signedRequests.required_for > capabilities.request_signing.required_for
+    // > fallback to every mutating task. Buyers read required_for from
+    // get_adcp_capabilities to decide which calls to sign — defaulting to
+    // MUTATING_TASKS when the seller advertised a narrower list would cause
+    // buyers to get request_signature_required on tools they had no contractual
+    // duty to sign.
+    const requiredFor = signedRequests.required_for ?? capabilityRequiredFor ?? [...idempotency_1.MUTATING_TASKS];
+    const verifier = (0, middleware_1.createExpressVerifier)({
+        capability: {
+            supported: true,
+            covers_content_digest: signedRequests.covers_content_digest ?? 'either',
+            required_for: requiredFor,
+        },
+        jwks: signedRequests.jwks,
+        replayStore: signedRequests.replayStore,
+        revocationStore: signedRequests.revocationStore,
+        ...(signedRequests.agentUrlForKeyid ? { agentUrlForKeyid: signedRequests.agentUrlForKeyid } : {}),
+        resolveOperation: req => {
+            const raw = req.rawBody;
+            if (!raw)
+                return undefined;
+            try {
+                const parsed = JSON.parse(raw);
+                if (parsed.method === 'tools/call' && typeof parsed.params?.name === 'string') {
+                    return parsed.params.name;
+                }
+            }
+            catch {
+                // Non-JSON or malformed body — let transport handle rejection.
+            }
+            return undefined;
+        },
+    });
+    return async function adcpPreTransport(req, res) {
+        const reqShim = {
+            method: req.method ?? 'POST',
+            url: req.url ?? '/mcp',
+            originalUrl: req.url ?? '/mcp',
+            headers: req.headers,
+            rawBody: req.rawBody ?? '',
+            protocol: 'http',
+            get(name) {
+                const v = req.headers[name.toLowerCase()];
+                return Array.isArray(v) ? v.join(', ') : v;
+            },
+        };
+        const resShim = {
+            status(code) {
+                res.statusCode = code;
+                return {
+                    set(k, v) {
+                        res.setHeader(k, v);
+                        return {
+                            json(body) {
+                                res.setHeader('Content-Type', 'application/json');
+                                res.end(JSON.stringify(body));
+                            },
+                        };
+                    },
+                };
+            },
+        };
+        let handled = false;
+        let verifierCompleted = false;
+        // The verifier calls `next(err?)` in the success / error path, but the
+        // 401 RequestSignatureError path writes the response and returns WITHOUT
+        // calling next. Race the next-callback against the response's 'finish' /
+        // 'close' events so a terminal 401 resolves the promise; otherwise the
+        // wrapper hangs forever and the agent server leaks (one McpServer per
+        // unsigned request under attack).
+        //
+        // Security: if 'close' fires before the verifier completes (client
+        // aborted the TCP connection mid-JWKS-fetch), we MUST NOT fall through
+        // to the MCP transport — doing so would execute the tool handler
+        // without a verified signature on an attacker-dropped connection. Mark
+        // handled=true so serve.ts skips dispatch.
+        await new Promise(resolve => {
+            let resolved = false;
+            const done = () => {
+                if (resolved)
+                    return;
+                resolved = true;
+                resolve();
+            };
+            res.once('finish', () => {
+                if (res.writableEnded)
+                    handled = true;
+                done();
+            });
+            res.once('close', () => {
+                if (!verifierCompleted)
+                    handled = true;
+                done();
+            });
+            verifier(reqShim, resShim, err => {
+                verifierCompleted = true;
+                if (err) {
+                    // Log internally; a leaked stack trace to the caller would
+                    // enumerate the verifier pipeline (js/stack-trace-exposure).
+                    // Narrow to name+code only — full error stringification can embed
+                    // JWKS URLs from transport failures, which leaks counterparty
+                    // key-discovery topology on shared log aggregators.
+                    const errName = err.name || 'Error';
+                    const errCode = err.code ?? 'unknown';
+                    console.error(`[adcp/signed-requests] verifier middleware error: ${errName} (${errCode})`);
+                    if (!res.writableEnded) {
+                        res.statusCode = 500;
+                        res.setHeader('Content-Type', 'application/json');
+                        res.end(JSON.stringify({ error: 'verifier_error' }));
+                    }
+                    handled = true;
+                }
+                if (res.writableEnded)
+                    handled = true;
+                done();
+            });
+        });
+        return handled;
+    };
+}
+// ---------------------------------------------------------------------------
+// createAdcpServer
+// ---------------------------------------------------------------------------
+/**
+ * Create an AdCP-compliant MCP server from domain-grouped handler functions.
+ *
+ * Before each handler runs, the framework:
+ * 1. Validates the request against the tool's Zod schema (MCP SDK)
+ * 2. Resolves the account (if the tool has an `account` field and `resolveAccount` is configured)
+ *
+ * The handler only runs when all preconditions pass. It receives the validated
+ * params and a context with the resolved account and state store.
+ *
+ * `get_adcp_capabilities` is auto-generated from registered tools.
+ */
+function createAdcpServer(config) {
+    const { name, version, adcpVersion: configuredAdcpVersion, resolveAccount, resolveSessionKey, exposeErrorDetails = process.env.NODE_ENV !== 'production', stateStore = new state_store_1.InMemoryStateStore(), logger = noopLogger, capabilities: capConfig, idempotency: idempotencyConfig, resolveIdempotencyPrincipal, instructions, taskStore, taskMessageQueue, webhooks, signedRequests, validation: validationConfig, testController: testControllerBridge, } = config;
+    // Defaults gated on `process.env.NODE_ENV`:
+    //   - Production → both sides `'off'` (zero AJV overhead; trust the
+    //     handler after its test suite has exercised it).
+    //   - Dev/test/CI → BOTH sides `'strict'`. Request validation is now
+    //     authoritative on both transports (#909) — we dropped the SDK
+    //     Zod from `registerTool` inputSchema, so if our framework validator
+    //     doesn't reject malformed payloads they reach the handler
+    //     unchecked over A2A. Matching responses' existing `'strict'`
+    //     default keeps behavior consistent across the wire in both
+    //     directions.
+    // Explicit `validation: { requests, responses }` on the config always
+    // wins. `process.env.NODE_ENV` matches the convention every other SDK
+    // consumer already tunes (Express, React, etc.); containers/CI that
+    // want prod-like behavior set NODE_ENV=production before start.
+    const isProduction = process.env.NODE_ENV === 'production';
+    const requestValidationMode = validationConfig?.requests ?? (isProduction ? 'off' : 'strict');
+    const responseValidationMode = validationConfig?.responses ?? (isProduction ? 'off' : 'strict');
+    // Split the `idempotency` config field into "the active store" and
+    // "explicitly opted out" so existing call sites keep working with a
+    // single nullable variable while the disabled-mode branches stay
+    // surgical. `idempotencyDisabled` gates: schema-level missing-key
+    // tolerance, the missing-store guardrail log, the capability
+    // declaration shift to `IdempotencyUnsupported`, and the runtime
+    // production check below.
+    const idempotencyDisabled = idempotencyConfig === 'disabled';
+    const idempotency = idempotencyDisabled ? undefined : idempotencyConfig;
+    if (idempotencyDisabled) {
+        // Allowlist gate. The earlier draft refused the flag only when
+        // NODE_ENV === 'production', which is a footgun: NODE_ENV defaults to
+        // unset in raw Lambda, custom containers, and many K8s deployments,
+        // so the strict equality returned `false` in exactly the
+        // hard-to-debug environments where disabled mode is most dangerous.
+        // Inverted to an allowlist of dev/test environments; any other value
+        // (unset, 'production', 'staging', 'qa', custom names) requires the
+        // operator to explicitly acknowledge the risk via
+        // `ADCP_IDEMPOTENCY_DISABLED_ACK=1`. Hard to set by accident, makes
+        // the choice deliberate, and turns a missing-NODE_ENV config into a
+        // startup crash instead of a silent money-flow incident on retry.
+        const env = process.env.NODE_ENV;
+        const acknowledged = process.env.ADCP_IDEMPOTENCY_DISABLED_ACK === '1';
+        const isAllowlistedDevEnv = env === 'test' || env === 'development';
+        if (!isAllowlistedDevEnv && !acknowledged) {
+            throw new Error("createAdcpServer: idempotency: 'disabled' refuses to start with NODE_ENV=" +
+                (env === undefined ? '<unset>' : JSON.stringify(env)) +
+                '. Disabled mode skips replay enforcement and silently double-executes mutating handlers on retry, ' +
+                'so the SDK only allows it under NODE_ENV=test or NODE_ENV=development by default. ' +
+                'Either: (a) wire a real store via `createIdempotencyStore({ backend, ttlSeconds })`, ' +
+                '(b) set NODE_ENV=test or NODE_ENV=development if this is a dev-only environment, or ' +
+                '(c) set ADCP_IDEMPOTENCY_DISABLED_ACK=1 to explicitly acknowledge the risk for non-standard environments.');
+        }
+        logger.warn("createAdcpServer: idempotency: 'disabled' is set. Mutating requests will not be replay-checked and " +
+            '`get_adcp_capabilities` will declare `idempotency.supported: false`. Use only in non-production test fleets.');
+    }
+    // Enforce lock-step between the `signed-requests` specialism claim and the
+    // verifier config for the auto-wiring path. When `signedRequests` is set
+    // but the specialism isn't declared, buyers can't discover the signing
+    // requirement from `get_adcp_capabilities` — they won't sign, the
+    // verifier rejects every mutating call, and the agent is dead on arrival.
+    // That's unambiguously wrong, so we throw.
+    //
+    // The opposite direction — claiming the specialism without a
+    // `signedRequests` config — is only wrong when the agent also doesn't
+    // wire a verifier via `serve({ preTransport })`. Legacy servers that
+    // hand-build the middleware fall into this case and are still conformant.
+    // We log a loud error so operators notice (matching the idempotency
+    // guardrail precedent) but don't throw, leaving the manual path working.
+    const specialismsClaimed = capConfig?.specialisms ?? [];
+    const claimsSignedRequests = specialismsClaimed.includes('signed-requests');
+    if (signedRequests && !claimsSignedRequests) {
+        throw new Error('createAdcpServer: `signedRequests` is configured but `capabilities.specialisms` does not include "signed-requests". ' +
+            'Add "signed-requests" to the specialisms list — buyers discover the signing requirement from get_adcp_capabilities, ' +
+            "and omitting the claim means they won't sign their requests.");
+    }
+    if (claimsSignedRequests && !signedRequests) {
+        logger.error('createAdcpServer: `capabilities.specialisms` claims "signed-requests" but no `signedRequests` config was provided. ' +
+            'Either pass `signedRequests: { jwks, replayStore, revocationStore }` to auto-wire the verifier, or ensure you wire ' +
+            'one manually via `serve({ preTransport })`. Claiming the specialism without verifying signatures is a spec violation.');
+    }
+    // The specialism is only meaningful when `capabilities.request_signing.supported`
+    // is true — the compliance storyboard treats a missing or false `supported`
+    // flag as "not opted in" and silently skips the whole conformance run. Claim
+    // + supported:false is the worst failure mode: the claim advertises
+    // signature enforcement while the capability block tells buyers the agent
+    // doesn't verify. Fail fast so the mismatch is caught at construction.
+    if (claimsSignedRequests && capConfig?.request_signing?.supported !== true) {
+        throw new Error('createAdcpServer: `capabilities.specialisms` claims "signed-requests" but `capabilities.request_signing.supported` is not true. ' +
+            'Set `capabilities.request_signing = { supported: true, ... }` — the compliance storyboard skips conformance entirely when ' +
+            '`supported` is falsy, and buyers cannot discover the signing requirement without the capability block.');
+    }
+    // Cross-domain specialism declaration check. When a domain handler group
+    // is wired, `capabilities.specialisms` SHOULD include at least one of that
+    // domain's specialisms — otherwise the conformance runner grades the agent
+    // as "No applicable tracks found for this agent" silently, even when every
+    // tool works. The matrix v18 run (issue #785) had this drift class account
+    // for ~30% of "agent built every tool but storyboard reports no applicable
+    // tracks" cases.
+    //
+    // Logged via `logger.error` (matching the idempotency-disabled precedent)
+    // rather than thrown because middleware-only test harnesses legitimately
+    // wire handlers without declaring specialisms — production agents will see
+    // the warning and conformance fail loudly, but tests stay passing.
+    //
+    // mediaBuy is intentionally excluded — its specialism choices
+    // (sales-non-guaranteed vs sales-guaranteed vs sales-broadcast-tv vs
+    // sales-social etc.) are commercially significant and an agent wiring
+    // `mediaBuy.getProducts` may legitimately defer the specialism
+    // declaration to a follow-up. The skill examples in build-seller-agent
+    // already cover the right declaration; the runtime guardrail floor is
+    // set at "if you wire creative/signals/brand/governance handlers,
+    // you SHOULD claim a specialism."
+    //
+    // governance is intentionally COARSE: any governance specialism
+    // satisfies the check even though individual handlers map to specific
+    // specialisms (createPropertyList → property-lists, calibrateContent →
+    // content-standards, etc.). Per-handler-subgroup mapping is a
+    // follow-up; the coarse rule catches the drift class (governance
+    // handlers wired, no claim at all) without false-positives on
+    // legitimate cross-cutting reads (e.g., a sales agent that calls
+    // getPropertyList for read-only joins and claims its sales specialism).
+    const isWired = (handlers) => {
+        // Filter to function-valued keys so `{ listCreativeFormats: undefined }`
+        // (a key set to undefined, e.g. via `{ ...maybeHandlers }` spread) is
+        // treated as not wired. `Object.keys` would otherwise count the key.
+        if (!handlers)
+            return false;
+        return Object.values(handlers).some(v => typeof v === 'function');
+    };
+    const DOMAIN_SPECIALISM_REQUIREMENTS = [
+        {
+            domain: 'creative',
+            wired: isWired(config.creative),
+            specialisms: ['creative-ad-server', 'creative-generative', 'creative-template'],
+        },
+        {
+            domain: 'signals',
+            wired: isWired(config.signals),
+            specialisms: ['signal-marketplace', 'signal-owned'],
+        },
+        {
+            domain: 'brandRights',
+            wired: isWired(config.brandRights),
+            specialisms: ['brand-rights'],
+        },
+        {
+            domain: 'governance',
+            wired: isWired(config.governance),
+            specialisms: [
+                'governance-spend-authority',
+                'governance-delivery-monitor',
+                'property-lists',
+                'collection-lists',
+                'content-standards',
+            ],
+        },
+    ];
+    for (const req of DOMAIN_SPECIALISM_REQUIREMENTS) {
+        if (!req.wired)
+            continue;
+        const claimedFromDomain = req.specialisms.filter(s => specialismsClaimed.includes(s));
+        if (claimedFromDomain.length === 0) {
+            logger.error(`createAdcpServer: ${req.domain} handlers are wired but capabilities.specialisms ` +
+                `does not include any ${req.domain} specialism. Add at least one of ` +
+                `${req.specialisms.map(s => `'${s}'`).join(', ')} to capabilities.specialisms — ` +
+                `without it, the conformance runner reports "No applicable tracks found" and ` +
+                `the agent grades as failing despite working tools.`);
+        }
+    }
+    // Instantiate the emitter once — handler contexts expose its `emit`
+    // bound method so per-request code calls `ctx.emitWebhook(...)` without
+    // knowing about the emitter's construction or options.
+    const webhookEmitter = webhooks ? (0, webhook_emitter_1.createWebhookEmitter)(webhooks) : undefined;
+    const server = (0, tasks_1.createTaskCapableServer)(name, version, {
+        taskStore,
+        taskMessageQueue,
+        instructions,
+    });
+    const registeredToolNames = new Set();
+    // Collect all domain handlers into a flat toolName → handler map
+    const domainGroups = [
+        [config.mediaBuy, MEDIA_BUY_ENTRIES],
+        [config.signals, SIGNALS_ENTRIES],
+        [config.creative, CREATIVE_ENTRIES],
+        [config.governance, GOVERNANCE_ENTRIES],
+        [config.accounts, ACCOUNT_ENTRIES],
+        [config.eventTracking, EVENT_TRACKING_ENTRIES],
+        [config.sponsoredIntelligence, SI_ENTRIES],
+        [config.brandRights, BRAND_RIGHTS_ENTRIES],
+    ];
+    for (const [handlers, entries] of domainGroups) {
+        if (!handlers)
+            continue;
+        // Warn on unrecognized handler keys (likely typos)
+        const knownKeys = new Set(entries.map(e => e.handlerKey));
+        for (const key of Object.keys(handlers)) {
+            if (typeof handlers[key] === 'function' && !knownKeys.has(key)) {
+                logger.warn(`Unknown handler key "${key}" — will not be registered. Check for typos.`);
+            }
+        }
+        for (const { handlerKey, toolName } of entries) {
+            const handler = handlers[handlerKey];
+            if (!handler)
+                continue;
+            if (registeredToolNames.has(toolName)) {
+                // Tool already registered by another domain (e.g., list_creative_formats
+                // in both mediaBuy and creative). First domain wins.
+                logger.warn(`Tool "${toolName}" already registered by another domain, skipping`);
+                continue;
+            }
+            const meta = TOOL_META[toolName];
+            const schema = tool_request_schemas_1.TOOL_REQUEST_SCHEMAS[toolName];
+            if (!schema?.shape) {
+                logger.warn(`No schema found for tool "${toolName}" in TOOL_REQUEST_SCHEMAS, skipping`);
+                continue;
+            }
+            const hasAccount = 'account' in schema.shape;
+            const wrap = meta?.wrap ?? ((data, summary) => genericResponse(toolName, data, summary));
+            const toolHandler = async (params, extra) => {
+                const ctx = { store: stateStore };
+                if (extra?.authInfo)
+                    ctx.authInfo = extra.authInfo;
+                if (webhookEmitter)
+                    ctx.emitWebhook = webhookEmitter.emit.bind(webhookEmitter);
+                // Echo params.context into any response (success or error) so buyers
+                // can trace correlation_id end-to-end. Framework-generated errors
+                // (ACCOUNT_NOT_FOUND, SERVICE_UNAVAILABLE) go through this too.
+                // `injectContextIntoResponse` skips non-object values so SI tools
+                // that override `context` as a string on the request don't leak the
+                // string into the response envelope.
+                //
+                // `sanitizeAdcpErrorEnvelope` re-applies `ADCP_ERROR_FIELD_ALLOWLIST`
+                // as a runtime belt-and-suspenders for handlers that build an error
+                // envelope outside `adcpError()` — `adcpError()` already filters its
+                // own output, but a hand-rolled `{ isError, structuredContent:
+                // { adcp_error: ... } }` would otherwise ship unfiltered.
+                const finalize = (response) => {
+                    sanitizeAdcpErrorEnvelope(response);
+                    injectContextIntoResponse(response, params.context);
+                    return response;
+                };
+                const toolIsMutating = (0, idempotency_1.isMutatingTask)(toolName);
+                // --- Request schema validation (opt-in) ---
+                // Runs before idempotency so drifted payloads never touch the
+                // replay cache. `off` short-circuits without calling AJV.
+                if (requestValidationMode !== 'off') {
+                    const outcome = (0, schema_validator_1.validateRequest)(toolName, params);
+                    if (!outcome.valid) {
+                        // When `idempotency: 'disabled'` is set, drop the synthetic
+                        // "missing idempotency_key" failure on mutating tools — the
+                        // operator has explicitly opted out of enforcement and would
+                        // otherwise need to UUID-inject every test payload to satisfy
+                        // the spec-required field. All other schema issues still fail.
+                        //
+                        // The exact-match `pointer === '/idempotency_key'` is
+                        // load-bearing: AJV builds the pointer from `instancePath +
+                        // /missingProperty`, so today every mutating tool's
+                        // idempotency_key sits at the top level (instancePath = '',
+                        // pointer = '/idempotency_key'). If a future spec revision
+                        // ever nests this field under another object, the new pointer
+                        // (`/foo/idempotency_key`) won't match this filter and the
+                        // strict-mode failure will correctly bubble up — drift is
+                        // surfaced rather than silently swallowed.
+                        const issues = idempotencyDisabled && toolIsMutating
+                            ? outcome.issues.filter(i => !(i.keyword === 'required' && i.pointer === '/idempotency_key'))
+                            : outcome.issues;
+                        if (issues.length > 0) {
+                            if (requestValidationMode === 'strict') {
+                                // Thread `exposeSchemaPath` the same way response-side does
+                                // so request-side schemaPath also ships in dev and stays
+                                // gated in production. Prior to this, request-side silently
+                                // stripped schemaPath even in dev — asymmetric with response-side.
+                                const payload = (0, schema_errors_1.buildAdcpValidationErrorPayload)(toolName, 'request', issues, {
+                                    exposeSchemaPath: exposeErrorDetails,
+                                });
+                                return finalize((0, errors_1.adcpError)('VALIDATION_ERROR', payload));
+                            }
+                            logger.warn(`Schema validation warning (request) for ${toolName}: ${(0, schema_validator_1.formatIssues)(issues)}`, {
+                                tool: toolName,
+                                issues,
+                            });
+                        }
+                    }
+                }
+                // --- Account resolution ---
+                if (hasAccount && params.account != null && resolveAccount) {
+                    try {
+                        const account = await resolveAccount(params.account, {
+                            toolName: toolName,
+                            authInfo: ctx.authInfo,
+                        });
+                        if (account == null) {
+                            logger.warn('Account not found', { tool: toolName, account: params.account });
+                            return finalize((0, errors_1.adcpError)('ACCOUNT_NOT_FOUND', {
+                                message: 'The specified account does not exist',
+                                field: 'account',
+                                suggestion: 'Use list_accounts to discover available accounts, or sync_accounts to create one',
+                            }));
+                        }
+                        ctx.account = account;
+                    }
+                    catch (err) {
+                        const reason = err instanceof Error ? err.message : String(err);
+                        logger.error('Account resolution failed', { tool: toolName, error: reason });
+                        return finalize((0, errors_1.adcpError)('SERVICE_UNAVAILABLE', {
+                            message: 'Account resolution failed',
+                            ...(exposeErrorDetails && { details: { reason } }),
+                        }));
+                    }
+                }
+                // --- Session key resolution ---
+                if (resolveSessionKey) {
+                    try {
+                        const sessionKey = await resolveSessionKey({
+                            toolName: toolName,
+                            params,
+                            account: ctx.account,
+                        });
+                        if (sessionKey !== undefined)
+                            ctx.sessionKey = sessionKey;
+                    }
+                    catch (err) {
+                        const reason = err instanceof Error ? err.message : String(err);
+                        logger.error('Session key resolution failed', { tool: toolName, error: reason });
+                        return finalize((0, errors_1.adcpError)('SERVICE_UNAVAILABLE', {
+                            message: 'Session key resolution failed',
+                            ...(exposeErrorDetails && { details: { reason } }),
+                        }));
+                    }
+                }
+                // --- idempotency_key shape gate (runs even in disabled mode) ---
+                // Defense-in-depth against buyers that bypass MCP schema
+                // validation (different transport, bespoke client) AND against
+                // disabled-mode environments where the replay middleware below is
+                // skipped. Low-entropy keys pollute the cache and enable
+                // enumeration; keys containing the internal scope-separator byte
+                // would collide with the cache's scope tuple. Even in disabled
+                // mode (no cache, no enforcement) a malformed key flowing into
+                // handler logs is a debuggability hazard — so we reject the
+                // shape whenever a key was supplied, regardless of whether the
+                // replay middleware will execute. Missing-key enforcement
+                // remains scoped to the middleware below (gated on `idempotency`),
+                // so disabled mode tolerates absence per the schema-filter
+                // contract earlier in this dispatcher.
+                if (toolIsMutating &&
+                    typeof params.idempotency_key === 'string' &&
+                    !idempotency_1.IDEMPOTENCY_KEY_PATTERN.test(params.idempotency_key)) {
+                    return finalize((0, errors_1.adcpError)('INVALID_REQUEST', {
+                        message: 'idempotency_key must match the spec pattern ^[A-Za-z0-9_.:-]{16,255}$',
+                        field: 'idempotency_key',
+                    }));
+                }
+                // --- Idempotency (mutating tools only) ---
+                let idempotencyCheck;
+                if (idempotency && toolIsMutating) {
+                    const key = typeof params.idempotency_key === 'string' ? params.idempotency_key : undefined;
+                    if (!key) {
+                        return finalize((0, errors_1.adcpError)('INVALID_REQUEST', {
+                            message: 'idempotency_key is required on mutating requests',
+                            field: 'idempotency_key',
+                        }));
+                    }
+                    // Pattern check already ran in the shape gate above. By this
+                    // point `key` is guaranteed to match IDEMPOTENCY_KEY_PATTERN.
+                    const principal = (resolveIdempotencyPrincipal
+                        ? resolveIdempotencyPrincipal(ctx, params, toolName)
+                        : ctx.sessionKey) ?? '';
+                    if (!principal) {
+                        logger.error('Idempotency principal unresolved', { tool: toolName });
+                        return finalize((0, errors_1.adcpError)('SERVICE_UNAVAILABLE', {
+                            message: 'Idempotency principal could not be resolved — configure resolveSessionKey or resolveIdempotencyPrincipal',
+                        }));
+                    }
+                    // SI `si_send_message` is scoped per-session — the same key under
+                    // two different sessions must not replay into each other. The
+                    // caller's session_id enters the scope tuple so each session has
+                    // its own idempotency namespace.
+                    const extraScope = resolveExtraScope(toolName, params);
+                    try {
+                        const checkResult = await idempotency.check({ principal, key, payload: params, extraScope });
+                        if (checkResult.kind === 'replay') {
+                            // The cache stores the already-formatted envelope (so
+                            // non-deterministic wrap fields like `confirmed_at` are
+                            // pinned to the first execution's values). Clone before
+                            // mutating so envelope stamps (replayed, echo-back context)
+                            // don't leak into the cache — the backend also clones on
+                            // read, but belt-and-suspenders: handler-returned objects
+                            // can alias pieces of the formatted envelope.
+                            const cachedFormatted = cloneFormattedResponse(checkResult.response);
+                            // Only stamp `replayed: true` on success envelopes — the
+                            // field is defined for successful replays, and transient
+                            // error cache entries (VALIDATION_ERROR from strict-mode
+                            // drift) are retry-storm guards, not spec replays.
+                            if (!isErrorResponse(cachedFormatted)) {
+                                stampReplayed(cachedFormatted);
+                            }
+                            return finalize(cachedFormatted);
+                        }
+                        if (checkResult.kind === 'conflict') {
+                            return finalize((0, errors_1.adcpError)('IDEMPOTENCY_CONFLICT', {
+                                message: 'idempotency_key was used earlier with a different canonical payload. Use a fresh UUID v4, or resend the exact original payload.',
+                            }));
+                        }
+                        if (checkResult.kind === 'expired') {
+                            return finalize((0, errors_1.adcpError)('IDEMPOTENCY_EXPIRED', {
+                                message: `idempotency_key is past the seller's replay window (${idempotency.ttlSeconds}s). Use a fresh UUID v4, or look up the resource by natural key if the prior call succeeded.`,
+                            }));
+                        }
+                        if (checkResult.kind === 'in-flight') {
+                            // A parallel request is currently executing this same key.
+                            // Tell the client to retry — returning SERVICE_UNAVAILABLE
+                            // with a short retry_after is transient-classified and the
+                            // buyer SDK auto-retries. Eventually the other request
+                            // completes and this retry either replays the cached
+                            // response or hits IDEMPOTENCY_CONFLICT.
+                            return finalize((0, errors_1.adcpError)('SERVICE_UNAVAILABLE', {
+                                message: 'A parallel request with the same idempotency_key is still in flight. Retry shortly.',
+                                retry_after: 1,
+                            }));
+                        }
+                        idempotencyCheck = { key, principal, payloadHash: checkResult.payloadHash, extraScope };
+                    }
+                    catch (err) {
+                        const reason = err instanceof Error ? err.message : String(err);
+                        logger.error('Idempotency check failed', { tool: toolName, error: reason });
+                        return finalize((0, errors_1.adcpError)('SERVICE_UNAVAILABLE', {
+                            message: 'Idempotency check failed',
+                            ...(exposeErrorDetails && { details: { reason } }),
+                        }));
+                    }
+                }
+                // --- Handler ---
+                try {
+                    const result = await handler(params, ctx);
+                    // Narrow Error / Submitted arms of the *Response union before
+                    // reaching the success-arm builder: wrap() on an Error payload
+                    // would still serialize it but apply success-shaped defaults
+                    // (revision, confirmed_at, 'Media buy undefined created') to
+                    // a shape that doesn't have those fields. Routing here keeps
+                    // the wire shape correct regardless of which arm the handler
+                    // chose to return.
+                    let formatted;
+                    if (isFormattedResponse(result)) {
+                        formatted = result;
+                    }
+                    else if (isSubmittedEnvelope(result)) {
+                        formatted = wrapSubmittedEnvelope(result);
+                    }
+                    else if (isErrorArm(result)) {
+                        // Log-warn (always) on spec-violating Error items — required
+                        // `code`/`message` are spec-mandatory on core/error.json. We
+                        // don't fail the response: response-schema validation is
+                        // already skipped for `isError: true` envelopes and flipping
+                        // a handler-returned Error arm into a framework VALIDATION_ERROR
+                        // would obscure the seller's intended error. A steady-state
+                        // warn is enough to surface drift in dev/test logs.
+                        const malformed = result.errors.some(e => e == null ||
+                            typeof e !== 'object' ||
+                            typeof e.code !== 'string' ||
+                            typeof e.message !== 'string');
+                        if (malformed) {
+                            logger.warn(`Handler returned ${toolName} Error arm with spec-violating errors[]`, {
+                                tool: toolName,
+                                errors: result.errors,
+                            });
+                        }
+                        formatted = wrapErrorArm(result);
+                    }
+                    else {
+                        formatted = wrap(result);
+                    }
+                    // --- Test-controller bridge: augment get_products with seeded fixtures. ---
+                    // Only runs when the seller opted in via `testController.getSeededProducts`
+                    // AND the request carries a sandbox marker (account.sandbox === true or
+                    // context.sandbox === true). When `resolveAccount` returned a concrete
+                    // account, we additionally require `ctx.account.sandbox === true` so a
+                    // request that happens to include `account.sandbox: true` can't leak
+                    // fixtures into a non-sandbox resolved account (belt-and-suspenders).
+                    // Seeded products append to whatever the handler returned; `product_id`
+                    // collisions resolve with the seeded entry winning, so storyboards that
+                    // override default inventory see their fixture.
+                    if (toolName === 'get_products' &&
+                        testControllerBridge?.getSeededProducts &&
+                        !isErrorResponse(formatted) &&
+                        (0, test_controller_bridge_1.isSandboxRequest)(params) &&
+                        // If resolveAccount produced a record, require it to be flagged
+                        // sandbox too. If no account was resolved, the request-signal
+                        // check above is the only line of defense — keep that contract.
+                        (ctx.account === undefined ||
+                            (typeof ctx.account === 'object' &&
+                                ctx.account !== null &&
+                                ctx.account.sandbox === true))) {
+                        try {
+                            const bridgeCtx = { input: params };
+                            if (ctx.account !== undefined)
+                                bridgeCtx.account = ctx.account;
+                            const rawSeeded = await testControllerBridge.getSeededProducts(bridgeCtx);
+                            const seeded = (0, test_controller_bridge_1.filterValidSeededProducts)(rawSeeded, logger);
+                            if (seeded.length > 0) {
+                                const sc = formatted.structuredContent;
+                                if (sc && typeof sc === 'object') {
+                                    const merged = (0, test_controller_bridge_1.mergeSeededProductsIntoResponse)(sc, seeded);
+                                    formatted = wrap(merged);
+                                }
+                            }
+                        }
+                        catch (err) {
+                            // Bridge failures are sandbox-only by construction, so logging +
+                            // returning the handler's response is the right default — a broken
+                            // test fixture shouldn't tank the request under test.
+                            const reason = err instanceof Error ? err.message : String(err);
+                            logger.warn('testController.getSeededProducts failed; returning handler response unchanged', {
+                                tool: toolName,
+                                error: reason,
+                            });
+                        }
+                    }
+                    // --- Response schema validation (opt-in) ---
+                    // Runs on the structured payload the handler produced. Errors
+                    // have their own envelope (`adcp_error`) and are skipped here —
+                    // their shape is enforced by the adcpError() builder.
+                    if (responseValidationMode !== 'off' && !isErrorResponse(formatted)) {
+                        const payload = formatted.structuredContent;
+                        const outcome = (0, schema_validator_1.validateResponse)(toolName, payload);
+                        if (!outcome.valid) {
+                            logger.warn(`Schema validation warning (response) for ${toolName}: ${(0, schema_validator_1.formatIssues)(outcome.issues)}`, {
+                                tool: toolName,
+                                issues: outcome.issues,
+                                variant: outcome.variant,
+                            });
+                            if (responseValidationMode === 'strict') {
+                                const errPayload = (0, schema_errors_1.buildAdcpValidationErrorPayload)(toolName, 'response', outcome.issues, {
+                                    exposeSchemaPath: exposeErrorDetails,
+                                });
+                                const errEnvelope = (0, errors_1.adcpError)('VALIDATION_ERROR', errPayload);
+                                if (idempotencyCheck && idempotency) {
+                                    // Cache the VALIDATION_ERROR briefly so a buyer SDK
+                                    // retrying on the same key doesn't trigger unbounded
+                                    // re-execution — strict-mode drift is deterministic,
+                                    // the next handler call would return the same error.
+                                    // Short TTL (10s) absorbs a typical retry burst.
+                                    //
+                                    // Stores that pre-date #758 may not implement
+                                    // `saveTransientError`; fall back to `release` so the
+                                    // claim is at least freed for a fresh retry.
+                                    try {
+                                        if (idempotency.saveTransientError) {
+                                            await idempotency.saveTransientError({
+                                                principal: idempotencyCheck.principal,
+                                                key: idempotencyCheck.key,
+                                                payloadHash: idempotencyCheck.payloadHash,
+                                                response: errEnvelope,
+                                                extraScope: idempotencyCheck.extraScope,
+                                            });
+                                        }
+                                        else {
+                                            await idempotency.release({
+                                                principal: idempotencyCheck.principal,
+                                                key: idempotencyCheck.key,
+                                                extraScope: idempotencyCheck.extraScope,
+                                            });
+                                        }
+                                    }
+                                    catch (err) {
+                                        const reason = err instanceof Error ? err.message : String(err);
+                                        logger.warn('Idempotency transient-error cache failed — retry storm may re-execute handler', {
+                                            tool: toolName,
+                                            error: reason,
+                                        });
+                                    }
+                                }
+                                return finalize(errEnvelope);
+                            }
+                        }
+                    }
+                    // Cache successful mutations for replay. Errors re-execute on
+                    // retry, not replayed — only cache when the wrapped response is
+                    // not an error shape. Release the in-flight claim on error so a
+                    // retry can re-execute rather than replay the transient failure.
+                    //
+                    // Cache the FORMATTED envelope, not the raw handler return:
+                    // some wrap functions inject non-deterministic fields
+                    // (`confirmed_at = new Date().toISOString()`) when the handler
+                    // omits them. Re-wrapping on replay would produce a different
+                    // `confirmed_at` each time, breaking the "same response on
+                    // replay" contract. Caching the formatted envelope pins those
+                    // fields to their first-execution values.
+                    if (idempotencyCheck && idempotency) {
+                        if (!isErrorResponse(formatted)) {
+                            try {
+                                // Strip `context` before caching — it's a per-request echo
+                                // field (buyer's correlation_id), not part of the cached
+                                // payload. If we cached it, replays would return the
+                                // FIRST caller's correlation_id to every subsequent
+                                // retry, breaking end-to-end request tracing. On replay,
+                                // `finalize()` re-injects the current request's context.
+                                const cacheable = stripEnvelopeEcho(formatted);
+                                await idempotency.save({
+                                    principal: idempotencyCheck.principal,
+                                    key: idempotencyCheck.key,
+                                    payloadHash: idempotencyCheck.payloadHash,
+                                    response: cacheable,
+                                    extraScope: idempotencyCheck.extraScope,
+                                });
+                            }
+                            catch (err) {
+                                const reason = err instanceof Error ? err.message : String(err);
+                                logger.warn('Idempotency save failed — response will not be cached', {
+                                    tool: toolName,
+                                    error: reason,
+                                });
+                            }
+                            // Fresh-path responses omit `replayed` — per envelope spec,
+                            // absence signals fresh execution. The replay path stamps
+                            // `replayed: true` on the cached copy at retrieval.
+                        }
+                        else {
+                            try {
+                                await idempotency.release({
+                                    principal: idempotencyCheck.principal,
+                                    key: idempotencyCheck.key,
+                                    extraScope: idempotencyCheck.extraScope,
+                                });
+                            }
+                            catch (err) {
+                                // Best-effort release; if it fails the claim TTL will
+                                // eventually evict. Log and move on.
+                                const reason = err instanceof Error ? err.message : String(err);
+                                logger.warn('Idempotency release failed — in-flight claim will expire on TTL', {
+                                    tool: toolName,
+                                    error: reason,
+                                });
+                            }
+                        }
+                    }
+                    return finalize(formatted);
+                }
+                catch (err) {
+                    // Release the idempotency claim on any thrown path — whether
+                    // we unwrap a typed envelope or fall through to SERVICE_UNAVAILABLE,
+                    // the handler did not produce a cached response and the next retry
+                    // should proceed normally.
+                    if (idempotencyCheck && idempotency) {
+                        try {
+                            await idempotency.release({
+                                principal: idempotencyCheck.principal,
+                                key: idempotencyCheck.key,
+                                extraScope: idempotencyCheck.extraScope,
+                            });
+                        }
+                        catch (releaseErr) {
+                            const releaseReason = releaseErr instanceof Error ? releaseErr.message : String(releaseErr);
+                            logger.warn('Idempotency release failed — in-flight claim will expire on TTL', {
+                                tool: toolName,
+                                error: releaseReason,
+                            });
+                        }
+                    }
+                    // Auto-unwrap `throw adcpError(...)`. Handlers that throw an
+                    // envelope (instead of returning it) should behave identically —
+                    // otherwise the envelope surfaces as `[object Object]` inside
+                    // SERVICE_UNAVAILABLE and the buyer loses the typed domain code.
+                    // Matrix harnesses and fresh-built agents consistently get this
+                    // wrong; unwrapping at the dispatcher closes the class of bugs
+                    // instead of relying on every skill to show `return` over `throw`.
+                    if (isThrownAdcpError(err)) {
+                        const env = err.structuredContent.adcp_error;
+                        // Log message + stack so forensic review sees what was thrown
+                        // (not just the code). The thrown envelope is a plain object so
+                        // `.stack` is typically absent, but authors sometimes subclass
+                        // `Error` and attach envelope fields; capture it defensively.
+                        logger.warn('Handler threw an adcpError envelope — prefer `return` over `throw` for typed errors', {
+                            tool: toolName,
+                            handler: handlerKey,
+                            code: env.code,
+                            message: env.message,
+                            stack: err instanceof Error ? err.stack : undefined,
+                        });
+                        return finalize(err);
+                    }
+                    const reason = err instanceof Error ? err.message : String(err);
+                    // Log the full stack — `logger.error` with just the message turned
+                    // every "Handler failed" into a guessing game for agent authors.
+                    // Stack tells you which import/typo/access chain blew up.
+                    logger.error('Handler failed', {
+                        tool: toolName,
+                        handler: handlerKey,
+                        error: reason,
+                        stack: err instanceof Error ? err.stack : undefined,
+                    });
+                    return finalize((0, errors_1.adcpError)('SERVICE_UNAVAILABLE', {
+                        // Include the cause message directly in the response text when
+                        // `exposeErrorDetails` is on. The opaque
+                        // "Tool X encountered an internal error" string cost us weeks
+                        // of diagnostic time on the matrix harness — dev callers want
+                        // the real reason at the call site, not hidden in server logs.
+                        message: exposeErrorDetails
+                            ? `Tool ${toolName} handler threw: ${reason}`
+                            : `Tool ${toolName} encountered an internal error`,
+                        ...(exposeErrorDetails && { details: { reason, handler: handlerKey } }),
+                    }));
+                }
+            };
+            // Register a PASSTHROUGH input schema (#909). The MCP SDK's Zod
+            // validator only fires on the MCP transport — A2A calls the
+            // handler via AdcpServer.invoke(), bypassing it. Registering the
+            // real per-tool Zod schema meant MCP and A2A produced different
+            // verdicts and different error shapes for the same malformed
+            // request. Our framework request validator (AJV, loaded from
+            // schemas/cache/<version>/) runs inside the handler closure on
+            // BOTH transports and produces a structured adcp_error envelope;
+            // make it authoritative.
+            //
+            // Passthrough (not omit): the SDK's `validateToolInput` returns
+            // `undefined` when `inputSchema` is absent (see @modelcontextprotocol/sdk
+            // server/mcp.js), and passes that `undefined` verbatim to the
+            // handler — destroying the actual arguments. `z.object({}).passthrough()`
+            // keeps every key intact, so args still reach the closure.
+            //
+            // Trade-off: MCP `tools/list` publishes `{ type: 'object' }` for
+            // every tool (no per-tool parameter schema). This is intentional,
+            // not a wiring gap — inlining ~50 full request schemas in
+            // `tools/list` would balloon the context window for LLM consumers,
+            // who are the primary readers of MCP discovery. Tool shapes live
+            // in `docs/llms.txt`, the SKILL.md files, and `schemas/cache/`,
+            // which curated agents read on demand instead of paying the cost
+            // every connection. AdCP-native discovery via `get_adcp_capabilities`
+            // already works over both transports; upstream #3057 proposes a
+            // `get_schema` capability tool for programmatic per-tool shape
+            // discovery.
+            //
+            // Implication for downstream consumers: if you need a tool's shape
+            // (cross-version field-stripping, gating, validation), read raw
+            // JSON from `schemas/cache/{version}/` via `schema-loader.ts` —
+            // see `schemaAllowsTopLevelField` for the canonical pattern (#940).
+            // Don't try to recover the shape from `tools/list`; it's empty by
+            // design and will fail open.
+            server.registerTool(toolName, {
+                inputSchema: PASSTHROUGH_INPUT_SCHEMA,
+                ...(meta?.annotations != null && { annotations: meta.annotations }),
+            }, toolHandler);
+            registeredToolNames.add(toolName);
+        }
+    }
+    // ─── Custom tools ──────────────────────────────────────────
+    // Seller extensions outside AdcpToolMap. No idempotency / governance /
+    // response-wrapping — handlers own those concerns directly. Registered
+    // after spec tools so the collision check can authoritatively block
+    // overlap with framework-owned names.
+    if (config.customTools) {
+        const customNames = Object.keys(config.customTools);
+        for (const customName of customNames) {
+            if (registeredToolNames.has(customName)) {
+                throw new Error(`createAdcpServer: customTools["${customName}"] collides with a framework-registered tool. ` +
+                    `Rename the custom tool or remove the handler from the conflicting domain group.`);
+            }
+            if (customName === 'get_adcp_capabilities') {
+                throw new Error(`createAdcpServer: customTools["get_adcp_capabilities"] is not allowed. ` +
+                    `The framework auto-generates this tool from registered handlers and capability config.`);
+            }
+            const custom = config.customTools[customName];
+            if (!custom)
+                continue;
+            const { description, title, inputSchema, outputSchema, annotations, handler } = custom;
+            server.registerTool(customName, {
+                ...(description != null && { description }),
+                ...(title != null && { title }),
+                ...(inputSchema != null && { inputSchema }),
+                ...(outputSchema != null && { outputSchema }),
+                ...(annotations != null && { annotations }),
+            }, handler);
+            registeredToolNames.add(customName);
+        }
+    }
+    // Tool coherence warnings
+    checkCoherence(registeredToolNames, logger);
+    // --- Idempotency configuration guardrails ---
+    //
+    // A seller that registers mutating handlers but doesn't supply an
+    // `idempotency` store cannot honor the v3 retry contract: buyer
+    // retries will double-book because there's no replay cache. The
+    // framework logs a loud error at server-creation time so operators
+    // notice before shipping to production, but doesn't throw — that
+    // would make the framework unusable in testing contexts where
+    // idempotency isn't the unit-under-test. Operators who've thought
+    // about it can suppress the error by setting
+    // `capabilities.idempotency.replay_ttl_seconds` directly.
+    const registeredMutatingTools = [...registeredToolNames].filter(t => idempotency_1.MUTATING_TASKS.has(t));
+    if (registeredMutatingTools.length > 0 &&
+        !idempotency &&
+        !idempotencyDisabled &&
+        !capConfig?.idempotency?.replay_ttl_seconds) {
+        logger.error(`createAdcpServer: ${registeredMutatingTools.length} mutating tools registered ` +
+            `(${registeredMutatingTools.slice(0, 3).join(', ')}${registeredMutatingTools.length > 3 ? ', ...' : ''}) without an idempotency store. AdCP v3 requires sellers to support idempotent replay ` +
+            `on mutating requests — buyer retries will double-book without it. ` +
+            `Pass \`idempotency: createIdempotencyStore({ backend, ttlSeconds })\`, ` +
+            `or set \`capabilities.idempotency.replay_ttl_seconds\` to acknowledge the non-compliance.`);
+    }
+    // MUTATING_TASKS is derived at module load by introspecting Zod
+    // schemas. If Zod's internals change or the tool-request-schemas map
+    // shifts, the derivation can silently return an empty set — which
+    // would make every mutating request bypass idempotency enforcement.
+    // Fail loud at server startup if the introspection produced
+    // surprisingly few results.
+    if (idempotency_1.MUTATING_TASKS.size < 20) {
+        throw new Error(`createAdcpServer: MUTATING_TASKS set has only ${idempotency_1.MUTATING_TASKS.size} entries — expected at least 20. ` +
+            `Schema introspection likely broke (Zod upgrade? tool-request-schemas change?). ` +
+            `Check \`src/lib/utils/idempotency.ts:deriveMutatingTasks\`.`);
+    }
+    // --- Auto-register get_adcp_capabilities ---
+    const protocols = detectProtocols([...registeredToolNames]);
+    // Idempotency capability declaration. Spec defines a discriminated
+    // union (`get-adcp-capabilities-response.json` `adcp.idempotency.oneOf`):
+    //   - `IdempotencySupported`  → `{ supported: true,  replay_ttl_seconds: N }`
+    //   - `IdempotencyUnsupported` → `{ supported: false }` (replay_ttl_seconds MUST be absent)
+    // Disabled mode flips to `IdempotencyUnsupported` so the wire contract
+    // matches actual behavior — buyers reading capabilities can fall back to
+    // natural-key dedup before retrying spend-committing operations. Lying
+    // here (declaring `supported: true` while skipping replay) is a
+    // money-flow footgun: a 504-retry under the same key double-books.
+    const idempotencyCapability = idempotencyDisabled
+        ? { supported: false }
+        : {
+            supported: true,
+            replay_ttl_seconds: clampReplayTtl(capConfig?.idempotency?.replay_ttl_seconds ?? idempotency?.ttlSeconds ?? 86400),
+        };
+    const capabilitiesData = {
+        adcp: {
+            major_versions: capConfig?.major_versions ?? [3],
+            idempotency: idempotencyCapability,
+        },
+        supported_protocols: protocols,
+    };
+    if (protocols.includes('media_buy') || capConfig?.features) {
+        capabilitiesData.media_buy = {
+            features: {
+                inline_creative_management: capConfig?.features?.inlineCreativeManagement ?? false,
+                property_list_filtering: capConfig?.features?.propertyListFiltering ?? false,
+                content_standards: capConfig?.features?.contentStandards ?? false,
+                conversion_tracking: capConfig?.features?.conversionTracking ?? false,
+                audience_targeting: capConfig?.features?.audienceTargeting ?? false,
+            },
+            ...(capConfig?.portfolio && { portfolio: capConfig.portfolio }),
+        };
+    }
+    if (capConfig?.account) {
+        capabilitiesData.account = {
+            require_operator_auth: capConfig.account.requireOperatorAuth ?? false,
+            ...(capConfig.account.authorizationEndpoint && {
+                authorization_endpoint: capConfig.account.authorizationEndpoint,
+            }),
+            supported_billing: capConfig.account.supportedBilling ?? [],
+            ...(capConfig.account.defaultBilling && { default_billing: capConfig.account.defaultBilling }),
+            required_for_products: capConfig.account.requiredForProducts ?? false,
+            sandbox: capConfig.account.sandbox ?? false,
+        };
+    }
+    if (capConfig?.creative) {
+        capabilitiesData.creative = {
+            supports_compliance: capConfig.creative.supportsCompliance ?? false,
+            has_creative_library: capConfig.creative.hasCreativeLibrary ?? false,
+            supports_generation: capConfig.creative.supportsGeneration ?? false,
+            supports_transformation: capConfig.creative.supportsTransformation ?? false,
+        };
+    }
+    if (capConfig?.extensions_supported?.length) {
+        capabilitiesData.extensions_supported = capConfig.extensions_supported;
+    }
+    if (capConfig?.request_signing) {
+        capabilitiesData.request_signing = capConfig.request_signing;
+    }
+    if (capConfig?.specialisms?.length) {
+        capabilitiesData.specialisms = capConfig.specialisms;
+    }
+    if (capConfig?.overrides) {
+        applyCapabilityOverrides(capabilitiesData, capConfig.overrides);
+    }
+    // Stamp the SDK version so conformance tooling can surface version-staleness
+    // hints when the agent's reported version predates recommended helpers.
+    // Cast needed because GetAdCPCapabilitiesResponse is generated and lacks
+    // this field; it remains a forward-compatible extension until the spec
+    // formally defines library_version in a future AdCP minor.
+    capabilitiesData.library_version = `@adcp/client@${version_1.LIBRARY_VERSION}`;
+    // Passthrough inputSchema — framework validation is authoritative on
+    // both transports (#909). Same rationale as the domain-tool loop above.
+    server.registerTool('get_adcp_capabilities', {
+        inputSchema: PASSTHROUGH_INPUT_SCHEMA,
+        annotations: { readOnlyHint: true },
+    }, (async (params) => {
+        const data = { ...capabilitiesData };
+        const ctx = params?.context;
+        if (ctx !== null && typeof ctx === 'object' && !Array.isArray(ctx)) {
+            data.context = ctx;
+        }
+        return (0, responses_1.capabilitiesResponse)(data);
+    }));
+    const compliance = {
+        async reset({ force = false, allowProduction = false, } = {}) {
+            // Check NODE_ENV BEFORE store-shape probes: the environment guard
+            // is the strongest signal that "this is not a test harness." An
+            // operator who reached this call in production by mistake hits the
+            // env gate regardless of which backend they wired.
+            if (!allowProduction && process.env.NODE_ENV === 'production') {
+                throw new Error('AdcpServer.compliance.reset: refused to run with NODE_ENV=production. ' +
+                    'Pass `{ allowProduction: true }` if you deliberately set NODE_ENV=production in a test environment, ' +
+                    'or unset NODE_ENV before running storyboards.');
+            }
+            // Positive allowlist for stores, not method-presence. A
+            // PostgresStateStore might expose `.clear()` for its own test
+            // utility needs — we don't want method-existence alone to permit
+            // a flush that would take out a shared test cluster. `force: true`
+            // is the documented opt-in for non-memory backends.
+            const stateStoreIsMemory = stateStore instanceof state_store_1.InMemoryStateStore;
+            const idempotencyIsFlushable = !idempotency || hasIdempotencyClearAll(idempotency);
+            if (!force) {
+                if (!stateStoreIsMemory) {
+                    throw new Error('AdcpServer.compliance.reset: configured stateStore is not InMemoryStateStore. ' +
+                        'Pass `{ force: true }` to acknowledge that flushing the configured backend is safe for this environment ' +
+                        '(e.g., a disposable test Postgres).');
+                }
+                if (!idempotencyIsFlushable) {
+                    throw new Error('AdcpServer.compliance.reset: configured idempotency backend does not expose `clearAll()`. ' +
+                        'Use `memoryBackend()` for test harnesses, or pass `{ force: true }` to skip idempotency flush.');
+                }
+            }
+            // `force` bypasses the allowlist checks but never the flush
+            // itself — if we reached here, the caller wants the flush to
+            // happen. `clear()` is only called when the store exposes it;
+            // a store without `clear()` reaching here under `force: true`
+            // is a no-op for the state side, which matches the shape the
+            // caller opted into.
+            const storeWithClear = stateStore;
+            if (typeof storeWithClear.clear === 'function')
+                storeWithClear.clear();
+            if (idempotency && idempotency.clearAll)
+                await idempotency.clearAll();
+        },
+    };
+    // Throws ConfigurationError on cross-major pin. See utils/adcp-version-config.ts.
+    const adcpVersion = (0, adcp_version_config_1.resolveAdcpVersion)(configuredAdcpVersion);
+    const wrapped = (0, adcp_server_1.wrapMcpServer)(server, compliance, adcpVersion);
+    // Attach the auto-wired preTransport so `serve()` mounts the verifier
+    // on the HTTP transport. Stashed under a non-enumerable symbol property
+    // on the wrapper — it's a private contract between this function and
+    // `serve()` for wiring, not part of the AdcpServer public API.
+    if (signedRequests) {
+        const preTransport = buildSignedRequestsPreTransport(signedRequests, capConfig?.request_signing?.required_for);
+        Object.defineProperty(wrapped, exports.ADCP_PRE_TRANSPORT, {
+            value: preTransport,
+            enumerable: false,
+            writable: false,
+            configurable: true,
+        });
+    }
+    const signedRequestsState = {
+        autoWired: Boolean(signedRequests),
+        specialismClaimed: claimsSignedRequests,
+        capabilitySupported: capConfig?.request_signing?.supported === true,
+        mismatch: claimsSignedRequests && !signedRequests ? 'claim_without_config' : 'ok',
+    };
+    Object.defineProperty(wrapped, exports.ADCP_SIGNED_REQUESTS_STATE, {
+        value: signedRequestsState,
+        enumerable: false,
+        configurable: true,
+        writable: false,
+    });
+    Object.defineProperty(wrapped, adcp_server_1.ADCP_STATE_STORE, {
+        value: stateStore,
+        enumerable: false,
+        configurable: true,
+        writable: false,
+    });
+    // Expose the capabilitiesData object so post-registration helpers
+    // (registerTestController) can add spec-defined capability blocks
+    // — comply_test_controller is registered AFTER createAdcpServer,
+    // so the compliance_testing block can't be emitted eagerly.
+    Object.defineProperty(wrapped, adcp_server_1.ADCP_CAPABILITIES, {
+        value: capabilitiesData,
+        enumerable: false,
+        configurable: true,
+        writable: false,
+    });
+    logger.info('AdCP server created', {
+        tools: [...registeredToolNames],
+        protocols,
+        signedRequests: signedRequestsState,
+    });
+    return wrapped;
+}
+//# sourceMappingURL=create-adcp-server.js.map