@wireai/activation 0.11.0 → 0.12.1

package/src/reviews/runtime.ts

@@ -6,6 +6,8 @@
  */
 import type { CoachmarkStorage } from "../coachmarks/types";
 import { getCoachmarkStorage } from "../coachmarks/runtime";
+import { getCurrentSessionId } 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. */
 export const reviewSeenKey = (id: string, version?: string): string =>
@@ -14,14 +16,59 @@ export const reviewSeenKey = (id: string, version?: string): string =>
 /** Last-shown timestamp key (epoch ms), for the cooldown rule. */
 export const reviewLastShownKey = (id: string): string => `wire_review_${id}_last`;
 
-/** Session-count key, incremented once per gate mount, for the min-sessions rule. */
+/** Session-count key, incremented once per APP-OPEN (not per mount), for the min-sessions rule. */
 export const reviewSessionsKey = (id: string): string => `wire_review_${id}_sessions`;
 
+/** 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. */
 export const resolveStorage = (
   override?: CoachmarkStorage | null,
 ): CoachmarkStorage | null => override ?? getCoachmarkStorage();
 
+/** RN sets this global; absent under node/SSR. Read defensively via {@link warnMissingGateStorage}. */
+declare const __DEV__: boolean | undefined;
+
+/** Once-per-process latch on its own `Symbol.for` slot: a plain `let` would warn once per inlined
+ *  bundle copy, and the gates live in three of them. */
+const NO_STORAGE_WARNED_SLOT: unique symbol = Symbol.for(
+  "@wireai/activation:gateStorageWarned",
+);
+
+type GlobalWithGateWarn = typeof globalThis & { [NO_STORAGE_WARNED_SLOT]?: boolean };
+
+const gateWarnGlobal = globalThis as GlobalWithGateWarn;
+
+/**
+ * Warn once, in dev builds only, when a gate has NO sync storage to count with.
+ *
+ * With no storage `readInt` returns 0, so `bumpSessionCount` answers `1` on every call forever and
+ * the fail-closed `minSessions: 2` default can never be met: the gate is pinned shut for the life of
+ * the app and nothing anywhere says so. The fix is one line at the app root (mount `CoachmarkProvider`
+ * with a sync storage, or pass `storage` to the gate), so name it.
+ */
+export const warnMissingGateStorage = (
+  storage: CoachmarkStorage | null,
+  gate: "review" | "questionnaire",
+): void => {
+  if (storage) return;
+  if (gateWarnGlobal[NO_STORAGE_WARNED_SLOT]) return;
+  if (typeof __DEV__ === "undefined" || !__DEV__) return;
+  if (typeof console === "undefined" || !console.warn) return;
+  gateWarnGlobal[NO_STORAGE_WARNED_SLOT] = true;
+  console.warn(
+    `[wireai] the ${gate} gate has no sync storage, so its app-open counter is stuck at 1 and the ` +
+      "fail-closed minSessions rule can never be satisfied — the gate will never fire. Mount " +
+      "CoachmarkProvider with a sync storage adapter at your app root, or pass `storage` to the gate.",
+  );
+};
+
+/** Test-only: forget the once-per-process no-storage warn latch. */
+export const resetGateStorageWarning = (): void => {
+  gateWarnGlobal[NO_STORAGE_WARNED_SLOT] = undefined;
+};
+
 /** Read an integer from sync storage (0 on a missing/unparseable/throwing read). */
 export const readInt = (storage: CoachmarkStorage | null, key: string): number => {
   if (!storage) return 0;
@@ -43,3 +90,108 @@ export const writeInt = (storage: CoachmarkStorage | null, key: string, value: n
     // Best-effort.
   }
 };
