@wireai/activation 0.14.3 → 0.16.0

package/src/reviews/idempotency.ts

@@ -0,0 +1,109 @@
+/**
+ * idempotency.ts — the ONE idempotency key and the ONE identity a single gate impression posts under.
+ *
+ * ── WHAT THE SERVER DOES WITH THESE, AND WHY BOTH ARE REQUIRED ───────────────────────────────
+ *
+ * `POST /v1/reviews` accepts an optional `idempotency_key`: two posts carrying the same key upsert
+ * ONE row instead of creating two, which is what stops a re-post double-counting `count` and
+ * corrupting `avg`. The row id is derived, never the key verbatim —
+ * `rev_ + sha256(app_id : unit : key)[:24]` — where `app_id` comes from the resolved `wai_` Bearer
+ * key (never the body) and `unit` is the USER the key is scoped to.
+ *
+ * THE PART THAT MAKES A KEY-ONLY CHANGE INERT: `unit` is `meta.device_key`, else `session_id`, and
+ * when the post carries NEITHER the server drops the key on the floor and inserts a normal row —
+ * deliberately, because an unbounded key could merge two strangers' reviews. The gate lives on the
+ * home feed, where a user legitimately has no onboarding session, so `session_id` is frequently
+ * absent; and nothing in the kit ever put a `device_key` into a review `meta` — that was documented
+ * as a host responsibility. Sending a key without guaranteeing the identity would therefore have
+ * shipped a field the server discards.
+ *
+ * ── THE SCOPE IS THE WHOLE DESIGN ────────────────────────────────────────────────────────────
+ *
+ * One key per gate IMPRESSION, held across every post of that impression:
+ *   • minted per POST instead → the re-post carries a different key, writes the second row, and
+ *     defeats the feature on the exact path it exists to protect.
+ *   • minted once per INSTALL instead → a later, genuine second review merges into the first and
+ *     destroys a rating.
+ * The identity is pinned for the same reason and in the same object: the auto device key is adopted
+ * from persistence ASYNCHRONOUSLY, so a value re-read between two posts of one impression can move
+ * under us, and two posts under two different units hash to two different rows.
+ */
+import { ambientAutoDeviceKey } from "../context/deviceId";
+
+/** Prefix so a kit-minted review key is visibly ours in a stored `meta` dump. */
+export const REVIEW_IDEMPOTENCY_PREFIX = "rvw_";
+
+/**
+ * Mint a fresh idempotency key. Dependency-free timestamp + randomness, the same scheme
+ * `makeSessionId` and `mintDeviceId` already use — the key only has to be unique among the
+ * impressions of ONE install, because the server hashes it together with `app_id` and the unit
+ * before it ever becomes a row id.
+ */
+export const mintIdempotencyKey = (): string =>
+  `${REVIEW_IDEMPOTENCY_PREFIX}${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+
+/** Whether a `meta` bucket already carries a usable, host-supplied `device_key`. */
+export const hasDeviceKey = (meta: Record<string, unknown> | undefined): boolean => {
+  const value = meta?.device_key;
+  return typeof value === "string" && value.trim().length > 0;
+};
+
+/** The key + identity every post of ONE gate impression carries. Both resolved once, at creation. */
+export interface ReviewImpression {
+  /** The `idempotency_key` on the wire. Stable for the impression, distinct across impressions. */
+  readonly idempotencyKey: string;
+  /**
+   * The auto `device_key` to stamp when the host supplied none, or `undefined` when the kit cannot
+   * name one honestly (two tenants in one process). A host-supplied key that {@link hasDeviceKey}
+   * accepts — a string with at least one non-whitespace character — always wins over this and is
+   * never touched; the caller checks that first.
+   */
+  readonly deviceKey: string | undefined;
+}
+
+/**
+ * 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(),
+  deviceKey: ambientAutoDeviceKey(),
+});

package/src/reviews/index.ts

@@ -55,8 +55,10 @@ export { requestStoreReview, openStoreListing, storeUrl } from "./storeReview";
 // hand-rolling a decision fetch: a host-rolled one that collapses `{fire:false}` into undefined
 // makes the server able to turn prompts ON but never OFF (the 2026-07-16 first-session incident).
 // `submitReview` resolves with a THREE-state `ReviewSubmitResult` (accepted / rejected / unsent),
-// not a boolean: only `unsent` may be retried, because the wire has no idempotency key and a
-// re-post after a non-2xx that already committed writes a second row.
+// not a boolean: only `unsent` is retried today. A body built by `ReviewGate` now carries an
+// `idempotency_key` plus the unit the server scopes it to, so that re-post upserts one row instead
+// of writing a second; whether a `rejected` verdict should ALSO retry is a separate recovery-budget
+// decision and is deliberately unchanged.
 export { submitReview, fetchReviewDecision, reportAppEvent } from "./transport";
 export type {
   FetchReviewDecisionOptions,

package/src/reviews/runtime.ts

@@ -5,8 +5,8 @@
  * mounted CoachmarkProvider gets review gating for free — no second storage to wire.
  */
 import type { CoachmarkStorage } from "../coachmarks/types";
-import { getCoachmarkStorage } from "../coachmarks/runtime";
-import { getCurrentSessionId } from "../analytics/currentSession";
+import { getCoachmarkStorage, validateGateStorage } from "../coachmarks/runtime";
+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. */
@@ -22,10 +22,12 @@ export const reviewSessionsKey = (id: string): string => `wire_review_${id}_sess
 /** Companion key holding the open id the counter was LAST incremented for (see {@link bumpSessionCount}). */
 export const reviewSessionOpenKey = (id: string): string => `wire_review_${id}_open`;
 
