pulse-updates 1.3.7 → 1.3.8

package/src/links.ts

@@ -134,6 +134,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 +208,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 +230,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 +326,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 +359,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 +388,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 +416,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 +434,7 @@ const emptyState = (): PersistedDeferredLinkState => ({
   appliedIds: [],
   notifiedOutcomes: [],
   outcomeQueue: [],
+  terminalDelivery: null,
   firstOpen: {
     installAttemptId: null,
     completed: false,
@@ -430,6 +546,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 +565,21 @@ 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;
+  // 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 +588,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 +614,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 +623,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,6 +639,229 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
     persistAndNotify();
   };
 
+  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 => {
+    let shouldQueue = Boolean(options.onFirstOpenResult);
+    if (shouldQueue && options.shouldQueueFirstOpenResult) {
+      try {
+        shouldQueue = options.shouldQueueFirstOpenResult() === true;
+      } catch (error) {
+        shouldQueue = false;
+        reportError(error);
+      }
+    }
+    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 = (): void => {
+    deterministicEpoch += 1;
+    if (state.firstOpen.completed && state.firstOpen.nextRetryAt === 0) return;
+    state = {
+      ...state,
+      firstOpen: { ...state.firstOpen, completed: true, nextRetryAt: 0 },
+    };
+    persistAndNotify();
+  };
+
   const isAccountReady = (): boolean => {
     try { return options.isAccountReady?.() ?? false; } catch (error) {
       reportError(error);
@@ -740,9 +1118,25 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
       return false;
     }
 
+    let applied: boolean | void = false;
+    let applicationFailed = false;
+    let applicationError: unknown;
+    const applicationEpoch = deterministicEpoch;
+    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');
     emitOutcome(link, 'deferred_link_resolved');
-    let applied: boolean | void;
+    // `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 +1147,51 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
         return false;
       }
     } catch (error) {
-      reportError(error);
+      applicationFailed = true;
+      applicationError = error;
+    } finally {
+      routingApplicationInFlight = false;
+    }
+
+    const newerIntentArrivedDuringApplication = hasNewerPendingIntent();
+    if (applicationFailed) {
+      reportError(applicationError);
+      if (newerIntentArrivedDuringApplication) {
+        // 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',
@@ -784,7 +1205,9 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
       accountRetryAt = 0;
     }
     emitOutcome(link, 'action_applied');
-    if (stillPending) void process();
+    if (stillPending && state.pending?.token !== deterministicTokenDeferredAfterCommittedJourney) {
+      void process();
+    }
     return true;
   };
 
@@ -822,8 +1245,13 @@ 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();
@@ -847,7 +1275,11 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
         return;
       }
       try {
-        const raw = await options.accountBridge.claim(token);
+        const raw = await withPromiseTimeout(
+          () => options.accountBridge!.claim(token),
+          requestTimeoutMs,
+          'account claim',
+        );
         if (disposed || state.pending?.token !== token) return;
         const normalizedClaim = normalizeResolved<Action>(
           raw,
@@ -862,7 +1294,10 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
           matchGuaranteed: true,
           confidence: 1,
         } : null;
-        if (claimed) await applyResolved(claimed, token);
+        if (claimed) {
+          blockFirstOpenForDeterministic();
+          await applyResolved(claimed, token);
+        }
         else clearPendingAsTerminal();
       } catch (error) {
         reportError(error);
@@ -872,8 +1307,17 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
     }
 
     if (!options.accountBridge || !isAccountReady() || accountRetryAt > now()) return;
+    const accountPendingEpoch = deterministicEpoch;
     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 || deterministicEpoch !== accountPendingEpoch || state.pending) return;
       if (!raw) {
         accountAttempts = 0;
         accountRetryAt = 0;
@@ -898,12 +1342,19 @@ 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.
+        blockFirstOpenForDeterministic();
+        if (!state.appliedIds.includes(pendingLink.id)) {
+          await applyResolved(pendingLink, null);
+        } else if (state.status !== 'applied') {
+          patchState({ status: 'applied' });
+        }
       }
     } catch (error) {
+      if (disposed || deterministicEpoch !== accountPendingEpoch || state.pending) return;
       reportError(error);
       // No token was consumed; the authenticated server outbox remains authoritative.
       scheduleAccountRetry();
@@ -912,6 +1363,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 +1391,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 +1410,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,7 +1444,7 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
     return true;
   };
 
-  const matchFirstOpen = async (
+  const matchFirstOpenOnce = async (
     context: AnonymousFirstOpenContext,
   ): Promise<AnonymousFirstOpenResult> => {
     if (disposed) return 'ineligible';
@@ -986,8 +1454,21 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
     if (state.firstOpen.nextRetryAt > now()) 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 && isAccountReady() && 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;
     state = {
       ...state,
       status: 'resolving',
@@ -1018,16 +1499,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,38 +1527,113 @@ 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> => {
@@ -1095,6 +1662,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 +1670,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 +1689,7 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
   scheduleWake();
   void process();
   void flushResolverOutcomes();
+  void flushTerminalDelivery();
 
   return {
     capture,
@@ -1138,6 +1708,8 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
     dispose: () => {
       if (disposed) return;
       disposed = true;
+      deterministicEpoch += 1;
+      terminalDeliveryGeneration += 1;
       if (retryTimer) clearTimeout(retryTimer);
       retryTimer = null;
       unsubscribeAccount?.();
@@ -1147,6 +1719,10 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
     reset: () => {
       accountRetryAt = 0;
       accountAttempts = 0;
+      deterministicEpoch += 1;
+      terminalDeliveryGeneration += 1;
+      terminalDeliverySending = null;
+      deterministicTokenDeferredAfterCommittedJourney = null;
       state = emptyState();
       persistAndNotify();
     },
@@ -1199,11 +1775,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 +1822,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 +1862,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'>> {
@@ -1397,6 +1982,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 +2122,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 +2280,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 +2292,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 +2310,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 {