@wireai/activation 0.14.3 → 0.16.0

package/src/coachmarks/runtime.ts

@@ -27,6 +27,9 @@
  */
 import type { CoachmarkStorage } from "./types";
 
+/** RN sets this global; absent under node/SSR. Read defensively via the async-adapter warn below. */
+declare const __DEV__: boolean | undefined;
+
 /**
  * Well-known key into the runtime-global symbol registry — one coachmark runtime across bundles.
  *
@@ -48,6 +51,12 @@ type CoachmarkRuntime = {
   // resolved flags. Disabled → the tour never ARMS and the overlay `show()` is a no-op, so nothing
   // paints and — critically — no once-gate is written, so re-enabling replays the tour correctly.
   coachmarksEnabled: boolean;
+  // Whether `coachmarksEnabled` is an ANSWER from the tenant, or still the optimistic all-on
+  // default nobody has confirmed. Default true = fail-open, and OPTIONAL on the type for the same
+  // reason as `listeners` below: a record left by an inlined copy from an OLDER kit version has no
+  // such field, and reading that absence as `false` would stop every tour under it from arming.
+  // See setCoachmarksResolved for why this is a SECOND flag and not a third state on the first.
+  coachmarksResolved?: boolean;
   // Subscribers to the kill switch. OPTIONAL on the type (never on the behaviour) so a record left
   // in the registry by an inlined copy from an OLDER kit version — which had no listener set — is
   // upgraded in place rather than read as corrupt.
@@ -115,6 +124,50 @@ export const setCoachmarksEnabled = (value: boolean): void => {
 /** Whether the coachmarks module is enabled. False → tours/overlays are silently skipped. */
 export const areCoachmarksEnabled = (): boolean => coachmarkRuntime().coachmarksEnabled;
 
