@adcp/sdk 5.25.1 → 6.1.0

package/dist/lib/server/decisioning/runtime/from-platform.js

@@ -0,0 +1,2196 @@
+"use strict";
+/**
+ * Build an `AdcpServer` from a `DecisioningPlatform` impl.
+ *
+ * v6.0 alpha entry point. Translates the per-specialism platform interface
+ * into the framework's existing handler-style config and delegates to
+ * `createAdcpServer()`. This means every framework primitive — idempotency,
+ * RFC 9421 signing, governance, schema validation, state store, MCP/A2A
+ * wire mapping, sandbox boundary — applies unchanged. The new code is the
+ * adapter shim, not a forked runtime.
+ *
+ * **Adopter shape (unified hybrid):** each HITL-eligible tool is a single
+ * method. The method returns the wire success arm (sync fast path) OR
+ * `ctx.handoffToTask(fn)` to promote the call to a background task (HITL
+ * slow path). Adopters branch per-call; framework detects the `TaskHandoff`
+ * marker and dispatches accordingly:
+ *
+ *   - Sync path: framework awaits the return value in foreground; projects
+ *     it to the wire success arm. `throw new AdcpError(...)` projects to
+ *     the wire `adcp_error` envelope.
+ *   - HITL path: framework detects the `TaskHandoff` marker, allocates
+ *     `taskId`, returns the submitted envelope to the buyer immediately,
+ *     then runs the handoff function in background. The function's return
+ *     value becomes the task's terminal `result`; thrown `AdcpError` becomes
+ *     the terminal `error`.
+ *
+ * Generic thrown errors (`Error`, `TypeError`) fall through to the
+ * framework's `SERVICE_UNAVAILABLE` mapping.
+ *
+ * **Wired surface (6.0):** `SalesPlatform` (14 tools — 3 required core +
+ * 11 optional; unified hybrid on `create_media_buy` / `sync_creatives`),
+ * `CreativeBuilderPlatform` (build_creative / sync_creatives unified
+ * hybrid, optional preview_creative sync-only, optional refineCreative),
+ * `AudiencePlatform.syncAudiences`, `SignalsPlatform` (activate_signal,
+ * list_signals), `AccountStore` (reportUsage, getAccountFinancials),
+ * `ContentStandardsPlatform`, `CampaignGovernancePlatform`,
+ * `TenantRegistry` (multi-tenant health), `createPostgresTaskRegistry`,
+ * `tasks/get` wire handler, per-server + module-level `publishStatusChange`.
+ *
+ * **Still deferred (rc.1+):** MCP Resources subscription projection for
+ * `publishStatusChange`; `resolveAccount(undefined, { authInfo, toolName })`
+ * refactor for `provide_performance_feedback` / `list_creative_formats`
+ * no-account path in `'explicit'`-mode adopters (see `SalesPlatform` JSDoc).
+ *
+ * Status: Preview / 6.0. Not yet exported from the public `./server`
+ * subpath; reach in via `@adcp/sdk/server/decisioning/runtime` for
+ * spike experimentation only.
+ *
+ * @public
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAdcpServerFromPlatform = createAdcpServerFromPlatform;
+exports._resetMergeSeamDedupe = _resetMergeSeamDedupe;
+exports.getAllAdcpMigrations = getAllAdcpMigrations;
+const node_crypto_1 = require("node:crypto");
+const create_adcp_server_1 = require("../../create-adcp-server");
+const account_1 = require("../account");
+const async_outcome_1 = require("../async-outcome");
+const errors_1 = require("../../errors");
+const validate_platform_1 = require("./validate-platform");
+const to_context_1 = require("./to-context");
+const ctx_metadata_1 = require("../../ctx-metadata");
+const idempotency_1 = require("../../idempotency");
+const pg_1 = require("../../idempotency/backends/pg");
+const postgres_task_registry_1 = require("./postgres-task-registry");
+const async_outcome_2 = require("../async-outcome");
+const zod_1 = require("zod");
+const task_registry_1 = require("./task-registry");
+const protocol_for_tool_1 = require("./protocol-for-tool");
+/**
+ * Default logger when adopters don't supply `opts.logger`. `debug` /
+ * `info` are no-op; `warn` / `error` route to console so framework
+ * warnings (merge-seam collisions, SSRF rejections, observability hook
+ * misuse) surface during development. Adopters wiring `pino`/`bunyan`
+ * supply all four levels via `opts.logger`.
+ */
+const DEFAULT_FRAMEWORK_LOGGER = {
+    debug: () => { },
+    info: () => { },
+    // eslint-disable-next-line no-console
+    warn: console.warn.bind(console),
+    // eslint-disable-next-line no-console
+    error: console.error.bind(console),
+};
+const status_changes_1 = require("../status-changes");
+const comply_controller_1 = require("../../../testing/comply-controller");
+const normalize_errors_1 = require("../../normalize-errors");
+/**
+ * Apply `normalizeErrors` to a sync_creatives row's optional `errors`
+ * field. Adopters often return errors as bare strings, native Error
+ * instances, or vendor-specific shapes; the wire schema requires
+ * `Error[]` with `{ code, message, ... }`. Normalizing at the
+ * projection seam means every adopter's syncCreatives method gets
+ * coerced to wire shape — the row passes strict response validation
+ * even when the adopter doesn't hand-shape every error.
+ */
+function normalizeRowErrors(row) {
+    if (row?.errors == null)
+        return row;
+    return { ...row, errors: (0, normalize_errors_1.normalizeErrors)(row.errors) };
+}
+// Use `DecisioningPlatform<any, any>` for the generic constraint. The default
+// `TCtxMeta = Record<string, unknown>` doesn't accept adopter metadata interfaces
+// without an index signature (e.g., `interface MyMeta { brand_id: string }`),
+// which is a needless friction point — adopter metadata is opaque to the
+// framework, so we don't need to constrain it here.
+function createAdcpServerFromPlatform(platform, opts) {
+    (0, validate_platform_1.validatePlatform)(platform);
+    // Compliance-testing capability/adapter consistency.
+    //
+    // Two failure modes the framework refuses to ship:
+    //   1. Capability declared, no adapter — discovery field projects to
+    //      `get_adcp_capabilities` but the wire tool has no implementation
+    //      behind it. Conformance harnesses would dispatch and crash.
+    //   2. Adapter wired, capability not declared — discovery field is
+    //      missing from `get_adcp_capabilities` so buyers / harnesses can't
+    //      tell the agent supports compliance testing.
+    //
+    // Both throw at construction with `PlatformConfigError`. Adopters who
+    // want one without the other are doing it wrong; the right escape hatch
+    // is to set `compliance_testing.scenarios = []` (a noop block, but the
+    // spec disallows empty `scenarios` so this should never come up in
+    // practice — included only to make the constraint explicit).
+    const capHasComplianceTesting = platform.capabilities.compliance_testing != null;
+    const optsHasComplyTest = opts.complyTest != null;
+    if (capHasComplianceTesting && !optsHasComplyTest) {
+        throw new validate_platform_1.PlatformConfigError(`capabilities.compliance_testing is declared but opts.complyTest is missing. ` +
+            `Either supply complyTest (the ComplyControllerConfig adapter set) or remove ` +
+            `the compliance_testing capability block — the framework refuses to advertise ` +
+            `comply_test_controller without an implementation.`);
+    }
+    if (optsHasComplyTest && !capHasComplianceTesting) {
+        throw new validate_platform_1.PlatformConfigError(`opts.complyTest is supplied but capabilities.compliance_testing is not declared. ` +
+            `Add 'compliance_testing: {}' to your platform.capabilities — the framework needs ` +
+            `the discovery block to project comply_test_controller scenarios on get_adcp_capabilities. ` +
+            `Scenarios auto-derive from your supplied adapters; explicit 'scenarios: [...]' is optional.`);
+    }
+    // Sec-M2: warn when `signed-requests` is claimed but a custom
+    // taskWebhookEmitter is wired without acknowledging signing posture.
+    // The default emitter (bound to `serve({ webhooks })`) signs; a custom
+    // emitter that doesn't declare `unsigned: true` and doesn't delegate
+    // to the framework's signed pipeline ships unsigned webhooks to buyers
+    // who expect signatures.
+    //
+    // Gate via DEV_ALLOWLIST inversion (matches feedback_node_env_allowlist):
+    // warn when NODE_ENV is NOT in {test, development} AND no explicit ack
+    // env. Catches NODE_ENV unset, 'staging', 'prod', 'live' — common
+    // production deployments that the previous `=== 'production'` check
+    // failed open on.
+    // Footgun guard for `allowPrivateWebhookUrls` — same DEV_ALLOWLIST
+    // inversion pattern as the unsigned-emitter check below. Adopters
+    // intentionally relaxing the SSRF gate for sandbox testing aren't
+    // doing anything wrong; production deployments that flip this on
+    // accidentally are. Warn on construction when the flag is true AND
+    // NODE_ENV is unset / 'staging' / 'prod' / 'live' AND no explicit
+    // ack env. Keeps the relaxation usable for real local-test setups
+    // without letting it sneak into production.
+    if (opts.allowPrivateWebhookUrls === true) {
+        const env = process.env.NODE_ENV;
+        const isDevOrTest = env === 'test' || env === 'development';
+        const ack = process.env.ADCP_DECISIONING_ALLOW_PRIVATE_WEBHOOK_URLS === '1';
+        if (!isDevOrTest && !ack) {
+            // eslint-disable-next-line no-console
+            console.warn('[adcp/decisioning] allowPrivateWebhookUrls: true relaxes the loopback / private-IP ' +
+                'guard on push_notification_config.url. NODE_ENV is not test/development and ' +
+                'ADCP_DECISIONING_ALLOW_PRIVATE_WEBHOOK_URLS is not set — accepting private ' +
+                'destinations in production is a SSRF / cloud-metadata exfiltration path. ' +
+                'For sandbox/local testing, scope this on your own NODE_ENV check.');
+        }
+    }
+    if (opts.taskWebhookEmitter && !opts.taskWebhookEmitter.unsigned) {
+        const claimsSigned = platform.capabilities?.specialisms?.includes('signed-requests');
+        const env = process.env.NODE_ENV;
+        const isDevOrTest = env === 'test' || env === 'development';
+        const ackUnsignedTestEmitter = process.env.ADCP_DECISIONING_ALLOW_UNSIGNED_TEST_EMITTER === '1';
+        if (claimsSigned && !isDevOrTest && !ackUnsignedTestEmitter) {
+            // eslint-disable-next-line no-console
+            console.warn('[adcp/decisioning] taskWebhookEmitter wired without unsigned:true while ' +
+                "platform.capabilities.specialisms claims 'signed-requests'. " +
+                'Buyers expecting RFC 9421 signatures will receive unsigned webhooks ' +
+                'unless your custom emitter delegates to the framework signing path. ' +
+                'If this is intentional (your emitter signs internally), set ' +
+                'unsigned: true on the emitter. For dev/test fakes, set ' +
+                'ADCP_DECISIONING_ALLOW_UNSIGNED_TEST_EMITTER=1 or NODE_ENV=test.');
+        }
+    }
+    // Pool shortcut: when `opts.pool` is wired and a specific store/registry
+    // is NOT explicitly set, derive that store from pool with sensible
+    // defaults. Explicit per-store opts always win — this is "fill the gaps,"
+    // not "override what the adopter passed."
+    const pooledIdempotency = opts.pool && opts.idempotency === undefined ? (0, idempotency_1.createIdempotencyStore)({ backend: (0, pg_1.pgBackend)(opts.pool) }) : undefined;
+    const pooledCtxMetadata = opts.pool && opts.ctxMetadata === undefined
+        ? (0, ctx_metadata_1.createCtxMetadataStore)({ backend: (0, ctx_metadata_1.pgCtxMetadataStore)(opts.pool) })
+        : undefined;
+    const pooledTaskRegistry = opts.pool && opts.taskRegistry === undefined ? (0, postgres_task_registry_1.createPostgresTaskRegistry)({ pool: opts.pool }) : undefined;
+    // Effective resolved values. Explicit > pooled > default.
+    const effectiveIdempotency = opts.idempotency ?? pooledIdempotency;
+    const effectiveCtxMetadata = opts.ctxMetadata ?? pooledCtxMetadata;
+    const taskRegistry = opts.taskRegistry ?? pooledTaskRegistry ?? buildDefaultTaskRegistry();
+    const baseBus = opts.statusChangeBus ?? (0, status_changes_1.createInMemoryStatusChangeBus)();
+    const taskWebhookEmit = opts.taskWebhookEmitter?.emit;
+    // Wrap the status-change bus so every publish fires onStatusChangePublish.
+    // Subscribers / recent-buffer behavior pass through unchanged — the wrap
+    // is only for the publish side. Hook-throw is caught + logged so adopter
+    // telemetry mistakes don't break event delivery.
+    const observability = opts.observability;
+    const statusChangeBus = observability?.onStatusChangePublish
+        ? wrapBusWithObservability(baseBus, observability)
+        : baseBus;
+    const fwLogger = opts.logger ?? DEFAULT_FRAMEWORK_LOGGER;
+    const mergeOpts = { mode: opts.mergeSeam ?? 'warn', logger: fwLogger };
+    // Project per-domain capability blocks declared on the platform onto
+    // get_adcp_capabilities via createAdcpServer's `overrides.media_buy`
+    // deep-merge seam. Adopters declare audience_targeting /
+    // conversion_tracking / content_standards on `platform.capabilities`;
+    // the framework wires the deep-merge so buyers see the discovery
+    // fields without an opaque custom get_adcp_capabilities tool (which
+    // the framework refuses anyway).
+    //
+    // Each rich block also forces the corresponding `media_buy.features.*`
+    // boolean to `true`. Buyers gating on `features.audience_targeting`
+    // (which the framework auto-derives as `false` by default) would
+    // otherwise skip the rich block sitting next to it.
+    const at = platform.capabilities.audience_targeting;
+    const ct = platform.capabilities.conversion_tracking;
+    const cs = platform.capabilities.content_standards;
+    const hasMediaBuyProjection = at != null || ct != null || cs != null;
+    const mediaBuyOverrides = {
+        ...(at != null && { audience_targeting: at }),
+        ...(ct != null && { conversion_tracking: ct }),
+        ...(cs != null && { content_standards: cs }),
+        ...(hasMediaBuyProjection && {
+            features: {
+                ...(at != null && { audience_targeting: true }),
+                ...(ct != null && { conversion_tracking: true }),
+                ...(cs != null && { content_standards: true }),
+            },
+        }),
+    };
+    // Brand-protocol capability projection. Adopters who declare
+    // `capabilities.brand` get the block projected via `overrides.brand`.
+    // When `BrandRightsPlatform` is supplied, `rights: true` is auto-
+    // derived (the framework knows the wire tools are available); adopter-
+    // declared `right_types` / `available_uses` / `generation_providers` /
+    // `description` ride the deep-merge.
+    const adopterBrand = platform.capabilities.brand;
+    const hasBrandRightsImpl = platform.brandRights != null;
+    const hasBrandProjection = adopterBrand != null || hasBrandRightsImpl;
+    const brandOverrides = {
+        ...(hasBrandRightsImpl && { rights: true }),
+        ...adopterBrand,
+    };
+    // Account-mode capability projection. Two redundant adopter signals
+    // resolve into the same wire bit:
+    //   - `capabilities.requireOperatorAuth: true` — explicit override
+    //   - `accounts.resolution: 'explicit'` — derived from the account-store
+    //     model (operators authenticate independently with the seller; the
+    //     buyer discovers accounts via `list_accounts`, NOT `sync_accounts`).
+    // Either, taken alone, projects to `account.require_operator_auth: true`.
+    // The conformance storyboard runner reads this bit at step time and
+    // grades `sync_accounts` steps as `'not_applicable'` (rather than the
+    // misleading `'missing_tool'`) for explicit-mode adopters who correctly
+    // don't implement that tool. See storyboard runner.ts account-mode gate.
+    //
+    // `supportedBillings` projects onto the parallel `account.supported_billing`
+    // wire field — buyers pre-flight check whether the seller bills the
+    // operator (retail-media model) or the buying agent (pass-through). Without
+    // the projection, retail-media adopters that declared `['operator']` saw
+    // their buyers default-route to agent-billed flows.
+    const requireOperatorAuth = platform.capabilities.requireOperatorAuth ?? platform.accounts.resolution === 'explicit';
+    const supportedBillings = platform.capabilities.supportedBillings;
+    const hasAccountProjection = requireOperatorAuth === true || (supportedBillings?.length ?? 0) > 0;
+    const accountOverrides = {
+        ...(requireOperatorAuth === true && { require_operator_auth: true }),
+        ...(supportedBillings?.length && { supported_billing: [...supportedBillings] }),
+    };
+    // Compliance-testing scenarios projection. Adopters who claim the
+    // `compliance_testing` capability AND wire `complyTest` adapters
+    // expect buyers to discover which scenarios they implement via
+    // `get_adcp_capabilities.compliance_testing.scenarios`. Without
+    // projection the wire response carried an empty `compliance_testing: {}`
+    // block, the comply-track runner emitted a warning on every call,
+    // and adopters saw an actionable-looking message pointing at
+    // something they'd already done correctly. Auto-derive scenario names
+    // from the wired adapters; let an explicit
+    // `capabilities.compliance_testing.scenarios` override the
+    // auto-derivation when adopters want to advertise a subset.
+    const declaredCT = platform.capabilities.compliance_testing;
+    const wiredComplyTest = opts.complyTest;
+    const hasComplianceTestingProjection = declaredCT != null && wiredComplyTest != null;
+    const complianceTestingOverrides = hasComplianceTestingProjection
+        ? {
+            scenarios: declaredCT.scenarios ? [...declaredCT.scenarios] : deriveScenariosFromAdapters(wiredComplyTest),
+        }
+        : undefined;
+    const projectedCapabilitiesConfig = hasMediaBuyProjection || hasBrandProjection || hasAccountProjection || hasComplianceTestingProjection
+        ? {
+            overrides: {
+                ...(hasMediaBuyProjection && { media_buy: mediaBuyOverrides }),
+                ...(hasBrandProjection && { brand: brandOverrides }),
+                ...(hasAccountProjection && { account: accountOverrides }),
+                ...(hasComplianceTestingProjection &&
+                    complianceTestingOverrides != null && { compliance_testing: complianceTestingOverrides }),
+            },
+        }
+        : undefined;
+    // Per-server `ctxFor` closure; threads the effective ctx-metadata store
+    // (explicit > pooled > none) into `buildRequestContext` so handlers see
+    // `ctx.ctxMetadata` as an account-scoped accessor. Multi-tenant hosts
+    // (TenantRegistry) get one closure per server, so per-tenant store
+    // routing is preserved.
+    const ctxFor = makeCtxFor(effectiveCtxMetadata);
+    // Construction-time warn: when the default `resolveIdempotencyPrincipal`
+    // is used (no explicit hook), the chain falls through:
+    //   ctx.authInfo.clientId → ctx.sessionKey → ctx.account.id → undefined
+    // The `account.id` fallback collapses unauthenticated buyers into one
+    // shared idempotency namespace per account — fine for single-tenant
+    // deployments where every buyer authenticates, dangerous for multi-
+    // tenant hosts serving unauthenticated traffic over a shared
+    // account_id. Gate via the dev-allowlist pattern: warn unless
+    // NODE_ENV ∈ {test, development} OR the operator explicitly acks via
+    // ADCP_DECISIONING_ALLOW_ACCOUNT_ID_PRINCIPAL=1.
+    if (opts.resolveIdempotencyPrincipal === undefined) {
+        const env = process.env.NODE_ENV;
+        const inDevAllowlist = env === 'test' || env === 'development';
+        const acked = process.env.ADCP_DECISIONING_ALLOW_ACCOUNT_ID_PRINCIPAL === '1';
+        if (!inDevAllowlist && !acked) {
+            // eslint-disable-next-line no-console
+            console.warn(`[adcp/decisioning] resolveIdempotencyPrincipal not explicitly wired. ` +
+                `Default falls through: authInfo.clientId → sessionKey → account.id → undefined. ` +
+                `The account.id fallback collapses unauthenticated buyers into one shared idempotency ` +
+                `namespace per account. SAFE for single-tenant deployments where every buyer ` +
+                `authenticates; UNSAFE for multi-tenant hosts serving unauthenticated traffic over a ` +
+                `shared account_id. Wire \`authenticate\` on serve() (verifyApiKey / verifyIntrospection) ` +
+                `OR pass an explicit \`resolveIdempotencyPrincipal\` in opts. ` +
+                `Set ADCP_DECISIONING_ALLOW_ACCOUNT_ID_PRINCIPAL=1 to silence this warning.`);
+        }
+    }
+    const config = {
+        ...opts,
+        ...(projectedCapabilitiesConfig != null && { capabilities: projectedCapabilitiesConfig }),
+        // Pool-derived stores override the spread above when adopters supplied
+        // `pool` but no explicit per-store opt. Explicit values still win.
+        ...(effectiveIdempotency !== undefined && { idempotency: effectiveIdempotency }),
+        // v6 default principal resolver: every mutating tool requires an
+        // idempotency principal (the v5 createAdcpServer surface returns
+        // SERVICE_UNAVAILABLE when one isn't wired). v6 platform adopters
+        // who skip the explicit hook get a sensible default — auth client
+        // id when present (multi-tenant: each buyer owns its own
+        // idempotency namespace), else session key, else account id
+        // (single-tenant fallback). Adopters override by passing
+        // resolveIdempotencyPrincipal in opts; the spread above keeps
+        // explicit values winning. Closed by the Emma matrix surfacing
+        // SERVICE_UNAVAILABLE on every v6 mutating call.
+        resolveIdempotencyPrincipal: opts.resolveIdempotencyPrincipal ??
+            (ctx => ctx.authInfo?.clientId ?? ctx.sessionKey ?? ctx.account?.id ?? undefined),
+        resolveAccount: async (ref, ctx) => {
+            const start = Date.now();
+            let resolved = false;
+            let resolvedAccountId;
+            try {
+                const account = await platform.accounts.resolve(ref, {
+                    ...(ctx.authInfo !== undefined && { authInfo: ctx.authInfo }),
+                    toolName: ctx.toolName,
+                });
+                resolved = account != null;
+                resolvedAccountId = account?.id;
+                return account;
+            }
+            catch (err) {
+                if (err instanceof account_1.AccountNotFoundError)
+                    return null;
+                throw err;
+            }
+            finally {
+                safeFire(observability?.onAccountResolve, {
+                    tool: ctx.toolName,
+                    durationMs: Date.now() - start,
+                    resolved,
+                    fromAuth: false,
+                    ...(resolvedAccountId !== undefined && { accountId: resolvedAccountId }),
+                }, 'onAccountResolve', fwLogger);
+            }
+        },
+        // Auth-derived path: framework calls this for tools whose wire request
+        // doesn't carry an `account` field (`provide_performance_feedback`,
+        // `list_creative_formats`, `tasks_get`). The platform's resolver runs
+        // with `undefined` ref + `authInfo` available — adopters of any
+        // `resolution` mode can return a non-null Account here:
+        //
+        //   - `'derived'` — return the singleton.
+        //   - `'implicit'` — look up by `ctx.authInfo.clientId`.
+        //   - `'explicit'` — also handle the `undefined` ref branch by
+        //     looking up via `ctx.authInfo.clientId` (or whichever principal
+        //     field your auth wires). The framework calls this resolver
+        //     regardless of declared `resolution` mode; only adopters who
+        //     intentionally don't model these tools return null.
+        //
+        // A `null` return is legal — handler runs with `ctx.account`
+        // undefined. Appropriate for tools that don't need tenant scoping
+        // (publisher-wide format catalogs).
+        resolveAccountFromAuth: async (ctx) => {
+            const start = Date.now();
+            let resolved = false;
+            let resolvedAccountId;
+            try {
+                const account = await platform.accounts.resolve(undefined, {
+                    ...(ctx.authInfo !== undefined && { authInfo: ctx.authInfo }),
+                    toolName: ctx.toolName,
+                });
+                resolved = account != null;
+                resolvedAccountId = account?.id;
+                return account;
+            }
+            catch (err) {
+                if (err instanceof account_1.AccountNotFoundError)
+                    return null;
+                throw err;
+            }
+            finally {
+                safeFire(observability?.onAccountResolve, {
+                    tool: ctx.toolName,
+                    durationMs: Date.now() - start,
+                    resolved,
+                    fromAuth: true,
+                    ...(resolvedAccountId !== undefined && { accountId: resolvedAccountId }),
+                }, 'onAccountResolve', fwLogger);
+            }
+        },
+        // Merge: platform-derived handlers WIN per-key over adopter-supplied
+        // custom handlers. Adopter handlers fill gaps for tools the v6 platform
+        // doesn't yet model (getMediaBuys, listCreativeFormats, content-standards
+        // CRUD, sync_event_sources, etc.). See `CreateAdcpServerFromPlatformOptions`
+        // JSDoc for the migration-seam contract.
+        mediaBuy: mergeHandlers(opts.mediaBuy, buildMediaBuyHandlers(platform, taskRegistry, taskWebhookEmit, observability, fwLogger, {
+            allowPrivateWebhookUrls: opts.allowPrivateWebhookUrls === true,
+            autoEmitCompletionWebhooks: opts.autoEmitCompletionWebhooks !== false,
+        }, ctxFor, effectiveCtxMetadata), 'mediaBuy', mergeOpts),
+        creative: mergeHandlers(opts.creative, buildCreativeHandlers(platform, taskRegistry, taskWebhookEmit, observability, fwLogger, {
+            allowPrivateWebhookUrls: opts.allowPrivateWebhookUrls === true,
+            autoEmitCompletionWebhooks: opts.autoEmitCompletionWebhooks !== false,
+        }, ctxFor), 'creative', mergeOpts),
+        eventTracking: mergeHandlers(opts.eventTracking, buildEventTrackingHandlers(platform, ctxFor), 'eventTracking', mergeOpts),
+        signals: mergeHandlers(opts.signals, buildSignalsHandlers(platform, ctxFor, effectiveCtxMetadata, fwLogger), 'signals', mergeOpts),
+        governance: mergeHandlers(opts.governance, buildGovernanceHandlers(platform, ctxFor), 'governance', mergeOpts),
+        accounts: mergeHandlers(opts.accounts, buildAccountHandlers(platform, ctxFor), 'accounts', mergeOpts),
+        brandRights: mergeHandlers(opts.brandRights, buildBrandRightsHandlers(platform, ctxFor, effectiveCtxMetadata, fwLogger), 'brandRights', mergeOpts),
+        customTools: {
+            ...opts.customTools,
+            tasks_get: buildTasksGetTool(platform, taskRegistry),
+        },
+    };
+    const server = (0, create_adcp_server_1.createAdcpServer)(config);
+    // Wire `comply_test_controller` if the adopter supplied adapters.
+    // `createComplyController` builds the tool definition + handler + raw
+    // dispatch; `register(server)` calls server.registerTool. Sandbox
+    // gating is the adopter's job (per-request via complyTest.sandboxGate
+    // or environment-level by guarding the createAdcpServerFromPlatform
+    // call site itself).
+    if (opts.complyTest != null) {
+        const controller = (0, comply_controller_1.createComplyController)(opts.complyTest);
+        controller.register(server);
+    }
+    return Object.assign(server, {
+        getTaskState: async (taskId, expectedAccountId) => {
+            const record = await taskRegistry.getTask(taskId);
+            if (record == null)
+                return null;
+            // Tenant boundary: if caller specified the expected account and the
+            // task's owner doesn't match, treat as not-found. Returning null
+            // here mirrors the "not-found / cross-tenant" envelope and avoids
+            // principal-enumeration via task_id probing.
+            if (expectedAccountId !== undefined && record.accountId !== expectedAccountId) {
+                return null;
+            }
+            return record;
+        },
+        awaitTask: (taskId) => taskRegistry.awaitTask(taskId),
+        statusChange: statusChangeBus,
+    });
+}
+// ---------------------------------------------------------------------------
+// `tasks_get` polling tool — buyer-facing wire path for HITL task lifecycle
+// ---------------------------------------------------------------------------
+/**
+ * Custom tool exposing `taskRegistry.getTask(taskId)` over the wire so
+ * buyer agents can poll HITL task state. Snake-case `tasks_get` (MCP tool
+ * names disallow `/`) approximates the spec's `tasks/get` method.
+ *
+ * Native MCP `tasks/get` integration via the SDK's experimental
+ * `registerToolTask` path lands in v6.1 — that registers HITL tools
+ * (`create_media_buy`, `sync_creatives`) as MCP task tools and the SDK
+ * handles the protocol-level `tasks/get` natively. Until then, this
+ * custom tool is the buyer-facing polling surface.
+ *
+ * **Tenant scoping.** The tool reads from `taskRegistry.getTask`
+ * directly. Adopters with multi-tenant deployments MUST pass `account`
+ * in the request so the framework's account-resolution flow scopes the
+ * read; the handler then verifies `record.accountId` matches the
+ * resolved account before returning the task. Single-tenant agents
+ * (`resolution: 'derived'`) get scoping for free via the auth-derived
+ * resolver.
+ */
+function buildTasksGetTool(platform, taskRegistry) {
+    const inputShape = {
+        // Cap task_id length: framework-issued task ids are
+        // `task_<UUIDv4>` = 41 chars. Cap at 128 so a malicious buyer can't
+        // hand us megabytes of string for a parameterized read query.
+        task_id: zod_1.z
+            .string()
+            .min(1)
+            .max(128)
+            .describe('Task identifier returned in the submitted envelope of a HITL tool call.'),
+        // `AccountReference.account_id` per `core/account-ref.json`. Stricter
+        // than `passthrough()` — must be a string when present. We don't
+        // accept the `{ brand, operator }` arm here because tenant scoping
+        // for `tasks_get` is by resolved account id, not by brand identity.
+        account: zod_1.z
+            .object({ account_id: zod_1.z.string().min(1).optional() })
+            .strict()
+            .optional()
+            .describe('Optional account reference for tenant scoping. Required for multi-tenant deployments.'),
+    };
+    return {
+        description: 'Call this when you receive `{ status: "submitted", task_id }` from create_media_buy ' +
+            'or sync_creatives — pass the same `task_id` plus your `account` to retrieve the ' +
+            'terminal lifecycle state. Returns the spec-flat tasks-get-response shape ' +
+            '(`status`, `result` on completed, `error: { code, message }` on failed). ' +
+            "Snake-case substitute for the spec's `tasks/get` method (MCP tool names disallow " +
+            '`/`); native MCP method dispatch lands in v6.1. Webhook delivery is the push-based ' +
+            'alternative when the buyer set `push_notification_config` on the original request.',
+        title: 'Get Task State',
+        inputSchema: inputShape,
+        annotations: { readOnlyHint: true },
+        // Handler receives the MCP RequestHandlerExtra as second arg — carries
+        // the caller's `authInfo` extracted by `serve({ authenticate })`. Thread
+        // it through `accounts.resolve(ref, ctx)` so adopters' `'explicit'`-mode
+        // resolvers can authorize the resolution against the principal — without
+        // this, an attacker passing `{ account: { account_id: 'tenant_B' } }`
+        // gets tenant B's account back from a naive `findById(ref.account_id)`
+        // resolver and reads tenant B's task. Same threading as the regular
+        // `resolveAccount` dispatch flow in `create-adcp-server.ts:2380-2398`.
+        handler: async (args, extra) => {
+            const ref = args.account;
+            const resolveCtx = {
+                ...(extra?.authInfo !== undefined && { authInfo: extra.authInfo }),
+                toolName: 'tasks_get',
+            };
+            let resolvedAccountId;
+            if (ref) {
+                try {
+                    const resolved = await platform.accounts.resolve(ref, resolveCtx);
+                    if (resolved)
+                        resolvedAccountId = resolved.id;
+                }
+                catch (err) {
+                    if (!(err instanceof account_1.AccountNotFoundError))
+                        throw err;
+                }
+                if (!resolvedAccountId) {
+                    return (0, errors_1.adcpError)('ACCOUNT_NOT_FOUND', {
+                        message: 'The specified account does not exist',
+                        field: 'account',
+                    });
+                }
+            }
+            else {
+                try {
+                    const resolved = await platform.accounts.resolve(undefined, resolveCtx);
+                    if (resolved)
+                        resolvedAccountId = resolved.id;
+                }
+                catch (err) {
+                    if (!(err instanceof account_1.AccountNotFoundError))
+                        throw err;
+                }
+            }
+            const record = await taskRegistry.getTask(args.task_id);
+            if (record == null) {
+                return (0, errors_1.adcpError)('REFERENCE_NOT_FOUND', {
+                    message: `Task ${args.task_id} not found`,
+                    field: 'task_id',
+                });
+            }
+            // Tenant boundary. Two checks to close the auth-derived bypass:
+            //   1. If we resolved an account, the task's owning account must match.
+            //   2. If we did NOT resolve an account but the task IS owned by an
+            //      account, refuse to leak. This catches the unauthenticated /
+            //      `'explicit'`-mode-misconfigured caller that hits the auth-derived
+            //      branch and would otherwise read any task by id.
+            if (resolvedAccountId === undefined && record.accountId) {
+                return (0, errors_1.adcpError)('REFERENCE_NOT_FOUND', {
+                    message: `Task ${args.task_id} not found`,
+                    field: 'task_id',
+                });
+            }
+            if (resolvedAccountId !== undefined && record.accountId !== resolvedAccountId) {
+                return (0, errors_1.adcpError)('REFERENCE_NOT_FOUND', {
+                    message: `Task ${args.task_id} not found`,
+                    field: 'task_id',
+                });
+            }
+            // Spec shape: `tasks-get-response.json` requires task_id, task_type,
+            // status, created_at, updated_at, protocol. Optional: completed_at
+            // (terminal states), error (failed tasks — top-level, NOT inside
+            // result), result (success-arm body for completed tasks),
+            // has_webhook (whether buyer wired push_notification_config).
+            const payload = {
+                task_id: record.taskId,
+                task_type: record.tool,
+                status: record.status,
+                protocol: (0, protocol_for_tool_1.protocolForTool)(record.tool),
+                has_webhook: record.hasWebhook === true,
+                created_at: record.createdAt,
+                updated_at: record.updatedAt,
+            };
+            // Terminal states get `completed_at` per spec (covers completed,
+            // failed, canceled). The framework writes terminal-state transitions
+            // by stamping `updated_at`, so the two coincide today.
+            if (record.status === 'completed' || record.status === 'failed' || record.status === 'canceled') {
+                payload.completed_at = record.updatedAt;
+            }
+            if (record.statusMessage)
+                payload.message = record.statusMessage;
+            if (record.status === 'completed' && record.result !== undefined) {
+                payload.result = record.result;
+            }
+            if (record.status === 'failed' && record.error) {
+                // Spec shape: top-level `error: { code, message, details? }` —
+                // matches `tasks-get-response.json`'s required `code` + `message`
+                // shape with optional `details` carrying the structured-error
+                // tail (`recovery`, `field`, `suggestion`, `retry_after`,
+                // adopter-supplied `details`).
+                const { code, message, ...details } = record.error;
+                payload.error = {
+                    code,
+                    message,
+                    ...(Object.keys(details).length > 0 && { details }),
+                };
+            }
+            return {
+                content: [{ type: 'text', text: `Task ${record.taskId} status: ${record.status}` }],
+                structuredContent: payload,
+            };
+        },
+    };
+}
+// Module-level dedupe set for `'log-once'` mode. Keyed on
+// `${domain}|${sortedColliders}` so two constructions hitting the same
+// collision pattern only log once across the lifetime of the process.
+// Cleared via `_resetMergeSeamDedupe()` in tests.
+const mergeSeamLoggedKeys = new Set();
+/** @internal — reset the log-once dedupe set. Tests only. */
+function _resetMergeSeamDedupe() {
+    mergeSeamLoggedKeys.clear();
+}
+function mergeHandlers(custom, platform, domain, opts) {
+    if (!custom && !platform)
+        return undefined;
+    if (!custom)
+        return platform;
+    if (!platform)
+        return custom;
+    if (opts.mode !== 'silent') {
+        const collisions = [];
+        for (const key of Object.keys(platform)) {
+            if (key in custom)
+                collisions.push(key);
+        }
+        if (collisions.length > 0) {
+            // Sort for stable dedupe key — same collision set logs the same key
+            // regardless of declaration order across constructions.
+            const dedupeKey = `${domain}|${[...collisions].sort().join(',')}`;
+            const shouldLog = opts.mode !== 'log-once' || !mergeSeamLoggedKeys.has(dedupeKey);
+            const message = `[adcp/decisioning] opts.${domain}.{${collisions.join(', ')}} ` +
+                `${collisions.length === 1 ? 'is' : 'are'} shadowed by platform-derived handlers. ` +
+                `The merge seam is for tools the platform doesn't model yet — once a tool has a native ` +
+                `platform method, move the logic there and remove the opts override.`;
+            if (opts.mode === 'strict') {
+                throw new validate_platform_1.PlatformConfigError(message);
+            }
+            if (shouldLog) {
+                opts.logger.warn(message);
+                if (opts.mode === 'log-once')
+                    mergeSeamLoggedKeys.add(dedupeKey);
+            }
+        }
+    }
+    return { ...custom, ...platform };
+}
+// ---------------------------------------------------------------------------
+// Observability hook plumbing
+// ---------------------------------------------------------------------------
+/**
+ * Fire an observability callback with throw-safe semantics — both sync
+ * throws AND rejected promises are caught + logged so a buggy span/metric
+ * callback never breaks dispatch. The framework does NOT await the
+ * callback; if you need async tracer work, do it inside the callback and
+ * the framework will not hold the dispatch path waiting for it.
+ */
+/**
+ * Derive scenario names from a wired `ComplyControllerConfig` adapter
+ * set. Each adapter slot maps to one wire scenario name. Order is
+ * stable (force → simulate) so adopter wire-fixture snapshots don't
+ * churn between releases. Used by the projection seam to populate
+ * `get_adcp_capabilities.compliance_testing.scenarios` when the adopter
+ * doesn't supply an explicit subset.
+ *
+ * Seed scenarios (`seed_product`, `seed_creative`, etc.) are
+ * deliberately NOT advertised on the wire — the spec scopes the
+ * `compliance_testing.scenarios` enum to forces + simulates, and the
+ * controller's own `list_scenarios` response follows the same rule.
+ * Adopters who wire seed adapters get them dispatched correctly at
+ * runtime; they just don't appear in capability discovery.
+ */
+function deriveScenariosFromAdapters(cfg) {
+    const out = [];
+    if (cfg.force?.creative_status)
+        out.push('force_creative_status');
+    if (cfg.force?.account_status)
+        out.push('force_account_status');
+    if (cfg.force?.media_buy_status)
+        out.push('force_media_buy_status');
+    if (cfg.force?.session_status)
+        out.push('force_session_status');
+    if (cfg.simulate?.delivery)
+        out.push('simulate_delivery');
+    if (cfg.simulate?.budget_spend)
+        out.push('simulate_budget_spend');
+    return out;
+}
+function safeFire(fn, arg, hookName, logger) {
+    if (!fn)
+        return;
+    let result;
+    try {
+        result = fn(arg);
+    }
+    catch (err) {
+        logger.warn(`[adcp/decisioning] observability hook ${hookName} threw — telemetry callbacks must never throw. ` +
+            `Error: ${err instanceof Error ? err.message : String(err)}`);
+        return;
+    }
+    // Catch rejected promises from accidentally-async callbacks. Without
+    // this an `async () => { throw ... }` hook would surface as
+    // UnhandledPromiseRejection and on `--unhandled-rejections=strict`
+    // would crash the process. `Promise.resolve()` coerces both real
+    // promises and user-land thenables (a thenable returning sync values
+    // is wrapped, a true Promise is returned as-is) — safer than the
+    // duck-typed `typeof .catch === 'function'` check.
+    if (result !== undefined && result !== null) {
+        Promise.resolve(result).catch((err) => {
+            logger.warn(`[adcp/decisioning] observability hook ${hookName} returned a rejected promise — ` +
+                `telemetry callbacks must never reject. ` +
+                `Error: ${err instanceof Error ? err.message : String(err)}`);
+        });
+    }
+}
+/**
+ * Wrap a `StatusChangeBus` so every publish fires `onStatusChangePublish`
+ * after the underlying bus persists the event. Subscribers + recent-buffer
+ * pass through; only the publish side is observed.
+ */
+function wrapBusWithObservability(bus, observability) {
+    return {
+        publish(eventOpts) {
+            bus.publish(eventOpts);
+            if (observability.onStatusChangePublish) {
+                try {
+                    observability.onStatusChangePublish({
+                        accountId: eventOpts.account_id,
+                        resourceType: eventOpts.resource_type,
+                        resourceId: eventOpts.resource_id,
+                    });
+                }
+                catch (err) {
+                    // eslint-disable-next-line no-console
+                    console.warn(`[adcp/decisioning] observability hook onStatusChangePublish threw: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+        },
+        subscribe: bus.subscribe.bind(bus),
+        recent: bus.recent.bind(bus),
+    };
+}
+// ---------------------------------------------------------------------------
+// Default task registry — gated by NODE_ENV
+// ---------------------------------------------------------------------------
+/**
+ * Build the default in-memory task registry, gated by NODE_ENV.
+ *
+ * The in-memory registry loses task state on process restart — fine for
+ * tests and local dev, NOT fine for production. Gate via allowlist:
+ * `NODE_ENV` must be `'test'` or `'development'`, OR the operator must
+ * explicitly opt in via `ADCP_DECISIONING_ALLOW_INMEMORY_TASKS=1`.
+ *
+ * Pattern follows `feedback_node_env_allowlist.md`: never compare
+ * `=== 'production'` (production may unset NODE_ENV entirely); always
+ * allowlist the safe modes.
+ */
+/**
+ * Combined DDL for all framework persistence tables: idempotency cache,
+ * ctx-metadata cache, and decisioning task registry. Run once per database
+ * during deployment / boot. Idempotent — safe to re-run.
+ *
+ * Use with the `pool` shortcut on `createAdcpServerFromPlatform`:
+ *
+ * ```ts
+ * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ * await pool.query(getAllAdcpMigrations());
+ *
+ * createAdcpServerFromPlatform(myPlatform, {
+ *   name: '...', version: '...',
+ *   pool,
+ * });
+ * ```
+ *
+ * Adopters who don't use the `pool` shortcut should call the per-store
+ * migration helpers (`getIdempotencyMigration`, `getCtxMetadataMigration`,
+ * `getDecisioningTaskRegistryMigration`) only for the stores they wire.
+ *
+ * @public
+ */
+function getAllAdcpMigrations() {
+    return [(0, pg_1.getIdempotencyMigration)(), (0, ctx_metadata_1.getCtxMetadataMigration)(), (0, postgres_task_registry_1.getDecisioningTaskRegistryMigration)()].join('\n\n');
+}
+function buildDefaultTaskRegistry() {
+    const env = process.env.NODE_ENV;
+    const safe = env === 'test' || env === 'development';
+    const ack = process.env.ADCP_DECISIONING_ALLOW_INMEMORY_TASKS === '1';
+    if (!safe && !ack) {
+        throw new Error('createAdcpServerFromPlatform: in-memory task registry refused outside ' +
+            '{NODE_ENV=test, NODE_ENV=development}. Production deployments need a ' +
+            'durable task registry — pick one of:\n' +
+            '  1. (Recommended) Pass `taskRegistry: createPostgresTaskRegistry({ pool })` ' +
+            'to keep HITL tasks across restarts. See `@adcp/sdk/server/decisioning` ' +
+            'for `getDecisioningTaskRegistryMigration()` — run it once against your DB.\n' +
+            '  2. Pass `taskRegistry: createInMemoryTaskRegistry()` explicitly if you ' +
+            'accept that in-flight tasks are lost on process restart. The explicit ' +
+            'pass-in is the contract — saying "yes I want in-memory in production" ' +
+            'in code is the right shape.\n' +
+            '  3. ADCP_DECISIONING_ALLOW_INMEMORY_TASKS=1 env flag is the ops escape ' +
+            'hatch (same effect as #2 but config-only); prefer #2 in adopter code.');
+    }
+    return (0, task_registry_1.createInMemoryTaskRegistry)();
+}
+/**
+ * Project a sync platform call onto the wire dispatch shape. `AdcpError`
+ * throws → wire `adcp_error` envelope; other thrown errors bubble to the
+ * framework's `SERVICE_UNAVAILABLE` mapping.
+ */
+async function projectSync(fn, mapResult) {
+    try {
+        const result = await fn();
+        const wire = mapResult(result);
+        // Single-chokepoint runtime strip: ctx_metadata MUST NEVER cross to the
+        // buyer. Defense-in-depth (compile-time WireShape<T> + runtime walk).
+        // Mutates `wire` in place — every handler builds a fresh response per
+        // call so mutation is safe. Runs BEFORE the framework wraps in envelope
+        // / caches in idempotency, so cached replays stay clean too.
+        if (wire != null && typeof wire === 'object') {
+            (0, ctx_metadata_1.stripCtxMetadata)(wire);
+        }
+        return wire;
+    }
+    catch (err) {
+        if (err instanceof async_outcome_1.AdcpError) {
+            return (0, errors_1.adcpError)(err.code, {
+                message: err.message,
+                recovery: err.recovery,
+                ...(err.field !== undefined && { field: err.field }),
+                ...(err.suggestion !== undefined && { suggestion: err.suggestion }),
+                ...(err.retry_after !== undefined && { retry_after: err.retry_after }),
+                ...(err.details !== undefined && { details: err.details }),
+            });
+        }
+        // AccountNotFoundError is documented as throwable only from
+        // AccountStore.resolve(); but adopters new to the framework
+        // sometimes throw it from a specialism method body. Project to
+        // ACCOUNT_NOT_FOUND so the wire envelope is right either way —
+        // closes the silent-SERVICE_UNAVAILABLE foot-gun the security
+        // review flagged. Adopters are still encouraged to handle account
+        // not-found inside resolve() (canonical) — this is a guardrail.
+        if (err instanceof account_1.AccountNotFoundError) {
+            return (0, errors_1.adcpError)('ACCOUNT_NOT_FOUND', {
+                message: 'Account not found',
+                field: 'account',
+                recovery: 'terminal',
+            });
+        }
+        throw err;
+    }
+}
+/**
+ * Route a unified-shape return value: if it's a `TaskHandoff` marker,
+ * dispatch through `dispatchHitl`; otherwise pass through the sync
+ * projection.
+ *
+ * Adopter return type is `Success | TaskHandoff<Success>`. Each
+ * specialism dispatcher uses this helper so all three call sites
+ * (`createMediaBuy`, `sales.syncCreatives`, `creative.syncCreatives`)
+ * route through a single seam — closes round-6 CR-1 (drift across
+ * three near-identical `isTaskHandoff` branches).
+ *
+ * `project` shapes both arms identically — for `syncCreatives`,
+ * `rows → { creatives: rows }`; for `createMediaBuy`, identity.
+ */
+async function routeIfHandoff(taskRegistry, opts, result, project) {
+    if ((0, async_outcome_2.isTaskHandoff)(result)) {
+        const taskFn = (0, async_outcome_2._extractTaskFn)(result);
+        if (!taskFn) {
+            // Forgery — adopter constructed something with the brand symbol
+            // but didn't go through ctx.handoffToTask. Treat as a sync
+            // success arm with an empty body (caller-supplied projection
+            // shapes the result; this branch is defensive).
+            return project(result);
+        }
+        return dispatchHitl(taskRegistry, opts, async (taskId) => {
+            const inner = await taskFn((0, to_context_1.buildHandoffContext)(taskRegistry, taskId));
+            return project(inner);
+        });
+    }
+    // Catch the most common LLM-scaffolded mistake: hand-rolling a
+    // `{status: 'submitted', task_id: '...'}` envelope instead of returning
+    // `ctx.handoffToTask(fn)`. The framework owns the submitted envelope —
+    // adopters either return the sync-success arm or a TaskHandoff marker.
+    // A bare submitted-shape return here would slip past dispatch and fail
+    // response-schema validation downstream with a generic shape error;
+    // pointing at the right SDK primitive up-front saves the debug round-trip.
+    if (result != null &&
+        typeof result === 'object' &&
+        result.status === 'submitted' &&
+        'task_id' in result) {
+        throw new Error(`Specialism handler returned a hand-rolled \`{status: 'submitted', task_id}\` ` +
+            `envelope. The framework owns the submitted envelope — return ` +
+            `\`ctx.handoffToTask(async (taskCtx) => { ... })\` from the handler ` +
+            `and the framework will issue the task_id, persist the handoff, and ` +
+            `wrap the wire envelope. Returning a bare submitted shape skips the ` +
+            `task registry and the buyer ends up polling a task_id the framework ` +
+            `never registered.`);
+    }
+    const projected = project(result);
+    if (opts.autoEmitCompletion === true && opts.pushNotificationUrl) {
+        // Auto-emit completion webhook on sync-success arm — fire-and-forget.
+        // Awaiting inline would let an attacker-controlled
+        // `push_notification_config.url` (e.g., a slowloris receiver) hold
+        // the seller's request worker for the full retry budget — minutes-
+        // to-tens-of-minutes per call, by spec-conformant payload. The buyer
+        // already has the result inline; webhook delivery is purely a
+        // notification convenience and shares the SPEC_WEBHOOK_TASK_TYPES
+        // gate with the HITL path. Errors land on the framework logger and
+        // the `onWebhookEmit` observability hook for operator alerting.
+        void emitSyncCompletionWebhook(opts, projected).catch((err) => {
+            const msg = err instanceof Error ? err.message : String(err);
+            opts.logger.warn(`[adcp/decisioning] sync completion webhook background-error: ${msg}`);
+        });
+    }
+    return projected;
+}
+/**
+ * Auto-fire the post-success webhook for the sync arm of a mutating
+ * tool. Mirrors `emitTaskWebhook` (HITL path) but synthesizes a
+ * `task_id` since sync responses don't allocate a registry task.
+ * Buyers correlate via the resource IDs embedded in `result`
+ * (`media_buy_id`, `creative_id`, etc.) — `task_id` is informational
+ * for the spec's required-field shape.
+ *
+ * Webhook delivery failures are logged-and-swallowed: the sync
+ * response succeeded and the buyer has the result inline, so blocking
+ * the response on a flaky webhook receiver would be strictly worse
+ * than the buyer eventually polling.
+ */
+async function emitSyncCompletionWebhook(opts, result) {
+    if (!opts.emitWebhook || !opts.pushNotificationUrl)
+        return;
+    if (!protocol_for_tool_1.SPEC_WEBHOOK_TASK_TYPES.has(opts.tool)) {
+        opts.logger.warn(`[adcp/decisioning] sync completion webhook for ${opts.tool} skipped — ` +
+            `tool not in spec task-type enum (closed 20-value set per enums/task-type.json). ` +
+            `Use publishStatusChange for long-running ${opts.tool} state.`);
+        return;
+    }
+    const taskId = `sync-${(0, node_crypto_1.randomUUID)()}`;
+    const wirePayload = buildTaskWebhookPayload(opts, taskId, 'completed', { result });
+    const start = Date.now();
+    let success = false;
+    let errorMessages;
+    let errorCode;
+    try {
+        const r = await opts.emitWebhook({
+            url: opts.pushNotificationUrl,
+            payload: wirePayload,
+            operation_id: `${opts.tool}.${taskId}`,
+        });
+        success = r?.delivered === true;
+        if (r && Array.isArray(r.errors) && r.errors.length > 0) {
+            errorMessages = r.errors;
+            errorCode = bucketWebhookError(r.errors[0] ?? '');
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        errorMessages = [msg];
+        errorCode = bucketWebhookError(msg);
+        opts.logger.warn(`[adcp/decisioning] sync completion webhook for ${opts.tool} failed: ${msg}`);
+    }
+    finally {
+        safeFire(opts.observability?.onWebhookEmit, {
+            taskId,
+            tool: opts.tool,
+            status: 'completed',
+            url: opts.pushNotificationUrl,
+            success,
+            durationMs: Date.now() - start,
+            ...(errorCode && { errorCode }),
+            ...(errorMessages && { errorMessages }),
+        }, 'onWebhookEmit', opts.logger);
+    }
+}
+async function dispatchHitl(taskRegistry, opts, taskFn) {
+    const createStart = Date.now();
+    const { taskId } = await taskRegistry.create({
+        tool: opts.tool,
+        accountId: opts.accountId,
+        hasWebhook: opts.pushNotificationUrl !== undefined,
+    });
+    safeFire(opts.observability?.onTaskCreate, {
+        tool: opts.tool,
+        taskId,
+        accountId: opts.accountId,
+        durationMs: Date.now() - createStart,
+    }, 'onTaskCreate', opts.logger);
+    const taskStart = Date.now();
+    // Single helper for the four `onTaskTransition` fire sites.
+    const fireTransition = (status, errorCode) => {
+        safeFire(opts.observability?.onTaskTransition, {
+            taskId,
+            tool: opts.tool,
+            accountId: opts.accountId,
+            status,
+            durationMs: Date.now() - taskStart,
+            ...(errorCode !== undefined && { errorCode }),
+        }, 'onTaskTransition', opts.logger);
+    };
+    // Three failure surfaces:
+    //   1. taskFn throws → record failure → emit failed webhook
+    //   2. taskFn succeeds but registry write fails (DB outage) → log only;
+    //      do NOT emit webhook (buyer doesn't know task succeeded), do NOT
+    //      try to fail() the task (taskFn DID succeed; mismatch would
+    //      mislead operator reconciliation)
+    //   3. taskFn fails AND registry fail-write also fails → log only;
+    //      do not emit webhook (registry state is inconsistent)
+    //
+    // Webhook delivery is gated on the registry write succeeding so the
+    // buyer's view (via webhook OR getTaskState) is always consistent.
+    const completion = (async () => {
+        let result;
+        let taskFnError;
+        try {
+            result = await taskFn(taskId);
+        }
+        catch (err) {
+            taskFnError = err;
+        }
+        if (taskFnError === undefined) {
+            // Success path
+            try {
+                await taskRegistry.complete(taskId, result);
+            }
+            catch (registryErr) {
+                opts.logger.error(`[adcp/decisioning] task ${taskId} (${opts.tool}) completed but registry write failed — ` +
+                    `manual reconciliation required. Webhook not emitted; buyer state will diverge until resolved. ` +
+                    `Error: ${registryErr instanceof Error ? registryErr.message : String(registryErr)}`);
+                fireTransition('failed', 'REGISTRY_WRITE_FAILED');
+                return;
+            }
+            fireTransition('completed');
+            await emitTaskWebhook(opts, {
+                task: { task_id: taskId, status: 'completed', result },
+            });
+            return;
+        }
+        // Failure path
+        const structured = taskFnError instanceof async_outcome_1.AdcpError
+            ? taskFnError.toStructuredError()
+            : {
+                code: 'SERVICE_UNAVAILABLE',
+                recovery: 'transient',
+                message: taskFnError instanceof Error ? taskFnError.message : String(taskFnError),
+            };
+        try {
+            await taskRegistry.fail(taskId, structured);
+        }
+        catch (registryErr) {
+            opts.logger.error(`[adcp/decisioning] task ${taskId} (${opts.tool}) failed AND registry fail-write also failed — ` +
+                `manual reconciliation required. Webhook not emitted. ` +
+                `taskFn error: ${structured.message}; registry error: ${registryErr instanceof Error ? registryErr.message : String(registryErr)}`);
+            fireTransition('failed', 'REGISTRY_WRITE_FAILED');
+            return;
+        }
+        fireTransition('failed', structured.code);
+        await emitTaskWebhook(opts, {
+            task: { task_id: taskId, status: 'failed', error: structured },
+        });
+    })();
+    taskRegistry._registerBackground(taskId, completion);
+    return { status: 'submitted', task_id: taskId };
+}
+/**
+ * AdCP wire spec puts task / status / context fields on the webhook envelope
+ * top level (`mcp-webhook-payload.json`); the success / failure body lives on
+ * `result`. This helper builds that shape from the v6 task lifecycle data.
+ *
+ * Spec requires top-level: `idempotency_key`, `task_id`, `task_type`, `status`,
+ * `timestamp`. Optional: `protocol`, `context_id`, `message`, `result`,
+ * `operation_id`. We add `validation_token` (echoed from
+ * `push_notification_config.token`) outside the spec but consistent with the
+ * intent — receivers that don't expect it ignore the extra property.
+ *
+ * The webhook emitter generates `idempotency_key` internally from
+ * `operation_id`; we mirror it on the payload body so receivers running
+ * spec-conformant `mcp-webhook-payload.json` validation see the required
+ * field. Same value is on the HTTP `Idempotency-Key` header for HTTP-level
+ * dedup.
+ */
+function buildTaskWebhookPayload(opts, taskId, status, artifact) {
+    const idempotencyKey = (0, node_crypto_1.randomUUID)();
+    const payload = {
+        idempotency_key: idempotencyKey,
+        task_id: taskId,
+        task_type: opts.tool,
+        status,
+        timestamp: new Date().toISOString(),
+        protocol: (0, protocol_for_tool_1.protocolForTool)(opts.tool),
+    };
+    // Spec doesn't define a wire field name for the echoed token. Buyers
+    // pass `push_notification_config.token` on the request; we echo it back
+    // under the same name `token` so receivers verifying via the request
+    // field can find it. (Earlier preview drops named this `validation_token`
+    // — that wasn't spec-aligned and won't be picked up by buyers wiring
+    // against the spec request shape.)
+    if (opts.pushNotificationToken !== undefined) {
+        payload.token = opts.pushNotificationToken;
+    }
+    // `result` is the AdCP async-response-data union — for completed it's
+    // the success-arm body; for failed it carries `errors: AdcpStructuredError[]`
+    // alongside the empty success shape.
+    if (status === 'completed' && artifact.result !== undefined) {
+        payload.result = artifact.result;
+    }
+    if (status === 'failed' && artifact.error !== undefined) {
+        payload.result = { errors: [artifact.error] };
+        payload.message = artifact.error.message;
+    }
+    return payload;
+}
+// `protocolForTool` and `SPEC_WEBHOOK_TASK_TYPES` are exported from
+// `protocol-for-tool.ts` — see import at top of file.
+async function emitTaskWebhook(opts, source) {
+    if (!opts.emitWebhook || !opts.pushNotificationUrl)
+        return;
+    const taskId = source.task.task_id;
+    // Spec gate: `enums/task-type.json` is a closed 20-value enum at AdCP
+    // 3.0 GA. Spec-validating receivers reject envelopes with a non-spec
+    // `task_type` value. The framework dispatches a wider tool surface
+    // than the spec-listed task types — for those, skip webhook delivery
+    // (adopters surface long-running state via `publishStatusChange`
+    // instead). Tracking spec issue to widen the enum.
+    if (!protocol_for_tool_1.SPEC_WEBHOOK_TASK_TYPES.has(opts.tool)) {
+        opts.logger.warn(`[adcp/decisioning] task webhook for ${taskId} (${opts.tool}) skipped — ` +
+            `tool not in spec task-type enum (closed 20-value set per enums/task-type.json). ` +
+            `Use publishStatusChange for long-running ${opts.tool} state.`);
+        return;
+    }
+    const wirePayload = buildTaskWebhookPayload(opts, taskId, source.task.status, {
+        ...(source.task.result !== undefined && { result: source.task.result }),
+        ...(source.task.error !== undefined && { error: source.task.error }),
+    });
+    const start = Date.now();
+    let success = false;
+    let errorMessages;
+    let errorCode;
+    try {
+        const result = await opts.emitWebhook({
+            url: opts.pushNotificationUrl,
+            payload: wirePayload,
+            operation_id: `${opts.tool}.${taskId}`,
+        });
+        success = result?.delivered === true;
+        if (result && Array.isArray(result.errors) && result.errors.length > 0) {
+            errorMessages = result.errors;
+            errorCode = bucketWebhookError(result.errors[0] ?? '');
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        errorMessages = [msg];
+        errorCode = bucketWebhookError(msg);
+        // Webhook failures don't fail the task — registry already records the
+        // terminal state. URL redacted from log to avoid leaking buyer-supplied
+        // attacker-controllable values into operator log aggregators.
+        opts.logger.warn(`[adcp/decisioning] task webhook for ${taskId} (${opts.tool}, status=${source.task.status}) ` + `failed: ${msg}`);
+    }
+    finally {
+        safeFire(opts.observability?.onWebhookEmit, {
+            taskId,
+            tool: opts.tool,
+            status: source.task.status,
+            url: opts.pushNotificationUrl,
+            success,
+            durationMs: Date.now() - start,
+            ...(errorCode && { errorCode }),
+            ...(errorMessages && { errorMessages }),
+        }, 'onWebhookEmit', opts.logger);
+    }
+}
+/**
+ * Bucket a free-text webhook error into a metric-tag-safe code. Matches
+ * `DecisioningObservabilityHooks.onWebhookEmit.errorCode` documented enum
+ * (`'TIMEOUT'`, `'CONNECTION_REFUSED'`, `'HTTP_4XX'`, `'HTTP_5XX'`,
+ * `'SIGNATURE_FAILURE'`, `'UNKNOWN'`). Adopters tag DD/Prom by the bucket;
+ * `errorMessages` carries the raw text for log adopters.
+ */
+function bucketWebhookError(msg) {
+    const lower = msg.toLowerCase();
+    if (lower.includes('timeout') || lower.includes('etimedout'))
+        return 'TIMEOUT';
+    if (lower.includes('econnrefused') || lower.includes('connection refused'))
+        return 'CONNECTION_REFUSED';
+    if (lower.includes('signature') || lower.includes('rfc 9421'))
+        return 'SIGNATURE_FAILURE';
+    // Find ALL 3-digit HTTP-status-shaped tokens. Take the LARGEST one —
+    // operator triage cares about the most-severe status, not the
+    // left-most occurrence. Fixes "upstream 502 (proxy received 401)"
+    // which would mis-bucket as HTTP_4XX under a first-match policy.
+    const matches = lower.match(/\b[45]\d\d\b/g);
+    if (matches && matches.length > 0) {
+        const codes = matches.map(m => parseInt(m, 10));
+        const max = Math.max(...codes);
+        return max >= 500 ? 'HTTP_5XX' : 'HTTP_4XX';
+    }
+    return 'UNKNOWN';
+}
+function makeCtxFor(ctxMetadataStore) {
+    return handlerCtx => (0, to_context_1.buildRequestContext)(handlerCtx, ctxMetadataStore);
+}
+/**
+ * Auto-store helper. After a publisher returns resources from a discovery
+ * tool (`getProducts`, `getMediaBuys`, etc.), persist each resource's wire
+ * shape (minus `ctx_metadata`) alongside the publisher's `ctx_metadata`
+ * blob. Subsequent calls referencing the same id by string can be hydrated
+ * (publisher sees the full resource as `req.packages[i].product`).
+ *
+ * Failures are logged + swallowed — auto-store must NEVER break a
+ * successful response.
+ */
+async function autoStoreResources(store, accountId, kind, resources, idField, logger) {
+    if (!store || !accountId || !resources)
+        return;
+    let skippedMissingId = 0;
+    for (const r of resources) {
+        if (r == null || typeof r !== 'object')
+            continue;
+        const obj = r;
+        const id = obj[idField];
+        if (typeof id !== 'string' || id.length === 0) {
+            // The id field is wire-required on every resource the framework
+            // auto-stores (e.g. `signal_agent_segment_id` on a signal,
+            // `product_id` on a product). Silently skipping leaves buyers with
+            // no way to reference the resource on a downstream mutating call —
+            // a strong indicator the handler returned a misshaped response.
+            skippedMissingId++;
+            continue;
+        }
+        const ctxMeta = obj['ctx_metadata'];
+        // Strip ctx_metadata from the resource before storing — round-trip
+        // restores it on hydration. Keeping a pristine wire copy in `resource`.
+        const { ctx_metadata: _stripped, ...wireResource } = obj;
+        void _stripped;
+        try {
+            // Use `setResource` (not `setEntry`) so a publisher's prior
+            // `ctx.ctxMetadata.set(kind, id, blob)` is preserved when the
+            // publisher returns the resource WITHOUT `ctx_metadata` inline.
+            // Auto-store should never clobber adopter-managed state.
+            await store.setResource(accountId, kind, id, wireResource, ctxMeta);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            logger.warn(`[adcp/decisioning] auto-store ${kind} ${id} failed: ${msg}`);
+        }
+    }
+    if (skippedMissingId > 0) {
+        logger.warn(`[adcp/decisioning] auto-store skipped ${skippedMissingId} ${kind} ` +
+            `record(s) missing required '${idField}' — buyers will not be able ` +
+            `to reference these resources on a subsequent mutating call.`);
+    }
+}
+/**
+ * Auto-hydrate helper. Before invoking a publisher's mutating handler,
+ * walk the request's resource references and attach the full wire
+ * resource (including `ctx_metadata`) to each. Mutates the request in
+ * place — adds an extra typed field alongside the original id.
+ *
+ * For `createMediaBuy`: walks `req.packages`, hydrates each with
+ * `pkg.product = { ...resource, ctx_metadata }` keyed by `pkg.product_id`.
+ *
+ * Failures are logged + swallowed; the publisher still receives the
+ * un-hydrated request and can fall back to its own DB.
+ */
+async function hydratePackagesWithProducts(store, accountId, packages, logger) {
+    if (!store || !accountId || !packages || packages.length === 0)
+        return;
+    const refs = [];
+    for (const pkg of packages) {
+        if (pkg == null || typeof pkg !== 'object')
+            continue;
+        const productId = pkg['product_id'];
+        if (typeof productId === 'string' && productId.length > 0) {
+            refs.push({ kind: 'product', id: productId });
+        }
+    }
+    if (refs.length === 0)
+        return;
+    let entries;
+    try {
+        entries = await store.bulkGetEntries(accountId, refs);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logger.warn(`[adcp/decisioning] auto-hydrate bulkGet failed: ${msg}`);
+        return;
+    }
+    for (const pkg of packages) {
+        if (pkg == null || typeof pkg !== 'object')
+            continue;
+        const productId = pkg['product_id'];
+        if (typeof productId !== 'string')
+            continue;
+        const entry = entries.get(`product:${productId}`);
+        if (!entry?.resource || typeof entry.resource !== 'object')
+            continue;
+        const hydrated = { ...entry.resource };
+        if (entry.value !== null && entry.value !== undefined) {
+            hydrated['ctx_metadata'] = entry.value;
+        }
+        Object.defineProperty(hydrated, '__adcp_hydrated__', {
+            value: true,
+            enumerable: false,
+            writable: false,
+            configurable: false,
+        });
+        // Non-enumerable: see hydrateSingleResource for rationale (no leak via
+        // JSON.stringify / spread / Object.entries; direct access works).
+        Object.defineProperty(pkg, 'product', {
+            value: hydrated,
+            enumerable: false,
+            writable: true,
+            configurable: true,
+        });
+    }
+}
+/**
+ * Auto-hydrate one resource referenced by id at the top level of a request.
+ *
+ * Generalization of {@link hydratePackagesWithProducts} for verbs whose
+ * primary resource lives directly on the request body (`update_media_buy`,
+ * `provide_performance_feedback`, `activate_signal`, `acquire_rights`).
+ * Walks the store for `(kind, id)`, attaches `target[attachField] =
+ * { ...resource, ctx_metadata }` when the entry has a wire resource.
+ *
+ * ## Error contract on missing references
+ *
+ * **Misses are silent. The handler runs anyway with `target[attachField]`
+ * undefined.** This is deliberate — the framework cache is a *hint*, not
+ * the source of truth. A miss can mean any of:
+ *
+ *   1. The buyer never called the discovery verb in this session (cold
+ *      start, fresh tenant). Hydration is purely additive context; the
+ *      publisher's own DB is authoritative for whether the id exists.
+ *   2. The cache evicted (TTL, LRU). Same: publisher's DB stays the
+ *      source of truth.
+ *   3. The buyer truly referenced an unknown id. The publisher SHOULD
+ *      reject this — see the handler-side guard pattern below.
+ *
+ * Adopters who want strict existence checks (option 1: framework throws
+ * `PRODUCT_NOT_FOUND` / `MEDIA_BUY_NOT_FOUND` and the handler never runs)
+ * implement that check inside the handler:
+ *
+ * ```ts
+ * updateMediaBuy: async (id, patch, ctx) => {
+ *   // Hydration miss + DB miss = unknown to this seller.
+ *   if (!patch.media_buy && !(await db.findMediaBuy(id))) {
+ *     throw new MediaBuyNotFoundError({ message: `media_buy ${id} not found` });
+ *   }
+ *   // ...
+ * }
+ * ```
+ *
+ * The framework cannot distinguish (1)/(2) from (3) without consulting the
+ * publisher's DB, which is exactly what the handler does. Erroring at the
+ * framework layer would force every adopter to manage cache warmth or
+ * pre-load every media_buy into the cache before serving traffic — wrong
+ * default for a hint-based cache.
+ *
+ * ## Field semantics on the hydrated value
+ *
+ * The attached field is **non-enumerable** so accidental serialization
+ * (`JSON.stringify(req)`, spread `{...req}`, `Object.entries(req)`)
+ * doesn't leak the publisher's `ctx_metadata` blob into request-side audit
+ * sinks. Direct property access (`req.media_buy.ctx_metadata`) still
+ * works; the field is invisible only to enumeration-based serializers.
+ *
+ * Hydrated fields carry a `__adcp_hydrated__: true` non-enumerable marker
+ * so handler authors and middleware can disambiguate "publisher passed it"
+ * from "framework attached it" — the field is **advisory context only**;
+ * the wire contract is defined by the spec request fields, not by what
+ * the SDK happens to attach.
+ *
+ * Store-fetch failures (Postgres unavailable, etc.) are logged + swallowed.
+ * Hydration must NEVER break a successful dispatch — same posture as a
+ * cache miss.
+ */
+async function hydrateSingleResource(store, accountId, kind, id, attachField, target, logger) {
+    if (!store || !accountId || !id || target == null || typeof target !== 'object')
+        return;
+    let entry;
+    try {
+        entry = await store.getEntry(accountId, kind, id);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logger.warn(`[adcp/decisioning] auto-hydrate ${kind}:${id} failed: ${msg}`);
+        return;
+    }
+    if (!entry?.resource || typeof entry.resource !== 'object')
+        return;
+    const hydrated = { ...entry.resource };
+    if (entry.value !== null && entry.value !== undefined) {
+        hydrated['ctx_metadata'] = entry.value;
+    }
+    Object.defineProperty(hydrated, '__adcp_hydrated__', {
+        value: true,
+        enumerable: false,
+        writable: false,
+        configurable: false,
+    });
+    // Attach as non-enumerable so JSON.stringify(req), spread {...req}, and
+    // Object.entries(req) do NOT carry the publisher's ctx_metadata blob into
+    // log lines, audit sinks, or replay payloads. Direct access (req.foo)
+    // still works.
+    Object.defineProperty(target, attachField, {
+        value: hydrated,
+        enumerable: false,
+        writable: true,
+        configurable: true,
+    });
+}
+/**
+ * Extract the buyer's push-notification webhook config from a request body
+ * and validate the URL + token against SSRF / replay primitives.
+ *
+ * AdCP wire requests for HITL tools carry `push_notification_config: { url,
+ * token? }`. The buyer-supplied URL is attacker-controllable — without
+ * validation, a buyer with `create_media_buy` access can force the agent
+ * process to POST signed payloads to internal admin endpoints, AWS metadata
+ * (`http://169.254.169.254/`), or RFC 1918 private ranges. Validation
+ * gates here:
+ *
+ * 1. **Scheme**: `https://` only in production; `http://` allowed when
+ *    `NODE_ENV` ∈ {test, development} OR the operator opts in via
+ *    `ADCP_DECISIONING_ALLOW_HTTP_WEBHOOKS=1`. Same allowlist pattern as
+ *    the in-memory task registry.
+ * 2. **Host**: rejects IP-literals targeting RFC 1918 private ranges
+ *    (10/8, 172.16/12, 192.168/16), link-local (169.254/16, fe80::/10),
+ *    loopback (127/8, ::1), CGNAT (100.64/10), and unspecified addresses
+ *    (0.0.0.0, ::). Rejects bare hostnames `localhost` / `0`.
+ * 3. **Token shape**: rejects tokens longer than 255 chars or containing
+ *    control characters. Tokens past 255 chars combined with a malicious
+ *    URL would inflate webhook payload size; control characters break log
+ *    redaction.
+ *
+ * Adopters who need stricter rules (host allowlist) can re-validate
+ * inside their `taskWebhookEmitter` impl. Adopters needing to relax for
+ * legitimate internal-network test setups use the env-var ack.
+ *
+ * **DNS rebinding caveat.** This validator only inspects the literal
+ * hostname/IP in the URL. A buyer registers `https://rebind.attacker.com/`
+ * whose A-record returns `8.8.8.8` at validate time and `127.0.0.1` /
+ * `169.254.169.254` at fetch time bypasses this layer. The framework's
+ * own `serve({ webhooks })`-wired emitter (RFC 9421-signed delivery via
+ * `WebhookManager`) re-resolves the host at fetch time and DOES NOT
+ * pin-and-bind to the validate-time IP. Adopters wiring a custom
+ * `taskWebhookEmitter` SHOULD pin the resolved IP at validate time and
+ * connect to that specific IP, OR run all webhook delivery through a
+ * forward proxy with an egress allowlist. Tracking issue:
+ * `adcp-client#TBD` for framework-side pin-and-bind.
+ *
+ * On rejection, throws `AdcpError('INVALID_REQUEST', { field })` so the
+ * buyer sees the bad config at the request boundary. Previous silent-skip
+ * posture lost buyer visibility.
+ */
+function extractPushConfig(params, _logger, opts = {}) {
+    if (!params || typeof params !== 'object')
+        return {};
+    const cfg = params.push_notification_config;
+    if (!cfg || typeof cfg !== 'object')
+        return {};
+    const rawUrl = cfg.url;
+    const rawToken = cfg.token;
+    let url;
+    if (typeof rawUrl === 'string') {
+        const validation = validatePushNotificationUrl(rawUrl, { allowPrivate: opts.allowPrivateWebhookUrls === true });
+        if (!validation.ok) {
+            // Fail fast: buyers thought they wired push and never saw it under
+            // the previous silent-skip posture. Rejecting upfront with
+            // `INVALID_REQUEST` and `field: 'push_notification_config.url'`
+            // surfaces the problem at the request boundary so buyers can fix
+            // their config before relying on webhooks. Buyers can still poll
+            // via `tasks_get` if they need a fallback path.
+            throw new async_outcome_1.AdcpError('INVALID_REQUEST', {
+                message: `push_notification_config.url rejected: ${validation.reason}`,
+                field: 'push_notification_config.url',
+                recovery: 'terminal',
+            });
+        }
+        url = rawUrl;
+    }
+    let token;
+    if (typeof rawToken === 'string') {
+        const validation = validatePushNotificationToken(rawToken);
+        if (!validation.ok) {
+            throw new async_outcome_1.AdcpError('INVALID_REQUEST', {
+                message: `push_notification_config.token rejected: ${validation.reason}`,
+                field: 'push_notification_config.token',
+                recovery: 'terminal',
+            });
+        }
+        token = rawToken;
+    }
+    return {
+        ...(url !== undefined && { url }),
+        ...(token !== undefined && { token }),
+    };
+}
+function validatePushNotificationUrl(rawUrl, opts = {}) {
+    let parsed;
+    try {
+        parsed = new URL(rawUrl);
+    }
+    catch {
+        return { ok: false, reason: 'malformed URL' };
+    }
+    const allowHttp = process.env.NODE_ENV === 'test' ||
+        process.env.NODE_ENV === 'development' ||
+        process.env.ADCP_DECISIONING_ALLOW_HTTP_WEBHOOKS === '1';
+    if (parsed.protocol === 'http:' && !allowHttp) {
+        return {
+            ok: false,
+            reason: 'http:// scheme not allowed (use https:// or set ADCP_DECISIONING_ALLOW_HTTP_WEBHOOKS=1)',
+        };
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        return { ok: false, reason: `unsupported scheme "${parsed.protocol}" (only http: / https:)` };
+    }
+    // Adopter-set flag bypasses ONLY the private-IP / loopback rejection.
+    // Malformed-URL and scheme checks above always fire — the relaxation
+    // is scoped to "let sandbox webhook receivers bind to loopback" not
+    // "trust everything." See CreateAdcpServerFromPlatformOptions.
+    if (opts.allowPrivate === true) {
+        return { ok: true };
+    }
+    // Node's `URL.hostname` returns IPv6 literals WITH brackets — so
+    // `https://[::1]/` yields `[::1]`. Strip them so our IPv6 checks below
+    // can match the unbracketed form. (`URL.host` includes the port, which
+    // we don't want here.)
+    let host = parsed.hostname.toLowerCase();
+    if (host.startsWith('[') && host.endsWith(']')) {
+        host = host.slice(1, -1);
+    }
+    if (host === '' || host === 'localhost' || host === '0') {
+        return { ok: false, reason: `host "${host}" rejected (loopback / unspecified)` };
+    }
+    // Note on IPv4 alternate forms (integer `2130706433`, hex `0x7f000001`,
+    // octal `0177.0.0.1`): Node's WHATWG URL parser canonicalizes all of
+    // these to dotted-decimal before we see `parsed.hostname`. So
+    // `https://2130706433/` arrives here with host `127.0.0.1` and falls
+    // through to the dotted-decimal range check below. Defense-in-depth
+    // alternate-form regex rejectors are not needed at this layer.
+    // IPv4 dotted-decimal check
+    const ipv4Match = host.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+    if (ipv4Match) {
+        const a = Number(ipv4Match[1]);
+        const b = Number(ipv4Match[2]);
+        if (a === 10)
+            return { ok: false, reason: 'RFC 1918 private range 10/8 rejected' };
+        if (a === 127)
+            return { ok: false, reason: 'loopback range 127/8 rejected' };
+        if (a === 0)
+            return { ok: false, reason: 'unspecified range 0/8 rejected' };
+        if (a === 169 && b === 254)
+            return { ok: false, reason: 'link-local 169.254/16 rejected (cloud metadata)' };
+        if (a === 172 && b >= 16 && b <= 31)
+            return { ok: false, reason: 'RFC 1918 private range 172.16/12 rejected' };
+        if (a === 192 && b === 168)
+            return { ok: false, reason: 'RFC 1918 private range 192.168/16 rejected' };
+        if (a === 100 && b >= 64 && b <= 127)
+            return { ok: false, reason: 'CGNAT range 100.64/10 rejected' };
+        if (a >= 224)
+            return { ok: false, reason: 'multicast / reserved range rejected' };
+    }
+    // IPv6 literal check — Node strips brackets so we match unbracketed forms.
+    // A hostname containing `:` is an IPv6 literal (DNS hostnames disallow `:`).
+    if (host.includes(':')) {
+        // Loopback + unspecified — exact match
+        if (host === '::1')
+            return { ok: false, reason: 'IPv6 loopback ::1 rejected' };
+        if (host === '::')
+            return { ok: false, reason: 'IPv6 unspecified :: rejected' };
+        // Link-local fe80::/10 — match strict prefix `fe80:` (not just `fe80`)
+        if (host.startsWith('fe80:')) {
+            return { ok: false, reason: 'IPv6 link-local fe80::/10 rejected' };
+        }
+        // Unique-local fc00::/7 — match strict prefix `fc` or `fd` followed
+        // by exactly one more hex char (so fc00:, fcab:, fd00:, fdef:) and
+        // then `:`. Old check `host.startsWith('fc')` would match the
+        // hostname-not-IP `fc-cdn.example.com`; since IPv6 hostnames always
+        // contain `:`, restrict to literals where char[2] is hex + `:`.
+        if (/^f[cd][0-9a-f]{2}:/.test(host)) {
+            return { ok: false, reason: 'IPv6 unique-local fc00::/7 rejected' };
+        }
+        // IPv4-mapped IPv6 — `::ffff:127.0.0.1` or `::ffff:7f00:0001`. Either
+        // form: extract the embedded IPv4 (if dotted) or the last 32 bits and
+        // re-run the IPv4 range checks. Simpler: reject any `::ffff:` prefix
+        // pointing to a private IPv4 by recursive validation.
+        const v4MappedMatch = host.match(/^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);
+        if (v4MappedMatch) {
+            const inner = v4MappedMatch[1];
+            const innerCheck = validatePushNotificationUrl(`http://${inner}/`);
+            if (!innerCheck.ok) {
+                return { ok: false, reason: `IPv4-mapped IPv6 ${host}: ${innerCheck.reason}` };
+            }
+        }
+        // Hex IPv4-mapped form (`::ffff:7f00:0001`): match the 32-bit
+        // suffix and convert to dotted form for re-check.
+        const v4MappedHexMatch = host.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+        if (v4MappedHexMatch) {
+            const high = parseInt(v4MappedHexMatch[1], 16);
+            const low = parseInt(v4MappedHexMatch[2], 16);
+            const dotted = `${(high >> 8) & 0xff}.${high & 0xff}.${(low >> 8) & 0xff}.${low & 0xff}`;
+            const innerCheck = validatePushNotificationUrl(`http://${dotted}/`);
+            if (!innerCheck.ok) {
+                return { ok: false, reason: `IPv4-mapped IPv6 ${host}: ${innerCheck.reason}` };
+            }
+        }
+    }
+    return { ok: true };
+}
+const TOKEN_MAX_LENGTH = 255;
+const TOKEN_CONTROL_CHAR_RE = /[\x00-\x1f\x7f]/;
+function validatePushNotificationToken(token) {
+    if (token.length === 0) {
+        return { ok: false, reason: 'token is empty' };
+    }
+    if (token.length > TOKEN_MAX_LENGTH) {
+        return { ok: false, reason: `token longer than ${TOKEN_MAX_LENGTH} chars` };
+    }
+    if (TOKEN_CONTROL_CHAR_RE.test(token)) {
+        return { ok: false, reason: 'token contains control characters' };
+    }
+    return { ok: true };
+}
+function buildMediaBuyHandlers(platform, taskRegistry, taskWebhookEmit, observability, logger, pushOpts, ctxFor, ctxMetadataStore) {
+    const sales = platform.sales;
+    if (!sales)
+        return undefined;
+    return {
+        getProducts: async (params, ctx) => {
+            const reqCtx = ctxFor(ctx);
+            return projectSync(async () => {
+                const result = await sales.getProducts(params, reqCtx);
+                // Auto-store products: persist each Product's wire shape +
+                // ctx_metadata so subsequent createMediaBuy / updateMediaBuy
+                // calls referencing product_id can hydrate the full Product
+                // automatically (publisher sees `req.packages[i].product`).
+                await autoStoreResources(ctxMetadataStore, reqCtx.account?.id, 'product', result?.products, 'product_id', logger);
+                return result;
+            }, r => r);
+        },
+        createMediaBuy: async (params, ctx) => {
+            const reqCtx = ctxFor(ctx);
+            // Auto-hydrate: walk `params.packages`, attach the full Product object
+            // (including `ctx_metadata`) at `pkg.product`. Publisher reads
+            // `pkg.product.format_ids`, `pkg.product.ctx_metadata?.gam?.ad_unit_ids`
+            // directly — no separate lookup, no boilerplate.
+            await hydratePackagesWithProducts(ctxMetadataStore, reqCtx.account?.id, params?.packages, logger);
+            return projectSync(async () => {
+                const push = extractPushConfig(params, logger, { allowPrivateWebhookUrls: pushOpts.allowPrivateWebhookUrls });
+                const result = await sales.createMediaBuy(params, reqCtx);
+                return routeIfHandoff(taskRegistry, {
+                    tool: 'create_media_buy',
+                    accountId: reqCtx.account.id,
+                    pushNotificationUrl: push.url,
+                    pushNotificationToken: push.token,
+                    emitWebhook: taskWebhookEmit ?? ctx.emitWebhook,
+                    autoEmitCompletion: pushOpts.autoEmitCompletionWebhooks,
+                    observability,
+                    logger,
+                }, result, r => r // identity projection for createMediaBuy
+                );
+            }, r => r);
+        },
+        updateMediaBuy: async (params, ctx) => {
+            const reqCtx = ctxFor(ctx);
+            // `media_buy_id` is required on the wire schema, but `validation: 'off'`
+            // mode skips the schema parse — guard at the seam so platform code can
+            // trust the value rather than re-checking. Also catches buyers calling
+            // with the param missing under an off-spec server config.
+            const { media_buy_id } = params;
+            if (!media_buy_id) {
+                return (0, errors_1.adcpError)('INVALID_REQUEST', {
+                    message: 'update_media_buy requires media_buy_id',
+                    field: 'media_buy_id',
+                    recovery: 'correctable',
+                });
+            }
+            // Auto-hydrate: attach the full MediaBuy (wire shape + ctx_metadata)
+            // at `req.media_buy`. Publisher reads `req.media_buy.ctx_metadata?.gam`
+            // directly — no separate lookup. Misses are silent; publisher falls
+            // back to its own DB.
+            await hydrateSingleResource(ctxMetadataStore, reqCtx.account?.id, 'media_buy', media_buy_id, 'media_buy', params, logger);
+            return projectSync(async () => {
+                const push = extractPushConfig(params, logger, {
+                    allowPrivateWebhookUrls: pushOpts.allowPrivateWebhookUrls,
+                });
+                const result = await sales.updateMediaBuy(media_buy_id, params, reqCtx);
+                // F12 sync auto-emit. updateMediaBuy is sync-only on the
+                // platform interface (no TaskHandoff arm — spec response
+                // doesn't include Submitted), so we don't route through
+                // routeIfHandoff. Fire-and-forget to keep slowloris webhook
+                // receivers from blocking the sync response.
+                if (pushOpts.autoEmitCompletionWebhooks && push.url) {
+                    const emitOpts = {
+                        tool: 'update_media_buy',
+                        accountId: reqCtx.account.id,
+                        pushNotificationUrl: push.url,
+                        ...(push.token !== undefined && { pushNotificationToken: push.token }),
+                        emitWebhook: taskWebhookEmit ?? ctx.emitWebhook,
+                        ...(observability && { observability }),
+                        logger,
+                    };
+                    void emitSyncCompletionWebhook(emitOpts, result).catch((err) => {
+                        const msg = err instanceof Error ? err.message : String(err);
+                        logger.warn(`[adcp/decisioning] sync completion webhook background-error: ${msg}`);
+                    });
+                }
+                return result;
+            }, r => r);
+        },
+        syncCreatives: async (params, ctx) => {
+            const reqCtx = ctxFor(ctx);
+            const creatives = params.creatives ?? [];
+            if (!sales.syncCreatives) {
+                return (0, errors_1.adcpError)('UNSUPPORTED_FEATURE', {
+                    message: 'sync_creatives not supported by this sales platform',
+                    recovery: 'terminal',
+                });
+            }
+            return projectSync(async () => {
+                const push = extractPushConfig(params, logger, { allowPrivateWebhookUrls: pushOpts.allowPrivateWebhookUrls });
+                const result = await sales.syncCreatives(creatives, reqCtx);
+                return routeIfHandoff(taskRegistry, {
+                    tool: 'sync_creatives',
+                    accountId: reqCtx.account.id,
+                    pushNotificationUrl: push.url,
+                    pushNotificationToken: push.token,
+                    emitWebhook: taskWebhookEmit ?? ctx.emitWebhook,
+                    autoEmitCompletion: pushOpts.autoEmitCompletionWebhooks,
+                    observability,
+                    logger,
+                }, result, rows => ({ creatives: rows.map(normalizeRowErrors) }));
+            }, r => r);
+        },
+        getMediaBuyDelivery: async (params, ctx) => {
+            const reqCtx = ctxFor(ctx);
+            return projectSync(() => sales.getMediaBuyDelivery(params, reqCtx), actuals => actuals);
+        },
+        // Optional methods — return UNSUPPORTED_FEATURE when the platform omits
+        // them. Adopters that haven't migrated to the v6 platform interface for
+        // these specific tools can still pass raw handlers via opts.mediaBuy
+        // (merge seam) — the merge runs AFTER buildMediaBuyHandlers, so opts
+        // handlers fill in for the methods this platform omits.
+        // `getMediaBuys` is REQUIRED at the type level, but we keep a runtime
+        // guard for the merge-seam migration path: legacy adopters wire it via
+        // `opts.mediaBuy.getMediaBuys` rather than on the platform interface.
+        // Once the migration completes (every adopter implements it natively),
+        // this conditional spreads can collapse — but for now, omitting the
+        // platform-derived handler when absent lets `mergeHandlers` pick up the
+        // adopter's custom handler from `opts.mediaBuy` instead of throwing
+        // `sales.getMediaBuys is not a function`.
+        ...(sales.getMediaBuys && {
+            getMediaBuys: async (params, ctx) => {
+                const reqCtx = ctxFor(ctx);
+                return projectSync(async () => {
+                    const result = await sales.getMediaBuys(params, reqCtx);
+                    await autoStoreResources(ctxMetadataStore, reqCtx.account?.id, 'media_buy', result?.media_buys, 'media_buy_id', logger);
+                    return result;
+                }, r => r);
+            },
+        }),
+        ...(sales.providePerformanceFeedback && {
+            providePerformanceFeedback: async (params, ctx) => {
+                const reqCtx = ctxFor(ctx);
+                // Auto-hydrate `req.media_buy` from the prior createMediaBuy /
+                // getMediaBuys store entry, plus `req.creative` when the buyer
+                // scoped feedback to a specific creative. Both fields are optional
+                // hydration targets — adopters who only care about the feedback
+                // payload itself can ignore them.
+                const accountId = reqCtx.account?.id;
+                await hydrateSingleResource(ctxMetadataStore, accountId, 'media_buy', params.media_buy_id, 'media_buy', params, logger);
+                const creativeId = params.creative_id;
+                if (creativeId) {
+                    await hydrateSingleResource(ctxMetadataStore, accountId, 'creative', creativeId, 'creative', params, logger);
+                }
+                return projectSync(() => sales.providePerformanceFeedback(params, reqCtx), r => r);
+            },
+        }),
+        ...(sales.listCreativeFormats && {
+            listCreativeFormats: async (params, ctx) => {
+                const reqCtx = ctxFor(ctx);
+                return projectSync(() => sales.listCreativeFormats(params, reqCtx), r => r);
+            },
+        }),
+        ...(sales.listCreatives && {
+            listCreatives: async (params, ctx) => {
+                const reqCtx = ctxFor(ctx);
+                return projectSync(() => sales.listCreatives(params, reqCtx), r => r);
+            },
+        }),
+    };
+}
+/**
+ * Project an adopter `buildCreative` return value into the wire response
+ * shape. Handles the four legal adopter shapes per `BuildCreativeReturn`:
+ *
+ *   - Already-shaped Single envelope (`creative_manifest` field present) →
+ *     passthrough. Adopter set `sandbox` / `expires_at` / `preview` themselves.
+ *   - Already-shaped Multi envelope (`creative_manifests` field present) →
+ *     passthrough. Same metadata-controlled case for multi-format requests.
+ *   - Bare array → wrap as `{ creative_manifests: <array> }` (multi, no metadata).
+ *   - Plain `CreativeManifest` → wrap as `{ creative_manifest: <obj> }`
+ *     (single, no metadata).
+ *
+ * The discriminator order matters: check shaped envelopes first so an
+ * adopter that returned `{ creative_manifest, sandbox: true }` (a Single
+ * envelope) doesn't get re-wrapped into
+ * `{ creative_manifest: { creative_manifest, sandbox: true } }`. Same
+ * concern applies symmetrically for Multi.
+ */
+function projectBuildCreativeReturn(ret) {
+    if (ret != null && typeof ret === 'object' && !Array.isArray(ret)) {
+        if ('creative_manifest' in ret)
+            return ret;
+        if ('creative_manifests' in ret)
+            return ret;
+    }
+    if (Array.isArray(ret)) {
+        return { creative_manifests: ret };
+    }
+    return { creative_manifest: ret };
+}
+function buildCreativeHandlers(platform, taskRegistry, taskWebhookEmit, observability, logger, pushOpts, ctxFor) {
+    const creative = platform.creative;
+    if (!creative)
+        return undefined;
+    return {
+        buildCreative: async (params, ctx) => {
+            const reqCtx = ctxFor(ctx);
+            return projectSync(() => creative.buildCreative(params, reqCtx), ret => projectBuildCreativeReturn(ret));
+        },
+        previewCreative: async (params, ctx) => {
+            if (!('previewCreative' in creative)) {
+                return (0, errors_1.adcpError)('UNSUPPORTED_FEATURE', {
+                    message: 'preview_creative not supported by this platform',
+                    recovery: 'terminal',
+                });
+            }
+            const reqCtx = ctxFor(ctx);
+            return projectSync(() => creative.previewCreative(params, reqCtx), preview => preview);
+        },
+        syncCreatives: async (params, ctx) => {
+            const reqCtx = ctxFor(ctx);
+            const creatives = params.creatives ?? [];
+            if (!creative.syncCreatives) {
+                return (0, errors_1.adcpError)('UNSUPPORTED_FEATURE', {
+                    message: 'sync_creatives not supported by this creative platform',
+                    recovery: 'terminal',
+                });
+            }
+            return projectSync(async () => {
+                const push = extractPushConfig(params, logger, { allowPrivateWebhookUrls: pushOpts.allowPrivateWebhookUrls });
+                const result = await creative.syncCreatives(creatives, reqCtx);
+                return routeIfHandoff(taskRegistry, {
+                    tool: 'sync_creatives',
+                    accountId: reqCtx.account.id,
+                    pushNotificationUrl: push.url,
+                    pushNotificationToken: push.token,
+                    emitWebhook: taskWebhookEmit ?? ctx.emitWebhook,
+                    autoEmitCompletion: pushOpts.autoEmitCompletionWebhooks,
+                    observability,
+                    logger,
+                }, result, rows => ({ creatives: rows.map(normalizeRowErrors) }));
+            }, r => r);
+        },
+        // Ad-server-specialism methods. Only the CreativeAdServerPlatform variant
+        // implements these; framework returns UNSUPPORTED_FEATURE for the other
+        // archetypes (template, generative).
+        listCreatives: async (params, ctx) => {
+            if (!('listCreatives' in creative)) {
+                return (0, errors_1.adcpError)('UNSUPPORTED_FEATURE', {
+                    message: 'list_creatives not supported by this platform',
+                    recovery: 'terminal',
+                });
+            }
+            const reqCtx = ctxFor(ctx);
+            return projectSync(() => creative.listCreatives(params, reqCtx), r => r);
+        },
+        getCreativeDelivery: async (params, ctx) => {
+            if (!('getCreativeDelivery' in creative)) {
+                return (0, errors_1.adcpError)('UNSUPPORTED_FEATURE', {
+                    message: 'get_creative_delivery not supported by this platform',
+                    recovery: 'terminal',
+                });
+            }
+            const reqCtx = ctxFor(ctx);
+            return projectSync(() => creative.getCreativeDelivery(params, reqCtx), r => r);
+        },
+    };
+}
+function buildEventTrackingHandlers(platform, ctxFor) {
+    const audiences = platform.audiences;
+    const sales = platform.sales;
+    // Retail-media adopters (sales-catalog-driven) implement sync_catalogs /
+    // log_event / sync_event_sources on `SalesPlatform`. The wire spec routes
+    // these through the `event-tracking` framework category so the handlers
+    // land on `EventTrackingHandlers` regardless of which specialism owns
+    // them on the platform side.
+    if (!audiences && !sales)
+        return undefined;
+    const handlers = {};
+    if (audiences) {
+        handlers.syncAudiences = async (params, ctx) => {
+            const reqCtx = ctxFor(ctx);
+            const audienceList = (params.audiences ?? []);
+            return projectSync(() => audiences.syncAudiences(audienceList, reqCtx), rows => ({ audiences: rows }));
+        };
+    }
+    if (sales?.syncCatalogs) {
+        handlers.syncCatalogs = async (params, ctx) => {
+            const reqCtx = ctxFor(ctx);
+            return projectSync(() => sales.syncCatalogs(params, reqCtx), r => r);
+        };
+    }
+    if (sales?.logEvent) {
+        handlers.logEvent = async (params, ctx) => {
+            const reqCtx = ctxFor(ctx);
+            return projectSync(() => sales.logEvent(params, reqCtx), r => r);
+        };
+    }
+    if (sales?.syncEventSources) {
+        handlers.syncEventSources = async (params, ctx) => {
+            const reqCtx = ctxFor(ctx);
+            return projectSync(() => sales.syncEventSources(params, reqCtx), r => r);
+        };
+    }
+    return Object.keys(handlers).length > 0 ? handlers : undefined;
+}
+function buildSignalsHandlers(platform, ctxFor, ctxMetadataStore, logger) {
+    const signals = platform.signals;
+    if (!signals)
+        return undefined;
+    return {
+        getSignals: async (params, ctx) => {
+            const reqCtx = ctxFor(ctx);
+            return projectSync(async () => {
+                const result = await signals.getSignals(params, reqCtx);
+                // Auto-store signals so subsequent activate_signal can hydrate
+                // `req.signal` from the publisher's prior catalog entry.
+                await autoStoreResources(ctxMetadataStore, reqCtx.account?.id, 'signal', result?.signals, 'signal_agent_segment_id', logger);
+                return result;
+            }, r => r);
+        },
+        activateSignal: async (params, ctx) => {
+            const reqCtx = ctxFor(ctx);
+            // Auto-hydrate `req.signal` from the prior getSignals store entry —
+            // publisher reads pricing options, agent segment id, ctx_metadata
+            // directly without the buyer round-tripping the full signal object.
+            await hydrateSingleResource(ctxMetadataStore, reqCtx.account?.id, 'signal', params.signal_agent_segment_id, 'signal', params, logger);
+            return projectSync(() => signals.activateSignal(params, reqCtx), r => r);
+        },
+    };
+}
+function buildBrandRightsHandlers(platform, ctxFor, ctxMetadataStore, logger) {
+    const br = platform.brandRights;
+    if (!br)
+        return undefined;
+    return {
+        getBrandIdentity: async (params, ctx) => {
+            const reqCtx = ctxFor(ctx);
+            return projectSync(() => br.getBrandIdentity(params, reqCtx), r => r);
+        },
+        getRights: async (params, ctx) => {
+            const reqCtx = ctxFor(ctx);
+            return projectSync(async () => {
+                const result = await br.getRights(params, reqCtx);
+                // Auto-store rights offerings so subsequent acquire_rights can
+                // hydrate `req.rights` (pricing_options + ctx_metadata) without
+                // a separate publisher lookup.
+                await autoStoreResources(ctxMetadataStore, reqCtx.account?.id, 'rights_grant', result?.rights, 'rights_id', logger);
+                return result;
+            }, r => r);
+        },
+        // `acquire_rights` has 3 native wire-spec arms (Acquired / PendingApproval /
+        // Rejected) handled by the platform directly. No framework task envelope —
+        // adopters return the spec-defined arm. Async delivery for the
+        // PendingApproval arm rides the buyer's `push_notification_config` webhook
+        // (the spec doesn't define a polling tool for `acquire_rights`).
+        acquireRights: async (params, ctx) => {
+            const reqCtx = ctxFor(ctx);
+            // Auto-hydrate `req.rights` from the prior getRights catalog entry.
+            // Publisher reads selected pricing option + ctx_metadata directly.
+            await hydrateSingleResource(ctxMetadataStore, reqCtx.account?.id, 'rights_grant', params.rights_id, 'rights', params, logger);
+            return projectSync(() => br.acquireRights(params, reqCtx), r => r);
+        },
+    };
+}
+function buildGovernanceHandlers(platform, ctxFor) {
+    const cg = platform.campaignGovernance;
+    const pl = platform.propertyLists;
+    const cl = platform.collectionLists;
+    const cs = platform.contentStandards;
+    if (!cg && !pl && !cl && !cs)
+        return undefined;
+    const handlers = {};
+    if (cg) {
+        handlers.checkGovernance = async (params, ctx) => {
+            const reqCtx = ctxFor(ctx);
+            return projectSync(() => cg.checkGovernance(params, reqCtx), r => r);
+        };
+        handlers.syncPlans = async (params, ctx) => {
+            const reqCtx = ctxFor(ctx);
+            return projectSync(() => cg.syncPlans(params, reqCtx), r => r);
+        };
+        handlers.reportPlanOutcome = async (params, ctx) => {
+            const reqCtx = ctxFor(ctx);
+            return projectSync(() => cg.reportPlanOutcome(params, reqCtx), r => r);
+        };
+        handlers.getPlanAuditLogs = async (params, ctx) => {
+            const reqCtx = ctxFor(ctx);
+            return projectSync(() => cg.getPlanAuditLogs(params, reqCtx), r => r);
+        };
+    }
+    if (pl) {
+        handlers.createPropertyList = async (params, ctx) => {
+            const reqCtx = ctxFor(ctx);
+            return projectSync(() => pl.createPropertyList(params, reqCtx), r => r);
+        };
+        handlers.updatePropertyList = async (params, ctx) => {
+            const reqCtx = ctxFor(ctx);
+            return projectSync(() => pl.updatePropertyList(params, reqCtx), r => r);
+        };
+        handlers.getPropertyList = async (params, ctx) => {
+            const reqCtx = ctxFor(ctx);
+            return projectSync(() => pl.getPropertyList(params, reqCtx), r => r);
+        };
+        handlers.listPropertyLists = async (params, ctx) => {
+            const reqCtx = ctxFor(ctx);
+            return projectSync(() => pl.listPropertyLists(params, reqCtx), r => r);
+        };
+        handlers.deletePropertyList = async (params, ctx) => {
+            const reqCtx = ctxFor(ctx);
+            return projectSync(() => pl.deletePropertyList(params, reqCtx), r => r);
+        };
+    }
+    if (cl) {
+        handlers.createCollectionList = async (params, ctx) => {
+            const reqCtx = ctxFor(ctx);
+            return projectSync(() => cl.createCollectionList(params, reqCtx), r => r);
+        };
+        handlers.updateCollectionList = async (params, ctx) => {
+            const reqCtx = ctxFor(ctx);
+            return projectSync(() => cl.updateCollectionList(params, reqCtx), r => r);
+        };
+        handlers.getCollectionList = async (params, ctx) => {
+            const reqCtx = ctxFor(ctx);
+            return projectSync(() => cl.getCollectionList(params, reqCtx), r => r);
+        };
+        handlers.listCollectionLists = async (params, ctx) => {
+            const reqCtx = ctxFor(ctx);
+            return projectSync(() => cl.listCollectionLists(params, reqCtx), r => r);
+        };
+        handlers.deleteCollectionList = async (params, ctx) => {
+            const reqCtx = ctxFor(ctx);
+            return projectSync(() => cl.deleteCollectionList(params, reqCtx), r => r);
+        };
+    }
+    if (cs) {
+        handlers.listContentStandards = async (params, ctx) => {
+            const reqCtx = ctxFor(ctx);
+            return projectSync(() => cs.listContentStandards(params, reqCtx), r => r);
+        };
+        handlers.getContentStandards = async (params, ctx) => {
+            const reqCtx = ctxFor(ctx);
+            return projectSync(() => cs.getContentStandards(params, reqCtx), r => r);
+        };
+        handlers.createContentStandards = async (params, ctx) => {
+            const reqCtx = ctxFor(ctx);
+            return projectSync(() => cs.createContentStandards(params, reqCtx), r => r);
+        };
+        handlers.updateContentStandards = async (params, ctx) => {
+            const reqCtx = ctxFor(ctx);
+            return projectSync(() => cs.updateContentStandards(params, reqCtx), r => r);
+        };
+        handlers.calibrateContent = async (params, ctx) => {
+            const reqCtx = ctxFor(ctx);
+            return projectSync(() => cs.calibrateContent(params, reqCtx), r => r);
+        };
+        handlers.validateContentDelivery = async (params, ctx) => {
+            const reqCtx = ctxFor(ctx);
+            return projectSync(() => cs.validateContentDelivery(params, reqCtx), r => r);
+        };
+        if (cs.getMediaBuyArtifacts) {
+            handlers.getMediaBuyArtifacts = async (params, ctx) => {
+                const reqCtx = ctxFor(ctx);
+                return projectSync(() => cs.getMediaBuyArtifacts(params, reqCtx), r => r);
+            };
+        }
+        if (cs.getCreativeFeatures) {
+            handlers.getCreativeFeatures = async (params, ctx) => {
+                const reqCtx = ctxFor(ctx);
+                return projectSync(() => cs.getCreativeFeatures(params, reqCtx), r => r);
+            };
+        }
+    }
+    return handlers;
+}
+function buildAccountHandlers(platform, ctxFor) {
+    const accounts = platform.accounts;
+    // Only emit framework-derived handlers for methods the platform actually
+    // implements. Emitting an UNSUPPORTED_FEATURE stub for an undefined
+    // method shadows adopter-supplied `opts.accounts.{syncAccounts,listAccounts}`
+    // fillers under the merge seam (platform-derived wins per-key), so the
+    // adopter's working handler silently never runs. This pattern matches the
+    // gating already used for `reportUsage` / `getAccountFinancials` below.
+    // Adopters who claim sync_accounts / list_accounts capability without
+    // implementing `accounts.upsert` / `accounts.list` AND without supplying a
+    // merge-seam override get framework's "tool not registered" path —
+    // closer to the truth than a fabricated UNSUPPORTED_FEATURE envelope.
+    const handlers = {};
+    if (accounts.upsert) {
+        handlers.syncAccounts = async (params, _ctx) => {
+            const refs = (params.accounts ?? []);
+            return projectSync(() => accounts.upsert(refs), rows => ({ accounts: rows }));
+        };
+    }
+    if (accounts.list) {
+        handlers.listAccounts = async (params, _ctx) => {
+            const filter = params;
+            // Wrap in projectSync so adopter `throw new AdcpError('PERMISSION_DENIED', ...)`
+            // from the list impl projects to the structured wire envelope rather
+            // than falling through to the framework's `SERVICE_UNAVAILABLE` mapping.
+            return projectSync(() => accounts.list(filter), page => ({
+                accounts: page.items.map(account_1.toWireAccount),
+                ...(page.nextCursor != null && { next_cursor: page.nextCursor }),
+            }));
+        };
+    }
+    if (accounts.reportUsage) {
+        handlers.reportUsage = async (params, ctx) => {
+            const resolveCtx = {
+                ...(ctx.authInfo !== undefined && { authInfo: ctx.authInfo }),
+                toolName: 'report_usage',
+            };
+            return projectSync(() => accounts.reportUsage(params, resolveCtx), r => r);
+        };
+    }
+    if (accounts.getAccountFinancials) {
+        handlers.getAccountFinancials = async (params, ctx) => {
+            const resolveCtx = {
+                ...(ctx.authInfo !== undefined && { authInfo: ctx.authInfo }),
+                toolName: 'get_account_financials',
+            };
+            return projectSync(() => accounts.getAccountFinancials(params, resolveCtx), r => r);
+        };
+    }
+    return handlers;
+}
+//# sourceMappingURL=from-platform.js.map