+
+/** Read a string from sync storage (undefined on a missing/blank/throwing read). */
+const readStr = (storage: CoachmarkStorage | null, key: string): string | undefined => {
+  if (!storage) return undefined;
+  try {
+    const raw = storage.getItem(key);
+    return typeof raw === "string" && raw.length > 0 ? raw : undefined;
+  } catch {
+    return undefined;
+  }
+};
+
+// ── The "which app-open is this" id ──────────────────────────────────────────────────────────
+//
+// The gates' `minSessions` rule needs a SESSION, and the counter behind it used to increment once
+// per gate MOUNT. A mount is not a session: navigating away from the home feed and back, a tab that
+// unmounts its screen, or React StrictMode's dev double-invoke of the `useState` initializer all
+// bumped it. So `minSessions: 2` — the fail-closed default added after the 2026-07-16 one-star
+// incident — was satisfiable inside the user's FIRST app open, which is the exact thing it exists
+// to prevent. `sessions` was a count of mounts wearing the name of a session.
+//
+// The correct unit already exists: `getCurrentSessionId()`, the per-open id the server sees on
+// `app.session_started`. When a host wires the lifecycle events, the counter keys off THAT and is
+// exactly "distinct app-opens", the same unit the server's own `min_sessions` uses.
+//
+// When no host wired lifecycle events there is no registered open, so we fall back to a PROCESS-
+// scoped id: one JS process is one app launch, which is still a genuine app-open and is strictly
+// closer to a session than a mount is. It lives in a `globalThis` slot keyed by `Symbol.for(...)`
+// for the same reason `currentSession` does: tsup inlines this module into several bundles and a
+// plain module-local `let` would give each bundle its own "process".
+//
+// ── WHY THE UNIT IS PINNED FOR THE WHOLE LAUNCH ──────────────────────────────────────────────
+// The first shape of this function read the two tiers LIVE on every call: the registered session id
+// when there was one, else the process id. That let the UNIT change mid-launch, and React's own
+// ordering guarantees it does. The gates call `bumpSessionCount` from a `useState` INITIALIZER,
+// which runs during render; `useLifecycleEvents` registers the session id from a root EFFECT; and
+// React runs every render before any effect. So a cold start went:
+//
+//   render:  gate initializer → no session registered yet → PROCESS id  → count = 1, open = <process>
+//   effect:  root lifecycle   → setCurrentSessionId(<session id>)
+//   remount: gate initializer → SESSION id ≠ the stored open           → count = 2
+//
+// Two "sessions" inside one app open, which makes the fail-closed `minSessions: 2` default (added
+// after the 2026-07-16 one-star incident) satisfiable in the very launch it exists to guard. So the
+// FIRST read pins whatever it resolved into the process slot and every later read returns that,
+// regardless of what the session registry does afterwards. The client counter only has to be
+// monotone and per-launch; the server's own `min_sessions` still counts real `app.session_started`
+// events, so nothing downstream needs the two ids to be identical.
+const PROCESS_OPEN_ID_SLOT: unique symbol = Symbol.for("@wireai/activation:processOpenId");
+
+type GlobalWithOpenId = typeof globalThis & { [PROCESS_OPEN_ID_SLOT]?: string };
+
+const openIdGlobal = globalThis as GlobalWithOpenId;
+
+/**
+ * The id identifying THIS app-open for gate counting, PINNED on first read for the whole launch:
+ * the live per-open `session_id` if one was already registered when the first gate asked, else a
+ * minted per-process id. Stable from the first render to the last. Never empty.
+ */
+export const currentOpenId = (): string => {
+  const existing = openIdGlobal[PROCESS_OPEN_ID_SLOT];
+  if (existing) return existing;
+  // Adopt the registered session id when the host wired lifecycle BEFORE any gate rendered; that is
+  // the same unit the server counts. Otherwise mint one. Either way it is pinned from here on.
+  const resolved = getCurrentSessionId() ?? makeSessionId();
+  openIdGlobal[PROCESS_OPEN_ID_SLOT] = resolved;
+  return resolved;
+};
+
+/** Test-only: forget the process open id so a unit test starts from a clean launch. */
+export const resetProcessOpenId = (): void => {
+  openIdGlobal[PROCESS_OPEN_ID_SLOT] = undefined;
+};
+
+/**
+ * Return the app-open count for the gate, incrementing it AT MOST ONCE per app-open.
+ *
+ * IDEMPOTENT by construction: the open id that last incremented the counter is stored alongside it,
+ * so a second call within the same open (a remount, a StrictMode double-invoke, a second gate render)
+ * reads the stored count back instead of bumping it. A new open id bumps exactly once.
+ *
+ * Storage-less hosts get `1` for the first call and `1` for every later call within the open —
+ * degraded but never inflating, which is the safe direction for a fail-closed gate.
+ */
+export const bumpSessionCount = (
+  storage: CoachmarkStorage | null,
+  sessionsKey: string,
+  openKey: string,
+  openId: string = currentOpenId(),
+): number => {
+  const lastOpen = readStr(storage, openKey);
+  const stored = readInt(storage, sessionsKey);
+  // Already counted this open → return what we counted, do not bump again.
+  if (lastOpen === openId) return stored > 0 ? stored : 1;
+  const next = stored + 1;
+  writeInt(storage, sessionsKey, next);
+  if (storage) {
+    try {
+      storage.setItem(openKey, openId);
+    } catch {
+      // Best-effort: a failed write only means this open may be counted twice.
+    }
+  }
+  return next;
+};

