pulse-updates 1.3.7 → 1.3.9

package/src/links.ts

@@ -122,6 +122,14 @@ export interface AnonymousFirstOpenContext {
   /** JavaScript Date#getTimezoneOffset semantics, bounded to real-world UTC offsets. */
   timezoneOffsetMinutes?: number;
   isEmulator?: boolean;
+  /**
+   * The address the person is signed in with, when the host app has one. An install that arrives
+   * with an account does not need to be guessed at: the resolver binds it to the message sent to
+   * that address and skips probabilistic matching entirely. Omitted for signed-out first opens,
+   * and never read from the clipboard or any other ambient source — the app passes what it
+   * already knows, or nothing.
+   */
+  accountEmail?: string;
 }
 
 export type AnonymousFirstOpenResult =
@@ -134,6 +142,51 @@ export type AnonymousFirstOpenResult =
   | 'retry_scheduled'
   | 'terminal_error';
 
+export type AnonymousFirstOpenTerminalStatus = 'FOUND' | 'NOT_FOUND' | 'FAILURE';
+
+/** Explicit receiver decision for one terminal-delivery attempt. */
+export type AnonymousFirstOpenTerminalDisposition = 'accepted' | 'retry' | 'drop';
+
+export type AnonymousFirstOpenTerminalReason =
+  | 'matched'
+  | 'unmatched'
+  | 'ambiguous'
+  | 'holdout'
+  | 'low_confidence'
+  | 'shadow_would_route'
+  | 'shadow_attributed'
+  | 'analytics_attributed'
+  | 'target_revoked'
+  | 'disabled'
+  | 'expired_replay'
+  | 'invalid_request'
+  | 'invalid_response'
+  | 'policy_rejected';
+
+/**
+ * Sanitized terminal result of the anonymous first-open rail. It deliberately carries no
+ * install-attempt id, token, device signal or raw server error. A 204 is always `no_route` and
+ * can never make the client navigate, including when Encore reports a shadow observation.
+ */
+export interface AnonymousFirstOpenTerminalOutcome {
+  /** Stable UUIDv4 for receiver-side deduplication of at-least-once delivery. */
+  eventId: string;
+  status: AnonymousFirstOpenTerminalStatus;
+  rail: 'fast_route' | 'no_route';
+  routed: boolean;
+  retryable: false;
+  reason: AnonymousFirstOpenTerminalReason;
+  occurredAt: string;
+  /** Present only for FOUND and copied from the already-normalized resolver result. */
+  matchBasis?: DeferredLinkMatchBasis;
+  /** Present only for FOUND, finite and clamped to [0, 1]. */
+  confidence?: number;
+  /** Optional FOUND-only campaign dimensions; strings are trimmed and bounded to 128 chars. */
+  campaignId?: string | null;
+  experimentId?: string | null;
+  variantId?: string | null;
+}
+
 export type AndroidInstallReferrerStatus =
   | 'OK'
   | 'NO_TOKEN'
@@ -163,7 +216,13 @@ export interface DeferredLinkClientOptions<Action extends string = DeferredLinkA
   allowedActions?: readonly Action[];
   /** Actions that require both a deterministic match and a stable signed-in account. */
   sensitiveActions?: readonly Action[];
+  /**
+   * Routing callbacks are irreversible commit boundaries: return `false` when no navigation
+   * happened. If a newer accepted capture arrives while a successful callback is pending, Pulse
+   * persists it but will not auto-route a second journey in the same client lifecycle.
+   */
   onDeepLink: (deepLink: string, link: ResolvedDeferredLink<Action>) => boolean | void | Promise<boolean | void>;
+  /** Same commit-boundary contract as `onDeepLink`. */
   onAction?: (link: ResolvedDeferredLink<Action>) => boolean | void | Promise<boolean | void>;
   accountBridge?: DeferredLinkAccountBridge<Action>;
   isAccountReady?: () => boolean;
@@ -179,11 +238,31 @@ export interface DeferredLinkClientOptions<Action extends string = DeferredLinkA
   requestTimeoutMs?: number;
   retryBaseMs?: number;
   retryMaxMs?: number;
+  /** Timeout for one terminal-result acknowledgement attempt. Defaults to requestTimeoutMs. */
+  terminalDeliveryTimeoutMs?: number;
   tokenMaxAgeMs?: number;
   recentInstallMaxAgeMs?: number;
   autoRetry?: boolean;
   reportResolverOutcomes?: boolean;
   onOutcome?: (event: DeferredLinkOutcomeEvent) => void | Promise<void>;
+  /**
+   * Synchronous privacy gate evaluated before a terminal record or eventId is created. A false
+   * result or throw completes first-open matching without retaining terminal metadata.
+   */
+  shouldQueueFirstOpenResult?: () => boolean;
+  /**
+   * Durable at-least-once terminal delivery. Return `accepted` (or legacy `true`) only after the
+   * stable eventId is durably accepted, `retry`/false to replay it, or `drop` to deliberately and
+   * durably discard it (for example after consent revocation). Throw, rejection and timeout retry
+   * the same eventId. `drop` is sticky: failed local deletion retries never re-enter the receiver.
+   * Receivers must deduplicate because a crash after acceptance can replay it. When this handler
+   * is absent no terminal record is created or retained.
+   */
+  onFirstOpenResult?: (
+    outcome: AnonymousFirstOpenTerminalOutcome,
+  ) => AnonymousFirstOpenTerminalDisposition
+    | boolean
+    | Promise<AnonymousFirstOpenTerminalDisposition | boolean>;
   onStateChange?: (state: DeferredLinkState) => void;
   onError?: (error: unknown) => void;
   now?: () => number;
@@ -255,6 +334,29 @@ const DEFAULT_ACTIONS = [
   'refresh_entitlement',
 ] as const;
 const DEFAULT_SENSITIVE_ACTIONS = ['manage_subscription', 'refresh_entitlement'] as const;
+const PROBABILISTIC_ACTIONS = new Set<string>(['open_home', 'open_premium']);
+const CAPTURE_PRIORITY: Readonly<Record<DeferredLinkCaptureBasis, number>> = {
+  direct_token: 3,
+  ios_user_paste: 2,
+  android_install_referrer: 1,
+};
+const NO_ROUTE_REASONS = new Set<AnonymousFirstOpenTerminalReason>([
+  'unmatched',
+  'ambiguous',
+  'holdout',
+  'low_confidence',
+  'shadow_would_route',
+  'shadow_attributed',
+  'analytics_attributed',
+  'target_revoked',
+  'disabled',
+  'expired_replay',
+]);
+const FAILURE_REASONS = new Set<AnonymousFirstOpenTerminalReason>([
+  'invalid_request',
+  'invalid_response',
+  'policy_rejected',
+]);
 const DEFAULT_STORAGE_KEY = 'pulse.links.v1';
 const DEFAULT_REQUEST_TIMEOUT_MS = 5_000;
 const DEFAULT_RETRY_BASE_MS = 15_000;
@@ -265,6 +367,7 @@ const MAX_APPLIED_IDS = 32;
 const MAX_NOTIFIED_OUTCOMES = MAX_APPLIED_IDS * 3;
 const MAX_RESOLVER_OUTCOMES = MAX_NOTIFIED_OUTCOMES;
 const MAX_PERSISTED_BYTES = 131_072;
+const ASYNCHRONOUS_STORAGE_ADAPTERS = new WeakSet<object>();
 const VERSION_SIGNAL = /^[A-Za-z0-9][A-Za-z0-9._+()-]*$/;
 const DEVICE_MODEL_CODE = /^[A-Za-z0-9][A-Za-z0-9._,+-]*$/;
 const DISTRIBUTION_SIGNAL = /^[a-z0-9][a-z0-9._-]*$/;