+/**
+ * Mark whether the value in `coachmarksEnabled` is the tenant's ANSWER or still the optimistic
+ * default nobody has confirmed. Written by CoachmarkProvider from the resolved features' `settled`;
+ * read (subscribed) by `useCoachmarkTour`'s ARM effect, and by nothing else.
+ *
+ * ── WHY A SECOND FLAG AND NOT A THIRD STATE ON `coachmarksEnabled` ──────────────────────────────
+ * The features fetch seeds the all-on defaults and swaps when `GET /v1/features` resolves, so on
+ * every cold start there is a window where "coachmarks: on" only means "nobody has asked yet". A
+ * tenant who switched the module OFF still gets the first tour of every launch out of that window.
+ *
+ * The obvious repair — hold the surface by writing `setCoachmarksEnabled(false)` until the answer
+ * lands — CANNOT be used here, and would ship a strictly worse defect. That flag is TERMINAL: the
+ * tour subscribes to it and a flip to false calls `exit()`, ending the tour. Writing it `false`
+ * during the wait would end the tour of every ENABLED tenant on every cold start. So the two facts
+ * are kept apart, and only one of them is terminal:
+ *   • `coachmarksEnabled`  — the verdict. `false` tears a tour down. Stays `true` while the answer
+ *     is unknown, so nothing is ever torn down on a guess.
+ *   • `coachmarksResolved` — "is that verdict an answer?". `false` only blocks ARMING a NEW tour.
+ *     No timer starts, no overlay shows, and no once-gate is consumed, so the tour plays in full
+ *     the moment an ON answer lands.
+ *
+ * "Resolved" means the fetch ANSWERED, not that it SUCCEEDED — `fetchWireFeatures` swallows a
+ * timeout / 401 / 5xx into the all-on defaults and that fallback IS the answer, so an unreachable
+ * control plane arms the tour rather than darking it (fail-open, unchanged).
+ *
+ * Shares the kill switch's listener set: a subscriber has to wake on either fact changing, and one
+ * set is one thing to keep correct rather than two.
+ */
+export const setCoachmarksResolved = (value: boolean): void => {
+  const runtime = coachmarkRuntime();
+  if ((runtime.coachmarksResolved ?? true) === value) return;
+  runtime.coachmarksResolved = value;
+  notifyCoachmarksEnabled();
+};
+
+/**
+ * Whether the coachmarks verdict is an ANSWER yet. False → a NEW tour must not arm (a tour already
+ * in flight is untouched). Absent field → true: no provider, or an older inlined copy's record,
+ * means nothing is going to answer this, which is the same fail-open default the features
+ * `settled` context takes.
+ */
+export const areCoachmarksResolved = (): boolean =>
+  coachmarkRuntime().coachmarksResolved ?? true;
+
 /**
  * Subscribe to kill-switch flips. Returns the unsubscribe function — the `useSyncExternalStore`
  * contract, and deliberately the SAME shape as `coachmarkOverlay.subscribe` next door rather than
@@ -126,6 +179,9 @@ export const areCoachmarksEnabled = (): boolean => coachmarkRuntime().coachmarks
  * nothing can be tapped to advance, and no terminal path is reachable. `useCoachmarkTour`
  * subscribes instead. The listener set lives in the SAME `globalThis` record as the flag, so every
  * inlined copy of this module shares one subscriber list.
+ *
+ * It also carries `coachmarksResolved` (see `setCoachmarksResolved`): both facts wake the same
+ * listeners, so a `useSyncExternalStore` over either one uses this same subscribe function.
  */
 export const subscribeCoachmarksEnabled = (listener: () => void): (() => void) => {
   const listeners = enabledListeners();
@@ -166,6 +222,104 @@ export const showcaseGateKey = (showcaseId: string): string =>
 /** Marker value written for a seen gate. */
 const SEEN_VALUE = "1";
 
+/** Key used only by the one-off synchronicity probe below. Never carries a meaningful value. */
+const GATE_PROBE_KEY = "wire_gate_probe";
+
+/** Once-per-process latch on its own `Symbol.for` slot, mirroring `gateStorageWarned` next door
+ *  in reviews/runtime: a plain `let` would warn once per inlined bundle copy, and the gates live
+ *  in three of them.
+ *
+ *  @globalSlot LATCH — written `true` by the first probe that caught an ASYNC gate adapter, and
+ *  never again. A second differing write re-arms a warning the process already spent, so a host
+ *  whose broken adapter reaches three gates gets the same paragraph three times and stops reading. */
+const ASYNC_GATE_STORAGE_WARNED_SLOT: unique symbol = Symbol.for(
+  "@wireai/activation:asyncGateStorageWarned",
+);
+
+type GlobalWithAsyncGateWarn = typeof globalThis & {
+  [ASYNC_GATE_STORAGE_WARNED_SLOT]?: boolean;
+};
+
+const asyncGateWarnGlobal = globalThis as GlobalWithAsyncGateWarn;
+
+/**
+ * The substitute for an adapter whose `getItem` returned a thenable (an ASYNC adapter, e.g.
+ * AsyncStorage handed straight in). Every seen-gate reads SEEN and every write is dropped, so
+ * nothing shows and nothing fires — FAIL CLOSED, deliberately in both directions the async bug
+ * could err: a Promise is never `=== "1"`, so a raw async adapter reports every gate UNSEEN
+ * forever — tours and showcases replay on every open, and a review gate with `minSessions` 0/1
+ * RE-FIRES its prompt each open (the 2026-07-16 one-star incident class). Never-fire is the only
+ * direction a once-per-user gate may err in.
+ */
+const closedGateStorage: CoachmarkStorage = Object.freeze({
+  getItem: (): string => SEEN_VALUE,
+  setItem: (): void => {},
+});
+
+/** Adapters probed sync (or throwing, which every reader already tolerates): pass through. */
+const syncGateAdapters = new WeakSet<CoachmarkStorage>();
+/** Adapters caught returning a thenable: substituted, and never probed again. */
+const asyncGateAdapters = new WeakSet<CoachmarkStorage>();
+
+/** Warn once, in dev builds only, when a gate adapter turned out to be async. */
+const warnAsyncGateStorage = (): void => {
+  if (asyncGateWarnGlobal[ASYNC_GATE_STORAGE_WARNED_SLOT]) return;
+  if (typeof __DEV__ === "undefined" || !__DEV__) return;
+  if (typeof console === "undefined" || !console.warn) return;
+  asyncGateWarnGlobal[ASYNC_GATE_STORAGE_WARNED_SLOT] = true;
+  console.warn(
+    "[wireai] the gate storage's getItem returned a Promise — an async adapter (e.g. AsyncStorage) " +
+      "cannot drive the once-per-user gates, so coachmark tours, showcases and the review/questionnaire " +
+      "gates are all DISABLED (fail closed: nothing shows, nothing fires) until a synchronous adapter " +
+      "is provided. Pass a sync adapter (e.g. MMKV: `{ getItem: (k) => mmkv.getString(k) ?? null, " +
+      "setItem: (k, v) => mmkv.set(k, v) }`) to CoachmarkProvider or the gate's `storage` prop.",
+  );
+};
+
+/** Test-only: forget the once-per-process async-adapter warn latch. */
+export const resetAsyncGateStorageWarning = (): void => {
+  asyncGateWarnGlobal[ASYNC_GATE_STORAGE_WARNED_SLOT] = undefined;
+};
+
+/**
+ * The thenable probe (fail closed): resolve an adapter to itself when its `getItem` is
+ * synchronous, and to `closedGateStorage` when it returns a thenable. Called on every gate READ
+ * rather than at injection, so (a) a host handing storage straight to a gate's `storage` prop is
+ * probed too, and (b) `CoachmarkProvider`'s unmount cleanup — which compares the singleton to its
+ * own prop by IDENTITY — keeps seeing the object the host passed. Verdicts are WeakSet-cached, so
+ * each adapter pays for exactly one probe read.
+ */
+export const validateGateStorage = (
+  storage: CoachmarkStorage | null,
+): CoachmarkStorage | null => {
+  if (!storage) return null;
+  if (syncGateAdapters.has(storage)) return storage;
+  if (asyncGateAdapters.has(storage)) return closedGateStorage;
+  let probed: unknown;
+  try {
+    probed = storage.getItem(GATE_PROBE_KEY);
+  } catch {
+    // A throwing adapter is synchronous, which is all the probe rules on; every reader already
+    // tolerates the throw itself.
+    syncGateAdapters.add(storage);
+    return storage;
+  }
+  if (probed != null && typeof (probed as { then?: unknown }).then === "function") {
+    asyncGateAdapters.add(storage);
+    try {
+      // Detach the probe's promise so an adapter that REJECTS (e.g. a broken native store) cannot
+      // surface as an unhandled rejection the host never scheduled.
+      (probed as PromiseLike<unknown>).then(undefined, () => {});
+    } catch {
+      // A hostile thenable whose `then` throws is still async; the verdict stands.
+    }
+    warnAsyncGateStorage();
+    return closedGateStorage;
+  }
+  syncGateAdapters.add(storage);
+  return storage;
+};
+
 /**
  * Read a seen gate. Testing mode ALWAYS reports unseen (so everything replays).
  * A missing storage (no provider) also reports unseen — the safe default is to
@@ -179,7 +333,7 @@ export const hasSeenGate = (
   testingOverride?: boolean,
 ): boolean => {
   if (testingOverride ?? isCoachmarkTesting()) return false;
-  const storage = storageOverride ?? getCoachmarkStorage();
+  const storage = validateGateStorage(storageOverride ?? getCoachmarkStorage());
   if (!storage) return false;
   try {
     return storage.getItem(key) === SEEN_VALUE;
@@ -198,7 +352,7 @@ export const markSeenGate = (
   testingOverride?: boolean,
 ): void => {
   if (testingOverride ?? isCoachmarkTesting()) return;
-  const storage = storageOverride ?? getCoachmarkStorage();
+  const storage = validateGateStorage(storageOverride ?? getCoachmarkStorage());
   if (!storage) return;
   try {
     storage.setItem(key, SEEN_VALUE);

package/src/coachmarks/types.ts

@@ -31,8 +31,13 @@ export interface TargetRect {
 
 /**
  * The host-injected gate storage. SYNCHRONOUS on purpose — a coachmark's
- * "seen?" gate must resolve during render with no async flash (otherwise a ring
- * momentarily paints before the read resolves and says "already seen"). MMKV's
+ * "seen?" gate must resolve during render. This is ENFORCED, fail closed: a
+ * probe on first read catches an adapter whose `getItem` returns a thenable
+ * (AsyncStorage handed straight in) and substitutes a closed adapter — every
+ * gate reads "seen", nothing shows, nothing fires, one dev warning names the
+ * fix (see `validateGateStorage` in ./runtime). A raw async adapter would
+ * otherwise report every gate unseen forever: tours replay each open, and a
+ * review gate with `minSessions` 0/1 re-fires each open. MMKV's
  * `getString`/`set` fit as-is; an in-memory `Map` wrapper works for tests. This
  * is deliberately separate from the async `WireOnboardingStorage` used for
  * session persistence.

package/src/coachmarks/useCoachmarkTour.ts

@@ -4,6 +4,7 @@ import { coachmarkAnchors } from "./coachmarkAnchorRegistry";
 import { coachmarkOverlay } from "./coachmarkOverlayStore";
 import {
   areCoachmarksEnabled,
+  areCoachmarksResolved,
   coachmarkGateKey,
   hasSeenGate,
   markSeenGate,
@@ -76,6 +77,15 @@ const DEFAULT_START_DELAY_MS = 3000;
  * `show()` is a no-op while the flag is off, so a tour that carried on would paint nothing, could
  * not be tapped to advance, and would never reach a terminal state.
  *
+ * ARM vs TERMINAL — the third gate, and why it is not the second one. Until the tenant's flags
+ * land, that kill switch reads ON because nobody has asked yet, so a tenant who turned coachmarks
+ * OFF still got the first tour of every cold start. The wait CANNOT be expressed by writing the
+ * kill switch false, precisely because that flag is terminal: it would end the tour of every
+ * ENABLED tenant on every cold start, a worse defect than the one being fixed. So an UNANSWERED
+ * verdict (`areCoachmarksResolved`, written by CoachmarkProvider from the features' `settled`)
+ * blocks only the ARM below — a tour already in flight is never touched by it — and costs nothing
+ * while it waits: no timer, no overlay, no once-gate spent.
+ *
  * IMPORTANT: `steps` MUST be a stable (memoized) array. If a new array identity
  * is passed on every render the drive effect re-runs and re-shows the current
  * step (wasteful anchor re-resolves / overlay churn), and analytics can
@@ -120,6 +130,15 @@ export const useCoachmarkTour = (
     areCoachmarksEnabled,
   );
 
+  // Whether that kill switch is an ANSWER yet, or still the optimistic all-on default. Gates the
+  // ARM effect only — see the ARM vs TERMINAL note above. Same subscribe function: both facts live
+  // in one runtime record and wake one listener set.
+  const coachmarksResolved = useSyncExternalStore(
+    subscribeCoachmarksEnabled,
+    areCoachmarksResolved,
+    areCoachmarksResolved,
+  );
+
   /**
    * The single terminal exit. `writeGate` is what separates the two ways a tour can end:
    *   • the user reached the end (or dismissed the last step) → the once-gate IS written, so a
@@ -147,18 +166,40 @@ export const useCoachmarkTour = (
   // Arm once, after the delay, when enabled and the gate is unseen.
   useEffect(() => {
     if (!enabled || startedRef.current) return undefined;
+    // AN EMPTY TOUR IS NOT A TOUR — never arm on one. With no steps the arm timer still fired, the
+    // drive effect below immediately hit `activeIndex >= steps.length`, and `finish()` wrote the
+    // once-gate for a tour the user never saw a single frame of. The gate is persisted and
+    // `finishedRef` blocks recovery in this mount, so the tour was dead for good — even after the
+    // catalog that produced the empty list was fixed. It is not a hypothetical list either: on the
+    // documented AI path `selectTourSteps(catalog, selection)` returns `[]` whenever the server
+    // sends ids that match nothing in the SHIPPED catalog (an app that cannot be force-updated),
+    // and any host whose steps arrive async passes `[]` on the first render.
+    //
+    // Keyed on `steps.length`, deliberately NOT on the array itself: the drive effect below already
+    // requires a memoized `steps`, and listing the identity here would restart the arm timer on
+    // every render of a host that passes an inline array (frequent_rules #11) — a tour that never
+    // arms, swapping one silent failure for another. The length is a value, so late-arriving steps
+    // still re-run this effect and arm the tour properly.
+    if (steps.length === 0) return undefined;
     // Feature kill switch: never arm while coachmarks are disabled, so no timer starts, no
     // overlay shows, and the once-gate is NOT consumed — re-enabling replays the tour. Reading
     // the SUBSCRIBED value (and listing it in the deps) is what makes that last clause true
     // without a remount: flipping it off clears a pending arm timer, flipping it back on re-arms.
     if (!coachmarksOn) return undefined;
+    // …and never arm on an UNANSWERED one. `coachmarksOn` is all-on until the tenant's flags land,
+    // so without this a tenant who switched coachmarks off still got the first tour of every cold
+    // start — the kill switch working everywhere except the one moment it is read. Blocking the
+    // ARM (rather than writing the kill switch false, which is terminal — see the note above) is
+    // what makes the wait free: no timer, no overlay, no once-gate spent, so an ON answer plays
+    // the tour in full. A FAILED fetch is an answer too, so a dead control plane still arms.
+    if (!coachmarksResolved) return undefined;
     if (showOnce && hasSeenGate(coachmarkGateKey(tourId))) return undefined;
     const timer = setTimeout(() => {
       startedRef.current = true;
       setActiveIndex(0);
     }, startDelayMs);
     return () => clearTimeout(timer);
-  }, [enabled, coachmarksOn, startDelayMs, showOnce, tourId]);
+  }, [enabled, coachmarksOn, coachmarksResolved, startDelayMs, showOnce, tourId, steps.length]);
 
   // Drive the active step. Keyed on `enabled` too, so a mid-tour focus loss
   // pauses (hide, keep position) and a return to focus resumes the same step.
@@ -182,6 +223,15 @@ export const useCoachmarkTour = (
       return undefined;
     }
 
+    // The other half of the empty-tour rule, for a list that goes empty AFTER the tour armed (a
+    // re-selection, a catalog swap): end it, but take the kill-switch exit — `exit(false)` — so the
+    // once-gate is not written. `finish()` here would spend it on a tour with nothing to show, which
+    // is exactly the burn the arm guard above refuses at the other end.
+    if (steps.length === 0) {
+      exit(false);
+      return undefined;
+    }
+
     if (activeIndex >= steps.length) {
       finish();
       return undefined;

package/src/context/deviceId.ts

@@ -73,8 +73,8 @@ export const mintDeviceId = (): string => {
  * Well-known key into the runtime-global symbol registry — one auto-id registry across every bundle.
  *
  * @globalSlot LATCH — the REGISTRY OBJECT is created once and its identity is then stable. A second
- * write empties `keys`/`hydrating`/`pending`, so the next surface mints a SECOND auto id for one
- * install and the `device_key` the server joins sessions on splits in two — the halved-counter
+ * write empties `keys`/`hydrating`/`pending`/`ambient`, so the next surface mints a SECOND auto id
+ * for one install and the `device_key` the server joins sessions on splits in two — the halved-counter
  * defect this registry exists to close. Its CONTENTS are live (the id per `appId` is replaced when
  * an async hydration adopts a persisted value), so callers must re-read through
  * `resolveAutoDeviceKey()` rather than hold the string a mount happened to see first.
@@ -91,11 +91,17 @@ const AUTO_DEVICE_KEY_SLOT: unique symbol = Symbol.for("@wireai/activation:autoD
 type HydrationOutcome = { value: string; durable: boolean };
 
 /** The shared registry: the live id per `appId`, the set of appIds whose hydration already started,
- *  and the in-flight (or settled) hydration promise per `appId` so a waiter can join it. */
+ *  and the in-flight (or settled) hydration promise per `appId` so a waiter can join it.
+ *
+ *  `ambient` is deliberately NOT an entry in `keys`: it is the last-resort id
+ *  {@link ambientAutoDeviceKey} mints for a process that has registered no id space at all, and
+ *  `keys` is the TENANT CENSUS that same function counts to decide whether it may answer. Putting
+ *  the fallback in the census made the fallback look like a tenant — see the note on that function. */
 type AutoDeviceKeyRegistry = {
   keys: Map<string, string>;
   hydrating: Set<string>;
   pending?: Map<string, Promise<HydrationOutcome>>;
+  ambient?: string;
 };
 
 type GlobalWithDeviceKeys = typeof globalThis & {
@@ -237,8 +243,19 @@ export const resolveAutoDeviceKey = (opts: ResolveAutoDeviceKeyOptions = {}): st
  * follows it. Only a caller that can afford one storage read should use this; the fire-and-forget
  * event paths must stay on the sync function.
  *
- * Never throws or rejects: a missing, hung, or rejecting adapter resolves to the in-memory id, and
- * with no `storage` it resolves immediately (there is nothing to hydrate from).
+ * Never throws or rejects: a missing or rejecting adapter resolves to the in-memory id, and with no
+ * `storage` it resolves immediately (there is nothing to hydrate from).
+ *
+ * ⛔ A HUNG ADAPTER IS THE ONE CASE IT DOES NOT COVER, and this line used to claim it did. The read
+ * underneath is a bare `storage.getItem` with no ceiling of its own, so an adapter that neither
+ * resolves nor rejects (a locked keychain, a wedged native bridge) leaves THIS PROMISE PENDING
+ * FOREVER — it does not fall back to the in-memory id, it simply never answers. Anything that gates
+ * a user-visible or metric-bearing action on the result must therefore race it against a ceiling of
+ * its own: `<WireOnboarding>` does (`AUTO_JOIN_HYDRATION_TIMEOUT_MS`), and so do the two lifecycle
+ * hooks (`session-analytics/useLifecycleEvents` + `useSessionStart`, through the shared
+ * `withTimeout` + `READ_TIMEOUT_MS` in `session/persistedSession`) — a hung read there had silently
+ * killed `app.session_started` and `app.first_open` for the whole process. Use the SYNC
+ * {@link resolveAutoDeviceKey} when you cannot afford to wait at all.
  *
  * ⚠️ IT RETURNS A BARE STRING, so it CANNOT say whether the id survives the launch — a degraded
  * adapter resolves to the in-memory mint and reads identically to a persisted one. No kit surface
@@ -263,7 +280,9 @@ export const hydrateAutoDeviceKey = async (
  *
  * Resolves `undefined` only when there is no usable id at all. With no `storage` it resolves
  * immediately with `durable: false` — a process-scoped id is exactly what "no persistence" means.
- * Never throws or rejects.
+ * Never throws or rejects — but, exactly like {@link hydrateAutoDeviceKey} above, it can also never
+ * SETTLE on a hung adapter (the underlying `getItem` carries no ceiling), so every caller races it
+ * against one of its own. See the note there.
  */
 export const hydrateDeviceIdentity = async (
   opts: ResolveAutoDeviceKeyOptions = {},
@@ -290,4 +309,51 @@ export const resetAutoDeviceKeys = (): void => {
   registry.keys.clear();
   registry.hydrating.clear();
   registry.pending?.clear();
+  registry.ambient = undefined;
+};
+
+/**
+ * The auto `device_key` a surface with NO `appId` and NO `storage` of its own may stamp onto a
+ * payload — the review gate being the one that exists (`ReviewGate` takes neither prop).
+ *
+ * WHY IT IS NOT JUST `resolveAutoDeviceKey()`. That function is keyed by `appId`, and `appId` is a
+ * REQUIRED field on `WireOnboardingConfig` that real hosts set to a real value. A propless caller
+ * can only pass `undefined`, which addresses the `"default"` slot — so on any host that names its
+ * app, a bare call would MINT a second id beside the one every other surface already shares. That is
+ * the halved-counter defect this registry exists to close (see the registry note above), arrived at
+ * from the other direction.
+ *
+ * So this READS the TENANT CENSUS (`registry.keys`) and does not address it:
+ *   • exactly one id space in the process → that id, whoever registered it. This is every
+ *     single-tenant app, i.e. every real app, and it is how the gate joins the analytics surfaces.
+ *   • none at all → the registry's `ambient` fallback, minted here on first ask. Nothing exists to
+ *     collide with, so it is not a second space, it is the only one. PROCESS-scoped (there is no
+ *     storage to persist through), which is honest and still resolvable: a review row is written
+ *     once per user, so a per-launch value here cannot corrupt a counter the way it corrupts
+ *     `min_sessions` — and without SOME unit the server discards the impression's
+ *     `idempotency_key` outright, so refusing to answer costs a re-post its upsert.
+ *   • two or more → `undefined`. Two tenants in one process must never share an id, and a caller
+ *     with no `appId` cannot say which one it belongs to. Refusing is the only safe answer;
+ *     guessing would stamp one tenant's device onto the other's row.
+ *
+ * ⛔ THE FALLBACK IS NOT A TENANT, AND THAT IS THE WHOLE REASON IT LIVES IN ITS OWN FIELD (0.15.1).
+ * It used to be minted through `resolveAutoDeviceKey()`, which registered it in `keys` under
+ * `"default"`. The three states above are only exhaustive at ONE INSTANT, and this one wrote into
+ * the very map the next instant is judged by: a gate that fired before any Wire surface had
+ * initialised (the review gate lives on the home feed, so a cold start can reach it first) left a
+ * `"default"` entry behind, and the moment the host's real `appId` registered the census read TWO —
+ * so every later call returned `undefined` and the injected `device_key` was silently dead for the
+ * rest of the process. Holding the fallback OUTSIDE the census makes it yield instead: a real id
+ * space appearing later simply wins, which is the answer the middle bullet wanted all along.
+ *
+ * Never throws, never mints a SECOND id into the census, and never overrides anything a host
+ * supplied — the caller checks for a host value first.
+ */
+export const ambientAutoDeviceKey = (): string | undefined => {
+  const registry = autoDeviceKeyRegistry();
+  if (registry.keys.size > 1) return undefined;
+  const sole = [...registry.keys.values()][0];
+  if (sole) return sole;
+  if (!registry.ambient) registry.ambient = mintDeviceId();
+  return registry.ambient;
 };

package/src/features/WireFeaturesProvider.tsx

@@ -15,7 +15,7 @@
 import React, { createContext, useContext, useMemo } from "react";
 
 import { defaultWireFeatures } from "./defaults";
-import { useWireFeatures } from "./useWireFeatures";
+import { useWireFeaturesState, type WireFeaturesState } from "./useWireFeatures";
 import type { WireFeatures, WireFeaturesConfig } from "./types";
 
 /**
@@ -26,16 +26,49 @@ import type { WireFeatures, WireFeaturesConfig } from "./types";
  * the all-on defaults with no crash and no warning. Because it is a latch, and only because of
  * that, the module-local `const WireFeaturesContext` below may cache it.
  */
-const CONTEXT_SYMBOL = Symbol.for("wireai.features.context");
+const CONTEXT_SYMBOL: unique symbol = Symbol.for("wireai.features.context");
 // `globalThis`, not `global`: the other nine `Symbol.for` slots in this kit all use it, and `global`
 // simply does not exist in a plain browser (RN-web / SSR-in-the-browser), where this line would
 // throw a ReferenceError before the provider could render anything.
-const globalObj = globalThis as any;
+//
+// The slot is TYPED rather than cast through `any` (which is banned, `ai_rules/rules/core.md`). The
+// cast was not cosmetic: with `any` on both sides, BOTH contexts below were inferred `any`, so every
+// `<X.Provider value={...}>` in this file and every `useContext` read of them was type-unchecked —
+// a provider publishing the wrong shape into either one would have compiled. Declaring each key
+// `unique symbol` is what lets it appear as a property key in a type at all.
+type GlobalWithFeaturesContext = typeof globalThis & {
+  [CONTEXT_SYMBOL]?: React.Context<WireFeatures | null>;
+};
+const featuresContextGlobal = globalThis as GlobalWithFeaturesContext;
 
-if (!globalObj[CONTEXT_SYMBOL]) {
-  globalObj[CONTEXT_SYMBOL] = createContext<WireFeatures | null>(null);
+if (!featuresContextGlobal[CONTEXT_SYMBOL]) {
+  featuresContextGlobal[CONTEXT_SYMBOL] = createContext<WireFeatures | null>(null);
 }
-const WireFeaturesContext = globalObj[CONTEXT_SYMBOL];
+const WireFeaturesContext = featuresContextGlobal[CONTEXT_SYMBOL];
+
+/**
+ * @globalSlot LATCH — the SECOND context, carrying only "has the provider's fetch answered yet?".
+ *
+ * WHY A SECOND CONTEXT AND NOT A WIDER VALUE: the value published above is a `WireFeatures`, and
+ * tsup inlines a copy of this module per subpath bundle. Changing the published SHAPE would mean a
+ * provider from one copy publishing an object a consumer from another copy reads as flags —
+ * silently wrong flags rather than a crash. An extra context is additive: a consumer that reads it
+ * without a provider (or under an OLDER copy's provider that publishes nothing here) gets the
+ * default below.
+ *
+ * THE DEFAULT IS `true`, AND FAIL-OPEN DEPENDS ON IT: "settled" gates a surface's first render, so
+ * defaulting to `false` would let a missing provider suppress a gate forever. `true` means "nothing
+ * above is going to answer this for you", which is the truth when there is no provider at all.
+ */
+const SETTLED_SYMBOL: unique symbol = Symbol.for("wireai.features.settled.context");
+type GlobalWithSettledContext = typeof globalThis & {
+  [SETTLED_SYMBOL]?: React.Context<boolean>;
+};
+const settledContextGlobal = globalThis as GlobalWithSettledContext;
+if (!settledContextGlobal[SETTLED_SYMBOL]) {
+  settledContextGlobal[SETTLED_SYMBOL] = createContext<boolean>(true);
+}
+const WireFeaturesSettledContext = settledContextGlobal[SETTLED_SYMBOL];
 
 export interface WireFeaturesProviderProps {
   /** Tenant creds (+ optional storage) to fetch the flags once for the whole tree. */
@@ -59,10 +92,16 @@ export const WireFeaturesProvider: React.FC<WireFeaturesProviderProps> = ({
 }) => {
   // Always call the hook (rules of hooks); when `flags` is supplied we pass no config so it
   // never fetches and the explicit flags win below.
-  const fetched = useWireFeatures(flags ? undefined : config);
-  const value = flags ?? fetched;
+  const fetched = useWireFeaturesState(flags ? undefined : config);
+  const value = flags ?? fetched.flags;
+  // Explicit `flags` are an answer by definition; otherwise the fetch decides.
+  const settled = flags ? true : fetched.settled;
   const stable = useMemo(() => value, [value]);
-  return <WireFeaturesContext.Provider value={stable}>{children}</WireFeaturesContext.Provider>;
+  return (
+    <WireFeaturesSettledContext.Provider value={settled}>
+      <WireFeaturesContext.Provider value={stable}>{children}</WireFeaturesContext.Provider>
+    </WireFeaturesSettledContext.Provider>
+  );
 };
 
 WireFeaturesProvider.displayName = "WireFeaturesProvider";
@@ -87,11 +126,32 @@ export interface ResolveFeaturesOptions {
  *   4. the all-on defaults.
  * Always fail-open, always a stable reference for a given value (so it's safe in effect deps).
  */
-export const useResolvedFeatures = (options?: ResolveFeaturesOptions): WireFeatures => {
+export const useResolvedFeatures = (options?: ResolveFeaturesOptions): WireFeatures =>
+  useResolvedFeaturesState(options).flags;
+
+/**
+ * The same resolution, plus whether the value is an ANSWER or still the optimistic default —
+ * `useResolvedFeatures` is the flags-only wrapper over this.
+ *
+ * A gated surface whose first render is irreversible (the review gate fires `review_prompt_shown`
+ * and can take a review row the moment it appears) must hold that first render until `settled`,
+ * or a tenant that turned the module OFF still gets one impression per launch while the fetch is
+ * in flight — the kill switch working everywhere except the one moment it is read.
+ *
+ * `settled` follows the same precedence as the flags: explicit `flags` are an answer; under a
+ * provider it is the PROVIDER's fetch that has to answer; otherwise it is this surface's own lazy
+ * fetch, which is already `true` when there is nothing to fetch. Deliberately INTERNAL (not in the
+ * root barrel): it exists for the kit's own gated surfaces, and the public flags-only contract is
+ * unchanged.
+ */
+export const useResolvedFeaturesState = (options?: ResolveFeaturesOptions): WireFeaturesState => {
   const ctx = useWireFeaturesContext();
+  const ctxSettled: boolean = useContext(WireFeaturesSettledContext);
   // Only lazily fetch when nothing else provides the flags — otherwise pass no config so the
   // hook stays inert (defaults, no network). The hook is always called (rules of hooks).
   const shouldFetch = !options?.flags && ctx == null;
-  const fetched = useWireFeatures(shouldFetch ? options?.config : undefined);
-  return options?.flags ?? ctx ?? fetched ?? defaultWireFeatures;
+  const fetched = useWireFeaturesState(shouldFetch ? options?.config : undefined);
+  const flags = options?.flags ?? ctx ?? fetched.flags ?? defaultWireFeatures;
+  const settled = options?.flags ? true : ctx != null ? ctxSettled : fetched.settled;
+  return useMemo(() => ({ flags, settled }), [flags, settled]);
 };

package/src/features/fetchWireFeatures.ts

@@ -30,23 +30,62 @@ const failOpen = async (
   return cached?.features ?? defaultWireFeatures;
 };
 
-/** GET with a hard timeout via AbortController (falls back to no-abort where unsupported). */
-const fetchWithTimeout = async (
+/** "The exchange produced nothing usable" — a non-2xx, or a deadline the body never met. Both mean
+ *  the caller must fail OPEN, and neither is distinguishable to it. A symbol so it can never
+ *  collide with a JSON body the server actually sent. */
+const NO_ANSWER: unique symbol = Symbol("wire-features-no-answer");
+
+/**
+ * GET **and read the body** under ONE deadline. Never pends longer than `timeoutMs`.
+ *
+ * ── THE DEFECT THIS CLOSES ─────────────────────────────────────────────────────────────────────
+ * The timer used to be cleared in a `finally` around the `fetch` alone, so it died the moment the
+ * HEADERS landed and `await res.json()` ran with NO ceiling at all. A 200 whose body then stalls —
+ * a half-open connection, a proxy that flushes headers and hangs, a captive portal — left this
+ * function pending forever. `settled` never flips, so `useReviewGate` and `useQuestionnaireGate`
+ * never become ready and BOTH gates stay dark for the life of the process, silently. That INVERTS
+ * this module's own stated contract at the top of the file: fail-open, never fail-dark.
+ *
+ * SCOPE, honestly: on native RN `fetch` is the XHR polyfill and the body is already buffered by the
+ * time the promise resolves, so this was effectively unreachable there. On RN-Web / Expo web — which
+ * the kit explicitly supports (`WireFeaturesProvider`) — it is real.
+ *
+ * TWO mechanisms, deliberately, because they fail differently. The abort tears the socket DOWN
+ * (a stalled stream is not just un-awaited, it is cancelled); the race guarantees this promise
+ * SETTLES even on a runtime that ignores `signal` once the body has started. A ceiling that depends
+ * on the host honouring abort is not a ceiling on a surface whose whole contract is "never dark".
+ */
+const fetchFeaturesJson = async (
   url: string,
   apiKey: string,
   timeoutMs: number,
-): Promise<Response> => {
+): Promise<unknown> => {
   const controller =
     typeof AbortController !== "undefined" ? new AbortController() : undefined;
-  const timer = setTimeout(() => controller?.abort(), timeoutMs);
-  try {
-    return await fetch(url, {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const expired = new Promise<typeof NO_ANSWER>((resolve) => {
+    timer = setTimeout(() => {
+      controller?.abort();
+      resolve(NO_ANSWER);
+    }, timeoutMs);
+  });
+  const exchange = (async (): Promise<unknown> => {
+    const res = await fetch(url, {
       method: "GET",
       headers: { Accept: "application/json", Authorization: `Bearer ${apiKey}` },
       signal: controller?.signal,
     });
+    // 401 (bad/rotated key), 5xx, any non-2xx → last-known, never dark.
+    if (!res || !res.ok) return NO_ANSWER;
+    return (await res.json()) as unknown; // throws on malformed body → caught by the caller
+  })();
+  try {
+    return await Promise.race([exchange, expired]);
   } finally {
     clearTimeout(timer);
+    // The loser can still settle after the race is decided and nothing is awaiting it. An
+    // unobserved rejection is a hard crash on some hosts, so it gets a handler either way.
+    void exchange.catch(() => {});
   }
 };
 
@@ -72,15 +111,14 @@ export const fetchWireFeatures = async (
   const timeoutMs = config.timeoutMs && config.timeoutMs > 0 ? config.timeoutMs : DEFAULT_TIMEOUT_MS;
 
   try {
-    const res = await fetchWithTimeout(url, config.apiKey, timeoutMs);
-    // 401 (bad/rotated key), 5xx, any non-2xx → last-known, never dark.
-    if (!res || !res.ok) return failOpen(storage, key);
-    const json: unknown = await res.json(); // throws on malformed body → caught below
+    const json: unknown = await fetchFeaturesJson(url, config.apiKey, timeoutMs);
+    // A non-2xx, or a headers-then-stall body that never met the deadline → last-known, never dark.
+    if (json === NO_ANSWER) return failOpen(storage, key);
     const features = parseWireFeatures(json);
     if (storage) writeCachedFeatures(storage, key, features);
     return features;
   } catch {
-    // Timeout/abort, network error, missing fetch, or malformed JSON — all fail open.
+    // Abort, network error, missing fetch, or malformed JSON — all fail open.
     return failOpen(storage, key);
   }
 };