package/src/reviews/transport.ts

@@ -12,6 +12,7 @@
  * question_key=<name>), which is what the backend review-firing rules evaluate on — and
  * it seeds the broader app-analytics stream. Keep payloads minimal + non-PII.
  */
+import { ensureCurrentSessionId } from "../analytics/currentSession";
 import { buildEventsRequest, type ClientEvent } from "../analytics/reportClientEvent";
 import type { ReviewDecisionResponse, ReviewSubmission, ReviewTarget } from "./types";
 
@@ -157,7 +158,11 @@ export const fetchReviewDecision = async (
 
 /** Options for a reported app event. `deviceKey` groups a device's sessions server-side. */
 export interface ReportAppEventOptions {
-  /** The onboarding/session id to correlate with, when known. */
+  /**
+   * The onboarding/session id to correlate with, when known. Optional: when omitted the event
+   * still carries the CURRENT per-open session id (`ensureCurrentSessionId()`), because an event
+   * with no `session_id` is dropped server-side behind a 200. Pass one only to override.
+   */
   sessionId?: string;
   /** A stable, non-PII device id — the review-decision endpoint reads it for min-sessions. */
   deviceKey?: string;
@@ -171,6 +176,16 @@ export interface ReportAppEventOptions {
  * stable identifier and `meta` small + non-PII.
  *
  *   reportAppEvent(target, "content_share", { sessionId, deviceKey });
+ *
+ * ── `session_id` IS NON-NEGOTIABLE ON THE WIRE ───────────────────────────────────────────
+ * The server's event model declares `session_id` required + non-empty, and `POST /v1/events`
+ * validates per event inside a try/except that counts the failure as `skipped` and STILL returns
+ * HTTP 200. An event sent without a `session_id` is therefore accepted and discarded, and a
+ * fire-and-forget caller never finds out. This used to be reachable through the ordinary API:
+ * `options.sessionId` was optional, so a host calling `reportAppEvent(target, "screen", { deviceKey })`
+ * posted every screen view into that hole. So the id is no longer conditional — an explicit
+ * `sessionId` wins, otherwise the CURRENT per-open id is used (minted + registered if no app-open
+ * has been registered yet).
  */
 export const reportAppEvent = (
   target: ReviewTarget | undefined,
@@ -179,11 +194,15 @@ export const reportAppEvent = (
 ): void => {
   if (!target?.serverUrl || !name) return;
   try {
+    // An explicit id wins; a missing OR BLANK one falls back to the current per-open id. A bare
+    // `??` would let `sessionId: ""` through, and the server rejects an empty string exactly like
+    // a missing key (`min_length=1`), so the blank case has to fall back too.
+    const supplied = options.sessionId ?? "";
     const event: Record<string, unknown> = {
       event_type: "app_event",
       question_key: name,
+      session_id: supplied.trim().length > 0 ? supplied : ensureCurrentSessionId(),
     };
-    if (options.sessionId) event.session_id = options.sessionId;
     // device_key rides in the non-PII user_context bucket the server sanitizes; the
     // review-decision endpoint reads it to group a device's sessions.
     if (options.deviceKey) event.user_context = { device_key: options.deviceKey };

package/src/reviews/useReviewGate.ts

@@ -19,11 +19,14 @@ import { useResolvedFeatures } from "../features/WireFeaturesProvider";
 import { decideReview, evaluateGate, resolveRules } from "./decision";
 import { sameDecision, shallowEqual } from "./equality";
 import {
+  bumpSessionCount,
   readInt,
   resolveStorage,
   reviewLastShownKey,
   reviewSeenKey,
+  reviewSessionOpenKey,
   reviewSessionsKey,
+  warnMissingGateStorage,
   writeInt,
 } from "./runtime";
 import type {
@@ -70,13 +73,20 @@ export const useReviewGate = ({
   const seenKey = reviewSeenKey(config.id, config.oncePerVersion === false ? undefined : config.appVersion);
   const lastKey = reviewLastShownKey(config.id);
   const sessionsKey = reviewSessionsKey(config.id);
+  const sessionOpenKey = reviewSessionOpenKey(config.id);
 
-  // Read (and bump) the session counter ONCE per mount: this mount is a new session.
+  // 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 store = resolveStorage(storage);
-    const next = readInt(store, sessionsKey) + 1;
-    writeInt(store, sessionsKey, next);
-    return next;
+    // 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];
 
   // Gate the local rules behind an optional client-side timeout, so a reachable server

package/src/session-analytics/lifecycle.ts

@@ -212,11 +212,18 @@ export interface WireLifecycleOptions extends ReportFirstOpenOptions {}
  * Route both through the same `sink` (the offline queue) to buffer them. Fire-and-forget.
  */
 export const wireLifecycleEvents = (opts: WireLifecycleOptions): void => {
-  reportFirstOpen(opts);
+  // ONE per-open id for BOTH events when the caller supplies none. Without this, `reportFirstOpen`
+  // fell through to `buildLifecycleEvent`'s own `makeSessionId()` while `reportSessionStart` minted a
+  // DIFFERENT one — so `app.first_open` carried a session id the server never saw a `session_started`
+  // for and back-filled into a phantom session, inflating session counts. `useLifecycleEvents` already
+  // pinned this (it mints `mountOpenSessionId`); the React-free entry point did not, so the identical
+  // bug was still reachable from the documented non-hook path.
+  const sessionId = opts.sessionId ?? makeSessionId();
+  reportFirstOpen({ ...opts, sessionId });
   reportSessionStart({
     target: opts.target,
     sink: opts.sink,
-    sessionId: opts.sessionId,
+    sessionId,
     userId: opts.userId,
     deviceKey: opts.deviceKey,
     sessionCount: opts.sessionCount,

package/src/session-analytics/reportSessionStart.ts

@@ -32,7 +32,12 @@
  * never be able to break the app.
  */
 import { setCurrentSessionId } from "../analytics/currentSession";
-import { makeSessionId, type ClientEvent, type ClientEventTarget } from "../analytics/reportClientEvent";
+import {
+  makeSessionId,
+  warnOnSkippedEvents,
+  type ClientEvent,
+  type ClientEventTarget,
+} from "../analytics/reportClientEvent";
 import type { DeviceContext } from "../device/deviceContext";
 import { sanitizeUserId } from "../identity/userIdentity";
 
@@ -162,9 +167,15 @@ export const reportSessionStart = (opts: ReportSessionStartOptions): void => {
       method: "POST",
       headers,
       body: JSON.stringify({ events: [event] }),
-    }).catch(() => {
-      // Network/transport error — analytics is best-effort, swallow.
-    });
+    })
+      .then((res) => {
+        // A 200 can still carry `skipped:N` — the server took the request and threw the event away.
+        // Log-only; this path has nothing to retry either way.
+        warnOnSkippedEvents(res);
+      })
+      .catch(() => {
+        // Network/transport error — analytics is best-effort, swallow.
+      });
   } catch {
     // URL construction, JSON serialization, a throwing sink, or a missing fetch — swallow.
   }

package/src/session-analytics/useLifecycleEvents.ts

@@ -10,7 +10,10 @@
  *
  * Firing moments mirror {@link useSessionStart} exactly:
  *   • ON MOUNT — the app opened (cold start / provider first render). `app.first_open` fires here
- *     too (once ever, gated by the persisted flag in `reportFirstOpen`).
+ *     too (once ever, gated by the persisted flag in `reportFirstOpen`). When the kit's AUTO device
+ *     key is the one in play (no host `deviceKey`, `config.storage` present) the mount fire waits on
+ *     one storage read so both events carry the PERSISTED key, not a freshly minted one — see the
+ *     `hydrateAutoDeviceKey` note below.
  *   • ON FOREGROUND after a real background of at least {@link BACKGROUND_SESSION_MS} (30 min) — a
  *     new app-open, so a fresh `app.session_started` fires. A quick app-switch does NOT count.
  *
@@ -29,6 +32,7 @@ import { AppState, Platform, type AppStateStatus } from "react-native";
 
 import { createEventQueue, type EnvelopeSource, type EventQueue } from "../analytics/eventQueue";
 import { makeSessionId, type ClientEvent, type ClientEventTarget } from "../analytics/reportClientEvent";
+import { hydrateAutoDeviceKey, resolveAutoDeviceKey } from "../context/deviceId";
 import { collectDeviceContext } from "../device/deviceContext";
 import type { WireOnboardingStorage } from "../session/persistedSession";
 import { reportFirstOpen } from "./lifecycle";
@@ -114,6 +118,31 @@ export const useLifecycleEvents = (
     const targetOf = (cfg: LifecycleConfig | undefined): ClientEventTarget | undefined =>
       cfg?.serverUrl ? { serverUrl: cfg.serverUrl, apiKey: cfg.apiKey ?? "" } : undefined;
 
+    /**
+     * The `device_key` these lifecycle events ride under. A host-supplied id always wins.
+     *
+     * WHY THE FALLBACK EXISTS: `min_sessions` (the review / questionnaire firing rule, and the
+     * "fire on the user's Nth session" recipe in the README) is computed SERVER-SIDE by counting
+     * distinct `app.session_started` events grouped by `user_context.device_key`. A host that took
+     * the batteries-included path and passed no `deviceKey` emitted those events with NO device key
+     * at all — while its `createAnalytics` / `createWireActivation` events carried an auto-minted
+     * one. Two disjoint identity spaces again: the counter the rule reads could never increase, so
+     * `min_sessions` was structurally unsatisfiable and the gate never fired from the server side.
+     *
+     * ONLY WITH `storage`: the auto id is per-INSTALL only when it can be persisted. With no
+     * storage it would be per-LAUNCH, which would make every open look like a brand-new device and
+     * corrupt `min_sessions` in the other direction. So no storage → no fallback, same as before.
+     */
+    const resolveDeviceKey = (
+      cfg: LifecycleConfig | undefined,
+      opts: UseLifecycleEventsOptions,
+    ): string | undefined => {
+      const host = typeof opts.deviceKey === "string" && opts.deviceKey.trim() ? opts.deviceKey : undefined;
+      if (host) return host;
+      if (!cfg?.storage) return undefined;
+      return resolveAutoDeviceKey({ appId: cfg.appId, storage: cfg.storage });
+    };
+
     // ONE per-open session id for the MOUNT open, shared by first_open AND session_started below.
     // WHY: `first_open` used to default to its OWN fresh `makeSessionId()` (via `buildLifecycleEvent`)
     // while `session_started` minted a different one — so every install's `first_open` carried a
@@ -138,7 +167,7 @@ export const useLifecycleEvents = (
         sink: resolveSink(),
         sessionId,
         userId: opts.userId,
-        deviceKey: opts.deviceKey,
+        deviceKey: resolveDeviceKey(cfg, opts),
         sessionCount: opts.sessionCount,
         appVersion: cfg?.appVersion ?? device.appVersion,
         platform: Platform.OS,
@@ -147,33 +176,58 @@ export const useLifecycleEvents = (
       });
     };
 
-    // 1) session_start FIRST (mount = an app-open), so the server has ingested `session_started`
-    //    for `mountOpenSessionId` before first_open references the same id.
-    fireSession(mountOpenSessionId);
+    // The mount open: session_start FIRST (mount = an app-open), so the server has ingested
+    // `session_started` for `mountOpenSessionId` before first_open references the same id; then
+    // first_open — once ever (persisted flag + in-memory latch inside reportFirstOpen), pinned to the
+    // SAME per-open id so it is never a phantom session.
+    const fireMountOpen = () => {
+      fireSession(mountOpenSessionId);
 
-    // 2) first_open — once ever (persisted flag + in-memory latch inside reportFirstOpen), pinned to
-    //    the SAME per-open id so it is never a phantom session.
-    {
       const { config: cfg, options: opts } = latest.current;
-      if (opts.enabled !== false) {
-        const device = collectDeviceContext();
-        // `device.appVersion` is auto-detected best-effort; an explicit host version always wins.
-        if (cfg?.appVersion) device.appVersion = cfg.appVersion;
-        reportFirstOpen({
-          target: targetOf(cfg),
-          sink: resolveSink(),
-          sessionId: mountOpenSessionId,
-          storage: cfg?.storage,
-          appId: cfg?.appId,
-          userId: opts.userId,
-          deviceKey: opts.deviceKey,
-          sessionCount: opts.sessionCount,
-          appVersion: cfg?.appVersion ?? device.appVersion,
-          platform: Platform.OS,
-          device,
-          meta: opts.meta,
-        });
-      }
+      if (opts.enabled === false) return;
+      const device = collectDeviceContext();
+      // `device.appVersion` is auto-detected best-effort; an explicit host version always wins.
+      if (cfg?.appVersion) device.appVersion = cfg.appVersion;
+      reportFirstOpen({
+        target: targetOf(cfg),
+        sink: resolveSink(),
+        sessionId: mountOpenSessionId,
+        storage: cfg?.storage,
+        appId: cfg?.appId,
+        userId: opts.userId,
+        deviceKey: resolveDeviceKey(cfg, opts),
+        sessionCount: opts.sessionCount,
+        appVersion: cfg?.appVersion ?? device.appVersion,
+        platform: Platform.OS,
+        device,
+        meta: opts.meta,
+      });
+    };
+
+    // WAIT FOR THE PERSISTED DEVICE KEY, but ONLY when the auto fallback is the one in play.
+    //
+    // `resolveAutoDeviceKey` is synchronous by contract: it returns a freshly minted id and adopts the
+    // PERSISTED one a storage read later. Firing at mount therefore stamped a brand-new `wdev_*` on
+    // BOTH lifecycle events on every launch, while every other surface adopted the persisted id
+    // milliseconds afterwards. Those two events are exactly the ones the server counts `min_sessions`
+    // from (distinct `app.session_started` grouped by `device_key`), so the counter could never exceed
+    // 1 — and `first_open`, fired once ever, ended up under a key no later event shares, which breaks
+    // `first_open` → `activated` cohorting too. One storage read at mount buys both back.
+    //
+    // A host-supplied `deviceKey` needs no read, and with no `storage` there is nothing to read (and
+    // `resolveDeviceKey` deliberately does not fall back), so both keep firing synchronously at mount.
+    let cancelled = false;
+    const { config: mountCfg, options: mountOpts } = latest.current;
+    const hostKey =
+      typeof mountOpts.deviceKey === "string" && mountOpts.deviceKey.trim()
+        ? mountOpts.deviceKey
+        : undefined;
+    if (!hostKey && mountCfg?.storage) {
+      void hydrateAutoDeviceKey({ appId: mountCfg.appId, storage: mountCfg.storage }).then(() => {
+        if (!cancelled) fireMountOpen();
+      });
+    } else {
+      fireMountOpen();
     }
 
     // Foreground after a real background = a new app-open.
@@ -191,6 +245,8 @@ export const useLifecycleEvents = (
     };
     const sub = AppState.addEventListener("change", onChange);
     return () => {
+      // A pending hydration must not fire an app-open for a mount that is already gone.
+      cancelled = true;
       // RN >= 0.65 returns a subscription with remove(); guard for older shims.
       if (sub && typeof (sub as { remove?: () => void }).remove === "function") sub.remove();
     };

package/src/session-analytics/useSessionStart.ts

@@ -10,6 +10,11 @@
  * Each firing mints its OWN per-open `session_id` (held in a ref so a re-render never re-fires),
  * so grouping over time is by `deviceKey`/`userId`, never by session_id (see reportSessionStart).
  *
+ * NOT THE DEFAULT WIRING. `useLifecycleEvents` is: this hook emits `app.session_started` ONLY, so a
+ * host on this path has a permanently empty `app.first_open` and no top of funnel. Use it when you
+ * already own an open counter and deliberately want session starts alone; otherwise mount
+ * `useLifecycleEvents(config, { deviceKey?, sessionCount?, userId? })` once at the app root.
+ *
  * The hook is OPTIONAL. A host that already owns a session counter (most hosts do) can skip
  * the hook and call `reportSessionStart(...)` directly from its own "app opened" path — BOTH
  * paths are first-class. This hook is the batteries-included option for a host that has none.
@@ -21,7 +26,9 @@ import { useEffect, useRef } from "react";
 import { AppState, Platform, type AppStateStatus } from "react-native";
 
 import type { ClientEventTarget } from "../analytics/reportClientEvent";
+import { resolveAutoDeviceKey } from "../context/deviceId";
 import { collectDeviceContext } from "../device/deviceContext";
+import 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). */
@@ -35,6 +42,11 @@ export interface SessionStartConfig {
   apiKey?: string;
   /** Host app version (e.g. "1.4.2"), forwarded for release segmentation. Optional. */
   appVersion?: string;
+  /** Tenant/app id — namespaces the auto `device_key` fallback below. */
+  appId?: string;
+  /** Host storage (AsyncStorage subset). Present → `app.session_started` falls back to the kit's
+   *  persisted auto `device_key` when the host passes none. Absent → no fallback (see below). */
+  storage?: WireOnboardingStorage;
 }
 
 /** Per-open identity the host supplies. All optional: a pre-auth open is device-only. */
@@ -66,6 +78,30 @@ export const useSessionStart = (
   latest.current = { config, options };
 
   useEffect(() => {
+    /**
+     * The `device_key` this open rides under. A host-supplied id always wins.
+     *
+     * BACKPORTED FROM `useLifecycleEvents` (which had this and this hook did not): `min_sessions` is
+     * computed server-side by counting distinct `app.session_started` grouped by
+     * `user_context.device_key`, so a host that passed no `deviceKey` emitted the counted event with
+     * NO key while its facade / activation events carried an auto-minted one — two disjoint identity
+     * spaces, and a counter that could never increase. The two session-start paths must not diverge
+     * on the thing the firing rule reads.
+     *
+     * ONLY WITH `storage`, for the same reason as the sibling hook: without persistence the auto id
+     * is per-LAUNCH, and a per-launch key makes every open look like a new device, corrupting
+     * `min_sessions` in the other direction.
+     */
+    const resolveDeviceKey = (
+      cfg: SessionStartConfig | undefined,
+      opts: UseSessionStartOptions,
+    ): string | undefined => {
+      const host = typeof opts.deviceKey === "string" && opts.deviceKey.trim() ? opts.deviceKey : undefined;
+      if (host) return host;
+      if (!cfg?.storage) return undefined;
+      return resolveAutoDeviceKey({ appId: cfg.appId, storage: cfg.storage });
+    };
+
     const fire = () => {
       const { config: cfg, options: opts } = latest.current;
       if (!cfg?.serverUrl) return;
@@ -78,7 +114,7 @@ export const useSessionStart = (
         target,
         // A fresh per-open id each fire; the emitter's once-guard dedupes within the open.
         userId: opts.userId,
-        deviceKey: opts.deviceKey,
+        deviceKey: resolveDeviceKey(cfg, opts),
         sessionCount: opts.sessionCount,
         appVersion: cfg.appVersion ?? device.appVersion,
         platform: Platform.OS,

package/src/types.ts

@@ -148,16 +148,53 @@ export type WireOnboardingProps = {
   /** Lifecycle hook for host-side analytics (started / per-turn / error). */
   onEvent?: (event: OnboardingEvent) => void;
   /**
-   * Host-injected, non-PII context the app already knows about the user — signup method,
-   * referral source, plan tier, a HASHED user id, etc. Same host-injection philosophy as
-   * `storage`: the kit collects nothing here; the host passes what it wants. Forwarded to the
-   * backend on the session metadata AND on client events so analytics can segment the funnel.
+   * **THIS IS WHERE THE JOIN KEY GOES.** `user_context.device_key` is the ONLY thing that joins an
+   * onboarding session to everything the app reports later (analytics, purchases, gate decisions).
+   * 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? read the kit's:
+   * <WireOnboarding userContext={activationJoinContext(resolveAutoDeviceKey({ appId, storage }))} ... />
+   * ```
+   *
+   * SINCE 0.12.2, leaving it out no longer silently empties the funnel: when you pass `storage` and
+   * this prop carries no `device_key`, the kit injects its OWN per-install key — the same one the
+   * analytics surfaces mint and persist — so the default wiring joins. Anything you DO pass wins
+   * verbatim and is never touched. See `autoJoinKey` for the opt-out and the two cases where the kit
+   * still cannot fill the gap (no `storage`, or you opted out), which keep warning in dev.
+   *
+   * Never hand-write `userContext={{ deviceKey }}`: the server's device lookup reads `device_key`,
+   * so a misspelled bucket produces a silently empty funnel rather than an error. And never join on
+   * `session_id` — an onboarding session id is the A2A `contextId` while an app-event session id is
+   * the per-open id, so intersecting those two id spaces returns zero rows every time.
+   *
+   * SECOND JOB, segmentation: anything else non-PII the app already knows — signup method, referral
+   * source, plan tier, a HASHED user id. Same host-injection philosophy as `storage`: the kit
+   * collects nothing here; the host passes what it wants. Forwarded to the backend on the session
+   * metadata AND on client events so analytics can segment the funnel.
    *
    * MUST NOT contain PII such as raw emails, names, or phone numbers — pass a hash if you need
    * a user key. Values are limited to primitives (`string | number | boolean`); the server caps
    * key count / size and drops deep nesting. Old servers ignore it (backward compatible).
    */
   userContext?: Record<string, string | number | boolean>;
+  /**
+   * OPT OUT of the automatic join key. Default `true`.
+   *
+   * By default (0.12.2+), an onboarding session that was given no `userContext.device_key` gets the
+   * kit's own per-install key injected — the SAME id `createAnalytics` / `createWireActivation` mint
+   * and persist — so the `activated` funnel joins without the host wiring anything. Pass
+   * `autoJoinKey={false}` if you genuinely want an UNLINKED onboarding session; that restores the
+   * pre-0.12.2 behavior exactly (nothing injected) and the dev warning fires again.
+   *
+   * Two things this flag does NOT do. It never overrides a `device_key` you passed — a host-supplied
+   * key always wins, whatever this is set to. And it cannot conjure a key without `storage`: with no
+   * persistence the kit's id is minted fresh every launch, and a per-launch key corrupts
+   * `min_sessions` instead of merely leaving the join empty, so the kit declines to inject and warns
+   * in dev instead.
+   */
+  autoJoinKey?: boolean;
   /**
    * The host's own user id, so onboarding sessions can be reconciled to real users later
    * (console sessions ↔ your user table / GA4 users). First-class alongside `userContext`.