@adcp/sdk 6.10.0 → 6.12.0

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

@@ -58,6 +58,7 @@ 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 proposal_1 = require("../proposal");
 const errors_1 = require("../../errors");
 const validate_platform_1 = require("./validate-platform");
 const validate_specialisms_1 = require("../validate-specialisms");
@@ -617,7 +618,7 @@ function createAdcpServerFromPlatform(platform, opts) {
         mediaBuy: mergeHandlers(opts.mediaBuy, buildMediaBuyHandlers(platform, taskRegistry, taskWebhookEmit, observability, fwLogger, {
             allowPrivateWebhookUrls: opts.allowPrivateWebhookUrls === true,
             autoEmitCompletionWebhooks: opts.autoEmitCompletionWebhooks !== false,
-        }, ctxFor, effectiveCtxMetadata, opts.mediaBuyStore), 'mediaBuy', mergeOpts),
+        }, ctxFor, effectiveCtxMetadata, opts.mediaBuyStore, opts.proposalStore), 'mediaBuy', mergeOpts),
         creative: mergeHandlers(opts.creative, buildCreativeHandlers(platform, taskRegistry, taskWebhookEmit, observability, fwLogger, {
             allowPrivateWebhookUrls: opts.allowPrivateWebhookUrls === true,
             autoEmitCompletionWebhooks: opts.autoEmitCompletionWebhooks !== false,
@@ -1367,8 +1368,18 @@ async function projectSync(fn, mapResult, refresh) {
         // 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.
+        //
+        // implementation_config strip: same pattern. Recipes ride on
+        // Product.implementation_config server-side (typed contract between
+        // ProposalManager and DecisioningPlatform via ctx.recipes) but are
+        // opaque-to-buyer. The wire schema is `additionalProperties: true`
+        // so the field is technically legal — but recipes carry upstream
+        // identifiers (network codes, line-item template ids, ad-unit ids,
+        // GAM line-item priority) that leak topology to buyers. Strip
+        // before the response leaves the dispatcher.
         if (wire != null && typeof wire === 'object') {
             (0, ctx_metadata_1.stripCtxMetadata)(wire);
+            (0, ctx_metadata_1.stripImplementationConfig)(wire);
         }
         return wire;
     }
@@ -1415,18 +1426,19 @@ async function projectSync(fn, mapResult, refresh) {
  */
 async function routeIfHandoff(taskRegistry, opts, result, project) {
     if ((0, async_outcome_2.isTaskHandoff)(result)) {
-        const taskFn = (0, async_outcome_2._extractTaskFn)(result);
-        if (!taskFn) {
+        const entry = (0, async_outcome_2._extractHandoffEntry)(result);
+        if (!entry) {
             // 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 await project(result);
         }
+        const { fn: taskFn, options } = entry;
         return dispatchHitl(taskRegistry, opts, async (taskId) => {
             const inner = await taskFn((0, to_context_1.buildHandoffContext)(taskRegistry, taskId));
             return await project(inner);
-        });
+        }, options?.task_id);
     }
     // Catch the most common LLM-scaffolded mistake: hand-rolling a
     // `{status: 'submitted', task_id: '...'}` envelope instead of returning
@@ -1524,12 +1536,13 @@ async function emitSyncCompletionWebhook(opts, result) {
         }, 'onWebhookEmit', opts.logger);
     }
 }
-async function dispatchHitl(taskRegistry, opts, taskFn) {
+async function dispatchHitl(taskRegistry, opts, taskFn, overrideTaskId) {
     const createStart = Date.now();
     const { taskId } = await taskRegistry.create({
         tool: opts.tool,
         accountId: opts.accountId,
         hasWebhook: opts.pushNotificationUrl !== undefined,
+        ...(overrideTaskId !== undefined && { overrideTaskId }),
     });
     safeFire(opts.observability?.onTaskCreate, {
         tool: opts.tool,
@@ -1570,7 +1583,18 @@ async function dispatchHitl(taskRegistry, opts, taskFn) {
             taskFnError = err;
         }
         if (taskFnError === undefined) {
-            // Success path
+            // Success path. Strip wire-only-server fields BEFORE the registry
+            // write so every downstream consumer (tasks/get polling at
+            // line 1826, emitTaskWebhook below at line 2493, idempotency
+            // replays of the Submitted envelope) inherits a clean payload.
+            // Mirrors the same chokepoint pattern projectSync uses for the
+            // sync arm. Without this strip, ctx_metadata + implementation_config
+            // ride to the buyer via the HITL completion path even though the
+            // sync path is clean — surfaced by security review on PR #1562.
+            if (result != null && typeof result === 'object') {
+                (0, ctx_metadata_1.stripCtxMetadata)(result);
+                (0, ctx_metadata_1.stripImplementationConfig)(result);
+            }
             try {
                 await taskRegistry.complete(taskId, result);
             }
@@ -2391,9 +2415,11 @@ function validatePushNotificationToken(token) {
     }
     return { ok: true };
 }
-function buildMediaBuyHandlers(platform, taskRegistry, taskWebhookEmit, observability, logger, pushOpts, ctxFor, ctxMetadataStore, mediaBuyStore) {
+function buildMediaBuyHandlers(platform, taskRegistry, taskWebhookEmit, observability, logger, pushOpts, ctxFor, ctxMetadataStore, mediaBuyStore, proposalStore) {
     const sales = platform.sales;
-    if (!sales)
+    const proposalManager = platform.proposalManager;
+    // Without sales AND without a proposal manager, there's nothing to dispatch.
+    if (!sales && !proposalManager)
         return undefined;
     // Core lifecycle methods are optional on the SalesPlatform interface
     // (#1341) — the per-specialism mapping in `RequiredPlatformsFor<S>`
@@ -2405,21 +2431,97 @@ function buildMediaBuyHandlers(platform, taskRegistry, taskWebhookEmit, observab
     // (`opts.mediaBuy.X`) can supply it OR the framework returns
     // `METHOD_NOT_FOUND` from `tools/list` for the unsupported tool.
     return {
-        ...(sales.getProducts && {
+        ...((sales?.getProducts || proposalManager) && {
             getProducts: async (params, ctx) => {
                 const reqCtx = ctxFor(ctx);
+                // v1.5 seam: intercept refine[i].action='finalize' before
+                // dispatching to the manager / sales. When the framework
+                // commits the proposal inline, project the response directly.
+                if (proposalManager && proposalStore) {
+                    const intercept = await (0, proposal_1.maybeInterceptFinalize)({
+                        request: params,
+                        manager: proposalManager,
+                        store: proposalStore,
+                        ctx: reqCtx,
+                    });
+                    if (intercept.kind === 'intercepted') {
+                        // Unified sync-or-HITL dispatch. routeIfHandoff runs
+                        // `intercept.project` inline for sync `FinalizeProposalSuccess`
+                        // returns and inside the background task for HITL handoffs.
+                        // Same machinery createMediaBuy / syncCreatives use — finalize
+                        // inherits the framework's task-lifecycle guarantees.
+                        //
+                        // **Known gap (HITL only)**: if the buyer calls tasks/cancel
+                        // while the adopter's handoff fn is still mid-run, the
+                        // framework marks the task cancelled but `intercept.project`
+                        // (which fires when the handoff fn resolves) still runs
+                        // store.commit. The committed proposal then sits in the
+                        // store with no buyer-facing task to retrieve it. Same gap
+                        // exists for createMediaBuy HITL today (see comment in
+                        // `sales.createMediaBuy` body re: CONSUMING reservation
+                        // cleanup). Mitigations: the proposal expires via the
+                        // 7-day eviction window in `InMemoryProposalStore`, and
+                        // production durable stores can implement a sweep against
+                        // the task registry to release stale committed-but-
+                        // unretrievable proposals. Closing the gap end-to-end
+                        // requires propagating an AbortSignal into the projection
+                        // — framework-level work tracked separately, not finalize-
+                        // specific.
+                        const push = extractPushConfig(params, logger, {
+                            allowPrivateWebhookUrls: pushOpts.allowPrivateWebhookUrls,
+                        });
+                        const out = await routeIfHandoff(taskRegistry, {
+                            tool: 'get_products',
+                            accountId: reqCtx.account.id,
+                            pushNotificationUrl: push.url,
+                            pushNotificationToken: push.token,
+                            emitWebhook: taskWebhookEmit ?? ctx.emitWebhook,
+                            autoEmitCompletion: pushOpts.autoEmitCompletionWebhooks,
+                            observability,
+                            logger,
+                        }, intercept.result, intercept.project);
+                        return out;
+                    }
+                }
                 return projectSync(async () => {
-                    const result = await sales.getProducts(params, reqCtx);
+                    // Pick dispatch target: ProposalManager (when wired) takes
+                    // ownership of get_products; sales is the v1 fallback.
+                    // Refine routing per Python's _select_proposal_method:
+                    // refine_products iff buying_mode='refine' AND
+                    // capabilities.refine AND the manager implements it.
+                    let result;
+                    if (proposalManager) {
+                        const buyingMode = params.buying_mode;
+                        const useRefine = buyingMode === 'refine' &&
+                            proposalManager.capabilities.refine === true &&
+                            typeof proposalManager.refineProducts === 'function';
+                        result = useRefine
+                            ? await proposalManager.refineProducts(params, reqCtx)
+                            : await proposalManager.getProducts(params, reqCtx);
+                    }
+                    else {
+                        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);
+                    // v1.5 seam: persist proposals[] as DRAFT records (with
+                    // typed recipes pulled from Product.implementation_config)
+                    // so subsequent finalize / create_media_buy can hydrate.
+                    if (proposalStore) {
+                        await (0, proposal_1.maybePersistDraftAfterGetProducts)({
+                            response: result,
+                            store: proposalStore,
+                            ctx: reqCtx,
+                        });
+                    }
                     return result;
                 }, r => r);
             },
         }),
-        ...(sales.createMediaBuy && {
+        ...(sales?.createMediaBuy && {
             createMediaBuy: async (params, ctx) => {
                 const reqCtx = ctxFor(ctx);
                 // Auto-hydrate: walk `params.packages`, attach the full Product object
@@ -2427,11 +2529,59 @@ function buildMediaBuyHandlers(platform, taskRegistry, taskWebhookEmit, observab
                 // `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);
+                // v1.5 seam: when the request carries a proposal_id, reserve
+                // the proposal (atomic CAS COMMITTED → CONSUMING), validate
+                // expiry + capability overlap, hydrate ctx.recipes. The
+                // adapter runs against the reservation; finalize_consumption
+                // (success) or release_consumption (failure) closes it out.
+                let reservation = null;
+                if (proposalStore) {
+                    reservation = await (0, proposal_1.maybeReserveProposalForCreateMediaBuy)({
+                        request: params,
+                        manager: proposalManager,
+                        store: proposalStore,
+                        ctx: reqCtx,
+                    });
+                    if (reservation) {
+                        reqCtx.recipes = reservation.recipes;
+                    }
+                }
                 return projectSync(async () => {
                     const push = extractPushConfig(params, logger, {
                         allowPrivateWebhookUrls: pushOpts.allowPrivateWebhookUrls,
                     });
-                    const result = await sales.createMediaBuy(params, reqCtx);
+                    let result;
+                    try {
+                        result = await sales.createMediaBuy(params, reqCtx);
+                    }
+                    catch (err) {
+                        // Adapter rejected — roll back the reservation so the buyer
+                        // can retry without PROPOSAL_NOT_COMMITTED blocking them.
+                        if (reservation && proposalStore) {
+                            await (0, proposal_1.releaseProposalReservation)({
+                                store: proposalStore,
+                                record: reservation,
+                                logger,
+                            });
+                        }
+                        throw err;
+                    }
+                    // Inline-success path: promote CONSUMING → CONSUMED with the
+                    // adapter's media_buy_id. HITL handoff: the proposal stays
+                    // CONSUMING until the handoff completes — wiring the
+                    // post-completion commit hook is a v1.6 follow-up; for now
+                    // adopters using HITL accept the reservation lingers until
+                    // eviction. Most adopters use inline create_media_buy.
+                    if (reservation && proposalStore && !(0, async_outcome_2.isTaskHandoff)(result)) {
+                        const mediaBuyId = result.media_buy_id;
+                        if (mediaBuyId) {
+                            await (0, proposal_1.finalizeProposalConsumption)({
+                                store: proposalStore,
+                                record: reservation,
+                                mediaBuyId,
+                            });
+                        }
+                    }
                     return routeIfHandoff(taskRegistry, {
                         tool: 'create_media_buy',
                         accountId: reqCtx.account.id,
@@ -2448,7 +2598,7 @@ function buildMediaBuyHandlers(platform, taskRegistry, taskWebhookEmit, observab
                 }, r => r);
             },
         }),
-        ...(sales.updateMediaBuy && {
+        ...(sales?.updateMediaBuy && {
             updateMediaBuy: async (params, ctx) => {
                 const reqCtx = ctxFor(ctx);
                 // `media_buy_id` is required on the wire schema, but `validation: 'off'`
@@ -2467,6 +2617,21 @@ function buildMediaBuyHandlers(platform, taskRegistry, taskWebhookEmit, observab
                 // directly — no separate lookup. Misses are silent; publisher falls
                 // back to its own DB. Schema-driven via `x-entity` (#1109).
                 await hydrateForTool(ctxMetadataStore, reqCtx.account?.id, 'update_media_buy', params, logger);
+                // v1.5 seam: hydrate ctx.recipes via reverse-index so the adapter's
+                // updateMediaBuy can apply the same recipe that drove createMediaBuy.
+                // Re-validates capability overlap on any packages-shaped patch
+                // (Resolutions §5).
+                if (proposalStore) {
+                    const record = await (0, proposal_1.maybeHydrateRecipesForMediaBuyId)({
+                        mediaBuyId: media_buy_id,
+                        store: proposalStore,
+                        ctx: reqCtx,
+                        packages: params.packages,
+                    });
+                    if (record) {
+                        reqCtx.recipes = record.recipes;
+                    }
+                }
                 return projectSync(async () => {
                     const push = extractPushConfig(params, logger, {
                         allowPrivateWebhookUrls: pushOpts.allowPrivateWebhookUrls,
@@ -2509,7 +2674,7 @@ function buildMediaBuyHandlers(platform, taskRegistry, taskWebhookEmit, observab
         syncCreatives: async (params, ctx) => {
             const reqCtx = ctxFor(ctx);
             const creatives = params.creatives ?? [];
-            if (!sales.syncCreatives) {
+            if (!sales?.syncCreatives) {
                 return (0, errors_1.adcpError)('UNSUPPORTED_FEATURE', {
                     message: 'sync_creatives not supported by this sales platform',
                 });
@@ -2529,9 +2694,29 @@ function buildMediaBuyHandlers(platform, taskRegistry, taskWebhookEmit, observab
                 }, result, rows => ({ creatives: rows.map(normalizeRowErrors) }));
             }, r => r);
         },
-        ...(sales.getMediaBuyDelivery && {
+        ...(sales?.getMediaBuyDelivery && {
             getMediaBuyDelivery: async (params, ctx) => {
                 const reqCtx = ctxFor(ctx);
+                // v1.5 seam: hydrate ctx.recipes for delivery reads. Per
+                // Resolutions §5, recipe-driven delivery aggregation needs the
+                // same recipe view the originating createMediaBuy used.
+                if (proposalStore) {
+                    const ids = params.media_buy_ids;
+                    // The wire shape uses `media_buy_ids[]`; hydrate from the first id
+                    // when present (per-buy recipe lookup; if buyer queries multiple
+                    // ids, the adapter is responsible for per-id recipe routing).
+                    const firstId = Array.isArray(ids) && ids.length > 0 ? ids[0] : undefined;
+                    if (firstId) {
+                        const record = await (0, proposal_1.maybeHydrateRecipesForMediaBuyId)({
+                            mediaBuyId: firstId,
+                            store: proposalStore,
+                            ctx: reqCtx,
+                        });
+                        if (record) {
+                            reqCtx.recipes = record.recipes;
+                        }
+                    }
+                }
                 return projectSync(async () => {
                     const result = await sales.getMediaBuyDelivery(params, reqCtx);
                     warnIfTruncatedMultiIdResponse('getMediaBuyDelivery', 'media_buy_ids', params.media_buy_ids, result?.media_buy_deliveries, logger);
@@ -2552,7 +2737,7 @@ function buildMediaBuyHandlers(platform, taskRegistry, taskWebhookEmit, observab
         // 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 && {
+        ...(sales?.getMediaBuys && {
             getMediaBuys: async (params, ctx) => {
                 const reqCtx = ctxFor(ctx);
                 return projectSync(async () => {
@@ -2564,7 +2749,7 @@ function buildMediaBuyHandlers(platform, taskRegistry, taskWebhookEmit, observab
                 }, r => r);
             },
         }),
-        ...(sales.providePerformanceFeedback && {
+        ...(sales?.providePerformanceFeedback && {
             providePerformanceFeedback: async (params, ctx) => {
                 const reqCtx = ctxFor(ctx);
                 // Auto-hydrate `req.media_buy` from the prior createMediaBuy /
@@ -2579,13 +2764,13 @@ function buildMediaBuyHandlers(platform, taskRegistry, taskWebhookEmit, observab
                 return projectSync(() => sales.providePerformanceFeedback(params, reqCtx), r => r);
             },
         }),
-        ...(sales.listCreativeFormats && {
+        ...(sales?.listCreativeFormats && {
             listCreativeFormats: async (params, ctx) => {
                 const reqCtx = ctxFor(ctx);
                 return projectSync(() => sales.listCreativeFormats(params, reqCtx), r => r);
             },
         }),
-        ...(sales.listCreatives && {
+        ...(sales?.listCreatives && {
             listCreatives: async (params, ctx) => {
                 const reqCtx = ctxFor(ctx);
                 return projectSync(async () => {