@@ -293,6 +396,24 @@ interface QueuedResolverOutcome {
   nextRetryAt: number;
 }
 
+interface QueuedFirstOpenTerminalDelivery extends AnonymousFirstOpenTerminalOutcome {
+  disposition?: never;
+  attempts: number;
+  nextRetryAt: number;
+}
+
+/** Minimal sticky privacy tombstone. It carries no terminal outcome or attribution metadata. */
+interface DroppedFirstOpenTerminalTombstone {
+  eventId: string;
+  disposition: 'drop';
+  attempts: number;
+  nextRetryAt: number;
+}
+
+type PersistedFirstOpenTerminalDelivery =
+  | QueuedFirstOpenTerminalDelivery
+  | DroppedFirstOpenTerminalTombstone;
+
 interface PersistedDeferredLinkState {
   version: 1;
   status: DeferredLinkStatus;
@@ -303,6 +424,8 @@ interface PersistedDeferredLinkState {
   notifiedOutcomes: string[];
   /** Durable Encore delivery queue. Exposure tokens stay local and are used only in URL paths. */
   outcomeQueue: QueuedResolverOutcome[];
+  /** One-record at-least-once application delivery outbox, independent of matcher completion. */
+  terminalDelivery: PersistedFirstOpenTerminalDelivery | null;
   firstOpen: DeferredLinkFirstOpenState;
 }
 
@@ -319,6 +442,7 @@ const emptyState = (): PersistedDeferredLinkState => ({
   appliedIds: [],
   notifiedOutcomes: [],
   outcomeQueue: [],
+  terminalDelivery: null,
   firstOpen: {
     installAttemptId: null,
     completed: false,
@@ -430,6 +554,12 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
   }
   const storageKey = explicitStorageKey || (appSlug ? `pulse.${appSlug}.links.v1` : DEFAULT_STORAGE_KEY);
   const requestTimeoutMs = boundedDuration(options.requestTimeoutMs, DEFAULT_REQUEST_TIMEOUT_MS, 500, 60_000);
+  const terminalDeliveryTimeoutMs = boundedDuration(
+    options.terminalDeliveryTimeoutMs,
+    requestTimeoutMs,
+    100,
+    60_000,
+  );
   const retryBaseMs = boundedDuration(options.retryBaseMs, DEFAULT_RETRY_BASE_MS, 100, 60 * 60 * 1_000);
   const retryMaxMs = boundedDuration(options.retryMaxMs, DEFAULT_RETRY_MAX_MS, retryBaseMs, 24 * 60 * 60 * 1_000);
   const tokenMaxAgeMs = boundedDuration(options.tokenMaxAgeMs, DEFAULT_TOKEN_MAX_AGE_MS, 60_000, 365 * 24 * 60 * 60 * 1_000);
@@ -443,11 +573,26 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
   let state = readState(options.storage, storageKey);
   let disposed = false;
   let processing: Promise<void> | null = null;
+  let firstOpenMatching: Promise<AnonymousFirstOpenResult> | null = null;
   let processRequested = false;
   let retryTimer: ReturnType<typeof setTimeout> | null = null;
   let outcomeSending: Promise<number> | null = null;
+  let terminalDeliverySending: Promise<boolean> | null = null;
+  let terminalDeliveryGeneration = 0;
   let accountRetryAt = 0;
   let accountAttempts = 0;
+  let deterministicEpoch = 0;
+  // Invalidates every host callback that crossed an await when this client is reset/disposed.
+  // This is deliberately separate from deterministicEpoch: captures during a committed callback
+  // have intentional last-touch semantics, whereas a lifecycle boundary must forbid every stale
+  // state write, retry and outcome from the old instance.
+  let lifecycleGeneration = 0;
+  // Host navigation is irreversible once any routing callback has started: it may perform its
+  // side effect synchronously before returning a Promise. Serialize captures against that commit
+  // boundary and keep the newer accepted token durable for the next client lifecycle instead of
+  // automatically opening a second journey behind the first one.
+  let routingApplicationInFlight = false;
+  let deterministicTokenDeferredAfterCommittedJourney: string | null = null;
   let lastFirstOpenContext: AnonymousFirstOpenContext | null = null;
   let unsubscribeAccount: (() => void) | null = null;
   const listeners = new Set<(value: DeferredLinkState) => void>();
@@ -456,6 +601,24 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
     try { options.onError?.(error); } catch { /* diagnostic hooks never break link handling */ }
   };
 
+  // A build without a receiver has not opted into retaining this analytics envelope. First replace
+  // an old full record with the same minimal sticky tombstone used by an explicit drop. Deletion
+  // may fail, but a later app version can then only retry local deletion, never resurrect delivery.
+  if (!options.onFirstOpenResult
+    && state.terminalDelivery
+    && state.terminalDelivery.disposition !== 'drop') {
+    const tombstone: DroppedFirstOpenTerminalTombstone = {
+      eventId: state.terminalDelivery.eventId,
+      disposition: 'drop',
+      attempts: state.terminalDelivery.attempts,
+      nextRetryAt: 0,
+    };
+    state = { ...state, terminalDelivery: tombstone };
+    if (!writeState(options.storage, storageKey, state)) {
+      reportError(new Error('Pulse Links: stale terminal delivery tombstone was not persisted'));
+    }
+  }
+
   const snapshot = (): DeferredLinkState => ({
     status: state.status,
     pending: state.pending ? { ...state.pending } : null,
@@ -464,8 +627,7 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
     firstOpen: { ...state.firstOpen },
   });
 
-  const persistAndNotify = (): void => {
-    writeState(options.storage, storageKey, state);
+  const notifyState = (): void => {
     const value = snapshot();
     for (const listener of listeners) {
       try { listener(value); } catch (error) { reportError(error); }
@@ -474,6 +636,12 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
     scheduleWake();
   };
 
+  const persistAndNotify = (): boolean => {
+    const persisted = writeState(options.storage, storageKey, state);
+    notifyState();
+    return persisted;
+  };
+
   const patchState = (patch: Partial<PersistedDeferredLinkState>): void => {
     state = { ...state, ...patch };
     persistAndNotify();
@@ -484,11 +652,257 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
     persistAndNotify();
   };
 
-  const isAccountReady = (): boolean => {
-    try { return options.isAccountReady?.() ?? false; } catch (error) {
-      reportError(error);
+  const terminalDeliveryOutcome = (
+    queued: QueuedFirstOpenTerminalDelivery,
+  ): AnonymousFirstOpenTerminalOutcome => ({
+    eventId: queued.eventId,
+    status: queued.status,
+    rail: queued.rail,
+    routed: queued.routed,
+    retryable: false,
+    reason: queued.reason,
+    occurredAt: queued.occurredAt,
+    ...(queued.matchBasis !== undefined ? { matchBasis: queued.matchBasis } : {}),
+    ...(queued.confidence !== undefined ? { confidence: queued.confidence } : {}),
+    ...(queued.campaignId !== undefined ? { campaignId: queued.campaignId } : {}),
+    ...(queued.experimentId !== undefined ? { experimentId: queued.experimentId } : {}),
+    ...(queued.variantId !== undefined ? { variantId: queued.variantId } : {}),
+  });
+
+  const scheduleTerminalDeliveryRetry = (
+    queued: PersistedFirstOpenTerminalDelivery,
+  ): void => {
+    if (disposed || state.terminalDelivery?.eventId !== queued.eventId) return;
+    const attempts = Math.min(queued.attempts + 1, 100_000);
+    state = {
+      ...state,
+      terminalDelivery: {
+        ...queued,
+        attempts,
+        nextRetryAt: now() + resolverOutcomeRetryDelay(
+          queued.eventId,
+          attempts,
+          retryBaseMs,
+          retryMaxMs,
+        ),
+      },
+    };
+    persistAndNotify();
+  };
+
+  const acknowledgeTerminalDelivery = (
+    queued: PersistedFirstOpenTerminalDelivery,
+  ): boolean => {
+    if (disposed || state.terminalDelivery?.eventId !== queued.eventId) return false;
+    const acknowledgedState: PersistedDeferredLinkState = {
+      ...state,
+      terminalDelivery: null,
+    };
+    // Clearing the record is itself transactional. If this write fails after the receiver
+    // accepted the event, retain and replay the same eventId: that is why the contract is
+    // at-least-once and why receivers must deduplicate.
+    if (!writeState(options.storage, storageKey, acknowledgedState, false)) {
+      reportError(new Error('Pulse Links: terminal delivery acknowledgement was not persisted'));
+      scheduleTerminalDeliveryRetry(queued);
+      return false;
+    }
+    state = acknowledgedState;
+    notifyState();
+    return true;
+  };
+
+  const flushTerminalDelivery = (): Promise<boolean> => {
+    if (disposed) return Promise.resolve(false);
+    if (terminalDeliverySending) return terminalDeliverySending;
+    const queued = state.terminalDelivery;
+    if (!queued || queued.nextRetryAt > now()) return Promise.resolve(false);
+    if (queued.disposition === 'drop') {
+      return Promise.resolve(acknowledgeTerminalDelivery(queued));
+    }
+    if (!options.onFirstOpenResult) return Promise.resolve(false);
+    const generation = terminalDeliveryGeneration;
+
+    const run = async (): Promise<boolean> => {
+      // Never call the receiver before the complete record is durable. With no storage adapter,
+      // this is an explicitly memory-only degradation rather than a cross-restart guarantee.
+      if (!writeState(options.storage, storageKey, state)) {
+        reportError(new Error('Pulse Links: terminal delivery outbox was not persisted'));
+        scheduleTerminalDeliveryRetry(queued);
+        return false;
+      }
+
+      let rawDisposition:
+        | AnonymousFirstOpenTerminalDisposition
+        | boolean
+        | Promise<AnonymousFirstOpenTerminalDisposition | boolean>;
+      try {
+        rawDisposition = options.onFirstOpenResult!(terminalDeliveryOutcome(queued));
+      } catch (error) {
+        reportError(error);
+        scheduleTerminalDeliveryRetry(queued);
+        return false;
+      }
+
+      let disposition: AnonymousFirstOpenTerminalDisposition;
+      if (typeof rawDisposition === 'boolean' || typeof rawDisposition === 'string') {
+        disposition = normalizeTerminalDeliveryDisposition(rawDisposition);
+      } else {
+        try {
+          const resolved = await withTerminalDeliveryTimeout(
+            Promise.resolve(rawDisposition),
+            terminalDeliveryTimeoutMs,
+          );
+          disposition = normalizeTerminalDeliveryDisposition(resolved);
+        } catch (error) {
+          if (!disposed && terminalDeliveryGeneration === generation) reportError(error);
+          if (!disposed && terminalDeliveryGeneration === generation) {
+            scheduleTerminalDeliveryRetry(queued);
+          }
+          return false;
+        }
+      }
+
+      if (disposed
+        || terminalDeliveryGeneration !== generation
+        || state.terminalDelivery?.eventId !== queued.eventId) return false;
+      if (disposition === 'accepted') return acknowledgeTerminalDelivery(queued);
+      if (disposition === 'drop') return dropTerminalDelivery(queued);
+      scheduleTerminalDeliveryRetry(queued);
+      return false;
+    };
+
+    let owned: Promise<boolean>;
+    owned = run().finally(() => {
+      if (terminalDeliverySending === owned) terminalDeliverySending = null;
+      const pending = state.terminalDelivery;
+      if (!disposed && options.onFirstOpenResult && pending && pending.nextRetryAt <= now()) {
+        void flushTerminalDelivery();
+      }
+    });
+    terminalDeliverySending = owned;
+    return owned;
+  };
+
+  const dropTerminalDelivery = (
+    queued: QueuedFirstOpenTerminalDelivery,
+  ): boolean => {
+    if (disposed || state.terminalDelivery?.eventId !== queued.eventId) return false;
+    const tombstone: DroppedFirstOpenTerminalTombstone = {
+      eventId: queued.eventId,
+      disposition: 'drop',
+      attempts: queued.attempts,
+      nextRetryAt: 0,
+    };
+    state = { ...state, terminalDelivery: tombstone };
+    // Persist the sticky disposition before trying to delete it. A failed local deletion can then
+    // retry only deletion after restart; it must never call the receiver or resurrect collection.
+    if (!writeState(options.storage, storageKey, state)) {
+      reportError(new Error('Pulse Links: terminal drop tombstone was not persisted'));
+      scheduleTerminalDeliveryRetry(tombstone);
       return false;
     }
+    notifyState();
+    return acknowledgeTerminalDelivery(tombstone);
+  };
+
+  const completeFirstOpen = (
+    status: DeferredLinkStatus,
+    outcome: Omit<AnonymousFirstOpenTerminalOutcome, 'eventId' | 'occurredAt' | 'retryable'>,
+  ): void => {
+    const completionLifecycleGeneration = lifecycleGeneration;
+    const completionDeterministicEpoch = deterministicEpoch;
+    const completionIsCurrent = (): boolean => !disposed
+      && lifecycleGeneration === completionLifecycleGeneration
+      && deterministicEpoch === completionDeterministicEpoch;
+    let shouldQueue = Boolean(options.onFirstOpenResult);
+    if (shouldQueue && options.shouldQueueFirstOpenResult) {
+      try {
+        shouldQueue = options.shouldQueueFirstOpenResult() === true;
+      } catch (error) {
+        shouldQueue = false;
+        reportError(error);
+      }
+      // Privacy/diagnostic hooks are host code and may synchronously reset, dispose, or capture a
+      // deterministic destination. Never resurrect the terminal first-open state they invalidated.
+      if (!completionIsCurrent()) return;
+    }
+    if (!shouldQueue) {
+      state = {
+        ...state,
+        status,
+        terminalDelivery: null,
+        firstOpen: {
+          ...state.firstOpen,
+          completed: true,
+          attempts: 0,
+          nextRetryAt: 0,
+        },
+      };
+      persistAndNotify();
+      return;
+    }
+
+    const existingEventIds = new Set<string>([
+      ...state.outcomeQueue.map((queued) => queued.eventId),
+      ...(state.firstOpen.installAttemptId ? [state.firstOpen.installAttemptId] : []),
+      ...(state.terminalDelivery ? [state.terminalDelivery.eventId] : []),
+    ]);
+    const delivery = state.terminalDelivery ?? {
+      ...outcome,
+      eventId: makeOutcomeEventId(options.randomUUID, existingEventIds),
+      retryable: false as const,
+      occurredAt: new Date(now()).toISOString(),
+      attempts: 0,
+      nextRetryAt: 0,
+    };
+    state = {
+      ...state,
+      status,
+      terminalDelivery: delivery,
+      firstOpen: {
+        ...state.firstOpen,
+        completed: true,
+        attempts: 0,
+        nextRetryAt: 0,
+      },
+    };
+    if (!persistAndNotify()) {
+      reportError(new Error('Pulse Links: terminal delivery outbox was not persisted'));
+    }
+    // Delivery is deliberately detached from routing/matcher completion.
+    void flushTerminalDelivery();
+  };
+
+  const blockFirstOpenForDeterministic = (): boolean => {
+    const blockingLifecycleGeneration = lifecycleGeneration;
+    deterministicEpoch += 1;
+    const blockingDeterministicEpoch = deterministicEpoch;
+    if (state.firstOpen.completed && state.firstOpen.nextRetryAt === 0) return true;
+    state = {
+      ...state,
+      firstOpen: { ...state.firstOpen, completed: true, nextRetryAt: 0 },
+    };
+    persistAndNotify();
+    return !disposed
+      && lifecycleGeneration === blockingLifecycleGeneration
+      && deterministicEpoch === blockingDeterministicEpoch;
+  };
+
+  const readAccountReadiness = (): { ready: boolean; current: boolean } => {
+    const readinessLifecycleGeneration = lifecycleGeneration;
+    const readinessDeterministicEpoch = deterministicEpoch;
+    let ready = false;
+    try { ready = options.isAccountReady?.() ?? false; } catch (error) {
+      reportError(error);
+    }
+    return {
+      ready,
+      // Readiness is host code, not a pure getter. A reset/dispose/capture inside it invalidates
+      // the caller's snapshot and must be observed before any waiting/retry/application write.
+      current: !disposed
+        && lifecycleGeneration === readinessLifecycleGeneration
+        && deterministicEpoch === readinessDeterministicEpoch,
+    };
   };
 
   const schedulePendingRetry = (): void => {
@@ -723,7 +1137,9 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
         if (!sourceToken || state.pending?.token === sourceToken) clearPendingAsTerminal();
         return false;
       }
-      if (!isAccountReady()) {
+      const accountReadiness = readAccountReadiness();
+      if (!accountReadiness.current) return false;
+      if (!accountReadiness.ready) {
         patchState({ status: 'waiting_for_account' });
         return false;
       }
@@ -740,9 +1156,36 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
       return false;
     }
 
+    let applied: boolean | void = false;
+    let applicationFailed = false;
+    let applicationError: unknown;
+    const applicationEpoch = deterministicEpoch;
+    const applicationLifecycleGeneration = lifecycleGeneration;
+    const lifecycleIsCurrent = (): boolean => !disposed
+      && lifecycleGeneration === applicationLifecycleGeneration;
+    const hasNewerPendingIntent = (): boolean => deterministicEpoch !== applicationEpoch
+      && state.pending !== null
+      // A provenance upgrade or rejected lower-priority capture for the token already being
+      // applied does not represent another destination and must not leave that token pending.
+      && (sourceToken === null || state.pending.token !== sourceToken);
+    routingApplicationInFlight = true;
     emitOutcome(link, 'app_open_confirmed');
+    if (!lifecycleIsCurrent()) {
+      routingApplicationInFlight = false;
+      return false;
+    }
     emitOutcome(link, 'deferred_link_resolved');
-    let applied: boolean | void;
+    if (!lifecycleIsCurrent()) {
+      routingApplicationInFlight = false;
+      return false;
+    }
+    // `emitOutcome` invokes host diagnostics synchronously. If those hooks re-enter capture with
+    // a newer accepted destination, it still arrived before the routing callback and must win.
+    if (hasNewerPendingIntent()) {
+      routingApplicationInFlight = false;
+      void process();
+      return false;
+    }
     try {
       if (link.deepLink) {
         applied = await options.onDeepLink(link.deepLink, link);
@@ -753,24 +1196,60 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
         return false;
       }
     } catch (error) {
-      reportError(error);
+      applicationFailed = true;
+      applicationError = error;
+    } finally {
+      routingApplicationInFlight = false;
+    }
+
+    // The callback may resolve after reset/dispose and after another client has already committed
+    // a newer journey into the same storage. The old instance must not schedule a retry, rewrite
+    // state, or emit action_applied regardless of whether the callback returned true/false/threw.
+    if (!lifecycleIsCurrent()) return false;
+
+    const newerIntentArrivedDuringApplication = hasNewerPendingIntent();
+    if (applicationFailed) {
+      reportError(applicationError);
+      if (!lifecycleIsCurrent()) return false;
+      // onError is host code too: it may capture a newer deterministic destination while reporting
+      // this failure. Re-evaluate after the callback instead of arming a stale retry from the value
+      // observed before diagnostics ran.
+      if (hasNewerPendingIntent()) {
+        // The current action did not commit. Resume the newer accepted intent that was captured
+        // while its callback was suspended, without scheduling a retry for the superseded one.
+        void process();
+        return false;
+      }
       if (sourceToken && state.pending?.token === sourceToken) schedulePendingRetry();
       else if (link.matchBasis === 'unique_probabilistic') scheduleFirstOpenRetry();
       else scheduleAccountRetry();
       return false;
     }
     if (applied === false) {
+      if (newerIntentArrivedDuringApplication) {
+        void process();
+        return false;
+      }
       if (sourceToken && state.pending?.token === sourceToken) schedulePendingRetry();
       else if (link.matchBasis === 'unique_probabilistic') scheduleFirstOpenRetry();
       else scheduleAccountRetry();
       return false;
     }
 
+    if (newerIntentArrivedDuringApplication) {
+      // Invocation of any host routing callback is the last safe commit boundary. A successful
+      // callback may already have navigated, so automatically applying the newly captured token
+      // now would create two journeys. Keep it pending and let a fresh SDK lifecycle recover it.
+      deterministicTokenDeferredAfterCommittedJourney = state.pending!.token;
+    }
+
     const newlyApplied = sourceToken && sourceToken !== link.id ? [link.id, sourceToken] : [link.id];
     const newlyAppliedSet = new Set(newlyApplied);
     const appliedIds = [...state.appliedIds.filter((id) => !newlyAppliedSet.has(id)), ...newlyApplied]
       .slice(-MAX_APPLIED_IDS);
-    const stillPending = sourceToken !== null && state.pending?.token !== sourceToken;
+    const stillPending = sourceToken !== null
+      ? state.pending?.token !== sourceToken
+      : newerIntentArrivedDuringApplication;
     state = {
       ...state,
       status: stillPending ? 'pending' : 'applied',
@@ -779,12 +1258,16 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
       appliedIds,
     };
     persistAndNotify();
+    if (!lifecycleIsCurrent()) return false;
     if (link.matchBasis === 'account_bound') {
       accountAttempts = 0;
       accountRetryAt = 0;
     }
     emitOutcome(link, 'action_applied');
-    if (stillPending) void process();
+    if (!lifecycleIsCurrent()) return false;
+    if (stillPending && state.pending?.token !== deterministicTokenDeferredAfterCommittedJourney) {
+      void process();
+    }
     return true;
   };
 
@@ -822,17 +1305,28 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
 
   const processOnce = async (): Promise<void> => {
     if (disposed) return;
+    // `capture()` can re-enter while any host callback is awaiting. Never start another routing
+    // application concurrently, and never auto-drain the exact token preserved after an already
+    // committed journey in this client lifecycle.
+    if (routingApplicationInFlight) return;
     const pending = state.pending;
     if (pending) {
+      if (pending.token === deterministicTokenDeferredAfterCommittedJourney) return;
       if (pending.nextRetryAt > now()) return;
       if (now() - pending.receivedAt > tokenMaxAgeMs) {
         clearPendingAsTerminal();
         return;
       }
       const token = pending.token;
+      const pendingLifecycleGeneration = lifecycleGeneration;
       patchState({ status: 'resolving' });
+      if (disposed
+        || lifecycleGeneration !== pendingLifecycleGeneration
+        || state.pending?.token !== token) return;
       const publicResult = await resolvePublic(token, pending.matchBasis);
-      if (disposed || state.pending?.token !== token) return;
+      if (disposed
+        || lifecycleGeneration !== pendingLifecycleGeneration
+        || state.pending?.token !== token) return;
       if (publicResult.kind === 'resolved') {
         await applyResolved(publicResult.link, token);
         return;
@@ -842,13 +1336,28 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
         return;
       }
 
-      if (!options.accountBridge || !isAccountReady()) {
+      if (!options.accountBridge) {
+        patchState({ status: 'waiting_for_account' });
+        return;
+      }
+      const accountReadiness = readAccountReadiness();
+      if (!accountReadiness.current
+        || disposed
+        || lifecycleGeneration !== pendingLifecycleGeneration
+        || state.pending?.token !== token) return;
+      if (!accountReadiness.ready) {
         patchState({ status: 'waiting_for_account' });
         return;
       }
       try {
-        const raw = await options.accountBridge.claim(token);
-        if (disposed || state.pending?.token !== token) return;
+        const raw = await withPromiseTimeout(
+          () => options.accountBridge!.claim(token),
+          requestTimeoutMs,
+          'account claim',
+        );
+        if (disposed
+          || lifecycleGeneration !== pendingLifecycleGeneration
+          || state.pending?.token !== token) return;
         const normalizedClaim = normalizeResolved<Action>(
           raw,
           token,
@@ -862,18 +1371,42 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
           matchGuaranteed: true,
           confidence: 1,
         } : null;
-        if (claimed) await applyResolved(claimed, token);
+        if (claimed) {
+          if (!blockFirstOpenForDeterministic()) return;
+          await applyResolved(claimed, token);
+        }
         else clearPendingAsTerminal();
       } catch (error) {
+        if (disposed
+          || lifecycleGeneration !== pendingLifecycleGeneration
+          || state.pending?.token !== token) return;
         reportError(error);
-        if (state.pending?.token === token) schedulePendingRetry();
+        if (!disposed
+          && lifecycleGeneration === pendingLifecycleGeneration
+          && state.pending?.token === token) schedulePendingRetry();
       }
       return;
     }
 
-    if (!options.accountBridge || !isAccountReady() || accountRetryAt > now()) return;
+    if (!options.accountBridge) return;
+    const accountReadiness = readAccountReadiness();
+    if (!accountReadiness.current || state.pending) return;
+    if (!accountReadiness.ready || accountRetryAt > now()) return;
+    const accountPendingEpoch = deterministicEpoch;
+    const accountPendingLifecycleGeneration = lifecycleGeneration;
     try {
-      const raw = await options.accountBridge.pending();
+      const raw = await withPromiseTimeout(
+        () => options.accountBridge!.pending(),
+        requestTimeoutMs,
+        'account pending',
+      );
+      // A URL/paste/referrer captured while the account lookup was in flight is newer explicit
+      // user intent. Ignore the stale bridge response and let the requested drain resolve the
+      // captured token; otherwise both deterministic destinations could be applied.
+      if (disposed
+        || lifecycleGeneration !== accountPendingLifecycleGeneration
+        || deterministicEpoch !== accountPendingEpoch
+        || state.pending) return;
       if (!raw) {
         accountAttempts = 0;
         accountRetryAt = 0;
@@ -898,13 +1431,27 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
         matchGuaranteed: true,
         confidence: 1,
       } : null;
-      if (pendingLink && !state.appliedIds.includes(pendingLink.id)) {
-        await applyResolved(pendingLink, null);
-      } else if (pendingLink && state.status !== 'applied') {
-        patchState({ status: 'applied' });
+      if (pendingLink) {
+        // Reserve the first-open journey for deterministic recovery before invoking any host
+        // callback. This also covers an already-applied account item restored from older SDK
+        // state, which must still prevent a second probabilistic destination.
+        if (!blockFirstOpenForDeterministic()) return;
+        if (!state.appliedIds.includes(pendingLink.id)) {
+          await applyResolved(pendingLink, null);
+        } else if (state.status !== 'applied') {
+          patchState({ status: 'applied' });
+        }
       }
     } catch (error) {
+      if (disposed
+        || lifecycleGeneration !== accountPendingLifecycleGeneration
+        || deterministicEpoch !== accountPendingEpoch
+        || state.pending) return;
       reportError(error);
+      if (disposed
+        || lifecycleGeneration !== accountPendingLifecycleGeneration
+        || deterministicEpoch !== accountPendingEpoch
+        || state.pending) return;
       // No token was consumed; the authenticated server outbox remains authoritative.
       scheduleAccountRetry();
     }
@@ -912,6 +1459,8 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
 
   const process = async (): Promise<void> => {
     if (disposed) return;
+    // Application delivery is independent: never await it on the routing drain.
+    void flushTerminalDelivery();
     processRequested = true;
     if (processing) return processing;
     const run = (async () => {
@@ -938,11 +1487,13 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
     const token = normalizeDeferredHandoffToken(rawToken);
     if (!token) return false;
     if (state.appliedIds.includes(token)) {
+      deterministicEpoch += 1;
       if (!state.firstOpen.completed) patchFirstOpen({ completed: true, nextRetryAt: 0 });
       return true;
     }
     if (state.pending?.token === token) {
-      if (state.pending.matchBasis === 'direct_token' && basis !== 'direct_token') {
+      deterministicEpoch += 1;
+      if (CAPTURE_PRIORITY[basis] > CAPTURE_PRIORITY[state.pending.matchBasis]) {
         state = {
           ...state,
           pending: { ...state.pending, matchBasis: basis },
@@ -955,6 +1506,19 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
       void process();
       return true;
     }
+
+    // Exact transports are deterministic, but when more than one arrives during cold start their
+    // provenance still has an explicit precedence. A lower-priority late callback must not replace
+    // the URL the user intentionally opened; equal priority keeps last-touch behaviour.
+    if (state.pending
+      && CAPTURE_PRIORITY[basis] < CAPTURE_PRIORITY[state.pending.matchBasis]) {
+      deterministicEpoch += 1;
+      if (!state.firstOpen.completed) patchFirstOpen({ completed: true, nextRetryAt: 0 });
+      void process();
+      return true;
+    }
+
+    deterministicEpoch += 1;
     state = {
       ...state,
       status: 'pending',
@@ -976,18 +1540,45 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
     return true;
   };
 
-  const matchFirstOpen = async (
+  const matchFirstOpenOnce = async (
     context: AnonymousFirstOpenContext,
   ): Promise<AnonymousFirstOpenResult> => {
     if (disposed) return 'ineligible';
     lastFirstOpenContext = context;
     if (state.pending) return 'deterministic_pending';
     if (state.firstOpen.completed) return 'already_completed';
-    if (state.firstOpen.nextRetryAt > now()) return 'backoff';
+    if (state.firstOpen.nextRetryAt > now()) {
+      // On a fresh client lifecycle scheduleWake() ran before the host supplied this ephemeral
+      // context, so the persisted first-open deadline could not be part of its candidates. Re-arm
+      // now that retrying is possible; otherwise a 503 followed by process death remains asleep
+      // until some unrelated foreground/manual call invokes matchFirstOpen again.
+      scheduleWake();
+      return 'backoff';
+    }
+    if (!isEligibleFirstOpen(context, now(), recentInstallMaxAgeMs)) return 'ineligible';
+
+    // The client starts account recovery at construction. Join that deterministic rail before
+    // asking the probabilistic matcher; otherwise a slow Billing/account response can navigate
+    // after the probabilistic destination and the user observes both journeys.
+    await process();
+    if (disposed) return 'ineligible';
+    if (state.pending || state.firstOpen.completed) return 'deterministic_pending';
+    if (options.accountBridge) {
+      const accountReadiness = readAccountReadiness();
+      if (!accountReadiness.current) {
+        return disposed ? 'ineligible' : 'deterministic_pending';
+      }
+      if (accountReadiness.ready && accountRetryAt > now()) {
+        if (state.firstOpen.nextRetryAt === 0) scheduleFirstOpenRetry();
+        return 'retry_scheduled';
+      }
+    }
     if (!isEligibleFirstOpen(context, now(), recentInstallMaxAgeMs)) return 'ineligible';
 
     const installAttemptId = state.firstOpen.installAttemptId
       ?? makeInstallAttemptId(options.randomUUID);
+    const startingDeterministicEpoch = deterministicEpoch;
+    const startingLifecycleGeneration = lifecycleGeneration;
     state = {
       ...state,
       status: 'resolving',
@@ -997,8 +1588,35 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
         attemptedAt: now(),
       },
     };
-    persistAndNotify();
+    const firstOpenReservationPersisted = persistAndNotify();
+    // Persistence notifies host state hooks synchronously. They may reset/dispose this client or
+    // capture a deterministic destination. In all three cases the reserved id no longer belongs to
+    // the current lifecycle and must never cross the network boundary.
+    if (disposed) return 'ineligible';
+    if (lifecycleGeneration !== startingLifecycleGeneration
+      || deterministicEpoch !== startingDeterministicEpoch
+      || state.pending
+      || state.firstOpen.completed) return 'deterministic_pending';
+    if (options.storage && !firstOpenReservationPersisted) {
+      // An unpersisted id must never leave the process: after a crash the retry would mint a new
+      // id and the server could count/route the same install twice. Keep the exact nonce in memory,
+      // arm a persistence retry without incrementing matcher attempts, and send nothing until a
+      // synchronous durable write succeeds. Memory-only clients have no restart contract and may
+      // continue normally.
+      state = {
+        ...state,
+        status: 'retryable_error',
+        firstOpen: {
+          ...state.firstOpen,
+          nextRetryAt: now() + retryBaseMs,
+        },
+      };
+      reportError(new Error('Pulse Links: first-open install attempt id was not durably persisted'));
+      notifyState();
+      return 'retry_scheduled';
+    }
 
+    const accountEmail = normalizeAccountEmail(context.accountEmail);
     const body = {
       appBundleId: context.appBundleId.trim(),
       platform: 'ios' as const,
@@ -1006,6 +1624,10 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
       firstOpen: true,
       installAttemptId,
       ...normalizeAnonymousFirstOpenSignals(context),
+      // Sent only when the app already knows it. The resolver treats an address that matches
+      // exactly one recent message as proof of origin; anything else falls back to the
+      // probabilistic path, so a shared or unknown address costs nothing.
+      ...(accountEmail ? { accountEmail } : {}),
     };
     try {
       const response = await withTimeout(
@@ -1018,16 +1640,27 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
         },
         requestTimeoutMs,
       );
-      if (state.pending) return 'deterministic_pending';
-      if (state.firstOpen.completed) return 'deterministic_pending';
+      if (disposed) return 'ineligible';
+      if (deterministicEpoch !== startingDeterministicEpoch
+        || state.pending
+        || state.firstOpen.completed) return 'deterministic_pending';
       if (response.status === 204) {
-        patchFirstOpen({ completed: true, attempts: 0, nextRetryAt: 0 });
-        patchState({ status: 'idle' });
+        completeFirstOpen('idle', {
+          status: 'NOT_FOUND',
+          rail: 'no_route',
+          routed: false,
+          reason: firstOpenNoRouteReason(response),
+        });
         return 'no_match';
       }
-      if (response.status === 400 || response.status === 404 || response.status === 410) {
-        patchFirstOpen({ completed: true, nextRetryAt: 0 });
-        patchState({ status: 'terminal_error' });
+      if (response.status === 400 || response.status === 404
+        || response.status === 410 || response.status === 413) {
+        completeFirstOpen('terminal_error', {
+          status: 'FAILURE',
+          rail: 'no_route',
+          routed: false,
+          reason: 'invalid_request',
+        });
         return 'terminal_error';
       }
       if (!response.ok) {
@@ -1035,41 +1668,118 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
           scheduleFirstOpenRetry();
           return 'retry_scheduled';
         }
-        patchFirstOpen({ completed: true, nextRetryAt: 0 });
-        patchState({ status: 'terminal_error' });
+        completeFirstOpen('terminal_error', {
+          status: 'FAILURE',
+          rail: 'no_route',
+          routed: false,
+          reason: 'invalid_response',
+        });
+        return 'terminal_error';
+      }
+      let rawLink: unknown;
+      try {
+        rawLink = await response.json();
+      } catch {
+        completeFirstOpen('terminal_error', {
+          status: 'FAILURE',
+          rail: 'no_route',
+          routed: false,
+          reason: 'invalid_response',
+        });
         return 'terminal_error';
       }
+      if (disposed) return 'ineligible';
+      if (deterministicEpoch !== startingDeterministicEpoch
+        || state.pending
+        || state.firstOpen.completed) return 'deterministic_pending';
       const link = normalizeResolved<Action>(
-        await response.json(),
+        rawLink,
         installAttemptId.replace(/-/g, ''),
         'unique_probabilistic',
         allowedActions,
         now(),
       );
-      // The probabilistic endpoint can personalize harmless UX only. It can never upgrade its own
-      // evidence to guaranteed or return a deterministic/account basis.
-      if (!link || link.matchBasis !== 'unique_probabilistic' || link.matchGuaranteed
-        || (link.action && sensitiveActions.has(link.action))) {
-        patchFirstOpen({ completed: true, nextRetryAt: 0 });
-        patchState({ status: 'terminal_error' });
+      if (!link) {
+        completeFirstOpen('terminal_error', {
+          status: 'FAILURE',
+          rail: 'no_route',
+          routed: false,
+          reason: 'invalid_response',
+        });
         return 'terminal_error';
       }
+      // A probabilistic result is navigation intent, never a remote URL transport. Only the two
+      // harmless closed discovery actions are accepted; all billing/account/entitlement actions
+      // and even an app-owned deepLink are rejected before application code runs.
+      if (link.matchBasis !== 'unique_probabilistic'
+        || link.matchGuaranteed
+        || link.deepLink !== undefined
+        || !link.action
+        || !PROBABILISTIC_ACTIONS.has(String(link.action))
+        || sensitiveActions.has(link.action)
+        || !options.onAction) {
+        completeFirstOpen('terminal_error', {
+          status: 'FAILURE',
+          rail: 'no_route',
+          routed: false,
+          reason: 'policy_rejected',
+        });
+        return 'terminal_error';
+      }
+      if (deterministicEpoch !== startingDeterministicEpoch
+        || state.pending
+        || state.firstOpen.completed) return 'deterministic_pending';
       if (await applyResolved(link, null)) {
-        patchFirstOpen({ completed: true, attempts: 0, nextRetryAt: 0 });
+        // `applyResolved()` returns true only after the host callback crossed its irreversible
+        // commit boundary successfully. A deterministic capture can arrive while that callback
+        // awaits; it remains pending for the next lifecycle, but it must not erase the terminal
+        // truth that this probabilistic journey really routed.
+        completeFirstOpen(state.pending ? 'pending' : 'applied', {
+          status: 'FOUND',
+          rail: 'fast_route',
+          routed: true,
+          reason: 'matched',
+          matchBasis: link.matchBasis,
+          confidence: link.confidence,
+          ...(link.campaignId !== undefined ? { campaignId: link.campaignId } : {}),
+          ...(link.experimentId !== undefined ? { experimentId: link.experimentId } : {}),
+          ...(link.variantId !== undefined ? { variantId: link.variantId } : {}),
+        });
         return 'matched';
       }
+      if (deterministicEpoch !== startingDeterministicEpoch
+        || state.pending
+        || state.firstOpen.completed) return 'deterministic_pending';
       if (state.firstOpen.nextRetryAt === 0) scheduleFirstOpenRetry();
       return 'retry_scheduled';
     } catch (error) {
+      if (disposed) return 'ineligible';
       reportError(error);
+      if (deterministicEpoch !== startingDeterministicEpoch
+        || state.pending
+        || state.firstOpen.completed) return 'deterministic_pending';
       scheduleFirstOpenRetry();
       return 'retry_scheduled';
     }
   };
 
+  const matchFirstOpen = (
+    context: AnonymousFirstOpenContext,
+  ): Promise<AnonymousFirstOpenResult> => {
+    if (firstOpenMatching) return firstOpenMatching;
+    let owned: Promise<AnonymousFirstOpenResult>;
+    owned = matchFirstOpenOnce(context).finally(() => {
+      if (firstOpenMatching === owned) firstOpenMatching = null;
+    });
+    firstOpenMatching = owned;
+    return owned;
+  };
+
   const captureAndroidInstallReferrer = async (
     bridge: AndroidInstallReferrerBridge,
   ): Promise<AndroidInstallReferrerResult> => {
+    const referrerLifecycleGeneration = lifecycleGeneration;
+    const referrerDeterministicEpoch = deterministicEpoch;
     let raw: unknown;
     try {
       raw = await bridge.getDeferredHandoff();
@@ -1078,6 +1788,9 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
       return { status: 'SERVICE_UNAVAILABLE', retryable: true, attempts: 0 };
     }
     const result = normalizeAndroidInstallReferrerResult(raw);
+    if (disposed
+      || lifecycleGeneration !== referrerLifecycleGeneration
+      || deterministicEpoch !== referrerDeterministicEpoch) return result;
     if (result.status === 'OK' && result.token) {
       capture(result.token, 'android_install_referrer');
     }
@@ -1095,6 +1808,7 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
       lastFirstOpenContext ? state.firstOpen.nextRetryAt : 0,
       accountRetryAt,
       state.outcomeQueue[0]?.nextRetryAt ?? 0,
+      state.terminalDelivery?.nextRetryAt ?? 0,
     ].filter((value) => value > now());
     if (candidates.length === 0) return;
     const next = Math.min(...candidates);
@@ -1102,6 +1816,7 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
       retryTimer = null;
       void process();
       void flushResolverOutcomes();
+      void flushTerminalDelivery();
       if (lastFirstOpenContext && state.firstOpen.nextRetryAt <= now()) {
         void matchFirstOpen(lastFirstOpenContext);
       }
@@ -1120,6 +1835,7 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
   scheduleWake();
   void process();
   void flushResolverOutcomes();
+  void flushTerminalDelivery();
 
   return {
     capture,
@@ -1138,6 +1854,9 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
     dispose: () => {
       if (disposed) return;
       disposed = true;
+      lifecycleGeneration += 1;
+      deterministicEpoch += 1;
+      terminalDeliveryGeneration += 1;
       if (retryTimer) clearTimeout(retryTimer);
       retryTimer = null;
       unsubscribeAccount?.();
@@ -1147,6 +1866,11 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
     reset: () => {
       accountRetryAt = 0;
       accountAttempts = 0;
+      lifecycleGeneration += 1;
+      deterministicEpoch += 1;
+      terminalDeliveryGeneration += 1;
+      terminalDeliverySending = null;
+      deterministicTokenDeferredAfterCommittedJourney = null;
       state = emptyState();
       persistAndNotify();
     },
@@ -1199,11 +1923,11 @@ function stableOutcomeKey(linkId: string, name: DeferredLinkOutcomeName): string
   return `${first.toString(16).padStart(8, '0')}${second.toString(16).padStart(8, '0')}|${name}`;
 }
 
-function boundedMetadata(value: unknown): string | null | undefined {
+function boundedMetadata(value: unknown, maxLength = 256): string | null | undefined {
   if (value === null) return null;
   if (typeof value !== 'string' && typeof value !== 'number') return undefined;
   const result = String(value).trim();
-  return result.length > 0 && result.length <= 256 ? result : undefined;
+  return result.length > 0 && result.length <= maxLength ? result : undefined;
 }
 
 function normalizeResolved<Action extends string>(
@@ -1246,9 +1970,9 @@ function normalizeResolved<Action extends string>(
     if (!Number.isFinite(expiry) || expiry <= now) return null;
   }
   const source = boundedMetadata(value.source);
-  const campaignId = boundedMetadata(value.campaignId);
-  const experimentId = boundedMetadata(value.experimentId);
-  const variantId = boundedMetadata(value.variantId);
+  const campaignId = boundedMetadata(value.campaignId, 128);
+  const experimentId = boundedMetadata(value.experimentId, 128);
+  const variantId = boundedMetadata(value.variantId, 128);
   return {
     id,
     ...(action ? { action } : {}),
@@ -1286,6 +2010,15 @@ function normalizeLocale(locale: string): string {
   return locale.trim().replace(/_/g, '-');
 }
 
+function firstOpenNoRouteReason(response: Response): AnonymousFirstOpenTerminalReason {
+  let raw = '';
+  try { raw = response.headers?.get('X-Encore-Match-Outcome')?.trim().toLowerCase() ?? ''; }
+  catch { raw = ''; }
+  return NO_ROUTE_REASONS.has(raw as AnonymousFirstOpenTerminalReason)
+    ? raw as AnonymousFirstOpenTerminalReason
+    : 'unmatched';
+}
+
 function normalizeAnonymousFirstOpenSignals(
   context: AnonymousFirstOpenContext,
 ): Partial<Omit<AnonymousFirstOpenContext, 'appBundleId' | 'locale' | 'platform' | 'installedAt'>> {
@@ -1382,6 +2115,20 @@ function resolverOutcomeRetryDelay(
   return Math.max(1, Math.floor(ceiling * jitter));
 }
 
+/**
+ * An address is only useful to the resolver if it is the same shape the send was recorded with.
+ * Anything that is not plausibly an address is dropped rather than sent: a malformed value can
+ * only ever fail to match, and not sending it keeps the payload free of stray user input.
+ */
+export function normalizeAccountEmail(raw: string | undefined | null): string | null {
+  const value = (raw ?? '').trim().toLowerCase();
+  if (value.length < 3 || value.length > 255) return null;
+  const at = value.indexOf('@');
+  if (at <= 0 || at !== value.lastIndexOf('@') || at === value.length - 1) return null;
+  if (/\s/.test(value)) return null;
+  return value;
+}
+
 async function withTimeout(
   fetcher: typeof fetch,
   input: string,
@@ -1397,6 +2144,55 @@ async function withTimeout(
   }
 }
 
+async function withPromiseTimeout<T>(
+  factory: () => Promise<T>,
+  timeoutMs: number,
+  operation: 'account claim' | 'account pending',
+): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  try {
+    return await Promise.race([
+      Promise.resolve().then(factory),
+      new Promise<T>((_resolve, reject) => {
+        timer = setTimeout(
+          () => reject(new Error(`Pulse Links: ${operation} timed out`)),
+          timeoutMs,
+        );
+      }),
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+async function withTerminalDeliveryTimeout(
+  acknowledgement: Promise<AnonymousFirstOpenTerminalDisposition | boolean>,
+  timeoutMs: number,
+): Promise<AnonymousFirstOpenTerminalDisposition | boolean> {
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  try {
+    return await Promise.race([
+      acknowledgement,
+      new Promise<AnonymousFirstOpenTerminalDisposition | boolean>((_resolve, reject) => {
+        timer = setTimeout(
+          () => reject(new Error('Pulse Links: terminal delivery acknowledgement timed out')),
+          timeoutMs,
+        );
+      }),
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+function normalizeTerminalDeliveryDisposition(
+  value: AnonymousFirstOpenTerminalDisposition | boolean,
+): AnonymousFirstOpenTerminalDisposition {
+  if (value === true || value === 'accepted') return 'accepted';
+  if (value === 'drop') return 'drop';
+  return 'retry';
+}
+
 async function postResolverOutcome(
   fetcher: typeof fetch,
   resolverBaseUrl: string,
@@ -1488,6 +2284,117 @@ function normalizeOccurredAt(value: unknown): string | null {
   return new Date(timestamp).toISOString() === value ? value : null;
 }
 
+function readTerminalDelivery(raw: unknown): PersistedFirstOpenTerminalDelivery | null {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  const value = raw as Record<string, unknown>;
+  const eventId = typeof value.eventId === 'string' && UUID_V4.test(value.eventId)
+    ? value.eventId.toLowerCase()
+    : null;
+  const status = value.status === 'FOUND' || value.status === 'NOT_FOUND' || value.status === 'FAILURE'
+    ? value.status
+    : null;
+  const rail = value.rail === 'fast_route' || value.rail === 'no_route' ? value.rail : null;
+  const reason = typeof value.reason === 'string'
+    ? value.reason as AnonymousFirstOpenTerminalReason
+    : null;
+  const occurredAt = normalizeOccurredAt(value.occurredAt);
+  const attempts = typeof value.attempts === 'number'
+    && Number.isSafeInteger(value.attempts)
+    && value.attempts >= 0
+    && value.attempts <= 100_000
+    ? value.attempts
+    : null;
+  const nextRetryAt = typeof value.nextRetryAt === 'number'
+    && Number.isSafeInteger(value.nextRetryAt)
+    && value.nextRetryAt >= 0
+    && value.nextRetryAt <= 8_640_000_000_000_000
+    ? value.nextRetryAt
+    : null;
+  if (value.disposition === 'drop') {
+    const allowedKeys = new Set(['eventId', 'disposition', 'attempts', 'nextRetryAt']);
+    if (!eventId
+      || attempts === null
+      || nextRetryAt === null
+      || Object.keys(value).some((key) => !allowedKeys.has(key))) return null;
+    return { eventId, disposition: 'drop', attempts, nextRetryAt };
+  }
+  const matchBasis = typeof value.matchBasis === 'string'
+    && MATCH_BASES.has(value.matchBasis as DeferredLinkMatchBasis)
+    ? value.matchBasis as DeferredLinkMatchBasis
+    : null;
+  const confidence = typeof value.confidence === 'number'
+    && Number.isFinite(value.confidence)
+    && value.confidence >= 0
+    && value.confidence <= 1
+    ? value.confidence
+    : null;
+  const metadata: Partial<Pick<
+    AnonymousFirstOpenTerminalOutcome,
+    'campaignId' | 'experimentId' | 'variantId'
+  >> = {};
+  let metadataValid = true;
+  for (const key of ['campaignId', 'experimentId', 'variantId'] as const) {
+    if (!Object.prototype.hasOwnProperty.call(value, key)) continue;
+    const field = value[key];
+    if (field === null) metadata[key] = null;
+    else if (typeof field === 'string'
+      && field.length > 0
+      && field.length <= 128
+      && field.trim() === field) metadata[key] = field;
+    else metadataValid = false;
+  }
+  const hasFoundDimensions = Object.prototype.hasOwnProperty.call(value, 'matchBasis')
+    && Object.prototype.hasOwnProperty.call(value, 'confidence');
+  const hasAnyAttributionDimension = Object.prototype.hasOwnProperty.call(value, 'matchBasis')
+    || Object.prototype.hasOwnProperty.call(value, 'confidence')
+    || Object.prototype.hasOwnProperty.call(value, 'campaignId')
+    || Object.prototype.hasOwnProperty.call(value, 'experimentId')
+    || Object.prototype.hasOwnProperty.call(value, 'variantId');
+  const validSemanticOutcome = status === 'FOUND'
+    ? rail === 'fast_route'
+      && value.routed === true
+      && reason === 'matched'
+      && hasFoundDimensions
+      && matchBasis === 'unique_probabilistic'
+      && confidence !== null
+      && metadataValid
+    : status === 'NOT_FOUND'
+      ? rail === 'no_route' && value.routed === false
+        && reason !== null && NO_ROUTE_REASONS.has(reason)
+        && !hasAnyAttributionDimension
+      : status === 'FAILURE'
+        ? rail === 'no_route' && value.routed === false
+          && reason !== null && FAILURE_REASONS.has(reason)
+          && !hasAnyAttributionDimension
+        : false;
+  if (!eventId
+    || !status
+    || !rail
+    || !reason
+    || !occurredAt
+    || attempts === null
+    || nextRetryAt === null
+    || Object.prototype.hasOwnProperty.call(value, 'disposition')
+    || value.retryable !== false
+    || !validSemanticOutcome) return null;
+  return {
+    eventId,
+    status,
+    rail,
+    routed: value.routed as boolean,
+    retryable: false,
+    reason,
+    occurredAt,
+    ...(status === 'FOUND' ? {
+      matchBasis: matchBasis as DeferredLinkMatchBasis,
+      confidence: confidence as number,
+      ...metadata,
+    } : {}),
+    attempts,
+    nextRetryAt,
+  };
+}
+
 function readState(storage: ConfigStorage | undefined, key: string): PersistedDeferredLinkState {
   if (!storage) return emptyState();
   try {
@@ -1535,6 +2442,7 @@ function readState(storage: ConfigStorage | undefined, key: string): PersistedDe
         .slice(-MAX_NOTIFIED_OUTCOMES)
       : [];
     const outcomeQueue = readResolverOutcomeQueue(parsed.outcomeQueue);
+    const terminalDelivery = readTerminalDelivery(parsed.terminalDelivery);
     return {
       version: 1,
       status: status === 'resolving' ? (pending ? 'pending' : 'idle') : status,
@@ -1546,6 +2454,7 @@ function readState(storage: ConfigStorage | undefined, key: string): PersistedDe
         ...outcomeQueue.map((outcome) => outcome.transitionKey),
       ])].slice(-MAX_NOTIFIED_OUTCOMES),
       outcomeQueue,
+      terminalDelivery,
       firstOpen: {
         installAttemptId: attemptId,
         completed: firstValue.completed === true,
@@ -1563,9 +2472,32 @@ function writeState(
   storage: ConfigStorage | undefined,
   key: string,
   state: PersistedDeferredLinkState,
-): void {
-  if (!storage) return;
-  try { void storage.set(key, JSON.stringify(state)); } catch { /* in-memory operation continues */ }
+  allowKnownAsyncBestEffort = true,
+): boolean {
+  if (!storage) return true;
+  const knownAsync = storage.supportsDurableSyncWrites === false
+    || ASYNCHRONOUS_STORAGE_ADAPTERS.has(storage as object);
+  if (knownAsync && !allowKnownAsyncBestEffort) return false;
+  try {
+    const result = (storage.set as unknown as (storageKey: string, value: string) => unknown)(
+      key,
+      JSON.stringify(state),
+    );
+    if (isThenable(result)) {
+      ASYNCHRONOUS_STORAGE_ADAPTERS.add(storage as object);
+      void Promise.resolve(result).catch(() => undefined);
+      return false;
+    }
+    return !knownAsync;
+  } catch {
+    return false;
+  }
+}
+
+function isThenable(value: unknown): value is PromiseLike<unknown> {
+  return (typeof value === 'object' && value !== null) || typeof value === 'function'
+    ? typeof (value as { then?: unknown }).then === 'function'
+    : false;
 }
 
 function safeTimestamp(value: unknown): number {