pulse-updates 1.3.7 → 1.3.8

package/lib/module/links.js

@@ -7,6 +7,14 @@
  * optional account bridge below.
  */
 
+/** Explicit receiver decision for one terminal-delivery attempt. */
+
+/**
+ * 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.
+ */
+
 /** Implemented by the separate native `PulseAttribution` module. */
 
 const OPAQUE_TOKEN = /^[A-Za-z0-9_-]{16,512}$/;
@@ -23,6 +31,14 @@ const STATUSES = new Set(['idle', 'pending', 'resolving', 'waiting_for_account',
 const INSTALL_REFERRER_STATUSES = new Set(['OK', 'NO_TOKEN', 'FEATURE_NOT_SUPPORTED', 'SERVICE_UNAVAILABLE', 'DEVELOPER_ERROR', 'SERVICE_DISCONNECTED']);
 const DEFAULT_ACTIONS = ['open_home', 'open_premium', 'manage_subscription', 'refresh_entitlement'];
 const DEFAULT_SENSITIVE_ACTIONS = ['manage_subscription', 'refresh_entitlement'];
+const PROBABILISTIC_ACTIONS = new Set(['open_home', 'open_premium']);
+const CAPTURE_PRIORITY = {
+  direct_token: 3,
+  ios_user_paste: 2,
+  android_install_referrer: 1
+};
+const NO_ROUTE_REASONS = new Set(['unmatched', 'ambiguous', 'holdout', 'low_confidence', 'shadow_would_route', 'shadow_attributed', 'analytics_attributed', 'target_revoked', 'disabled', 'expired_replay']);
+const FAILURE_REASONS = new Set(['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;
@@ -33,10 +49,14 @@ 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();
 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._-]*$/;
 const DEVICE_TYPES = new Set(['phone', 'tablet', 'tv', 'desktop', 'gaming_console', 'unknown']);
+
+/** Minimal sticky privacy tombstone. It carries no terminal outcome or attribution metadata. */
+
 const emptyState = () => ({
   version: 1,
   status: 'idle',
@@ -45,6 +65,7 @@ const emptyState = () => ({
   appliedIds: [],
   notifiedOutcomes: [],
   outcomeQueue: [],
+  terminalDelivery: null,
   firstOpen: {
     installAttemptId: null,
     completed: false,
@@ -145,6 +166,7 @@ export function createPulseLinkClient(options) {
   }
   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);
@@ -153,11 +175,21 @@ export function createPulseLinkClient(options) {
   let state = readState(options.storage, storageKey);
   let disposed = false;
   let processing = null;
+  let firstOpenMatching = null;
   let processRequested = false;
   let retryTimer = null;
   let outcomeSending = null;
+  let terminalDeliverySending = 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 = null;
   let lastFirstOpenContext = null;
   let unsubscribeAccount = null;
   const listeners = new Set();
@@ -166,6 +198,25 @@ export function createPulseLinkClient(options) {
       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 = {
+      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 = () => ({
     status: state.status,
     pending: state.pending ? {
@@ -177,8 +228,7 @@ export function createPulseLinkClient(options) {
       ...state.firstOpen
     }
   });
-  const persistAndNotify = () => {
-    writeState(options.storage, storageKey, state);
+  const notifyState = () => {
     const value = snapshot();
     for (const listener of listeners) {
       try {
@@ -194,6 +244,11 @@ export function createPulseLinkClient(options) {
     }
     scheduleWake();
   };
+  const persistAndNotify = () => {
+    const persisted = writeState(options.storage, storageKey, state);
+    notifyState();
+    return persisted;
+  };
   const patchState = patch => {
     state = {
       ...state,
@@ -211,6 +266,205 @@ export function createPulseLinkClient(options) {
     };
     persistAndNotify();
   };
+  const terminalDeliveryOutcome = queued => ({
+    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 => {
+    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 => {
+    if (disposed || state.terminalDelivery?.eventId !== queued.eventId) return false;
+    const acknowledgedState = {
+      ...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 = () => {
+    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 () => {
+      // 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;
+      try {
+        rawDisposition = options.onFirstOpenResult(terminalDeliveryOutcome(queued));
+      } catch (error) {
+        reportError(error);
+        scheduleTerminalDeliveryRetry(queued);
+        return false;
+      }
+      let disposition;
+      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;
+    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 => {
+    if (disposed || state.terminalDelivery?.eventId !== queued.eventId) return false;
+    const tombstone = {
+      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, outcome) => {
+    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([...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,
+      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 = () => {
+    deterministicEpoch += 1;
+    if (state.firstOpen.completed && state.firstOpen.nextRetryAt === 0) return;
+    state = {
+      ...state,
+      firstOpen: {
+        ...state.firstOpen,
+        completed: true,
+        nextRetryAt: 0
+      }
+    };
+    persistAndNotify();
+  };
   const isAccountReady = () => {
     try {
       return options.isAccountReady?.() ?? false;
@@ -443,9 +697,24 @@ export function createPulseLinkClient(options) {
       if (!sourceToken || state.pending?.token === sourceToken) clearPendingAsTerminal();
       return false;
     }
+    let applied = false;
+    let applicationFailed = false;
+    let applicationError;
+    const applicationEpoch = deterministicEpoch;
+    const hasNewerPendingIntent = () => 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;
+    // `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);
@@ -456,18 +725,41 @@ export function createPulseLinkClient(options) {
         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',
@@ -481,7 +773,9 @@ export function createPulseLinkClient(options) {
       accountRetryAt = 0;
     }
     emitOutcome(link, 'action_applied');
-    if (stillPending) void process();
+    if (stillPending && state.pending?.token !== deterministicTokenDeferredAfterCommittedJourney) {
+      void process();
+    }
     return true;
   };
   const resolvePublic = async (token, basis) => {
@@ -518,8 +812,13 @@ export function createPulseLinkClient(options) {
   };
   const processOnce = async () => {
     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();
@@ -546,7 +845,7 @@ export function createPulseLinkClient(options) {
         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(raw, token, 'account_bound', allowedActions, now());
         const claimed = normalizedClaim ? {
@@ -555,7 +854,10 @@ export function createPulseLinkClient(options) {
           matchGuaranteed: true,
           confidence: 1
         } : null;
-        if (claimed) await applyResolved(claimed, token);else clearPendingAsTerminal();
+        if (claimed) {
+          blockFirstOpenForDeterministic();
+          await applyResolved(claimed, token);
+        } else clearPendingAsTerminal();
       } catch (error) {
         reportError(error);
         if (state.pending?.token === token) schedulePendingRetry();
@@ -563,8 +865,13 @@ export function createPulseLinkClient(options) {
       return;
     }
     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;
@@ -583,14 +890,21 @@ export function createPulseLinkClient(options) {
         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();
@@ -598,6 +912,8 @@ export function createPulseLinkClient(options) {
   };
   const process = async () => {
     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 () => {
@@ -621,6 +937,7 @@ export function createPulseLinkClient(options) {
     const token = normalizeDeferredHandoffToken(rawToken);
     if (!token) return false;
     if (state.appliedIds.includes(token)) {
+      deterministicEpoch += 1;
       if (!state.firstOpen.completed) patchFirstOpen({
         completed: true,
         nextRetryAt: 0
@@ -628,7 +945,8 @@ export function createPulseLinkClient(options) {
       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: {
@@ -651,6 +969,20 @@ export function createPulseLinkClient(options) {
       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',
@@ -671,14 +1003,27 @@ export function createPulseLinkClient(options) {
     void process();
     return true;
   };
-  const matchFirstOpen = async context => {
+  const matchFirstOpenOnce = async context => {
     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 (!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',
@@ -706,26 +1051,23 @@ export function createPulseLinkClient(options) {
         },
         body: JSON.stringify(body)
       }, 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';
       }
@@ -734,44 +1076,95 @@ export function createPulseLinkClient(options) {
           scheduleFirstOpenRetry();
           return 'retry_scheduled';
         }
-        patchFirstOpen({
-          completed: true,
-          nextRetryAt: 0
+        completeFirstOpen('terminal_error', {
+          status: 'FAILURE',
+          rail: 'no_route',
+          routed: false,
+          reason: 'invalid_response'
         });
-        patchState({
-          status: 'terminal_error'
+        return 'terminal_error';
+      }
+      let rawLink;
+      try {
+        rawLink = await response.json();
+      } catch {
+        completeFirstOpen('terminal_error', {
+          status: 'FAILURE',
+          rail: 'no_route',
+          routed: false,
+          reason: 'invalid_response'
         });
         return 'terminal_error';
       }
-      const link = normalizeResolved(await response.json(), 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
+      if (disposed) return 'ineligible';
+      if (deterministicEpoch !== startingDeterministicEpoch || state.pending || state.firstOpen.completed) return 'deterministic_pending';
+      const link = normalizeResolved(rawLink, installAttemptId.replace(/-/g, ''), 'unique_probabilistic', allowedActions, now());
+      if (!link) {
+        completeFirstOpen('terminal_error', {
+          status: 'FAILURE',
+          rail: 'no_route',
+          routed: false,
+          reason: 'invalid_response'
         });
-        patchState({
-          status: 'terminal_error'
+        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 => {
+    if (firstOpenMatching) return firstOpenMatching;
+    let owned;
+    owned = matchFirstOpenOnce(context).finally(() => {
+      if (firstOpenMatching === owned) firstOpenMatching = null;
+    });
+    firstOpenMatching = owned;
+    return owned;
+  };
   const captureAndroidInstallReferrer = async bridge => {
     let raw;
     try {
@@ -796,13 +1189,14 @@ export function createPulseLinkClient(options) {
       retryTimer = null;
     }
     if (disposed || options.autoRetry === false) return;
-    const candidates = [state.pending?.nextRetryAt ?? 0, lastFirstOpenContext ? state.firstOpen.nextRetryAt : 0, accountRetryAt, state.outcomeQueue[0]?.nextRetryAt ?? 0].filter(value => value > now());
+    const candidates = [state.pending?.nextRetryAt ?? 0, 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);
     retryTimer = setTimeout(() => {
       retryTimer = null;
       void process();
       void flushResolverOutcomes();
+      void flushTerminalDelivery();
       if (lastFirstOpenContext && state.firstOpen.nextRetryAt <= now()) {
         void matchFirstOpen(lastFirstOpenContext);
       }
@@ -822,6 +1216,7 @@ export function createPulseLinkClient(options) {
   scheduleWake();
   void process();
   void flushResolverOutcomes();
+  void flushTerminalDelivery();
   return {
     capture,
     captureUrl: url => {
@@ -839,6 +1234,8 @@ export function createPulseLinkClient(options) {
     dispose: () => {
       if (disposed) return;
       disposed = true;
+      deterministicEpoch += 1;
+      terminalDeliveryGeneration += 1;
       if (retryTimer) clearTimeout(retryTimer);
       retryTimer = null;
       unsubscribeAccount?.();
@@ -848,6 +1245,10 @@ export function createPulseLinkClient(options) {
     reset: () => {
       accountRetryAt = 0;
       accountAttempts = 0;
+      deterministicEpoch += 1;
+      terminalDeliveryGeneration += 1;
+      terminalDeliverySending = null;
+      deterministicTokenDeferredAfterCommittedJourney = null;
       state = emptyState();
       persistAndNotify();
     }
@@ -891,11 +1292,11 @@ function stableOutcomeKey(linkId, name) {
   }
   return `${first.toString(16).padStart(8, '0')}${second.toString(16).padStart(8, '0')}|${name}`;
 }
-function boundedMetadata(value) {
+function boundedMetadata(value, maxLength = 256) {
   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(raw, fallbackId, fallbackBasis, allowedActions, now) {
   if (!raw || typeof raw !== 'object') return null;
@@ -917,9 +1318,9 @@ function normalizeResolved(raw, fallbackId, fallbackBasis, allowedActions, now)
     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 ? {
@@ -956,6 +1357,15 @@ function isEligibleFirstOpen(context, now, maxAgeMs) {
 function normalizeLocale(locale) {
   return locale.trim().replace(/_/g, '-');
 }
+function firstOpenNoRouteReason(response) {
+  let raw = '';
+  try {
+    raw = response.headers?.get('X-Encore-Match-Outcome')?.trim().toLowerCase() ?? '';
+  } catch {
+    raw = '';
+  }
+  return NO_ROUTE_REASONS.has(raw) ? raw : 'unmatched';
+}
 function normalizeAnonymousFirstOpenSignals(context) {
   const appVersion = normalizeSignalString(context.appVersion, VERSION_SIGNAL, 64);
   const osVersion = normalizeSignalString(context.osVersion, VERSION_SIGNAL, 64);
@@ -1047,6 +1457,31 @@ async function withTimeout(fetcher, input, init, timeoutMs) {
     clearTimeout(timer);
   }
 }
+async function withPromiseTimeout(factory, timeoutMs, operation) {
+  let timer = null;
+  try {
+    return await Promise.race([Promise.resolve().then(factory), new Promise((_resolve, reject) => {
+      timer = setTimeout(() => reject(new Error(`Pulse Links: ${operation} timed out`)), timeoutMs);
+    })]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+async function withTerminalDeliveryTimeout(acknowledgement, timeoutMs) {
+  let timer = null;
+  try {
+    return await Promise.race([acknowledgement, new Promise((_resolve, reject) => {
+      timer = setTimeout(() => reject(new Error('Pulse Links: terminal delivery acknowledgement timed out')), timeoutMs);
+    })]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+function normalizeTerminalDeliveryDisposition(value) {
+  if (value === true || value === 'accepted') return 'accepted';
+  if (value === 'drop') return 'drop';
+  return 'retry';
+}
 async function postResolverOutcome(fetcher, resolverBaseUrl, outcome, timeoutMs) {
   return withTimeout(fetcher, `${resolverBaseUrl}${encodeURIComponent(outcome.token)}/event/${outcome.name}`, {
     method: 'POST',
@@ -1113,6 +1548,56 @@ function normalizeOccurredAt(value) {
   if (!Number.isFinite(timestamp)) return null;
   return new Date(timestamp).toISOString() === value ? value : null;
 }
+function readTerminalDelivery(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  const value = raw;
+  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 : 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) ? value.matchBasis : null;
+  const confidence = typeof value.confidence === 'number' && Number.isFinite(value.confidence) && value.confidence >= 0 && value.confidence <= 1 ? value.confidence : null;
+  const metadata = {};
+  let metadataValid = true;
+  for (const key of ['campaignId', 'experimentId', 'variantId']) {
+    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,
+    retryable: false,
+    reason,
+    occurredAt,
+    ...(status === 'FOUND' ? {
+      matchBasis: matchBasis,
+      confidence: confidence,
+      ...metadata
+    } : {}),
+    attempts,
+    nextRetryAt
+  };
+}
 function readState(storage, key) {
   if (!storage) return emptyState();
   try {
@@ -1139,6 +1624,7 @@ function readState(storage, key) {
     const attemptId = typeof firstValue.installAttemptId === 'string' && INSTALL_ATTEMPT_ID.test(firstValue.installAttemptId) ? firstValue.installAttemptId.toLowerCase() : null;
     const notifiedOutcomes = Array.isArray(parsed.notifiedOutcomes) ? parsed.notifiedOutcomes.filter(value => typeof value === 'string' && /^[a-f0-9]{16}\|(app_open_confirmed|deferred_link_resolved|action_applied)$/.test(value)).slice(-MAX_NOTIFIED_OUTCOMES) : [];
     const outcomeQueue = readResolverOutcomeQueue(parsed.outcomeQueue);
+    const terminalDelivery = readTerminalDelivery(parsed.terminalDelivery);
     return {
       version: 1,
       status: status === 'resolving' ? pending ? 'pending' : 'idle' : status,
@@ -1147,6 +1633,7 @@ function readState(storage, key) {
       appliedIds: [...new Set(appliedIds)].slice(-MAX_APPLIED_IDS),
       notifiedOutcomes: [...new Set([...notifiedOutcomes, ...outcomeQueue.map(outcome => outcome.transitionKey)])].slice(-MAX_NOTIFIED_OUTCOMES),
       outcomeQueue,
+      terminalDelivery,
       firstOpen: {
         installAttemptId: attemptId,
         completed: firstValue.completed === true,
@@ -1159,11 +1646,24 @@ function readState(storage, key) {
     return emptyState();
   }
 }
-function writeState(storage, key, state) {
-  if (!storage) return;
+function writeState(storage, key, state, allowKnownAsyncBestEffort = true) {
+  if (!storage) return true;
+  const knownAsync = storage.supportsDurableSyncWrites === false || ASYNCHRONOUS_STORAGE_ADAPTERS.has(storage);
+  if (knownAsync && !allowKnownAsyncBestEffort) return false;
   try {
-    void storage.set(key, JSON.stringify(state));
-  } catch {/* in-memory operation continues */}
+    const result = storage.set(key, JSON.stringify(state));
+    if (isThenable(result)) {
+      ASYNCHRONOUS_STORAGE_ADAPTERS.add(storage);
+      void Promise.resolve(result).catch(() => undefined);
+      return false;
+    }
+    return !knownAsync;
+  } catch {
+    return false;
+  }
+}
+function isThenable(value) {
+  return typeof value === 'object' && value !== null || typeof value === 'function' ? typeof value.then === 'function' : false;
 }
 function safeTimestamp(value) {
   return typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.trunc(value) : 0;