-/** Resolve the storage to use: an explicit override, else the provider-injected singleton. */
+/** Resolve the storage to use: an explicit override, else the provider-injected singleton — both
+ *  routed through the thenable probe, so an ASYNC adapter resolves to the fail-closed substitute
+ *  (see `validateGateStorage` in coachmarks/runtime) instead of feeding Promises to `readInt`. */
 export const resolveStorage = (
   override?: CoachmarkStorage | null,
-): CoachmarkStorage | null => override ?? getCoachmarkStorage();
+): CoachmarkStorage | null => validateGateStorage(override ?? getCoachmarkStorage());
 
 /** RN sets this global; absent under node/SSR. Read defensively via {@link warnMissingGateStorage}. */
 declare const __DEV__: boolean | undefined;
@@ -154,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
@@ -182,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 };
@@ -196,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";
 
@@ -45,23 +46,28 @@ export type ReviewSubmitResult = SubmitResult;
  *
  * It was, for exactly one unpublished release, and the boolean was the bug. `false` meant both
  * "nothing reached the server" and "the server answered non-2xx", and the one caller that reads
- * this (`ReviewGate.postOnce`) treats `false` as "still owed" and re-posts. But the server mints
- * its own row id (`create_review` / `_new_id()`) and `CreateReviewRequest` carries no id, so there
- * is NO idempotency key on the wire: a 502 returned AFTER the insert commits means the re-post
- * writes a SECOND row, double-counting `count` and corrupting `avg` — the precise corruption the
- * one-row latch exists to prevent. A response of any status proves the server was reached, and
- * that is a different question from whether it liked the row. So the two are different values.
+ * this (`ReviewGate.postOnce`) treats `false` as "still owed" and re-posts. At the time there was
+ * no idempotency key on the wire at all, so a 502 returned AFTER the insert commits meant the
+ * re-post wrote a SECOND row, double-counting `count` and corrupting `avg` — the precise corruption
+ * the one-row latch exists to prevent. A response of any status proves the server was reached, and
+ * that is a different question from whether it liked the row. So the two are different values, and
+ * they stay different: the split is what lets the caller decide, and the retry-on-`rejected`
+ * question is a recovery-budget decision the key does not answer on its own.
  *
  * ── THE RESIDUAL, STATED HONESTLY ────────────────────────────────────────────────────────────
  *
  * `unsent` is not proof the server never got the row. A connection dropped after the request was
  * written — or after the row committed — surfaces as a thrown/rejected `fetch` here, exactly like
- * an offline device. Retrying only on `unsent` is therefore SAFER, not SAFE: it removes the
- * double-post the server itself told us about, and leaves the narrow window where the answer never
- * made it back onto the wire. Closing that window needs a CLIENT-MINTED IDEMPOTENCY KEY the server
- * upserts on, which is a server change (`CreateReviewRequest` + `create_review`) and is not
- * something the kit can fake. Until it exists, prefer losing a row over inventing one: a lost
- * detractor is a gap in the data, a duplicated one is a lie in the data.
+ * an offline device. That used to make the `unsent` re-post SAFER rather than SAFE, and it is what
+ * the client-minted idempotency key now covers: `ReviewSubmission.idempotency_key` reaches
+ * `CreateReviewRequest`, and the server upserts the derived row rather than inserting a second one.
+ *
+ * IT IS A CAPABILITY, NOT A GUARANTEE, and the condition is not ours to enforce from in here. The
+ * server honours the key only when the post also carries a unit it can scope it to —
+ * `meta.device_key`, else `session_id` — and ignores it outright otherwise. `ReviewGate` fills the
+ * device key in for exactly this reason, but this function posts whatever body it is handed, so a
+ * caller that assembles its own body without a unit is back in the old world where a lost detractor
+ * is a gap in the data and a duplicated one is a lie in the data.
  */
 export const submitReview = async (
   target: ReviewTarget | undefined,
@@ -72,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";
@@ -188,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/types.ts

@@ -97,6 +97,13 @@ export interface ReviewSubmission {
   contact?: string;
   session_id?: string;
   source?: string;
+  /**
+   * OPTIONAL client-minted key for the two-phase submit: two posts carrying the same key upsert ONE
+   * row instead of creating two. The server honours it ONLY when the post also carries a resolvable
+   * user — `meta.device_key`, else `session_id` — and silently ignores it otherwise, so it always
+   * travels with one of those. One key per gate impression, stable across that impression's posts.
+   */
+  idempotency_key?: string;
   meta?: Record<string, unknown>;
 }
 

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);
       });
     };