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

package/dist/lib/server/notification-subscriptions/postgres-runtime.js

@@ -32,6 +32,7 @@ function createPostgresPersistentNotificationRuntime(options) {
     store,
     proofAdapter: options.proofAdapter,
     ...options.credentialAdapter === void 0 ? {} : { credentialAdapter: options.credentialAdapter },
+    ...options.checkpointDeliveryAttempt === void 0 ? {} : { checkpointDeliveryAttempt: options.checkpointDeliveryAttempt },
     authorizeDelivery: options.authorizeDelivery,
     ...options.validateDestination === void 0 ? {} : { validateDestination: options.validateDestination },
     ...options.supportedCallerEventTypes === void 0 ? {} : { supportedCallerEventTypes: options.supportedCallerEventTypes },

package/dist/lib/server/notification-subscriptions/postgres-runtime.mjs

@@ -14,6 +14,7 @@ function createPostgresPersistentNotificationRuntime(options) {
     store,
     proofAdapter: options.proofAdapter,
     ...options.credentialAdapter === void 0 ? {} : { credentialAdapter: options.credentialAdapter },
+    ...options.checkpointDeliveryAttempt === void 0 ? {} : { checkpointDeliveryAttempt: options.checkpointDeliveryAttempt },
     authorizeDelivery: options.authorizeDelivery,
     ...options.validateDestination === void 0 ? {} : { validateDestination: options.validateDestination },
     ...options.supportedCallerEventTypes === void 0 ? {} : { supportedCallerEventTypes: options.supportedCallerEventTypes },

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

@@ -1,4 +1,5 @@
-import type { NotificationSubscriptionConfigInput, NotificationSubscriptionView, PersistentNotificationRuntime, PersistentNotificationRuntimeOptions } from './types.mjs';
+import type { WebhookAttemptSuppressionReason } from '../webhook-emitter.mjs';
+import type { NotificationSubscriptionConfigInput, NotificationSubscriptionView, NotificationSuppressionDisposition, PersistentNotificationRuntime, PersistentNotificationRuntimeOptions } from './types.mjs';
 export declare const CALLER_NOTIFICATION_TYPES: readonly ["capabilities.changed", "principal.changed"];
 export declare const ACCOUNT_NOTIFICATION_TYPES: readonly ["creative.status_changed", "creative.assignment_changed", "indicators.changed", "creative.purged", "account.status_changed", "account.change_recorded", "product.created", "product.updated", "product.priced", "product.removed", "signal.created", "signal.updated", "signal.priced", "signal.removed", "wholesale_feed.bulk_change", "reporting.delivery_ready", "reporting.status_changed", "reporting.ledger_changed"];
 /**
@@ -10,6 +11,16 @@ export declare const ACCOUNT_NOTIFICATION_TYPES: readonly ["creative.status_chan
 export declare function createPersistentNotificationRuntime(options: PersistentNotificationRuntimeOptions): PersistentNotificationRuntime;
 /** Strip SDK operational generations for generated AdCP response projections. */
 export declare function projectNotificationSubscriptionReadback(views: readonly NotificationSubscriptionView[]): NotificationSubscriptionConfigInput[];
+/**
+ * Classifies a live-authority suppression so an emission owner can tell a
+ * deliberate decision not to deliver from an operational failure.
+ *
+ * Treating every suppression as terminal silently drops notifications whenever
+ * a store read or an authorization/credential callback has a bad minute, and
+ * treating every suppression as retryable poisons the queue for a subscriber
+ * that was legitimately revoked or denied.
+ */
+export declare function notificationSuppressionDisposition(reason: WebhookAttemptSuppressionReason): NotificationSuppressionDisposition;
 /** Point-in-time registration validation; delivery still re-resolves and pins every attempt. */
 export declare function validatePersistentNotificationDestination(input: {
     url: string;

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

@@ -1,4 +1,5 @@
-import type { NotificationSubscriptionConfigInput, NotificationSubscriptionView, PersistentNotificationRuntime, PersistentNotificationRuntimeOptions } from './types';
+import type { WebhookAttemptSuppressionReason } from '../webhook-emitter';
+import type { NotificationSubscriptionConfigInput, NotificationSubscriptionView, NotificationSuppressionDisposition, PersistentNotificationRuntime, PersistentNotificationRuntimeOptions } from './types';
 export declare const CALLER_NOTIFICATION_TYPES: readonly ["capabilities.changed", "principal.changed"];
 export declare const ACCOUNT_NOTIFICATION_TYPES: readonly ["creative.status_changed", "creative.assignment_changed", "indicators.changed", "creative.purged", "account.status_changed", "account.change_recorded", "product.created", "product.updated", "product.priced", "product.removed", "signal.created", "signal.updated", "signal.priced", "signal.removed", "wholesale_feed.bulk_change", "reporting.delivery_ready", "reporting.status_changed", "reporting.ledger_changed"];
 /**
@@ -10,6 +11,16 @@ export declare const ACCOUNT_NOTIFICATION_TYPES: readonly ["creative.status_chan
 export declare function createPersistentNotificationRuntime(options: PersistentNotificationRuntimeOptions): PersistentNotificationRuntime;
 /** Strip SDK operational generations for generated AdCP response projections. */
 export declare function projectNotificationSubscriptionReadback(views: readonly NotificationSubscriptionView[]): NotificationSubscriptionConfigInput[];
+/**
+ * Classifies a live-authority suppression so an emission owner can tell a
+ * deliberate decision not to deliver from an operational failure.
+ *
+ * Treating every suppression as terminal silently drops notifications whenever
+ * a store read or an authorization/credential callback has a bad minute, and
+ * treating every suppression as retryable poisons the queue for a subscriber
+ * that was legitimately revoked or denied.
+ */
+export declare function notificationSuppressionDisposition(reason: WebhookAttemptSuppressionReason): NotificationSuppressionDisposition;
 /** Point-in-time registration validation; delivery still re-resolves and pins every attempt. */
 export declare function validatePersistentNotificationDestination(input: {
     url: string;

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

@@ -21,6 +21,7 @@ __export(runtime_exports, {
   ACCOUNT_NOTIFICATION_TYPES: () => ACCOUNT_NOTIFICATION_TYPES,
   CALLER_NOTIFICATION_TYPES: () => CALLER_NOTIFICATION_TYPES,
   createPersistentNotificationRuntime: () => createPersistentNotificationRuntime,
+  notificationSuppressionDisposition: () => notificationSuppressionDisposition,
   projectNotificationSubscriptionReadback: () => projectNotificationSubscriptionReadback,
   validatePersistentNotificationDestination: () => validatePersistentNotificationDestination
 });
@@ -28,6 +29,7 @@ module.exports = __toCommonJS(runtime_exports);
 var import_node_crypto = require("node:crypto");
 var import_promises = require("node:dns/promises");
 var import_jcs = require('../../utils/jcs.js');
+var import_common = require('../webhook-delivery/common.js');
 var import_ssrf = require('../../substitution/observer/ssrf.js');
 var import_pin_and_bind_fetch = require('../pin-and-bind-fetch.js');
 var import_types = require('./types.js');
@@ -96,6 +98,30 @@ function createPersistentNotificationRuntime(options) {
     ...futureCallerInvalidationEventTypes
   ]);
   const validateDestination = options.validateDestination ?? validatePersistentNotificationDestination;
+  const checkpointAttempt = async (context) => {
+    if (!options.checkpointDeliveryAttempt) return true;
+    const controller = new AbortController();
+    try {
+      await options.checkpointDeliveryAttempt({
+        scope: structuredClone(context.scope),
+        eventAnchor: context.eventAnchor,
+        ...context.accountId === void 0 ? {} : { accountId: context.accountId },
+        subscriberId: context.subscriberId,
+        destinationGeneration: context.destinationGeneration,
+        eventType: context.eventType,
+        notificationId: context.notificationId,
+        signal: controller.signal
+      });
+      return true;
+    } catch {
+      return false;
+    }
+  };
+  const suppress = (reason) => ({
+    decision: "suppress",
+    reason,
+    ...notificationSuppressionDisposition(reason) === "retryable" ? { retryable: true } : {}
+  });
   const authorizeWebhookAttempt = async (attempt) => {
     const context = parseAttemptContext(attempt.attemptAuthorizationContext);
     if (!context) return { decision: "suppress", reason: "authorization_error" };
@@ -103,22 +129,22 @@ function createPersistentNotificationRuntime(options) {
     try {
       set = await options.store.get(context.scope);
     } catch {
-      return { decision: "suppress", reason: "authorization_error" };
+      return suppress("authorization_error");
     }
-    if (!set) return { decision: "suppress", reason: "subscription_missing" };
+    if (!set) return suppress("subscription_missing");
     const subscription = set.subscriptions.find((item) => item.subscriberId === context.subscriberId);
-    if (!subscription) return { decision: "suppress", reason: "subscription_missing" };
+    if (!subscription) return suppress("subscription_missing");
     if (subscription.destinationGeneration !== context.destinationGeneration) {
-      return { decision: "suppress", reason: "subscription_stale" };
+      return attempt.recovered === true ? { decision: "suppress", reason: "subscription_stale" } : suppress("subscription_stale");
     }
     if (!subscription.active || subscription.proofGeneration !== subscription.destinationGeneration) {
-      return { decision: "suppress", reason: "subscription_inactive" };
+      return suppress("subscription_inactive");
     }
     if (!subscription.eventTypes.includes(context.eventType) && !(context.futureCallerInvalidation === true && futureCallerInvalidationEventTypes.has(context.eventType) && subscription.includeFutureEventTypes)) {
-      return { decision: "suppress", reason: "event_not_allowed" };
+      return suppress("event_not_allowed");
     }
     if (context.eventAnchor === "account" && !context.accountId || context.eventAnchor === "caller" && context.accountId !== void 0 || context.scope.kind === "account" && (context.eventAnchor !== "account" || context.scope.accountId !== context.accountId) || context.scope.kind === "caller" && context.eventAnchor === "account" && !subscription.allAuthorizedAccounts) {
-      return { decision: "suppress", reason: "event_not_allowed" };
+      return suppress("event_not_allowed");
     }
     let decision;
     try {
@@ -137,16 +163,17 @@ function createPersistentNotificationRuntime(options) {
         })
       );
     } catch {
-      return { decision: "suppress", reason: "authorization_error" };
+      return suppress("authorization_error");
     }
-    if (decision?.authorized !== true) return { decision: "suppress", reason: "authorization_denied" };
+    if (decision?.authorized !== true) return suppress("authorization_denied");
     const authenticationMode = subscription.authentication.mode;
     if (authenticationMode === "rfc9421") {
+      if (!await checkpointAttempt(context)) return suppress("attempt_checkpoint_unavailable");
       return { decision: "allow", authentication: null };
     }
     const bindingId = subscription.authentication.bindingId;
     if (!bindingId || !options.credentialAdapter) {
-      return { decision: "suppress", reason: "credential_unavailable" };
+      return suppress("credential_unavailable");
     }
     try {
       const authentication = await runAdopterCallback(
@@ -162,11 +189,12 @@ function createPersistentNotificationRuntime(options) {
         })
       );
       if (!resolvedAuthenticationMatches(authenticationMode, authentication)) {
-        return { decision: "suppress", reason: "credential_unavailable" };
+        return suppress("credential_unavailable");
       }
+      if (!await checkpointAttempt(context)) return suppress("attempt_checkpoint_unavailable");
       return { decision: "allow", authentication };
     } catch {
-      return { decision: "suppress", reason: "credential_unavailable" };
+      return suppress("credential_unavailable");
     }
   };
   const emitter = options.createEmitter(authorizeWebhookAttempt);
@@ -177,6 +205,8 @@ function createPersistentNotificationRuntime(options) {
     store: options.store,
     emitter,
     authorizeWebhookAttempt,
+    hasDeliveryAttemptCheckpoint: options.checkpointDeliveryAttempt !== void 0,
+    ...options.checkpointDeliveryAttempt === void 0 ? {} : { deliveryAttemptCheckpoint: options.checkpointDeliveryAttempt },
     async replace(scope, configs, replaceOptions = {}) {
       assertScope(scope);
       assertUniqueSubscribers(configs);
@@ -316,14 +346,15 @@ function createPersistentNotificationRuntime(options) {
       if (candidateSets.length > maxFanoutCandidates) {
         throw new Error("Persistent notification fanout exceeded maxFanoutCandidates; no deliveries were attempted");
       }
-      const targets = candidateSets.flatMap(
+      const resolved = candidateSets.flatMap(
         (set) => set.subscriptions.filter(
           (subscription) => subscription.active && subscription.proofGeneration === subscription.destinationGeneration && (subscription.eventTypes.includes(event.notificationType) || futureCallerInvalidation && subscription.includeFutureEventTypes) && (set.scope.kind !== "caller" || event.anchor !== "account" || subscription.allAuthorizedAccounts)
         ).map((subscription) => ({ set, subscription }))
       );
-      if (targets.length > maxFanoutCandidates) {
+      if (resolved.length > maxFanoutCandidates) {
         throw new Error("Persistent notification fanout exceeded maxFanoutCandidates; no deliveries were attempted");
       }
+      const targets = event.freezeRecipients ? await pinResolvedRecipients(resolved, event.freezeRecipients) : resolved;
       const deliveries = await mapConcurrent(targets, fanoutConcurrency, async ({ set, subscription }) => {
         const deliveryId = deliveryIdentity(event.emissionId, set.scope, subscription);
         const payload = notificationPayload(event, subscription.subscriberId);
@@ -353,10 +384,10 @@ function createPersistentNotificationRuntime(options) {
             attemptAuthorizationContext: context
           });
           return { ...delivery, result };
-        } catch {
+        } catch (error) {
           return {
             ...delivery,
-            failure: { reason: "delivery_runtime_error" }
+            failure: (0, import_common.isWebhookDeliveryTerminalError)(error) ? { reason: "delivery_binding_retired", terminal: true } : { reason: "delivery_runtime_error" }
           };
         }
       });
@@ -622,6 +653,60 @@ function assertPayloadField(payload, field, expected) {
     );
   }
 }
+async function pinResolvedRecipients(resolved, freezeRecipients) {
+  const frozen = await freezeRecipients(
+    resolved.map((target) => ({
+      scope: structuredClone(target.set.scope),
+      subscriberId: target.subscription.subscriberId,
+      destinationGeneration: target.subscription.destinationGeneration
+    }))
+  );
+  if (!Array.isArray(frozen)) {
+    throw new TypeError("freezeRecipients must return the durably committed recipient set");
+  }
+  const committed = new Set(
+    frozen.map((recipient) => {
+      if (!recipient || typeof recipient.subscriberId !== "string" || typeof recipient.destinationGeneration !== "string" || !recipient.scope) {
+        throw new TypeError("freezeRecipients returned a malformed recipient reference");
+      }
+      return recipientKey(recipient);
+    })
+  );
+  return resolved.filter(
+    (target) => committed.has(
+      recipientKey({
+        scope: target.set.scope,
+        subscriberId: target.subscription.subscriberId,
+        destinationGeneration: target.subscription.destinationGeneration
+      })
+    )
+  );
+}
+function notificationSuppressionDisposition(reason) {
+  switch (reason) {
+    case "authorization_error":
+    case "credential_unavailable":
+      return "retryable";
+    case "subscription_stale":
+      return "retryable";
+    case "attempt_checkpoint_unavailable":
+      return "retryable";
+    case "subscription_missing":
+    case "subscription_inactive":
+    case "event_not_allowed":
+    case "authorization_denied":
+      return "terminal";
+    default:
+      return "retryable";
+  }
+}
+function recipientKey(recipient) {
+  return (0, import_jcs.canonicalJsonSha256)({
+    scope: recipient.scope,
+    subscriberId: recipient.subscriberId,
+    destinationGeneration: recipient.destinationGeneration
+  });
+}
 function deliveryIdentity(emissionId, scope, subscription) {
   return `notification_${(0, import_jcs.canonicalJsonSha256)({
     emissionId,
@@ -844,6 +929,7 @@ function validation(message, index, field) {
   ACCOUNT_NOTIFICATION_TYPES,
   CALLER_NOTIFICATION_TYPES,
   createPersistentNotificationRuntime,
+  notificationSuppressionDisposition,
   projectNotificationSubscriptionReadback,
   validatePersistentNotificationDestination
 });

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

@@ -1,6 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { lookup } from "node:dns/promises";
 import { canonicalJsonSha256 } from "../../utils/jcs.mjs";
+import { isWebhookDeliveryTerminalError } from "../webhook-delivery/common.mjs";
 import { enforceSsrfPolicy, enforceSsrfPolicyResolved } from "../../substitution/observer/ssrf.mjs";
 import { WEBHOOK_SSRF_POLICY } from "../pin-and-bind-fetch.mjs";
 import { NotificationSubscriptionValidationError } from "./types.mjs";
@@ -69,6 +70,30 @@ function createPersistentNotificationRuntime(options) {
     ...futureCallerInvalidationEventTypes
   ]);
   const validateDestination = options.validateDestination ?? validatePersistentNotificationDestination;
+  const checkpointAttempt = async (context) => {
+    if (!options.checkpointDeliveryAttempt) return true;
+    const controller = new AbortController();
+    try {
+      await options.checkpointDeliveryAttempt({
+        scope: structuredClone(context.scope),
+        eventAnchor: context.eventAnchor,
+        ...context.accountId === void 0 ? {} : { accountId: context.accountId },
+        subscriberId: context.subscriberId,
+        destinationGeneration: context.destinationGeneration,
+        eventType: context.eventType,
+        notificationId: context.notificationId,
+        signal: controller.signal
+      });
+      return true;
+    } catch {
+      return false;
+    }
+  };
+  const suppress = (reason) => ({
+    decision: "suppress",
+    reason,
+    ...notificationSuppressionDisposition(reason) === "retryable" ? { retryable: true } : {}
+  });
   const authorizeWebhookAttempt = async (attempt) => {
     const context = parseAttemptContext(attempt.attemptAuthorizationContext);
     if (!context) return { decision: "suppress", reason: "authorization_error" };
@@ -76,22 +101,22 @@ function createPersistentNotificationRuntime(options) {
     try {
       set = await options.store.get(context.scope);
     } catch {
-      return { decision: "suppress", reason: "authorization_error" };
+      return suppress("authorization_error");
     }
-    if (!set) return { decision: "suppress", reason: "subscription_missing" };
+    if (!set) return suppress("subscription_missing");
     const subscription = set.subscriptions.find((item) => item.subscriberId === context.subscriberId);
-    if (!subscription) return { decision: "suppress", reason: "subscription_missing" };
+    if (!subscription) return suppress("subscription_missing");
     if (subscription.destinationGeneration !== context.destinationGeneration) {
-      return { decision: "suppress", reason: "subscription_stale" };
+      return attempt.recovered === true ? { decision: "suppress", reason: "subscription_stale" } : suppress("subscription_stale");
     }
     if (!subscription.active || subscription.proofGeneration !== subscription.destinationGeneration) {
-      return { decision: "suppress", reason: "subscription_inactive" };
+      return suppress("subscription_inactive");
     }
     if (!subscription.eventTypes.includes(context.eventType) && !(context.futureCallerInvalidation === true && futureCallerInvalidationEventTypes.has(context.eventType) && subscription.includeFutureEventTypes)) {
-      return { decision: "suppress", reason: "event_not_allowed" };
+      return suppress("event_not_allowed");
     }
     if (context.eventAnchor === "account" && !context.accountId || context.eventAnchor === "caller" && context.accountId !== void 0 || context.scope.kind === "account" && (context.eventAnchor !== "account" || context.scope.accountId !== context.accountId) || context.scope.kind === "caller" && context.eventAnchor === "account" && !subscription.allAuthorizedAccounts) {
-      return { decision: "suppress", reason: "event_not_allowed" };
+      return suppress("event_not_allowed");
     }
     let decision;
     try {
@@ -110,16 +135,17 @@ function createPersistentNotificationRuntime(options) {
         })
       );
     } catch {
-      return { decision: "suppress", reason: "authorization_error" };
+      return suppress("authorization_error");
     }
-    if (decision?.authorized !== true) return { decision: "suppress", reason: "authorization_denied" };
+    if (decision?.authorized !== true) return suppress("authorization_denied");
     const authenticationMode = subscription.authentication.mode;
     if (authenticationMode === "rfc9421") {
+      if (!await checkpointAttempt(context)) return suppress("attempt_checkpoint_unavailable");
       return { decision: "allow", authentication: null };
     }
     const bindingId = subscription.authentication.bindingId;
     if (!bindingId || !options.credentialAdapter) {
-      return { decision: "suppress", reason: "credential_unavailable" };
+      return suppress("credential_unavailable");
     }
     try {
       const authentication = await runAdopterCallback(
@@ -135,11 +161,12 @@ function createPersistentNotificationRuntime(options) {
         })
       );
       if (!resolvedAuthenticationMatches(authenticationMode, authentication)) {
-        return { decision: "suppress", reason: "credential_unavailable" };
+        return suppress("credential_unavailable");
       }
+      if (!await checkpointAttempt(context)) return suppress("attempt_checkpoint_unavailable");
       return { decision: "allow", authentication };
     } catch {
-      return { decision: "suppress", reason: "credential_unavailable" };
+      return suppress("credential_unavailable");
     }
   };
   const emitter = options.createEmitter(authorizeWebhookAttempt);
@@ -150,6 +177,8 @@ function createPersistentNotificationRuntime(options) {
     store: options.store,
     emitter,
     authorizeWebhookAttempt,
+    hasDeliveryAttemptCheckpoint: options.checkpointDeliveryAttempt !== void 0,
+    ...options.checkpointDeliveryAttempt === void 0 ? {} : { deliveryAttemptCheckpoint: options.checkpointDeliveryAttempt },
     async replace(scope, configs, replaceOptions = {}) {
       assertScope(scope);
       assertUniqueSubscribers(configs);
@@ -289,14 +318,15 @@ function createPersistentNotificationRuntime(options) {
       if (candidateSets.length > maxFanoutCandidates) {
         throw new Error("Persistent notification fanout exceeded maxFanoutCandidates; no deliveries were attempted");
       }
-      const targets = candidateSets.flatMap(
+      const resolved = candidateSets.flatMap(
         (set) => set.subscriptions.filter(
           (subscription) => subscription.active && subscription.proofGeneration === subscription.destinationGeneration && (subscription.eventTypes.includes(event.notificationType) || futureCallerInvalidation && subscription.includeFutureEventTypes) && (set.scope.kind !== "caller" || event.anchor !== "account" || subscription.allAuthorizedAccounts)
         ).map((subscription) => ({ set, subscription }))
       );
-      if (targets.length > maxFanoutCandidates) {
+      if (resolved.length > maxFanoutCandidates) {
         throw new Error("Persistent notification fanout exceeded maxFanoutCandidates; no deliveries were attempted");
       }
+      const targets = event.freezeRecipients ? await pinResolvedRecipients(resolved, event.freezeRecipients) : resolved;
       const deliveries = await mapConcurrent(targets, fanoutConcurrency, async ({ set, subscription }) => {
         const deliveryId = deliveryIdentity(event.emissionId, set.scope, subscription);
         const payload = notificationPayload(event, subscription.subscriberId);
@@ -326,10 +356,10 @@ function createPersistentNotificationRuntime(options) {
             attemptAuthorizationContext: context
           });
           return { ...delivery, result };
-        } catch {
+        } catch (error) {
           return {
             ...delivery,
-            failure: { reason: "delivery_runtime_error" }
+            failure: isWebhookDeliveryTerminalError(error) ? { reason: "delivery_binding_retired", terminal: true } : { reason: "delivery_runtime_error" }
           };
         }
       });
@@ -595,6 +625,60 @@ function assertPayloadField(payload, field, expected) {
     );
   }
 }
+async function pinResolvedRecipients(resolved, freezeRecipients) {
+  const frozen = await freezeRecipients(
+    resolved.map((target) => ({
+      scope: structuredClone(target.set.scope),
+      subscriberId: target.subscription.subscriberId,
+      destinationGeneration: target.subscription.destinationGeneration
+    }))
+  );
+  if (!Array.isArray(frozen)) {
+    throw new TypeError("freezeRecipients must return the durably committed recipient set");
+  }
+  const committed = new Set(
+    frozen.map((recipient) => {
+      if (!recipient || typeof recipient.subscriberId !== "string" || typeof recipient.destinationGeneration !== "string" || !recipient.scope) {
+        throw new TypeError("freezeRecipients returned a malformed recipient reference");
+      }
+      return recipientKey(recipient);
+    })
+  );
+  return resolved.filter(
+    (target) => committed.has(
+      recipientKey({
+        scope: target.set.scope,
+        subscriberId: target.subscription.subscriberId,
+        destinationGeneration: target.subscription.destinationGeneration
+      })
+    )
+  );
+}
+function notificationSuppressionDisposition(reason) {
+  switch (reason) {
+    case "authorization_error":
+    case "credential_unavailable":
+      return "retryable";
+    case "subscription_stale":
+      return "retryable";
+    case "attempt_checkpoint_unavailable":
+      return "retryable";
+    case "subscription_missing":
+    case "subscription_inactive":
+    case "event_not_allowed":
+    case "authorization_denied":
+      return "terminal";
+    default:
+      return "retryable";
+  }
+}
+function recipientKey(recipient) {
+  return canonicalJsonSha256({
+    scope: recipient.scope,
+    subscriberId: recipient.subscriberId,
+    destinationGeneration: recipient.destinationGeneration
+  });
+}
 function deliveryIdentity(emissionId, scope, subscription) {
   return `notification_${canonicalJsonSha256({
     emissionId,
@@ -816,6 +900,7 @@ export {
   ACCOUNT_NOTIFICATION_TYPES,
   CALLER_NOTIFICATION_TYPES,
   createPersistentNotificationRuntime,
+  notificationSuppressionDisposition,
   projectNotificationSubscriptionReadback,
   validatePersistentNotificationDestination
 };

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

@@ -208,6 +208,16 @@ export type NotificationDeliveryAuthorizer = (input: Readonly<NotificationDelive
 } | {
     authorized: false;
 }>;
+/**
+ * One resolved delivery target. Together with the event's `emissionId` these
+ * three fields are exactly the inputs to the per-subscriber delivery identity,
+ * so pinning them pins the idempotency key the subscriber sees.
+ */
+export interface NotificationRecipientRef {
+    scope: NotificationSubscriptionScope;
+    subscriberId: string;
+    destinationGeneration: string;
+}
 export interface NotificationEvent {
     /** Application-stable identity for this delivery event; reuse on crash retry, rotate on re-emission. */
     emissionId: string;
@@ -221,7 +231,69 @@ export interface NotificationEvent {
     /** Required for account-anchored events. */
     accountId?: string;
     payload: Record<string, unknown>;
+    /**
+     * Durably freezes the recipient set before any external send.
+     *
+     * The runtime resolves its candidates, hands them to this callback, and then
+     * delivers to exactly the intersection of those candidates and what the
+     * callback returns. An emitter that persists the first resolved set and
+     * replays it verbatim therefore keeps every `delivery_id` — and so every
+     * subscriber-visible idempotency key — stable across an ambiguous retry: a
+     * subscription replaced or revoked after the first send is skipped rather
+     * than addressed under a new destination generation, so a replay can never
+     * add a second logical delivery of the same notification.
+     *
+     * Called at most once per `emit`, before the first attempt. It is a
+     * durability barrier owned by the emitting subsystem, not an adopter policy
+     * hook, so it is deliberately not bounded by `adopterCallbackTimeoutMs`: the
+     * runtime cannot safely abandon a write that may still commit. Implementations
+     * must enforce their own transaction-level deadline. Throwing aborts the
+     * emission before anything is sent.
+     */
+    freezeRecipients?: (candidates: readonly NotificationRecipientRef[]) => MaybePromise<readonly NotificationRecipientRef[]>;
 }
+/** Durable record that one recipient is about to receive an external POST. */
+export interface NotificationDeliveryAttemptCheckpointInput {
+    scope: Readonly<NotificationSubscriptionScope>;
+    eventAnchor: NotificationEventAnchor;
+    accountId?: string;
+    subscriberId: string;
+    destinationGeneration: string;
+    eventType: string;
+    notificationId: string;
+    signal: AbortSignal;
+}
+/**
+ * Durably records that a delivery is about to be attempted, awaited on the
+ * allow path of live delivery authority immediately before every external POST.
+ *
+ * It is keyed on the durable attempt context rather than on a per-emission
+ * closure precisely so that recovered outbox attempts participate: an emission
+ * snapshot cannot carry a function, so a per-emission barrier would be silently
+ * skipped by the very path — a restarted outbox worker — where an ambiguous send
+ * is most likely.
+ *
+ * This is what makes a frozen recipient set safely revisable. Suppression fails
+ * closed before this point, so a recipient with no checkpoint provably never
+ * received a POST and may be replaced; a recipient with one is pinned forever,
+ * because a crash after it is an ambiguous send. Rejecting suppresses that
+ * delivery as retryable with no external attempt.
+ */
+export type NotificationDeliveryAttemptCheckpoint = (input: Readonly<NotificationDeliveryAttemptCheckpointInput>) => MaybePromise<void>;
+/**
+ * Whether a live-authority suppression is a deliberate decision not to deliver
+ * or an operational failure that says nothing about the subscriber.
+ *
+ * `terminal` — the subscriber must not receive this event: it is gone, inactive,
+ * not subscribed to the type, or the adopter denied it. Settle the emission.
+ *
+ * `retryable` — the runtime could not establish authority: a store read failed,
+ * an authorization or credential callback threw or timed out, or the
+ * subscription generation moved while the emission was in flight. Nothing was
+ * sent (`attempts: 0`), so the owner must release and retry rather than record
+ * the notification as delivered.
+ */
+export type NotificationSuppressionDisposition = 'terminal' | 'retryable';
 export interface NotificationSubscriptionView {
     subscriber_id: string;
     url: string;
@@ -264,8 +336,14 @@ export type NotificationFanoutDelivery = NotificationFanoutDeliveryBase & ({
     failure?: never;
 } | {
     result?: never;
+    /**
+     * `delivery_binding_retired` is terminal: the delivery identity is
+     * retired or past its retry horizon and can never succeed. Anything
+     * else is an operational failure worth retrying.
+     */
     failure: {
-        reason: 'delivery_runtime_error';
+        reason: 'delivery_runtime_error' | 'delivery_binding_retired';
+        terminal?: boolean;
     };
 });
 export interface NotificationFanoutResult {
@@ -279,6 +357,14 @@ export interface PersistentNotificationRuntimeOptions {
     proofAdapter: NotificationProofAdapter;
     credentialAdapter?: NotificationCredentialBindingAdapter;
     authorizeDelivery: NotificationDeliveryAuthorizer;
+    /**
+     * Durable pre-POST checkpoint. Required by any emission owner that freezes a
+     * recipient set and needs to know whether a recipient was ever addressed;
+     * `PersistentNotificationRuntime.hasDeliveryAttemptCheckpoint` reports whether
+     * it is wired so such an owner can fail closed at startup instead of silently
+     * losing the guarantee.
+     */
+    checkpointDeliveryAttempt?: NotificationDeliveryAttemptCheckpoint;
     /** Defaults to DNS resolution plus the SDK's strict webhook SSRF policy. */
     validateDestination?: NotificationDestinationValidator;
     /** Build the emitter with the supplied mandatory per-attempt authorizer. */
@@ -317,6 +403,23 @@ export interface PersistentNotificationRuntime {
     readonly store: NotificationSubscriptionStore;
     readonly emitter: RecoverableWebhookEmitter;
     readonly authorizeWebhookAttempt: WebhookAttemptAuthorizer;
+    /**
+     * True when a durable pre-POST attempt checkpoint is wired.
+     *
+     * Optional so a custom implementation written against an earlier release
+     * still satisfies this interface structurally. An emission owner that needs
+     * the checkpoint treats an absent flag as "not proven" and fails closed.
+     */
+    readonly hasDeliveryAttemptCheckpoint?: boolean;
+    /**
+     * The checkpoint this runtime actually invokes, exposed so an emission owner
+     * can verify by identity that its own checkpoint is the one that runs.
+     * Declaring the capability is not the same as wiring the right function:
+     * two correctly-built checkpoints pointing at different stores each look
+     * valid in isolation, and the mismatch only shows up as deliveries that
+     * checkpoint nothing.
+     */
+    readonly deliveryAttemptCheckpoint?: NotificationDeliveryAttemptCheckpoint;
     replace(scope: Readonly<NotificationSubscriptionScope>, configs: readonly NotificationSubscriptionConfigInput[], options?: {
         expectedGeneration?: string;
         dryRun?: boolean;