pulse-updates 1.3.7 → 1.3.9

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,26 @@ 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;
+  // Invalidates every host callback that crossed an await when this client is reset/disposed.
+  // This is deliberately separate from deterministicEpoch: captures during a committed callback
+  // have intentional last-touch semantics, whereas a lifecycle boundary must forbid every stale
+  // state write, retry and outcome from the old instance.
+  let lifecycleGeneration = 0;
+  // Host navigation is irreversible once any routing callback has started: it may perform its
+  // side effect synchronously before returning a Promise. Serialize captures against that commit
+  // boundary and keep the newer accepted token durable for the next client lifecycle instead of
+  // automatically opening a second journey behind the first one.
+  let routingApplicationInFlight = false;
+  let deterministicTokenDeferredAfterCommittedJourney = null;
   let lastFirstOpenContext = null;
   let unsubscribeAccount = null;
   const listeners = new Set();
@@ -166,6 +203,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 +233,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 +249,11 @@ export function createPulseLinkClient(options) {
     }
     scheduleWake();
   };
+  const persistAndNotify = () => {
+    const persisted = writeState(options.storage, storageKey, state);
+    notifyState();
+    return persisted;
+  };
   const patchState = patch => {
     state = {
       ...state,
@@ -211,13 +271,229 @@ export function createPulseLinkClient(options) {
     };
     persistAndNotify();
   };
-  const isAccountReady = () => {
+  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) => {
+    const completionLifecycleGeneration = lifecycleGeneration;
+    const completionDeterministicEpoch = deterministicEpoch;
+    const completionIsCurrent = () => !disposed && lifecycleGeneration === completionLifecycleGeneration && deterministicEpoch === completionDeterministicEpoch;
+    let shouldQueue = Boolean(options.onFirstOpenResult);
+    if (shouldQueue && options.shouldQueueFirstOpenResult) {
+      try {
+        shouldQueue = options.shouldQueueFirstOpenResult() === true;
+      } catch (error) {
+        shouldQueue = false;
+        reportError(error);
+      }
+      // Privacy/diagnostic hooks are host code and may synchronously reset, dispose, or capture a
+      // deterministic destination. Never resurrect the terminal first-open state they invalidated.
+      if (!completionIsCurrent()) return;
+    }
+    if (!shouldQueue) {
+      state = {
+        ...state,
+        status,
+        terminalDelivery: null,
+        firstOpen: {
+          ...state.firstOpen,
+          completed: true,
+          attempts: 0,
+          nextRetryAt: 0
+        }
+      };
+      persistAndNotify();
+      return;
+    }
+    const existingEventIds = new Set([...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 = () => {
+    const blockingLifecycleGeneration = lifecycleGeneration;
+    deterministicEpoch += 1;
+    const blockingDeterministicEpoch = deterministicEpoch;
+    if (state.firstOpen.completed && state.firstOpen.nextRetryAt === 0) return true;
+    state = {
+      ...state,
+      firstOpen: {
+        ...state.firstOpen,
+        completed: true,
+        nextRetryAt: 0
+      }
+    };
+    persistAndNotify();
+    return !disposed && lifecycleGeneration === blockingLifecycleGeneration && deterministicEpoch === blockingDeterministicEpoch;
+  };
+  const readAccountReadiness = () => {
+    const readinessLifecycleGeneration = lifecycleGeneration;
+    const readinessDeterministicEpoch = deterministicEpoch;
+    let ready = false;
     try {
-      return options.isAccountReady?.() ?? false;
+      ready = options.isAccountReady?.() ?? false;
     } catch (error) {
       reportError(error);
-      return false;
     }
+    return {
+      ready,
+      // Readiness is host code, not a pure getter. A reset/dispose/capture inside it invalidates
+      // the caller's snapshot and must be observed before any waiting/retry/application write.
+      current: !disposed && lifecycleGeneration === readinessLifecycleGeneration && deterministicEpoch === readinessDeterministicEpoch
+    };
   };
   const schedulePendingRetry = () => {
     const pending = state.pending;
@@ -425,7 +701,9 @@ export function createPulseLinkClient(options) {
         if (!sourceToken || state.pending?.token === sourceToken) clearPendingAsTerminal();
         return false;
       }
-      if (!isAccountReady()) {
+      const accountReadiness = readAccountReadiness();
+      if (!accountReadiness.current) return false;
+      if (!accountReadiness.ready) {
         patchState({
           status: 'waiting_for_account'
         });
@@ -443,9 +721,34 @@ 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 applicationLifecycleGeneration = lifecycleGeneration;
+    const lifecycleIsCurrent = () => !disposed && lifecycleGeneration === applicationLifecycleGeneration;
+    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');
+    if (!lifecycleIsCurrent()) {
+      routingApplicationInFlight = false;
+      return false;
+    }
     emitOutcome(link, 'deferred_link_resolved');
-    let applied;
+    if (!lifecycleIsCurrent()) {
+      routingApplicationInFlight = false;
+      return false;
+    }
+    // `emitOutcome` invokes host diagnostics synchronously. If those hooks re-enter capture with
+    // a newer accepted destination, it still arrived before the routing callback and must win.
+    if (hasNewerPendingIntent()) {
+      routingApplicationInFlight = false;
+      void process();
+      return false;
+    }
     try {
       if (link.deepLink) {
         applied = await options.onDeepLink(link.deepLink, link);
@@ -456,18 +759,50 @@ export function createPulseLinkClient(options) {
         return false;
       }
     } catch (error) {
-      reportError(error);
+      applicationFailed = true;
+      applicationError = error;
+    } finally {
+      routingApplicationInFlight = false;
+    }
+
+    // The callback may resolve after reset/dispose and after another client has already committed
+    // a newer journey into the same storage. The old instance must not schedule a retry, rewrite
+    // state, or emit action_applied regardless of whether the callback returned true/false/threw.
+    if (!lifecycleIsCurrent()) return false;
+    const newerIntentArrivedDuringApplication = hasNewerPendingIntent();
+    if (applicationFailed) {
+      reportError(applicationError);
+      if (!lifecycleIsCurrent()) return false;
+      // onError is host code too: it may capture a newer deterministic destination while reporting
+      // this failure. Re-evaluate after the callback instead of arming a stale retry from the value
+      // observed before diagnostics ran.
+      if (hasNewerPendingIntent()) {
+        // The current action did not commit. Resume the newer accepted intent that was captured
+        // while its callback was suspended, without scheduling a retry for the superseded one.
+        void process();
+        return false;
+      }
       if (sourceToken && state.pending?.token === sourceToken) schedulePendingRetry();else if (link.matchBasis === 'unique_probabilistic') scheduleFirstOpenRetry();else scheduleAccountRetry();
       return false;
     }
     if (applied === false) {
+      if (newerIntentArrivedDuringApplication) {
+        void process();
+        return false;
+      }
       if (sourceToken && state.pending?.token === sourceToken) schedulePendingRetry();else if (link.matchBasis === 'unique_probabilistic') scheduleFirstOpenRetry();else scheduleAccountRetry();
       return false;
     }
+    if (newerIntentArrivedDuringApplication) {
+      // Invocation of any host routing callback is the last safe commit boundary. A successful
+      // callback may already have navigated, so automatically applying the newly captured token
+      // now would create two journeys. Keep it pending and let a fresh SDK lifecycle recover it.
+      deterministicTokenDeferredAfterCommittedJourney = state.pending.token;
+    }
     const newlyApplied = sourceToken && sourceToken !== link.id ? [link.id, sourceToken] : [link.id];
     const newlyAppliedSet = new Set(newlyApplied);
     const appliedIds = [...state.appliedIds.filter(id => !newlyAppliedSet.has(id)), ...newlyApplied].slice(-MAX_APPLIED_IDS);
-    const stillPending = sourceToken !== null && state.pending?.token !== sourceToken;
+    const stillPending = sourceToken !== null ? state.pending?.token !== sourceToken : newerIntentArrivedDuringApplication;
     state = {
       ...state,
       status: stillPending ? 'pending' : 'applied',
@@ -476,12 +811,16 @@ export function createPulseLinkClient(options) {
       appliedIds
     };
     persistAndNotify();
+    if (!lifecycleIsCurrent()) return false;
     if (link.matchBasis === 'account_bound') {
       accountAttempts = 0;
       accountRetryAt = 0;
     }
     emitOutcome(link, 'action_applied');
-    if (stillPending) void process();
+    if (!lifecycleIsCurrent()) return false;
+    if (stillPending && state.pending?.token !== deterministicTokenDeferredAfterCommittedJourney) {
+      void process();
+    }
     return true;
   };
   const resolvePublic = async (token, basis) => {
@@ -518,19 +857,26 @@ 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();
         return;
       }
       const token = pending.token;
+      const pendingLifecycleGeneration = lifecycleGeneration;
       patchState({
         status: 'resolving'
       });
+      if (disposed || lifecycleGeneration !== pendingLifecycleGeneration || state.pending?.token !== token) return;
       const publicResult = await resolvePublic(token, pending.matchBasis);
-      if (disposed || state.pending?.token !== token) return;
+      if (disposed || lifecycleGeneration !== pendingLifecycleGeneration || state.pending?.token !== token) return;
       if (publicResult.kind === 'resolved') {
         await applyResolved(publicResult.link, token);
         return;
@@ -539,15 +885,23 @@ export function createPulseLinkClient(options) {
         schedulePendingRetry();
         return;
       }
-      if (!options.accountBridge || !isAccountReady()) {
+      if (!options.accountBridge) {
+        patchState({
+          status: 'waiting_for_account'
+        });
+        return;
+      }
+      const accountReadiness = readAccountReadiness();
+      if (!accountReadiness.current || disposed || lifecycleGeneration !== pendingLifecycleGeneration || state.pending?.token !== token) return;
+      if (!accountReadiness.ready) {
         patchState({
           status: 'waiting_for_account'
         });
         return;
       }
       try {
-        const raw = await options.accountBridge.claim(token);
-        if (disposed || state.pending?.token !== token) return;
+        const raw = await withPromiseTimeout(() => options.accountBridge.claim(token), requestTimeoutMs, 'account claim');
+        if (disposed || lifecycleGeneration !== pendingLifecycleGeneration || state.pending?.token !== token) return;
         const normalizedClaim = normalizeResolved(raw, token, 'account_bound', allowedActions, now());
         const claimed = normalizedClaim ? {
           ...normalizedClaim,
@@ -555,16 +909,29 @@ export function createPulseLinkClient(options) {
           matchGuaranteed: true,
           confidence: 1
         } : null;
-        if (claimed) await applyResolved(claimed, token);else clearPendingAsTerminal();
+        if (claimed) {
+          if (!blockFirstOpenForDeterministic()) return;
+          await applyResolved(claimed, token);
+        } else clearPendingAsTerminal();
       } catch (error) {
+        if (disposed || lifecycleGeneration !== pendingLifecycleGeneration || state.pending?.token !== token) return;
         reportError(error);
-        if (state.pending?.token === token) schedulePendingRetry();
+        if (!disposed && lifecycleGeneration === pendingLifecycleGeneration && state.pending?.token === token) schedulePendingRetry();
       }
       return;
     }
-    if (!options.accountBridge || !isAccountReady() || accountRetryAt > now()) return;
+    if (!options.accountBridge) return;
+    const accountReadiness = readAccountReadiness();
+    if (!accountReadiness.current || state.pending) return;
+    if (!accountReadiness.ready || accountRetryAt > now()) return;
+    const accountPendingEpoch = deterministicEpoch;
+    const accountPendingLifecycleGeneration = lifecycleGeneration;
     try {
-      const raw = await options.accountBridge.pending();
+      const raw = await withPromiseTimeout(() => options.accountBridge.pending(), requestTimeoutMs, 'account pending');
+      // A URL/paste/referrer captured while the account lookup was in flight is newer explicit
+      // user intent. Ignore the stale bridge response and let the requested drain resolve the
+      // captured token; otherwise both deterministic destinations could be applied.
+      if (disposed || lifecycleGeneration !== accountPendingLifecycleGeneration || deterministicEpoch !== accountPendingEpoch || state.pending) return;
       if (!raw) {
         accountAttempts = 0;
         accountRetryAt = 0;
@@ -583,21 +950,31 @@ 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.
+        if (!blockFirstOpenForDeterministic()) return;
+        if (!state.appliedIds.includes(pendingLink.id)) {
+          await applyResolved(pendingLink, null);
+        } else if (state.status !== 'applied') {
+          patchState({
+            status: 'applied'
+          });
+        }
       }
     } catch (error) {
+      if (disposed || lifecycleGeneration !== accountPendingLifecycleGeneration || deterministicEpoch !== accountPendingEpoch || state.pending) return;
       reportError(error);
+      if (disposed || lifecycleGeneration !== accountPendingLifecycleGeneration || deterministicEpoch !== accountPendingEpoch || state.pending) return;
       // No token was consumed; the authenticated server outbox remains authoritative.
       scheduleAccountRetry();
     }
   };
   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 +998,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 +1006,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 +1030,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 +1064,41 @@ 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 (state.firstOpen.nextRetryAt > now()) {
+      // On a fresh client lifecycle scheduleWake() ran before the host supplied this ephemeral
+      // context, so the persisted first-open deadline could not be part of its candidates. Re-arm
+      // now that retrying is possible; otherwise a 503 followed by process death remains asleep
+      // until some unrelated foreground/manual call invokes matchFirstOpen again.
+      scheduleWake();
+      return 'backoff';
+    }
+    if (!isEligibleFirstOpen(context, now(), recentInstallMaxAgeMs)) return 'ineligible';
+
+    // The client starts account recovery at construction. Join that deterministic rail before
+    // asking the probabilistic matcher; otherwise a slow Billing/account response can navigate
+    // after the probabilistic destination and the user observes both journeys.
+    await process();
+    if (disposed) return 'ineligible';
+    if (state.pending || state.firstOpen.completed) return 'deterministic_pending';
+    if (options.accountBridge) {
+      const accountReadiness = readAccountReadiness();
+      if (!accountReadiness.current) {
+        return disposed ? 'ineligible' : 'deterministic_pending';
+      }
+      if (accountReadiness.ready && accountRetryAt > now()) {
+        if (state.firstOpen.nextRetryAt === 0) scheduleFirstOpenRetry();
+        return 'retry_scheduled';
+      }
+    }
     if (!isEligibleFirstOpen(context, now(), recentInstallMaxAgeMs)) return 'ineligible';
     const installAttemptId = state.firstOpen.installAttemptId ?? makeInstallAttemptId(options.randomUUID);
+    const startingDeterministicEpoch = deterministicEpoch;
+    const startingLifecycleGeneration = lifecycleGeneration;
     state = {
       ...state,
       status: 'resolving',
@@ -688,14 +1108,44 @@ export function createPulseLinkClient(options) {
         attemptedAt: now()
       }
     };
-    persistAndNotify();
+    const firstOpenReservationPersisted = persistAndNotify();
+    // Persistence notifies host state hooks synchronously. They may reset/dispose this client or
+    // capture a deterministic destination. In all three cases the reserved id no longer belongs to
+    // the current lifecycle and must never cross the network boundary.
+    if (disposed) return 'ineligible';
+    if (lifecycleGeneration !== startingLifecycleGeneration || deterministicEpoch !== startingDeterministicEpoch || state.pending || state.firstOpen.completed) return 'deterministic_pending';
+    if (options.storage && !firstOpenReservationPersisted) {
+      // An unpersisted id must never leave the process: after a crash the retry would mint a new
+      // id and the server could count/route the same install twice. Keep the exact nonce in memory,
+      // arm a persistence retry without incrementing matcher attempts, and send nothing until a
+      // synchronous durable write succeeds. Memory-only clients have no restart contract and may
+      // continue normally.
+      state = {
+        ...state,
+        status: 'retryable_error',
+        firstOpen: {
+          ...state.firstOpen,
+          nextRetryAt: now() + retryBaseMs
+        }
+      };
+      reportError(new Error('Pulse Links: first-open install attempt id was not durably persisted'));
+      notifyState();
+      return 'retry_scheduled';
+    }
+    const accountEmail = normalizeAccountEmail(context.accountEmail);
     const body = {
       appBundleId: context.appBundleId.trim(),
       platform: 'ios',
       locale: normalizeLocale(context.locale),
       firstOpen: true,
       installAttemptId,
-      ...normalizeAnonymousFirstOpenSignals(context)
+      ...normalizeAnonymousFirstOpenSignals(context),
+      // Sent only when the app already knows it. The resolver treats an address that matches
+      // exactly one recent message as proof of origin; anything else falls back to the
+      // probabilistic path, so a shared or unknown address costs nothing.
+      ...(accountEmail ? {
+        accountEmail
+      } : {})
     };
     try {
       const response = await withTimeout(fetcher, matchUrlOf(resolverBaseUrl), {
@@ -706,26 +1156,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,45 +1181,98 @@ 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 => {
+    const referrerLifecycleGeneration = lifecycleGeneration;
+    const referrerDeterministicEpoch = deterministicEpoch;
     let raw;
     try {
       raw = await bridge.getDeferredHandoff();
@@ -785,6 +1285,7 @@ export function createPulseLinkClient(options) {
       };
     }
     const result = normalizeAndroidInstallReferrerResult(raw);
+    if (disposed || lifecycleGeneration !== referrerLifecycleGeneration || deterministicEpoch !== referrerDeterministicEpoch) return result;
     if (result.status === 'OK' && result.token) {
       capture(result.token, 'android_install_referrer');
     }
@@ -796,13 +1297,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 +1324,7 @@ export function createPulseLinkClient(options) {
   scheduleWake();
   void process();
   void flushResolverOutcomes();
+  void flushTerminalDelivery();
   return {
     capture,
     captureUrl: url => {
@@ -839,6 +1342,9 @@ export function createPulseLinkClient(options) {
     dispose: () => {
       if (disposed) return;
       disposed = true;
+      lifecycleGeneration += 1;
+      deterministicEpoch += 1;
+      terminalDeliveryGeneration += 1;
       if (retryTimer) clearTimeout(retryTimer);
       retryTimer = null;
       unsubscribeAccount?.();
@@ -848,6 +1354,11 @@ export function createPulseLinkClient(options) {
     reset: () => {
       accountRetryAt = 0;
       accountAttempts = 0;
+      lifecycleGeneration += 1;
+      deterministicEpoch += 1;
+      terminalDeliveryGeneration += 1;
+      terminalDeliverySending = null;
+      deterministicTokenDeferredAfterCommittedJourney = null;
       state = emptyState();
       persistAndNotify();
     }
@@ -891,11 +1402,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 +1428,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 +1467,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);
@@ -1035,6 +1555,20 @@ function resolverOutcomeRetryDelay(eventId, attempts, retryBaseMs, retryMaxMs) {
   const jitter = 0.5 + hash / 0xffffffff * 0.5;
   return Math.max(1, Math.floor(ceiling * jitter));
 }
+
+/**
+ * An address is only useful to the resolver if it is the same shape the send was recorded with.
+ * Anything that is not plausibly an address is dropped rather than sent: a malformed value can
+ * only ever fail to match, and not sending it keeps the payload free of stray user input.
+ */
+export function normalizeAccountEmail(raw) {
+  const value = (raw ?? '').trim().toLowerCase();
+  if (value.length < 3 || value.length > 255) return null;
+  const at = value.indexOf('@');
+  if (at <= 0 || at !== value.lastIndexOf('@') || at === value.length - 1) return null;
+  if (/\s/.test(value)) return null;
+  return value;
+}
 async function withTimeout(fetcher, input, init, timeoutMs) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
@@ -1047,6 +1581,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 +1672,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 +1748,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 +1757,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 +1770,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;