@adcp/sdk 14.0.0-rc.38 → 14.0.0-rc.39

package/dist/lib/server/media-buy-action-resolver.mjs

@@ -0,0 +1,285 @@
+import { ADCP_VERSION } from "../version.mjs";
+import {
+  actionAllowedStatuses,
+  changeTermIssues,
+  defaultMediaBuyActionTask,
+  productTemplateIssues,
+  slaWithin,
+  elapsedDuration,
+  findProductAction,
+  legacyActionSupported,
+  supportsRc3Actions,
+  supportsChangeTermIdentity,
+  packageActionStatus
+} from "../media-buy/action-contracts.mjs";
+import { assessActionAvailability } from "../media-buy/action-assessment.mjs";
+import { decomposeUpdateMediaBuy } from "../media-buy/mutations.mjs";
+const mediaBuyActionResolver = {
+  /**
+   * Explicitly accept complete binding terms selected by the seller from all
+   * affected product templates. Nothing is materialized from a product alone.
+   * Omitting sellerAccepted or supplying false throws, including for JS callers.
+   */
+  materialize(input) {
+    if (input.sellerAccepted !== true)
+      throw new TypeError("Explicit seller acceptance is required to materialize binding change terms.");
+    const issues = changeTermIssues(input.acceptedTerms, input.currency);
+    for (const product of input.products)
+      issues.push(...productTemplateIssues(product.allowed_actions ?? [], input.currency));
+    if (!input.products.length) issues.push("Every affected product must be supplied.");
+    if (issues.length) throw new TypeError(issues.join("; "));
+    const materialized = structuredClone([...input.acceptedTerms]);
+    for (const term of materialized) {
+      const templates = input.products.map((product) => findProductAction(product.allowed_actions, term.action));
+      const constraints = templates.find((t) => t?.constraints)?.constraints;
+      const sla = templates.find((t) => t?.sla)?.sla;
+      if (term.constraints === void 0 && constraints !== void 0) term.constraints = structuredClone(constraints);
+      if (term.processing_sla === void 0 && sla !== void 0) term.processing_sla = structuredClone(sla);
+      if (!term.allowed_statuses && templates.some((t) => t?.allowed_statuses)) {
+        term.allowed_statuses = actionAllowedStatuses(term).filter(
+          (status) => templates.every((t) => !t?.allowed_statuses || t.allowed_statuses.includes(status))
+        );
+      }
+      const reference = templates[0]?.terms_ref;
+      if (reference && templates.every((t) => t?.terms_ref === reference)) term.terms_ref ??= reference;
+      for (const product of input.products) {
+        const template = findProductAction(product.allowed_actions, term.action);
+        if (!template || !template.modes.includes(term.service_mode) || !slaWithin(template.sla, term.processing_sla)) {
+          issues.push("Accepted terms exceed product template.");
+          continue;
+        }
+        if (template.allowed_statuses && actionAllowedStatuses(term).some((s) => !template.allowed_statuses.includes(s)))
+          issues.push("Accepted status scope exceeds product template.");
+        if (template.constraints && !constraintsWithin(template.constraints, term.constraints))
+          issues.push("Materialized constraints must retain the product bound.");
+      }
+    }
+    issues.push(...changeTermIssues(materialized, input.currency));
+    if (issues.length) throw new TypeError(issues.join("; "));
+    return materialized;
+  },
+  resolve(input) {
+    const terms = input.buy.accepted_proposal?.commercial_terms?.change_terms ?? [];
+    const currency = typeof input.buy.total_budget === "object" ? input.buy.total_budget?.currency : input.buy.currency;
+    const issues = changeTermIssues(terms, currency);
+    for (const product of input.productPolicy ?? [])
+      issues.push(...productTemplateIssues(product.allowed_actions ?? [], currency));
+    if (issues.length) throw new TypeError(issues.join("; "));
+    const available_actions = [], unavailable = [], request_assessments = [];
+    const requestedActions = input.request ? decomposeUpdateMediaBuy(input.buy, input.request).actions : [];
+    for (const original of terms) {
+      const term = structuredClone(original);
+      const decision = input.decide(structuredClone(term));
+      const blocked = (message, unknown = false) => unavailable.push({
+        status: "currently_unavailable",
+        action: term.action,
+        reason: "condition_unresolved",
+        certainty: unknown ? "unknown" : "blocked",
+        message
+      });
+      if (decision.authorization !== true || decision.governance !== true || decision.policy !== true) {
+        blocked(
+          "Seller authorization, governance, and policy must all admit the action.",
+          [decision.authorization, decision.governance, decision.policy].includes("unknown")
+        );
+        continue;
+      }
+      if (term.conditions?.length && decision.conditionsSatisfied !== true) {
+        blocked("Seller conditions are unresolved.", true);
+        continue;
+      }
+      let productBlocked = false;
+      for (const product of input.productPolicy ?? []) {
+        const template = findProductAction(product.allowed_actions, term.action);
+        if (!template || !template.modes.includes(term.service_mode) || !slaWithin(template.sla, decision.sla ?? term.processing_sla) || template.allowed_statuses && !template.allowed_statuses.includes(input.buy.status)) {
+          productBlocked = true;
+          break;
+        }
+        if (template.constraints && !constraintsWithin(template.constraints, term.constraints)) productBlocked = true;
+      }
+      if (productBlocked) {
+        unavailable.push({
+          status: "currently_unavailable",
+          action: term.action,
+          reason: "not_supported_on_product",
+          certainty: "blocked",
+          message: "Not every affected product currently admits this accepted action."
+        });
+        continue;
+      }
+      if (input.wireVersion !== "3.1" && !supportsChangeTermIdentity(input.adcpVersion ?? ADCP_VERSION)) {
+        blocked("Accepted change-term links require a beta.9-or-newer served schema.", true);
+        continue;
+      }
+      if (!supportsRc3Actions(input.adcpVersion ?? ADCP_VERSION) && (term.action === "update_media_buy_frequency_cap" || decision.applicable_package_ids !== void 0)) {
+        blocked("This action or package scope requires an rc.3-or-newer served schema.", true);
+        continue;
+      }
+      const entry = {
+        action: term.action,
+        mode: term.service_mode,
+        task: decision.task ?? defaultMediaBuyActionTask(term.action),
+        change_term_id: term.term_id,
+        ...decision.applicable_package_ids && { applicable_package_ids: [...decision.applicable_package_ids] },
+        ...term.processing_sla && { sla: structuredClone(term.processing_sla) },
+        ...decision.sla && { sla: structuredClone(decision.sla) }
+      };
+      if (decision.applicable_package_ids !== void 0 && (!decision.applicable_package_ids.length || new Set(decision.applicable_package_ids).size !== decision.applicable_package_ids.length || decision.applicable_package_ids.some(
+        (id) => typeof id !== "string" || !id || !input.buy.packages?.some((p) => p.package_id === id)
+      ))) {
+        blocked("Invalid or unknown package scope.", true);
+        continue;
+      }
+      if (["pause", "resume"].includes(term.action) && entry.applicable_package_ids) {
+        const eligible = entry.applicable_package_ids.filter((id) => {
+          const status = packageActionStatus(input.buy.packages?.find((p) => p.package_id === id));
+          return status !== void 0 && actionAllowedStatuses({ action: term.action }).includes(
+            status
+          );
+        });
+        if (eligible.length) entry.applicable_package_ids = eligible;
+      }
+      if (input.wireVersion === "3.1" && (!legacyActionSupported(term.action) || decision.applicable_package_ids !== void 0)) {
+        blocked("This right cannot be represented safely in the requested legacy projection.", true);
+        continue;
+      }
+      const evaluatedTerm = { ...term };
+      delete evaluatedTerm.conditions;
+      const evaluatedBuy = {
+        ...input.buy,
+        accepted_proposal: { ...input.buy.accepted_proposal, commercial_terms: { change_terms: [evaluatedTerm] } },
+        available_actions: [entry]
+      };
+      if (input.request && requestedActions.some((a) => a.action === term.action))
+        request_assessments.push(
+          structuredClone(
+            assessActionAvailability(evaluatedBuy, term.action, { request: input.request, now: input.now })
+          )
+        );
+      const constraint = evaluatedTerm.constraints;
+      const hasTimingGate = constraint?.kind === "effective_timing" && (constraint.earliest_effective_at !== void 0 || constraint.latest_effective_at !== void 0);
+      if (!hasTimingGate) delete evaluatedTerm.constraints;
+      else
+        evaluatedTerm.constraints = {
+          kind: "effective_timing",
+          ...constraint.earliest_effective_at !== void 0 && {
+            earliest_effective_at: constraint.earliest_effective_at
+          },
+          ...constraint.latest_effective_at !== void 0 && { latest_effective_at: constraint.latest_effective_at }
+        };
+      const packageLifecycleRequest = ["pause", "resume"].includes(term.action) && entry.applicable_package_ids ? {
+        packages: entry.applicable_package_ids.map((package_id) => ({
+          package_id,
+          paused: term.action === "pause"
+        }))
+      } : void 0;
+      evaluatedBuy.available_actions = [
+        { ...entry, ...packageLifecycleRequest ? {} : { applicable_package_ids: void 0 } }
+      ];
+      const result = assessActionAvailability(evaluatedBuy, term.action, {
+        request: packageLifecycleRequest ?? (hasTimingGate ? {} : void 0),
+        now: input.now
+      });
+      if (result.status !== "available_now") {
+        unavailable.push(result);
+        continue;
+      }
+      if (input.wireVersion === "3.1") {
+        const legacy = {
+          ...entry,
+          terms_ref: term.term_id,
+          mode: term.service_mode === "seller_managed" ? "requires_approval" : term.service_mode
+        };
+        delete legacy.change_term_id;
+        delete legacy.task;
+        available_actions.push(legacy);
+      } else available_actions.push({ ...entry, ...input.emitTermsRefAlias && { terms_ref: term.term_id } });
+    }
+    const metadata = input.metadata?.update_name;
+    if (metadata) {
+      const entry = {
+        action: "update_name",
+        mode: "self_serve",
+        task: metadata.task ?? "control_media_buy",
+        ...metadata.sla && { sla: structuredClone(metadata.sla) }
+      };
+      const result = assessActionAvailability({ ...input.buy, available_actions: [entry] }, "update_name", {
+        adcpVersion: input.adcpVersion ?? ADCP_VERSION
+      });
+      if (metadata.authorization === true && metadata.governance === true && metadata.policy === true && metadata.applicable_package_ids === void 0 && (input.productPolicy ?? []).every((p) => {
+        const template = findProductAction(p.allowed_actions, "update_name");
+        return template?.modes.includes("self_serve") && (!template.allowed_statuses || template.allowed_statuses.includes(input.buy.status)) && slaWithin(template.sla, entry.sla);
+      }) && result.status === "available_now") {
+        if (input.wireVersion !== "3.1") available_actions.push(entry);
+        else
+          unavailable.push({
+            status: "currently_unavailable",
+            action: "update_name",
+            reason: "not_supported_on_buy",
+            certainty: "blocked",
+            message: "Naming is not in the 3.1.19 action vocabulary."
+          });
+      } else
+        unavailable.push(
+          result.status === "currently_unavailable" ? result : {
+            status: "currently_unavailable",
+            action: "update_name",
+            reason: "condition_unresolved",
+            certainty: "unknown",
+            message: "Explicit seller metadata gates must all admit this action."
+          }
+        );
+    }
+    return {
+      available_actions,
+      unavailable,
+      ...input.request && {
+        request_assessments: requestedActions.map(
+          ({ action }) => structuredClone(
+            request_assessments.find((assessment) => assessment.action === action) ?? unavailable.find((assessment) => assessment.action === action) ?? assessActionAvailability({ ...input.buy, available_actions }, action, {
+              request: input.request,
+              now: input.now,
+              adcpVersion: input.adcpVersion ?? ADCP_VERSION
+            })
+          )
+        )
+      }
+    };
+  }
+};
+function sameData(a, b) {
+  if (a === b) return true;
+  if (!a || !b || typeof a !== "object" || typeof b !== "object" || Array.isArray(a) !== Array.isArray(b)) return false;
+  const left = Object.keys(a), right = Object.keys(b);
+  return left.length === right.length && left.every(
+    (k) => Object.hasOwn(b, k) && sameData(a[k], b[k])
+  );
+}
+function constraintsWithin(ceiling, candidate) {
+  if (sameData(ceiling, candidate)) return true;
+  if (!ceiling || !candidate || typeof ceiling !== "object" || typeof candidate !== "object") return false;
+  const a = ceiling, b = candidate;
+  if (a.kind !== b.kind) return false;
+  return Object.keys(a).filter((key) => key !== "kind").every((key) => {
+    if (sameData(a[key], b[key])) return true;
+    if (b[key] === void 0) return false;
+    const minimum = key.startsWith("min_") || key === "minimum_notice" || key.startsWith("earliest_");
+    let left = a[key], right = b[key];
+    if (key.endsWith("_amount")) {
+      const x = left, y = right;
+      if (x.currency !== y.currency) return false;
+      left = x.amount;
+      right = y.amount;
+    } else if (key === "max_change" || key === "minimum_notice") {
+      left = elapsedDuration(left);
+      right = elapsedDuration(right);
+    } else if (key.startsWith("earliest_") || key.startsWith("latest_")) {
+      left = Date.parse(String(left));
+      right = Date.parse(String(right));
+    }
+    return typeof left === "number" && Number.isFinite(left) && typeof right === "number" && Number.isFinite(right) && (minimum ? right >= left : right <= left);
+  });
+}
+export {
+  mediaBuyActionResolver
+};

