@wireai/activation 0.15.0 → 0.16.0

package/src/reviews/idempotency.ts

@@ -64,6 +64,44 @@ export interface ReviewImpression {
 /**
  * Open one impression. Both fields are resolved EAGERLY here rather than read per post, which is the
  * entire point: a lazily re-read key or identity is a per-post value wearing an impression's name.
+ *
+ * ── WHY A NON-DURABLE UNIT IS DELIBERATELY ACCEPTED HERE (ruled 0.15.1) ──────────────────────
+ *
+ * The kit's standing identity rule is that a caller writing a cross-launch join key must read
+ * `IdentityRecord.durable` and REFUSE a `false` — see `context/deviceId.ts`. That rule does not
+ * transfer to this field, and an audit that ports it here makes the data WORSE, so the reasoning is
+ * recorded rather than left to be rediscovered:
+ *
+ *   • WHAT THE RULE PROTECTS elsewhere is a COUNTER. `app.session_started` is counted by distinct
+ *     opens grouped on `device_key`, so a per-launch key there makes `min_sessions` structurally
+ *     incapable of exceeding 1 — the key actively corrupts the metric. A review row is written once
+ *     per user, so a per-launch value here cannot corrupt a count the same way.
+ *   • WHAT REFUSING WOULD COST is the feature itself. With no unit the server's
+ *     `_idempotency_unit` returns nothing, it DISCARDS the key and inserts a plain row — so the
+ *     `unsent` re-post and the abandonment net each write a SECOND review row, double-counting
+ *     `count` and corrupting `avg`. That is the exact corruption the key was added to prevent, and
+ *     it is a corruption traded for an under-count, which is the wrong direction.
+ *   • THE SCOPE THE UNIT ACTUALLY NEEDS is one impression inside one launch, and that is precisely
+ *     what a pinned in-memory value guarantees. Durability buys nothing the server ever reads here.
+ *   • THE ORPHANED-JOIN WORRY (a review row stamped with a key no analytics event carries) is real
+ *     and is NOT closed by any of the above — it is an ID-SPACE problem, not a durability one, and
+ *     it survives here. Two sequences still produce it, both of them ordinary:
+ *       (1) the impression opens BEFORE any surface has registered a real `appId`, so it pins the
+ *           ambient fallback while every later analytics event carries the host's id. This is the
+ *           same cold-start ordering the ambient reader was fixed for, and the test that covers
+ *           that fix calls it the sequence rather than an edge case.
+ *       (2) the impression opens while a hydration is IN FLIGHT, so it pins the synchronous mint
+ *           and the persisted id replaces it in the registry a moment later.
+ *     What WAS closed is a different and larger failure: the ambient reader used to answer
+ *     `undefined` permanently once the real `appId` registered, which cost every later impression
+ *     its unit outright. The orphan that remains is bounded to impressions opened before the
+ *     process's id space settles, and the gate is once-per-user, so in practice it is at most the
+ *     first row.
+ *   • AND THE ORPHAN IS NOT AN ARGUMENT FOR REFUSING, which is the trap. Dropping the unit does not
+ *     repair the join — it removes it AND removes the server's ability to dedupe, so an orphaned
+ *     row that is at least idempotent becomes a row that is neither. Closing it properly means
+ *     giving the gate a settled identity to pin, which is a public-API change (`appId` / `storage`
+ *     props on `ReviewGate`) and is deliberately not attempted here.
  */
 export const createImpression = (): ReviewImpression => ({
   idempotencyKey: mintIdempotencyKey(),

package/src/reviews/runtime.ts

@@ -6,7 +6,7 @@
  */
 import type { CoachmarkStorage } from "../coachmarks/types";
 import { getCoachmarkStorage, validateGateStorage } from "../coachmarks/runtime";
-import { getCurrentSessionId } from "../analytics/currentSession";
+import { getCurrentSessionId, isMintedSessionId } from "../analytics/currentSession";
 import { makeSessionId } from "../analytics/reportClientEvent";
 
 /** Once-gate key. Keyed by app version when `oncePerVersion` is on, so a new release re-enables. */
@@ -156,12 +156,26 @@ const readStr = (storage: CoachmarkStorage | null, key: string): string | undefi
 // that was live when the pin was taken, and read it lazily.
 //
 //   • pin unset              → pin = the registered id ?? a freshly minted one, and remember which
-//                              registered id that was (`undefined` when we had to mint).
-//   • remembered `undefined` → the FIRST registration merely NAMES the open the gate already
-//                              counted under a minted id. Adopt it, leave the PIN alone. This is
+//                              registered id that was (`undefined` when we had to mint) and whether
+//                              it was itself a MINTED fallback.
+//   • remembered `undefined`
+//     or remembered MINTED   → the FIRST REAL registration merely NAMES the open the gate already
+//                              counted under a fallback id. Adopt it, leave the PIN alone. This is
 //                              the cold-start case, and it stays shut.
 //   • live id ≠ remembered   → a genuinely new app-open. Re-pin to it; the counter bumps once.
 //
+// ── A MINTED ID IS NOT AN APP-OPEN (the second half of the same rule) ────────────────────────
+// The bullet above says "remembered MINTED" because the registry has TWO writers, not one.
+// `reportSessionStart` registers a real open — but `ensureCurrentSessionId()` also WRITES the shared
+// slot, with a fallback id it minted so a fire-and-forget event is not dropped for want of a
+// `session_id`, and it is reached from `analyticsFacade.resolveSessionId`, `wireActivation.track`
+// and `reviews/transport.reportAppEvent`. A host can hit any of those before `useLifecycleEvents`
+// mounts. That made the pin's `observed` a minted id rather than `undefined`, so the cold-start
+// branch never fired and the real `app.session_started` that followed fell through to the last
+// branch as "a genuinely new app-open": ONE launch counted as TWO, and `minSessions: 2` became
+// satisfiable inside a user's FIRST session — failing in the UNSAFE direction. `isMintedSessionId`
+// is the seam that tells the two writers apart; a fallback is not evidence the app was opened.
+//
 // ⚠️ ONE ACCEPTED MISS, deliberately in the safe direction: if the mount open never registers (a
 // refused non-durable device key over a broken store) and a LATER foreground is the first
 // registration the launch ever sees, that registration is ADOPTED rather than counted, costing one
@@ -184,6 +198,12 @@ type OpenPin = {
   openId: string;
   /** The registered session id observed at pin time; `undefined` when `openId` was minted. */
   observed: string | undefined;
+  /**
+   * True when `observed` was a FALLBACK id `ensureCurrentSessionId` minted, not a real app-open.
+   * Such a pin has to behave exactly like `observed === undefined`: nothing has named this open yet,
+   * so the first REAL registration adopts it rather than starting a second one.
+   */
+  observedMinted: boolean;
 };
 
 type GlobalWithOpenId = typeof globalThis & { [PROCESS_OPEN_ID_SLOT]?: OpenPin };
@@ -198,28 +218,37 @@ const openIdGlobal = globalThis as GlobalWithOpenId;
  */
 export const currentOpenId = (): string => {
   const live = getCurrentSessionId();
+  // A FALLBACK id is not an app-open (see the note above `OpenPin.observedMinted`), so it is
+  // recorded as such and never treated as a registration this pin could be measured against.
+  const liveMinted = isMintedSessionId(live);
   const pin = openIdGlobal[PROCESS_OPEN_ID_SLOT];
 
   // First read of the launch. Adopt the registered id when the host wired lifecycle BEFORE any gate
   // rendered — that is the same unit the server counts — otherwise mint one and record that we did.
   if (!pin) {
     const openId = live ?? makeSessionId();
-    openIdGlobal[PROCESS_OPEN_ID_SLOT] = { openId, observed: live };
+    openIdGlobal[PROCESS_OPEN_ID_SLOT] = { openId, observed: live, observedMinted: liveMinted };
     return openId;
   }
 
   // Nothing registered yet, or still the same registered open: the pin stands.
   if (!live || live === pin.observed) return pin.openId;
 
-  // The first registration of the launch NAMES the open we already pinned under a minted id, so it
-  // is adopted, not counted. Re-pinning here is exactly the cold-start double-count described above.
-  if (pin.observed === undefined) {
-    openIdGlobal[PROCESS_OPEN_ID_SLOT] = { openId: pin.openId, observed: live };
+  // The first REAL registration of the launch NAMES the open we already pinned — whether we pinned
+  // under an id this function minted (`observed === undefined`) or under one `ensureCurrentSessionId`
+  // minted for an early event (`observedMinted`). Either way nothing had named the open yet, so it is
+  // adopted, not counted. Re-pinning here is exactly the cold-start double-count described above.
+  if (pin.observed === undefined || pin.observedMinted) {
+    openIdGlobal[PROCESS_OPEN_ID_SLOT] = {
+      openId: pin.openId,
+      observed: live,
+      observedMinted: liveMinted,
+    };
     return pin.openId;
   }
 
   // A second, DIFFERENT registration is a genuinely new app-open.
-  openIdGlobal[PROCESS_OPEN_ID_SLOT] = { openId: live, observed: live };
+  openIdGlobal[PROCESS_OPEN_ID_SLOT] = { openId: live, observed: live, observedMinted: liveMinted };
   return live;
 };
 

package/src/reviews/transport.ts

@@ -16,6 +16,7 @@
  */
 import { ensureCurrentSessionId } from "../analytics/currentSession";
 import { buildEventsRequest, type ClientEvent } from "../analytics/reportClientEvent";
+import { DEADLINE_EXPIRED, withDeadline } from "../utils/withDeadline";
 import type { SubmitResult } from "../utils/submitResult";
 import type { ReviewDecisionResponse, ReviewSubmission, ReviewTarget } from "./types";
 
@@ -77,11 +78,19 @@ export const submitReview = async (
     const url = `${target.serverUrl.replace(/\/$/, "")}/v1/reviews`;
     const headers: Record<string, string> = { "Content-Type": "application/json" };
     if (target.apiKey) headers.Authorization = `Bearer ${target.apiKey}`;
-    const res = await fetch(url, {
-      method: "POST",
-      headers,
-      body: JSON.stringify(review),
-    });
+    // Under a deadline (see `utils/withDeadline`): a hung POST used to hold `ReviewGate`'s
+    // `postOnce` latch closed for the ~60s platform default, which is exactly the window the
+    // unmount recovery net cannot re-post inside.
+    const res = await withDeadline((signal) =>
+      fetch(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(review),
+        signal,
+      }),
+    );
+    // A deadline that expired is not a rejection: nothing reached the server, so it stays re-postable.
+    if (res === DEADLINE_EXPIRED) return "unsent";
     // No response object at all is not an answer — treat it as nothing having reached the server
     // rather than as a rejection, or a stubbed-out `fetch` would silently latch the row away.
     if (!res) return "unsent";
@@ -193,9 +202,14 @@ export const fetchReviewDecision = async (
     const url = `${base}/v1/reviews/decision${qs ? `?${qs}` : ""}`;
     const headers: Record<string, string> = {};
     if (target.apiKey) headers.Authorization = `Bearer ${target.apiKey}`;
-    const res = await fetch(url, { headers });
-    if (!res || !res.ok) return null;
-    const json = (await res.json()) as ReviewDecisionResponse | null;
+    // The BODY read is inside the deadline too: a ceiling cleared when the headers land is not a
+    // ceiling (the `fetchWireFeatures` lesson — see `utils/withDeadline`).
+    const json = await withDeadline(async (signal): Promise<ReviewDecisionResponse | null> => {
+      const res = await fetch(url, { headers, signal });
+      if (!res || !res.ok) return null;
+      return (await res.json()) as ReviewDecisionResponse | null;
+    });
+    if (json === DEADLINE_EXPIRED) return null;
     // A body without a boolean `fire` is not a decision. Guard it explicitly rather than
     // letting `{}` through as a truthy object that `decideReview` would treat as a verdict
     // (`{}.fire === undefined` is falsy, so it would silently read as "never fire").

package/src/reviews/useReviewGate.ts

@@ -12,10 +12,11 @@
  * (`wire_review_<id>_seen`) always applies locally, so a server bug can never spam the prompt.
  * The global `isTestingCoachmark` flag force-shows the gate for QA replay.
  */
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 
+import { getCurrentSessionId, subscribeCurrentSessionId } from "../analytics/currentSession";
 import { hasSeenGate, isCoachmarkTesting, markSeenGate } from "../coachmarks/runtime";
-import { useResolvedFeatures } from "../features/WireFeaturesProvider";
+import { useResolvedFeaturesState } from "../features/WireFeaturesProvider";
 import { decideReview, evaluateGate, resolveRules } from "./decision";
 import { sameDecision, shallowEqual } from "./equality";
 import {
@@ -67,7 +68,19 @@ export const useReviewGate = ({
 
   // The review MASTER switch. Disabled → the gate never fires, composing as an extra AND over
   // the local rules + the server decision seam below (fail-open: defaults to enabled).
-  const featureEnabled = useResolvedFeatures({ flags: features, config: featuresConfig }).review.enabled;
+  //
+  // `settled` is read too, and it is the half that makes the switch real. The flags start on the
+  // all-on defaults and swap only when the fetch resolves, so `featureEnabled` is `true` on the
+  // FIRST render of every mount — including a tenant with `review.enabled: false`. With no
+  // `timeoutFallbackMs` the local wait is skipped as well (`elapsed` starts `true`), so the gate
+  // could become visible, fire `review_prompt_shown`, and take a POSTed row from a user the tenant
+  // had switched off. The comment below ("must never see the gate") was falsified by its own async
+  // default. Holding the FIRST impression until an answer exists is what honours the switch.
+  const { flags: resolvedFeatures, settled: featuresSettled } = useResolvedFeaturesState({
+    flags: features,
+    config: featuresConfig,
+  });
+  const featureEnabled = resolvedFeatures.review.enabled;
 
   const testing = isTesting ?? isCoachmarkTesting();
   const seenKey = reviewSeenKey(config.id, config.oncePerVersion === false ? undefined : config.appVersion);
@@ -75,19 +88,51 @@ export const useReviewGate = ({
   const sessionsKey = reviewSessionsKey(config.id);
   const sessionOpenKey = reviewSessionOpenKey(config.id);
 
+  // ── FOLLOW real app-opens, do not sample one ────────────────────────────────────────────────
+  //
+  // `bumpSessionCount` is IDEMPOTENT per app-open and moves once per open — but it used to be reached
+  // ONLY from the `useState` initializer below, which runs once per component INSTANCE. On a screen
+  // that never unmounts (a home feed, a tab that stays alive) that meant once per PROCESS, and iOS
+  // suspends rather than kills: `useLifecycleEvents` fires a fresh `app.session_started` on every
+  // foreground past its threshold and the SERVER's `min_sessions` advances, while `wire_review_<id>_sessions`
+  // stayed at its launch value and the LOCAL `minSessions` rule was unsatisfiable for the life of the
+  // app. Silent, and in the safe direction (a prompt that never shows), which is why it survived —
+  // `sessionCountAcrossOpens.test.ts` proved the FUNCTION advances and could not see that the HOOK
+  // never asked it again.
+  //
+  // So subscribe to the registry that knows. A notification naming the same open is a no-op by
+  // construction (`bumpSessionCount` reads its stored count back), so the cold-start ordering this
+  // pin exists for is untouched.
+  const openSessionId = useSyncExternalStore(
+    subscribeCurrentSessionId,
+    getCurrentSessionId,
+    getCurrentSessionId,
+  );
+  // Read through a ref: a host that passes `storage={{ … }}` inline (idiomatic React, and what
+  // `frequent_rules` #11 requires this hook to tolerate) mints a fresh identity every render, and
+  // listing it in the deps below would re-run the effect on every one of them.
+  const storageRef = useRef(storage);
+  storageRef.current = storage;
+
   // Read (and bump) the app-open counter. IDEMPOTENT per app-open, NOT per mount: `bumpSessionCount`
   // keys off the live per-open session id (or a per-process id when no host wired the lifecycle
   // events), so a remount, a navigation return, or React StrictMode's dev double-invoke of this
   // initializer all read the same number back instead of inflating it. Before this, `sessions`
   // counted mounts, so the fail-closed `minSessions: 2` default could be satisfied inside the user's
   // very first app open — the exact scenario it was added to prevent.
-  const sessions = useState(() => {
+  const [sessions, setSessions] = useState(() => {
     const store = resolveStorage(storage);
     // No storage pins the counter at 1 forever, so the fail-closed minSessions rule can never be
     // met and the gate silently never fires. Dev-only, once per process.
     warnMissingGateStorage(store, "review");
     return bumpSessionCount(store, sessionsKey, sessionOpenKey);
-  })[0];
+  });
+  useEffect(() => {
+    const next = bumpSessionCount(resolveStorage(storageRef.current), sessionsKey, sessionOpenKey);
+    // A bail-out when the count is unchanged, so a notification for an open already counted costs
+    // nothing: React skips the re-render when the state is identical.
+    setSessions((prev) => (prev === next ? prev : next));
+  }, [openSessionId, sessionsKey, sessionOpenKey]);
 
   // Gate the local rules behind an optional client-side timeout, so a reachable server
   // gets a window to answer first. A present `decision` bypasses the wait entirely.
@@ -123,10 +168,15 @@ export const useReviewGate = ({
     const resolved = decideReview(local, decision);
     // (3) the once-gate always wins locally, even over a server "fire".
     const alreadySeen = hasSeenGate(seenKey, storage, isTesting);
-    const ready = hasServerDecision || elapsed;
+    // FAIL-OPEN IS NOT WEAKENED BY THIS. `featuresSettled` is `false` only while a fetch that could
+    // still change the answer is in flight; it is `true` with no `featuresConfig` (nothing to ask),
+    // with explicit `features`, and — the case that matters — the moment a FAILED fetch resolves,
+    // because `fetchWireFeatures` swallows a timeout / 401 / 5xx into the all-on defaults. So an
+    // unreachable control plane still allows the gate; only an unanswered one holds it.
+    const ready = (hasServerDecision || elapsed) && featuresSettled;
     return { visible: ready && resolved.fire && !alreadySeen, verdict: resolved };
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [featureEnabled, testing, config, decision, events, sessions, elapsed, hasServerDecision, seenKey, lastKey, storage, isTesting]);
+  }, [featureEnabled, featuresSettled, testing, config, decision, events, sessions, elapsed, hasServerDecision, seenKey, lastKey, storage, isTesting]);
 
   // Stable callbacks + a stable controller object, so a host can safely list any of
   // them in its own effect deps without the effect re-firing every render.

package/src/session-analytics/lifecycle.ts

@@ -173,8 +173,24 @@ const emitFirstOpen = (opts: ReportFirstOpenOptions): void => {
  *   • Race guard: an in-memory latch is set SYNCHRONOUSLY before the async read, so two
  *     near-simultaneous calls fire at most once.
  *   • Without `storage`: degraded mode — fires once per PROCESS via the latch only (documented).
+ *   • WITHOUT A TRANSPORT: no-op, and — the point of the check — the once-ever flag is NOT spent.
+ *     See below.
  */
 export const reportFirstOpen = (opts: ReportFirstOpenOptions): void => {
+  // NO TRANSPORT, NO SPEND. `emitFirstOpen` routes through `buildEventsRequest`, which returns
+  // `null` when there is no `target.serverUrl` — so with neither a `sink` nor a server URL the emit
+  // is a silent no-op. Both once-ever guards were still consumed underneath it: the in-memory latch
+  // synchronously, and then the PERSISTED `wireai:first_open:<appId>` flag on the write below. That
+  // marks the install as having reported its first open when NOTHING was ever sent, and the flag
+  // survives app kills — so `app.first_open` was dead for that install FOREVER, with no error and
+  // no event. Reachable on the documented wiring: a `LifecycleConfig` carrying `storage` + `appId`
+  // whose `serverUrl` is optional and resolves late (the hook's effect is mount-only).
+  //
+  // The sibling emitter already gets this right — `reportSessionStart` bails on
+  // `!opts.sink && !target?.serverUrl` BEFORE its own once-per-open guard — and this is the same
+  // check in the same position, for the same reason. A guard may only be spent by a real send.
+  if (!opts.sink && !opts.target?.serverUrl) return;
+
   const appId = opts.appId ?? "default";
 
   // Synchronous latch FIRST: guarantees at-most-one before any await (same-process race guard) and

package/src/session-analytics/useLifecycleEvents.ts

@@ -36,7 +36,12 @@ import { makeSessionId, type ClientEvent, type ClientEventTarget } from "../anal
 import { hydrateDeviceIdentity } from "../context/deviceId";
 import { resolveIdentity } from "../identity/identityRecord";
 import { collectDeviceContext } from "../device/deviceContext";
-import type { WireOnboardingStorage } from "../session/persistedSession";
+import {
+  READ_TIMED_OUT,
+  READ_TIMEOUT_MS,
+  withTimeout,
+  type WireOnboardingStorage,
+} from "../session/persistedSession";
 import { reportFirstOpen } from "./lifecycle";
 import { reportSessionStart } from "./reportSessionStart";
 import { BACKGROUND_SESSION_MS } from "./useSessionStart";
@@ -173,6 +178,23 @@ export const useLifecycleEvents = (
      * emits the event with NO auto key — the same verdict `<WireOnboarding>` reaches on a broken
      * adapter, and strictly better than a key that differs on every launch. Never rejects: the read
      * resolves to a record or `undefined`, never a throw.
+     *
+     * ── AND IT IS CAPPED, BECAUSE "NEVER REJECTS" IS NOT "ALWAYS SETTLES" ──────────────────────
+     *
+     * `hydrateDeviceIdentity` awaits a BARE `storage.getItem`, so an adapter that HANGS (the read
+     * neither resolves nor rejects — a locked keychain, a wedged native bridge) leaves the promise
+     * pending forever. Every fire in this hook lives inside that `.then`, so a hung adapter did not
+     * degrade the device key: it silently killed `app.session_started` AND `app.first_open` for the
+     * whole process, on every launch. Those two events are the funnel's denominator and what the
+     * server counts `min_sessions` from, so `min_sessions` stays 0 and every review / questionnaire
+     * trigger becomes unsatisfiable — with nothing logged and nothing thrown.
+     *
+     * The read is therefore raced against the SAME ceiling the rest of the kit reads through
+     * (`session/persistedSession`'s exported `withTimeout` + `READ_TIMEOUT_MS`, which is also the
+     * ceiling `<WireOnboarding>`'s auto-join gate names). Blowing it fires with NO auto key —
+     * byte-identical to the refusal a rejecting adapter already gets — because a read that did not
+     * answer cannot prove the id is durable, and an event with no device key is a recoverable gap
+     * while no event at all is a permanent one.
      */
     const openAutoDeviceKey = (fire: (autoDeviceKey: string | undefined) => void): void => {
       const { config: cfg, options: opts } = latest.current;
@@ -182,8 +204,14 @@ export const useLifecycleEvents = (
         fire(undefined);
         return;
       }
-      void hydrateDeviceIdentity({ appId: cfg.appId, storage: cfg.storage }).then((identity) => {
+      void withTimeout(
+        hydrateDeviceIdentity({ appId: cfg.appId, storage: cfg.storage }),
+        READ_TIMEOUT_MS,
+      ).then((read) => {
         if (cancelled) return;
+        // READ_TIMED_OUT = the adapter never answered in time. It collapses onto the SAME branch as
+        // a non-durable record — fire with no auto key — so the events still go out, degraded.
+        const identity = read === READ_TIMED_OUT ? undefined : read;
         fire(identity?.durable ? identity.value : undefined);
       });
     };

package/src/session-analytics/useSessionStart.ts

@@ -31,7 +31,12 @@ import { AppState, Platform, type AppStateStatus } from "react-native";
 import type { ClientEventTarget } from "../analytics/reportClientEvent";
 import { hydrateDeviceIdentity } from "../context/deviceId";
 import { collectDeviceContext } from "../device/deviceContext";
-import type { WireOnboardingStorage } from "../session/persistedSession";
+import {
+  READ_TIMED_OUT,
+  READ_TIMEOUT_MS,
+  withTimeout,
+  type WireOnboardingStorage,
+} from "../session/persistedSession";
 import { reportSessionStart } from "./reportSessionStart";
 
 /** A foreground after at least this long in the background counts as a NEW app-open (30 min). */
@@ -125,6 +130,15 @@ export const useSessionStart = (
      * rule `context/deviceId.ts` states for exactly these callers: *"Callers that write a key onto the
      * wire as a cross-launch join must read `durable` and refuse a `false`."* A host-supplied key or a
      * config with no `storage` still fires synchronously — there is nothing to read.
+     *
+     * AND THE WAIT IS CAPPED. `hydrateDeviceIdentity` awaits a BARE `storage.getItem`, so an adapter
+     * that HANGS (neither resolves nor rejects) leaves that promise pending forever — and since the
+     * only fire path in this hook lives inside the `.then`, `app.session_started` then never fires at
+     * all, for the whole process, on every launch. That is the event the server counts `min_sessions`
+     * from, so the counter stays 0 and every server-side trigger becomes unsatisfiable, silently. The
+     * read is raced against the kit's shared storage ceiling (`session/persistedSession`'s exported
+     * `withTimeout` + `READ_TIMEOUT_MS`, the same one `<WireOnboarding>`'s auto-join gate names), and
+     * blowing it fires with NO auto key — exactly the branch a rejecting adapter already takes.
      */
     const openAutoDeviceKey = (fireOpen: (autoDeviceKey: string | undefined) => void): void => {
       const { config: cfg, options: opts } = latest.current;
@@ -134,8 +148,14 @@ export const useSessionStart = (
         fireOpen(undefined);
         return;
       }
-      void hydrateDeviceIdentity({ appId: cfg.appId, storage: cfg.storage }).then((identity) => {
+      void withTimeout(
+        hydrateDeviceIdentity({ appId: cfg.appId, storage: cfg.storage }),
+        READ_TIMEOUT_MS,
+      ).then((read) => {
         if (cancelled) return;
+        // READ_TIMED_OUT = the adapter never answered in time. Same branch as a non-durable record:
+        // fire with no auto key, so the app-open is still counted.
+        const identity = read === READ_TIMED_OUT ? undefined : read;
         fireOpen(identity?.durable ? identity.value : undefined);
       });
     };

package/src/showcase/FeatureShowcase.tsx

@@ -9,7 +9,8 @@ import { type ImageSourcePropType, StyleSheet, View } from "react-native";
 
 import { GestureHint } from "../coachmarks/GestureHint";
 import { hasSeenGate, markSeenGate, showcaseGateKey } from "../coachmarks/runtime";
-import { useResolvedFeatures } from "../features/WireFeaturesProvider";
+import { useResolvedFeaturesState } from "../features/WireFeaturesProvider";
+import { READ_TIMEOUT_MS } from "../session/persistedSession";
 import { useOnboardingTheme } from "../theme/ThemeContext";
 import type { OnboardingTheme } from "../theme/types";
 import { resolveShowcaseOnboarding } from "./blazejOnboarding";
@@ -49,6 +50,11 @@ const mergeThemeOver = (
  * When the gate says "seen", it renders nothing and calls `onDone` from an
  * effect (never during render).
  *
+ * When the tenant's feature answer has not landed yet AND the flags could still change the
+ * outcome (an unseen gate + a resolvable pager), it renders nothing and calls nothing for up to
+ * `READ_TIMEOUT_MS`, then falls through to the optimistic path. That window is bounded, and only
+ * ever reached on the launch the showcase would actually play; see the hold note below.
+ *
  * The underlying package is an OPTIONAL peer, resolved through the guarded lazy
  * require in `blazejOnboarding.ts` rather than a static import, so the showcase
  * subpath builds on a host that never installed it. Absent, this takes the SAME
@@ -76,7 +82,11 @@ const _FeatureShowcase: React.FC<FeatureShowcaseProps> = ({
 
   // Feature kill switch: disabled → treat like "already seen" (render nothing, call onDone so the
   // host flow continues) but WITHOUT writing the seen gate, so re-enabling replays the showcase.
-  const flags = useResolvedFeatures({ flags: features, config: featuresConfig });
+  // `settled` separates the tenant's ANSWER from the optimistic all-on default; see the hold below.
+  const { flags, settled } = useResolvedFeaturesState({
+    flags: features,
+    config: featuresConfig,
+  });
   const disabled = !flags.showcase.enabled;
 
   // The optional pager peer. Resolved once, on first render, instead of at module scope — so
@@ -94,6 +104,37 @@ const _FeatureShowcase: React.FC<FeatureShowcaseProps> = ({
   // the feature is re-enabled or the peer is installed.
   const skip = seen || disabled || !Onboarding;
 
+  /**
+   * THE FIRST-FRAME HOLD, and why it is scoped this tightly.
+   *
+   * The flags start all-on and swap when `GET /v1/features` resolves, so on a cold start `disabled`
+   * reads false because nobody has asked yet. A tenant who switched the showcase OFF therefore got
+   * the whole full-screen intro anyway — and if the user tapped through it inside that window,
+   * `finish` wrote the seen gate, so the showcase never replayed even after the tenant re-enabled
+   * it. Silent, permanent, once per install.
+   *
+   * The seam the review + questionnaire gates use — hold the first render outright until the
+   * flags settle — does not port unchanged: this component's disabled path calls `onDone`, so a
+   * naive hold on `!settled` would leave a blank full screen, and on every launch, including the
+   * ones where the flags cannot change the outcome at all.
+   * Two things bound it:
+   *   • `flagsCouldMatter` — an already-seen gate or an absent pager skips whatever the tenant
+   *     answers, so those launches (which is every launch after the first) never wait at all;
+   *   • `READ_TIMEOUT_MS` — the repo's one exported read ceiling, reused rather than a third
+   *     number invented here. The features fetch's own ceiling is 4000ms, which is too long to
+   *     stare at nothing, so an answer that has not arrived by then falls through to the previous
+   *     optimistic behaviour. Fail-open in the time dimension: the worst case is what shipped
+   *     before, reached later.
+   */
+  const flagsCouldMatter = !seen && !!Onboarding;
+  const [holdExpired, setHoldExpired] = useState(false);
+  useEffect(() => {
+    if (settled || holdExpired || !flagsCouldMatter) return undefined;
+    const timer = setTimeout(() => setHoldExpired(true), READ_TIMEOUT_MS);
+    return () => clearTimeout(timer);
+  }, [settled, holdExpired, flagsCouldMatter]);
+  const holding = flagsCouldMatter && !settled && !holdExpired;
+
   const doneRef = useRef(false);
   const finish = useCallback(() => {
     if (doneRef.current) return;
@@ -105,11 +146,14 @@ const _FeatureShowcase: React.FC<FeatureShowcaseProps> = ({
   // Already seen OR disabled → skip without rendering; call onDone from an effect so the host's
   // navigation continues (never write the gate here — `finish` owns the seen write).
   useEffect(() => {
+    // Never advance the host while holding: `onDone` is the host's navigation, and a skip decided
+    // on the optimistic default is the same guess the render path refuses below.
+    if (holding) return;
     if (skip && !doneRef.current) {
       doneRef.current = true;
       onDone();
     }
-  }, [skip, onDone]);
+  }, [holding, skip, onDone]);
 
   const [activeIndex, setActiveIndex] = useState(0);
 
@@ -191,6 +235,9 @@ const _FeatureShowcase: React.FC<FeatureShowcaseProps> = ({
     [t],
   );
 
+  // Holding for the tenant's answer: render nothing AND advance nothing (the effect above is
+  // gated too), so a disabled tenant never gets the first frame and never burns the seen gate.
+  if (holding) return null;
   // `!Onboarding` is already folded into `skip`; it is repeated here so the narrowing is explicit
   // to the reader and to the compiler at the JSX below.
   if (skip || !Onboarding) return null;

package/src/types.ts

@@ -240,10 +240,11 @@ export type WireOnboardingProps = {
    * Build the value with the helper so the wire spelling is decided in one place:
    *
    * ```tsx
-   * <WireOnboarding userContext={activationJoinContext(deviceKey)} ... />
-   * // no device id of your own? pass `storage` and leave this prop alone — the kit injects its
-   * // own key, and only after it has confirmed the key actually persists (see `autoJoinKey`).
-   * <WireOnboarding config={{ ...config, storage }} ... />
+   * <WireOnboarding config={config} userContext={activationJoinContext(deviceKey)} ... />
+   * // no device id of your own? pass the `storage` PROP (it is a prop of this component, never a
+   * // field of `WireOnboardingConfig`) and leave this prop alone — the kit injects its own key,
+   * // and only after it has confirmed the key actually persists (see `autoJoinKey`).
+   * <WireOnboarding config={config} storage={storage} ... />
    * ```
    *
    * ⛔ Do NOT hand-build the auto key with `activationJoinContext(resolveAutoDeviceKey({...}))`.

package/src/utils/withDeadline.ts

@@ -0,0 +1,70 @@
+/**
+ * withDeadline — put a CEILING on an awaited network exchange, body read included.
+ *
+ * ── THE DEFECT CLASS THIS CLOSES ───────────────────────────────────────────────────────────────
+ * The kit's awaited `fetch` calls used to split into two groups. `eventQueue.postBatch` and
+ * `wireDoctor` each carried their own `AbortController` + 15s / 10s timer; the review and
+ * questionnaire transports and `reportClientEventsOutcome` carried nothing at all. A hung request on
+ * one of those has no ceiling but the PLATFORM's, which on iOS is ~60s — and for that whole window
+ * `ReviewGate` / `QuestionnaireGate`'s `postOnce` latch stays closed (so the unmount recovery net
+ * cannot re-post) and a host's `await wire.track()` stays pending. It is bounded, so it is not the
+ * hang; it is the thing that WIDENS the in-flight window every other fix in this area narrows.
+ *
+ * ── WHY TWO MECHANISMS, NOT JUST AN ABORT ──────────────────────────────────────────────────────
+ * Lifted verbatim in shape from `features/fetchWireFeatures.ts`, which learned it the expensive way:
+ * a timer cleared around the `fetch` alone dies the moment the HEADERS land, so `await res.json()`
+ * then runs with no ceiling at all and a proxy that flushes headers and hangs pends forever. So the
+ * exchange callback owns the body read too, and there are two independent guards:
+ *
+ *   • the ABORT tears the socket down, so a stalled stream is cancelled and not merely un-awaited;
+ *   • the RACE guarantees this promise SETTLES even on a runtime that ignores `signal` once the body
+ *     has started (RN's `fetch` is the XHR polyfill; abort support is not something to bet a latch on).
+ *
+ * A ceiling that depends on the host honouring abort is not a ceiling.
+ *
+ * INTERNAL SEAM — deliberately not on the public barrels, like `utils/warnInDev` and
+ * `analytics/currentSession`'s `isMintedSessionId`. It is dependency-free and imports nothing, so it
+ * is safe for the tree-shaken `./analytics` graph (`analytics/treeShake.test.ts`).
+ */
+
+/**
+ * "The deadline passed before the exchange produced anything." A `unique symbol`, so it can never
+ * collide with a value the exchange itself resolved — `null`, `undefined` and `false` are all
+ * legitimate answers at these call sites, which is exactly why the sentinel cannot be one of them.
+ */
+export const DEADLINE_EXPIRED: unique symbol = Symbol("wire-deadline-expired");
+
+/**
+ * The one ceiling for the kit's awaited transports. 15s, matching `eventQueue.postBatch`'s existing
+ * ceiling on an awaited POST — the precedent in this repo for "long enough that a slow but real
+ * network still lands, short enough that nothing waits on the ~60s platform default".
+ */
+export const DEFAULT_DEADLINE_MS = 15_000;
+
+/**
+ * Run `exchange` under `timeoutMs`, handing it the abort signal to pass to `fetch`. Resolves what
+ * the exchange resolved, or {@link DEADLINE_EXPIRED} if the deadline won. REJECTS with whatever the
+ * exchange threw (an abort included), so every existing `try/catch` at a call site keeps its meaning.
+ */
+export const withDeadline = async <T>(
+  exchange: (signal: AbortSignal | undefined) => Promise<T>,
+  timeoutMs: number = DEFAULT_DEADLINE_MS,
+): Promise<T | typeof DEADLINE_EXPIRED> => {
+  const controller = typeof AbortController !== "undefined" ? new AbortController() : undefined;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const expired = new Promise<typeof DEADLINE_EXPIRED>((resolve) => {
+    timer = setTimeout(() => {
+      controller?.abort();
+      resolve(DEADLINE_EXPIRED);
+    }, timeoutMs);
+  });
+  const running = exchange(controller?.signal);
+  try {
+    return await Promise.race([running, expired]);
+  } finally {
+    clearTimeout(timer);
+    // The loser can still settle after the race is decided with nothing awaiting it, and an
+    // unobserved rejection is a hard crash on some hosts. Attach a handler either way.
+    void running.catch(() => {});
+  }
+};