package/dist/lib/server/media-buy-actions.d.mts

@@ -1,13 +1,12 @@
-/**
- * Server/adopter helpers for enforcing the update_media_buy action surface.
- *
- * The media-buy module owns pure decomposition and preflight. This wrapper
- * converts denied preflights into the canonical server-side `AdcpError` shape
- * so DecisioningPlatform implementations can reject unavailable mutations
- * without hand-building ACTION_NOT_ALLOWED envelopes.
- */
 import { type ActionNotAllowedReason, type MediaBuyActionContext, type MediaBuyActionMode, type PreflightAllowed, type PreflightDenied, type PreflightDenial, type UpdateMediaBuyRequestLike } from '../media-buy/index.mjs';
 export interface AssertUpdateMediaBuyAllowedOptions {
+    /** Exact error-details schema version; defaults to the SDK pin. */
+    adcpVersion?: string;
+    /** Defaults to update_media_buy compatibility. Compact handlers must pass their own task explicitly. */
+    task?: import('../media-buy/action-types.mjs').MediaBuyTask;
+    proposal?: import('../media-buy/action-types.mjs').ActionProposal;
+    termsRefIsAlias?: boolean;
+    now?: number;
     /**
      * Restrict the modes this call path may execute directly. Omit to enforce
      * availability only. Pass `['self_serve']` when the handler cannot queue

package/dist/lib/server/media-buy-actions.d.ts

@@ -1,13 +1,12 @@
-/**
- * Server/adopter helpers for enforcing the update_media_buy action surface.
- *
- * The media-buy module owns pure decomposition and preflight. This wrapper
- * converts denied preflights into the canonical server-side `AdcpError` shape
- * so DecisioningPlatform implementations can reject unavailable mutations
- * without hand-building ACTION_NOT_ALLOWED envelopes.
- */
 import { type ActionNotAllowedReason, type MediaBuyActionContext, type MediaBuyActionMode, type PreflightAllowed, type PreflightDenied, type PreflightDenial, type UpdateMediaBuyRequestLike } from '../media-buy';
 export interface AssertUpdateMediaBuyAllowedOptions {
+    /** Exact error-details schema version; defaults to the SDK pin. */
+    adcpVersion?: string;
+    /** Defaults to update_media_buy compatibility. Compact handlers must pass their own task explicitly. */
+    task?: import('../media-buy/action-types').MediaBuyTask;
+    proposal?: import('../media-buy/action-types').ActionProposal;
+    termsRefIsAlias?: boolean;
+    now?: number;
     /**
      * Restrict the modes this call path may execute directly. Omit to enforce
      * availability only. Pass `['self_serve']` when the handler cannot queue

package/dist/lib/server/media-buy-actions.js

@@ -21,13 +21,21 @@ __export(media_buy_actions_exports, {
   assertUpdateMediaBuyAllowed: () => assertUpdateMediaBuyAllowed
 });
 module.exports = __toCommonJS(media_buy_actions_exports);
+var import_version = require('../version.js');
+var import_action_contracts = require('../media-buy/action-contracts.js');
 var import_errors = require('../errors/index.js');
 var import_media_buy = require('../media-buy/index.js');
 var import_async_outcome = require('./decisioning/async-outcome.js');
 function assertUpdateMediaBuyAllowed(currentBuy, request, options = {}) {
   let result;
   try {
-    result = (0, import_media_buy.preflightUpdateMediaBuy)(currentBuy, request);
+    result = (0, import_media_buy.preflightUpdateMediaBuy)(currentBuy, request, {
+      task: options.task ?? "update_media_buy",
+      proposal: options.proposal,
+      termsRefIsAlias: options.termsRefIsAlias,
+      now: options.now,
+      adcpVersion: options.adcpVersion ?? import_version.ADCP_VERSION
+    });
   } catch (err) {
     if (err instanceof import_errors.ValidationError) {
       throw new import_async_outcome.AdcpError("INVALID_REQUEST", {
@@ -39,15 +47,47 @@ function assertUpdateMediaBuyAllowed(currentBuy, request, options = {}) {
     throw err;
   }
   const currentlyAvailable = (0, import_media_buy.getAvailableActions)(currentBuy, { silent: true }).actions;
-  if (!result.ok) {
-    throw actionNotAllowedFromDenied(result, currentlyAvailable, options);
+  if (result.ok) {
+    const mismatch = result.matched.find(
+      (entry) => options.task !== void 0 && options.task !== "update_media_buy" && (entry.task ?? "update_media_buy") !== options.task
+    );
+    if (mismatch) throw actionNotAllowed(mismatch.action, "mode_mismatch", currentlyAvailable, options.adcpVersion);
+  }
+  if (!result.ok && result.denials.some((d) => !d.assessment?.code && d.reason !== "mode_mismatch"))
+    throw actionNotAllowedFromDenied(
+      { ...result, denials: result.denials.filter((d) => !d.assessment?.code && d.reason !== "mode_mismatch") },
+      currentlyAvailable,
+      options
+    );
+  if (options.allowedModes?.length) {
+    const requested = result.ok ? result.actions : result.mutations;
+    const mismatch = requested.find(({ action }) => {
+      const entry = (0, import_media_buy.findAvailableAction)(currentBuy, action, { silent: true })?.entry;
+      return entry && !options.allowedModes.includes(entry.mode);
+    });
+    if (mismatch) throw actionNotAllowed(mismatch.action, "mode_mismatch", currentlyAvailable, options.adcpVersion);
   }
-  if (options.allowedModes && options.allowedModes.length > 0) {
-    const modeMismatch = result.matched.findIndex((match) => !options.allowedModes.includes(match.mode));
-    if (modeMismatch >= 0) {
-      const action = result.actions[modeMismatch]?.action ?? result.matched[modeMismatch].action;
-      throw actionNotAllowed(action, "mode_mismatch", currentlyAvailable);
+  if (!result.ok) {
+    const hardDenial = result.denials.find((d) => !d.assessment?.code);
+    if (hardDenial) throw actionNotAllowedFromDenied({ ...result, denials: [hardDenial] }, currentlyAvailable, options);
+    const assessment = result.denials.find((d) => d.assessment?.code === "CONFLICT")?.assessment ?? result.denials[0]?.assessment;
+    if (assessment?.code) {
+      throw new import_async_outcome.AdcpError(assessment.code, {
+        message: assessment.message,
+        recovery: assessment.code === "CONFLICT" ? "transient" : "correctable",
+        field: assessment.constraints && assessment.constraints.status !== "satisfied" ? assessment.constraints.path : "revision",
+        ...assessment.constraints && assessment.constraints.status !== "satisfied" && {
+          details: {
+            envelope_field: assessment.constraints.path,
+            change_term_id: (currentBuy.accepted_proposal ?? options.proposal)?.commercial_terms?.change_terms?.find(
+              (t) => t.action === assessment.action
+            )?.term_id,
+            constraint: assessment.constraints.constraint
+          }
+        }
+      });
     }
+    throw actionNotAllowedFromDenied(result, currentlyAvailable, options);
   }
   return result;
 }
@@ -61,19 +101,22 @@ function actionNotAllowedFromDenied(result, currentlyAvailable, options) {
     });
   }
   const reason = typeof options.reason === "function" ? options.reason(denial, result) : options.reason ?? denial.reason;
-  return actionNotAllowed(denial.action, reason, currentlyAvailable);
+  return actionNotAllowed(denial.action, reason, currentlyAvailable, options.adcpVersion);
 }
-function actionNotAllowed(attemptedAction, reason, currentlyAvailable) {
-  const details = {
+function actionNotAllowed(attemptedAction, reason, currentlyAvailable, version = import_version.ADCP_VERSION) {
+  const echoFits = !(0, import_action_contracts.liveActionIssues)(currentlyAvailable).length && currentlyAvailable.every(
+    (entry) => (0, import_action_contracts.actionFitsErrorDetails)(entry.action, version) && ["self_serve", "conditional_self_serve", "seller_managed", "requires_approval"].includes(entry.mode) && (0, import_action_contracts.liveActionFitsVersion)(entry, version)
+  );
+  const details = (0, import_action_contracts.actionFitsErrorDetails)(attemptedAction, version) && (reason !== "condition_unresolved" || (0, import_action_contracts.supportsChangeTermIdentity)(version)) ? {
     attempted_action: attemptedAction,
     reason,
-    currently_available_actions: currentlyAvailable
-  };
+    ...echoFits && { currently_available_actions: currentlyAvailable }
+  } : void 0;
   return new import_async_outcome.AdcpError("ACTION_NOT_ALLOWED", {
     message: buildActionNotAllowedMessage(attemptedAction, reason),
     recovery: "correctable",
     field: "update_media_buy",
-    details
+    ...details && { details }
   });
 }
 function buildActionNotAllowedMessage(action, reason) {

package/dist/lib/server/media-buy-actions.mjs

@@ -1,13 +1,27 @@
+import { ADCP_VERSION } from "../version.mjs";
+import {
+  actionFitsErrorDetails,
+  liveActionFitsVersion,
+  liveActionIssues,
+  supportsChangeTermIdentity
+} from "../media-buy/action-contracts.mjs";
 import { ValidationError } from "../errors/index.mjs";
 import {
   getAvailableActions,
+  findAvailableAction,
   preflightUpdateMediaBuy
 } from "../media-buy/index.mjs";
 import { AdcpError } from "./decisioning/async-outcome.mjs";
 function assertUpdateMediaBuyAllowed(currentBuy, request, options = {}) {
   let result;
   try {
-    result = preflightUpdateMediaBuy(currentBuy, request);
+    result = preflightUpdateMediaBuy(currentBuy, request, {
+      task: options.task ?? "update_media_buy",
+      proposal: options.proposal,
+      termsRefIsAlias: options.termsRefIsAlias,
+      now: options.now,
+      adcpVersion: options.adcpVersion ?? ADCP_VERSION
+    });
   } catch (err) {
     if (err instanceof ValidationError) {
       throw new AdcpError("INVALID_REQUEST", {
@@ -19,15 +33,47 @@ function assertUpdateMediaBuyAllowed(currentBuy, request, options = {}) {
     throw err;
   }
   const currentlyAvailable = getAvailableActions(currentBuy, { silent: true }).actions;
-  if (!result.ok) {
-    throw actionNotAllowedFromDenied(result, currentlyAvailable, options);
+  if (result.ok) {
+    const mismatch = result.matched.find(
+      (entry) => options.task !== void 0 && options.task !== "update_media_buy" && (entry.task ?? "update_media_buy") !== options.task
+    );
+    if (mismatch) throw actionNotAllowed(mismatch.action, "mode_mismatch", currentlyAvailable, options.adcpVersion);
   }
-  if (options.allowedModes && options.allowedModes.length > 0) {
-    const modeMismatch = result.matched.findIndex((match) => !options.allowedModes.includes(match.mode));
-    if (modeMismatch >= 0) {
-      const action = result.actions[modeMismatch]?.action ?? result.matched[modeMismatch].action;
-      throw actionNotAllowed(action, "mode_mismatch", currentlyAvailable);
+  if (!result.ok && result.denials.some((d) => !d.assessment?.code && d.reason !== "mode_mismatch"))
+    throw actionNotAllowedFromDenied(
+      { ...result, denials: result.denials.filter((d) => !d.assessment?.code && d.reason !== "mode_mismatch") },
+      currentlyAvailable,
+      options
+    );
+  if (options.allowedModes?.length) {
+    const requested = result.ok ? result.actions : result.mutations;
+    const mismatch = requested.find(({ action }) => {
+      const entry = findAvailableAction(currentBuy, action, { silent: true })?.entry;
+      return entry && !options.allowedModes.includes(entry.mode);
+    });
+    if (mismatch) throw actionNotAllowed(mismatch.action, "mode_mismatch", currentlyAvailable, options.adcpVersion);
+  }
+  if (!result.ok) {
+    const hardDenial = result.denials.find((d) => !d.assessment?.code);
+    if (hardDenial) throw actionNotAllowedFromDenied({ ...result, denials: [hardDenial] }, currentlyAvailable, options);
+    const assessment = result.denials.find((d) => d.assessment?.code === "CONFLICT")?.assessment ?? result.denials[0]?.assessment;
+    if (assessment?.code) {
+      throw new AdcpError(assessment.code, {
+        message: assessment.message,
+        recovery: assessment.code === "CONFLICT" ? "transient" : "correctable",
+        field: assessment.constraints && assessment.constraints.status !== "satisfied" ? assessment.constraints.path : "revision",
+        ...assessment.constraints && assessment.constraints.status !== "satisfied" && {
+          details: {
+            envelope_field: assessment.constraints.path,
+            change_term_id: (currentBuy.accepted_proposal ?? options.proposal)?.commercial_terms?.change_terms?.find(
+              (t) => t.action === assessment.action
+            )?.term_id,
+            constraint: assessment.constraints.constraint
+          }
+        }
+      });
     }
+    throw actionNotAllowedFromDenied(result, currentlyAvailable, options);
   }
   return result;
 }
@@ -41,19 +87,22 @@ function actionNotAllowedFromDenied(result, currentlyAvailable, options) {
     });
   }
   const reason = typeof options.reason === "function" ? options.reason(denial, result) : options.reason ?? denial.reason;
-  return actionNotAllowed(denial.action, reason, currentlyAvailable);
+  return actionNotAllowed(denial.action, reason, currentlyAvailable, options.adcpVersion);
 }
-function actionNotAllowed(attemptedAction, reason, currentlyAvailable) {
-  const details = {
+function actionNotAllowed(attemptedAction, reason, currentlyAvailable, version = ADCP_VERSION) {
+  const echoFits = !liveActionIssues(currentlyAvailable).length && currentlyAvailable.every(
+    (entry) => actionFitsErrorDetails(entry.action, version) && ["self_serve", "conditional_self_serve", "seller_managed", "requires_approval"].includes(entry.mode) && liveActionFitsVersion(entry, version)
+  );
+  const details = actionFitsErrorDetails(attemptedAction, version) && (reason !== "condition_unresolved" || supportsChangeTermIdentity(version)) ? {
     attempted_action: attemptedAction,
     reason,
-    currently_available_actions: currentlyAvailable
-  };
+    ...echoFits && { currently_available_actions: currentlyAvailable }
+  } : void 0;
   return new AdcpError("ACTION_NOT_ALLOWED", {
     message: buildActionNotAllowedMessage(attemptedAction, reason),
     recovery: "correctable",
     field: "update_media_buy",
-    details
+    ...details && { details }
   });
 }
 function buildActionNotAllowedMessage(action, reason) {

package/dist/lib/server/notification-subscriptions/index.d.mts

@@ -1,4 +1,4 @@
-export { ACCOUNT_NOTIFICATION_TYPES, CALLER_NOTIFICATION_TYPES, createPersistentNotificationRuntime, projectNotificationSubscriptionReadback, validatePersistentNotificationDestination, } from './runtime.mjs';
+export { ACCOUNT_NOTIFICATION_TYPES, CALLER_NOTIFICATION_TYPES, createPersistentNotificationRuntime, notificationSuppressionDisposition, projectNotificationSubscriptionReadback, validatePersistentNotificationDestination, } from './runtime.mjs';
 export { memoryNotificationSubscriptionStore } from './memory-store.mjs';
 export { NOTIFICATION_SUBSCRIPTION_MIGRATION, getNotificationSubscriptionMigration, pgNotificationSubscriptionStore, } from './postgres-store.mjs';
 export type { PostgresNotificationSubscriptionStoreOptions } from './postgres-store.mjs';
@@ -6,4 +6,4 @@ export { createPostgresPersistentNotificationRuntime } from './postgres-runtime.
 export { createPersistentNotificationProtocolHandlers } from './protocol-handlers.mjs';
 export type { CreatePostgresPersistentNotificationRuntimeOptions, PostgresPersistentNotificationRuntime, } from './postgres-runtime.mjs';
 export { NotificationSubscriptionValidationError } from './types.mjs';
-export type { NotificationAuthenticationMode, NotificationCredentialBindingAdapter, NotificationDeliveryAuthorizationInput, NotificationDeliveryAuthorizer, NotificationDestinationValidator, NotificationEvent, NotificationEventAnchor, NotificationFanoutDelivery, NotificationFanoutResult, NotificationProofAdapter, NotificationReplacementResult, NotificationSubscriptionConfigInput, NotificationSubscriptionMatch, NotificationSubscriptionScope, NotificationSubscriptionSet, NotificationSubscriptionStore, NotificationSubscriptionStoreReplaceResult, NotificationSubscriptionView, PersistentNotificationRuntime, PersistentNotificationRuntimeOptions, StoredNotificationAuthentication, StoredNotificationSubscription, } from './types.mjs';
+export type { NotificationAuthenticationMode, NotificationCredentialBindingAdapter, NotificationDeliveryAuthorizationInput, NotificationDeliveryAttemptCheckpoint, NotificationDeliveryAttemptCheckpointInput, NotificationDeliveryAuthorizer, NotificationDestinationValidator, NotificationEvent, NotificationEventAnchor, NotificationFanoutDelivery, NotificationFanoutResult, NotificationProofAdapter, NotificationRecipientRef, NotificationReplacementResult, NotificationSubscriptionConfigInput, NotificationSubscriptionMatch, NotificationSubscriptionScope, NotificationSubscriptionSet, NotificationSubscriptionStore, NotificationSubscriptionStoreReplaceResult, NotificationSuppressionDisposition, NotificationSubscriptionView, PersistentNotificationRuntime, PersistentNotificationRuntimeOptions, StoredNotificationAuthentication, StoredNotificationSubscription, } from './types.mjs';

package/dist/lib/server/notification-subscriptions/index.d.ts

@@ -1,4 +1,4 @@
-export { ACCOUNT_NOTIFICATION_TYPES, CALLER_NOTIFICATION_TYPES, createPersistentNotificationRuntime, projectNotificationSubscriptionReadback, validatePersistentNotificationDestination, } from './runtime';
+export { ACCOUNT_NOTIFICATION_TYPES, CALLER_NOTIFICATION_TYPES, createPersistentNotificationRuntime, notificationSuppressionDisposition, projectNotificationSubscriptionReadback, validatePersistentNotificationDestination, } from './runtime';
 export { memoryNotificationSubscriptionStore } from './memory-store';
 export { NOTIFICATION_SUBSCRIPTION_MIGRATION, getNotificationSubscriptionMigration, pgNotificationSubscriptionStore, } from './postgres-store';
 export type { PostgresNotificationSubscriptionStoreOptions } from './postgres-store';
@@ -6,4 +6,4 @@ export { createPostgresPersistentNotificationRuntime } from './postgres-runtime'
 export { createPersistentNotificationProtocolHandlers } from './protocol-handlers';
 export type { CreatePostgresPersistentNotificationRuntimeOptions, PostgresPersistentNotificationRuntime, } from './postgres-runtime';
 export { NotificationSubscriptionValidationError } from './types';
-export type { NotificationAuthenticationMode, NotificationCredentialBindingAdapter, NotificationDeliveryAuthorizationInput, NotificationDeliveryAuthorizer, NotificationDestinationValidator, NotificationEvent, NotificationEventAnchor, NotificationFanoutDelivery, NotificationFanoutResult, NotificationProofAdapter, NotificationReplacementResult, NotificationSubscriptionConfigInput, NotificationSubscriptionMatch, NotificationSubscriptionScope, NotificationSubscriptionSet, NotificationSubscriptionStore, NotificationSubscriptionStoreReplaceResult, NotificationSubscriptionView, PersistentNotificationRuntime, PersistentNotificationRuntimeOptions, StoredNotificationAuthentication, StoredNotificationSubscription, } from './types';
+export type { NotificationAuthenticationMode, NotificationCredentialBindingAdapter, NotificationDeliveryAuthorizationInput, NotificationDeliveryAttemptCheckpoint, NotificationDeliveryAttemptCheckpointInput, NotificationDeliveryAuthorizer, NotificationDestinationValidator, NotificationEvent, NotificationEventAnchor, NotificationFanoutDelivery, NotificationFanoutResult, NotificationProofAdapter, NotificationRecipientRef, NotificationReplacementResult, NotificationSubscriptionConfigInput, NotificationSubscriptionMatch, NotificationSubscriptionScope, NotificationSubscriptionSet, NotificationSubscriptionStore, NotificationSubscriptionStoreReplaceResult, NotificationSuppressionDisposition, NotificationSubscriptionView, PersistentNotificationRuntime, PersistentNotificationRuntimeOptions, StoredNotificationAuthentication, StoredNotificationSubscription, } from './types';

package/dist/lib/server/notification-subscriptions/index.js

@@ -27,6 +27,7 @@ __export(notification_subscriptions_exports, {
   createPostgresPersistentNotificationRuntime: () => import_postgres_runtime.createPostgresPersistentNotificationRuntime,
   getNotificationSubscriptionMigration: () => import_postgres_store.getNotificationSubscriptionMigration,
   memoryNotificationSubscriptionStore: () => import_memory_store.memoryNotificationSubscriptionStore,
+  notificationSuppressionDisposition: () => import_runtime.notificationSuppressionDisposition,
   pgNotificationSubscriptionStore: () => import_postgres_store.pgNotificationSubscriptionStore,
   projectNotificationSubscriptionReadback: () => import_runtime.projectNotificationSubscriptionReadback,
   validatePersistentNotificationDestination: () => import_runtime.validatePersistentNotificationDestination
@@ -49,6 +50,7 @@ var import_types = require('./types.js');
   createPostgresPersistentNotificationRuntime,
   getNotificationSubscriptionMigration,
   memoryNotificationSubscriptionStore,
+  notificationSuppressionDisposition,
   pgNotificationSubscriptionStore,
   projectNotificationSubscriptionReadback,
   validatePersistentNotificationDestination

package/dist/lib/server/notification-subscriptions/index.mjs

@@ -2,6 +2,7 @@ import {
   ACCOUNT_NOTIFICATION_TYPES,
   CALLER_NOTIFICATION_TYPES,
   createPersistentNotificationRuntime,
+  notificationSuppressionDisposition,
   projectNotificationSubscriptionReadback,
   validatePersistentNotificationDestination
 } from "./runtime.mjs";
@@ -24,6 +25,7 @@ export {
   createPostgresPersistentNotificationRuntime,
   getNotificationSubscriptionMigration,
   memoryNotificationSubscriptionStore,
+  notificationSuppressionDisposition,
   pgNotificationSubscriptionStore,
   projectNotificationSubscriptionReadback,
   validatePersistentNotificationDestination

package/dist/lib/server/notification-subscriptions/postgres-runtime.d.mts

@@ -1,7 +1,7 @@
 import type { PgQueryable } from '../postgres-task-store.mjs';
 import { type CreatePostgresWebhookRuntimeOptions, type PostgresWebhookRecoveryPollOptions, type PostgresWebhookRuntime } from '../webhook-delivery/postgres-runtime.mjs';
 import { type PostgresNotificationSubscriptionStoreOptions } from './postgres-store.mjs';
-import type { NotificationCredentialBindingAdapter, NotificationDestinationValidator, NotificationDeliveryAuthorizer, NotificationProofAdapter, PersistentNotificationRuntime, PersistentNotificationRuntimeOptions } from './types.mjs';
+import type { NotificationCredentialBindingAdapter, NotificationDeliveryAttemptCheckpoint, NotificationDestinationValidator, NotificationDeliveryAuthorizer, NotificationProofAdapter, PersistentNotificationRuntime, PersistentNotificationRuntimeOptions } from './types.mjs';
 export interface CreatePostgresPersistentNotificationRuntimeOptions {
     db: PgQueryable;
     publisherScope: string;
@@ -9,6 +9,8 @@ export interface CreatePostgresPersistentNotificationRuntimeOptions {
     webhooks: Omit<CreatePostgresWebhookRuntimeOptions, 'db' | 'publisherScope' | 'authorizeAttempt'>;
     proofAdapter: NotificationProofAdapter;
     credentialAdapter?: NotificationCredentialBindingAdapter;
+    /** Durable pre-POST attempt checkpoint; see `PersistentNotificationRuntimeOptions`. */
+    checkpointDeliveryAttempt?: NotificationDeliveryAttemptCheckpoint;
     authorizeDelivery: NotificationDeliveryAuthorizer;
     validateDestination?: NotificationDestinationValidator;
     supportedCallerEventTypes?: readonly string[];

package/dist/lib/server/notification-subscriptions/postgres-runtime.d.ts

@@ -1,7 +1,7 @@
 import type { PgQueryable } from '../postgres-task-store';
 import { type CreatePostgresWebhookRuntimeOptions, type PostgresWebhookRecoveryPollOptions, type PostgresWebhookRuntime } from '../webhook-delivery/postgres-runtime';
 import { type PostgresNotificationSubscriptionStoreOptions } from './postgres-store';
-import type { NotificationCredentialBindingAdapter, NotificationDestinationValidator, NotificationDeliveryAuthorizer, NotificationProofAdapter, PersistentNotificationRuntime, PersistentNotificationRuntimeOptions } from './types';
+import type { NotificationCredentialBindingAdapter, NotificationDeliveryAttemptCheckpoint, NotificationDestinationValidator, NotificationDeliveryAuthorizer, NotificationProofAdapter, PersistentNotificationRuntime, PersistentNotificationRuntimeOptions } from './types';
 export interface CreatePostgresPersistentNotificationRuntimeOptions {
     db: PgQueryable;
     publisherScope: string;
@@ -9,6 +9,8 @@ export interface CreatePostgresPersistentNotificationRuntimeOptions {
     webhooks: Omit<CreatePostgresWebhookRuntimeOptions, 'db' | 'publisherScope' | 'authorizeAttempt'>;
     proofAdapter: NotificationProofAdapter;
     credentialAdapter?: NotificationCredentialBindingAdapter;
+    /** Durable pre-POST attempt checkpoint; see `PersistentNotificationRuntimeOptions`. */
+    checkpointDeliveryAttempt?: NotificationDeliveryAttemptCheckpoint;
     authorizeDelivery: NotificationDeliveryAuthorizer;
     validateDestination?: NotificationDestinationValidator;
     supportedCallerEventTypes?: readonly string[];