@wireai/activation 0.13.6 → 0.14.0

package/src/session/persistedSession.ts

@@ -52,16 +52,29 @@ export type LoadedSession = {
 };
 
 /**
- * Race a storage read against a ceiling, resolving `undefined` when the adapter did not answer.
+ * The verdict of a read that RAN OUT OF TIME. A distinct value, and deliberately never `undefined`:
+ * an `undefined` here is byte-identical to "the adapter answered, there is nothing stored", and that
+ * conflation is what let a timed-out read mint a fresh session id and WRITE IT OVER the still-valid
+ * one it had not managed to read yet. The event queue reached the same conclusion independently
+ * (`analytics/eventQueue.ts`); this is the same sentinel for the same reason.
+ *
+ * "Did not answer in time" is not "there is nothing there", and the difference is the difference
+ * between starting clean and destroying a session mid-onboarding.
+ */
+export const READ_TIMED_OUT: unique symbol = Symbol("wireai:storage-read-timeout");
+
+/**
+ * Race a storage read against a ceiling, resolving {@link READ_TIMED_OUT} when the adapter did not
+ * answer in time.
  * Exported so the permission memory reads through the same ceiling as the session seed rather than
  * carrying a second copy of it. NOT the kit's only such helper: `features/cache.ts`,
  * `session-analytics/lifecycle.ts` and `analytics/eventQueue.ts` each keep their own local timeout
  * for their own transports. Consolidating those is a separate change, not this one.
  */
-export const withTimeout = <T>(p: Promise<T>, ms: number): Promise<T | undefined> => {
+export const withTimeout = <T>(p: Promise<T>, ms: number): Promise<T | typeof READ_TIMED_OUT> => {
   let timer: ReturnType<typeof setTimeout>;
-  const timeout = new Promise<undefined>((resolve) => {
-    timer = setTimeout(() => resolve(undefined), ms);
+  const timeout = new Promise<typeof READ_TIMED_OUT>((resolve) => {
+    timer = setTimeout(() => resolve(READ_TIMED_OUT), ms);
   });
   // Clear the timer once the race settles, so a won read doesn't leave a ≤ms no-op
   // timer holding the closure alive.
@@ -96,12 +109,19 @@ export const loadPersistedSession = async (
   key: string,
   ttlMs: number = DEFAULT_SESSION_TTL_MS,
 ): Promise<LoadedSession> => {
-  let stored: PersistedSession | undefined;
+  let raw: string | null | typeof READ_TIMED_OUT;
   try {
-    stored = parsePersisted(await withTimeout(storage.getItem(key), READ_TIMEOUT_MS));
+    raw = await withTimeout(storage.getItem(key), READ_TIMEOUT_MS);
   } catch {
-    stored = undefined;
+    raw = null;
   }
+  // TIMED OUT: the mount cannot wait, so it still gets an id and starts clean — but it must NOT
+  // persist it. Writing here overwrites a session the read was still fetching, and a valid
+  // mid-onboarding session id is exactly the thing whose loss the server reads as a phantom drop.
+  // Losing persistence for ONE launch is recoverable; overwriting the blob is not.
+  if (raw === READ_TIMED_OUT) return { id: makeSessionId(), resumed: false };
+
+  const stored = parsePersisted(raw);
   if (stored && Date.now() - stored.ts < ttlMs) {
     return { id: stored.id, resumed: true };
   }
@@ -121,7 +141,11 @@ export const peekPersistedSession = async (
   key: string,
 ): Promise<{ id: string; ts: number } | undefined> => {
   try {
-    return parsePersisted(await withTimeout(storage.getItem(key), READ_TIMEOUT_MS));
+    const raw = await withTimeout(storage.getItem(key), READ_TIMEOUT_MS);
+    // A timed-out read is `undefined` here exactly as before: this function only READS, so
+    // "unknown" and "absent" lead to the same caller behaviour and nothing destructive follows.
+    if (raw === READ_TIMED_OUT) return undefined;
+    return parsePersisted(raw);
   } catch {
     return undefined;
   }

package/src/session-analytics/lifecycle.ts

@@ -51,10 +51,18 @@ export const firstOpenStorageKey = (appId: string): string => `wireai:first_open
 /** Ceiling on the flag read — a hung adapter degrades to the in-memory latch, never a stuck gate. */
 const READ_TIMEOUT_MS = 1_500;
 
-const withTimeout = <T>(p: Promise<T>, ms: number): Promise<T | undefined> => {
+/**
+ * The verdict of a flag read that ran out of time. DISTINCT from `null`/`undefined`, because on this
+ * particular read those mean "this install has never fired its first open" — and acting on that
+ * belief is an irreversible emit. Same sentinel, same reasoning, as `session/persistedSession.ts`
+ * and `analytics/eventQueue.ts`.
+ */
+const READ_TIMED_OUT: unique symbol = Symbol("wireai:first-open-read-timeout");
+
+const withTimeout = <T>(p: Promise<T>, ms: number): Promise<T | typeof READ_TIMED_OUT> => {
   let timer: ReturnType<typeof setTimeout>;
-  const timeout = new Promise<undefined>((resolve) => {
-    timer = setTimeout(() => resolve(undefined), ms);
+  const timeout = new Promise<typeof READ_TIMED_OUT>((resolve) => {
+    timer = setTimeout(() => resolve(READ_TIMED_OUT), ms);
   });
   return Promise.race([p, timeout]).finally(() => clearTimeout(timer));
 };
@@ -185,6 +193,12 @@ export const reportFirstOpen = (opts: ReportFirstOpenOptions): void => {
   void (async () => {
     try {
       const seen = await withTimeout(storage.getItem(key), READ_TIMEOUT_MS);
+      // TIMED OUT: the flag may well say "already fired" — the read is still in flight, it just blew
+      // the ceiling. Emitting on that guess turns once-EVER into once-per-slow-launch, and the
+      // top-of-funnel count inflates on exactly the devices (cold start, slow storage) that are
+      // slowest. Declining costs at most one launch's first_open on a genuinely first install, and
+      // the next launch retries with a read that lands. See the sentinel above.
+      if (seen === READ_TIMED_OUT) return;
       // A prior launch already fired + wrote the flag → once-ever satisfied, no-op.
       if (seen) return;
       emitFirstOpen(opts);
@@ -195,8 +209,15 @@ export const reportFirstOpen = (opts: ReportFirstOpenOptions): void => {
         // Missing/broken storage write — swallow.
       }
     } catch {
-      // Unreadable flag → the in-memory latch still caps us at one fire this process.
-      emitFirstOpen(opts);
+      // UNREADABLE (a locked / full / permission-denied adapter): the same question with a worse
+      // answer, because it fails on every launch. This used to emit, which meant `app.first_open`
+      // fired on EVERY launch of that install for as long as the adapter stayed broken — the top of
+      // the funnel counting one device as an unbounded number of installs. The kit's standing rule
+      // for an unverifiable persistence answer (0.13.0 `autoJoinKey`, 0.14.0 lifecycle device keys)
+      // is to decline rather than to emit something that corrupts the metric. Same verdict here.
+      //
+      // A host that wants a first_open on a device with no working storage should pass no `storage`
+      // at all: that is the documented degraded mode and it still fires once per process.
     }
   })();
 };

package/src/session-analytics/reportSessionStart.ts

@@ -33,6 +33,7 @@
  */
 import { setCurrentSessionId } from "../analytics/currentSession";
 import {
+  buildEventsRequest,
   makeSessionId,
   warnOnSkippedEvents,
   type ClientEvent,
@@ -158,16 +159,19 @@ export const reportSessionStart = (opts: ReportSessionStartOptions): void => {
       return;
     }
 
-    // Fallback: this emitter's own direct POST when no sink is wired.
-    if (!target?.serverUrl) return;
-    const url = `${target.serverUrl.replace(/\/$/, "")}/v1/events`;
-    const headers: Record<string, string> = { "Content-Type": "application/json" };
-    if (target.apiKey) headers.Authorization = `Bearer ${target.apiKey}`;
-    void fetch(url, {
-      method: "POST",
-      headers,
-      body: JSON.stringify({ events: [event] }),
-    })
+    // Fallback: this emitter's own direct POST when no sink is wired — routed through the ONE
+    // canonical `/v1/events` builder (url + headers + body + the epoch-ms → ISO8601 `ts`
+    // conversion), exactly as `lifecycle.ts` already does with its own fallback.
+    //
+    // It used to hand-build the request here. That was harmless as long as this event carried no
+    // field needing wire conversion, but it made this the ONE send path of five that skipped the
+    // converter — on the event `min_sessions` is counted from, where the failure shape is a 200 with
+    // `{written: 0, skipped: N}` and no client-visible error at all (the 0.13.0 `ts` defect). The
+    // choke-point comment in `reportClientEvent.ts` claimed five paths and delivered four;
+    // `sendPathChokePoint.test.ts` now holds the claim to the code.
+    const req = buildEventsRequest(target, [event as unknown as ClientEvent]);
+    if (!req) return;
+    void fetch(req.url, req.init)
       .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.

package/src/session-analytics/useLifecycleEvents.ts

@@ -11,9 +11,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`). 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.
+ *     key is the one in play (no host `deviceKey`, `config.storage` present) the fire waits on one
+ *     storage read so both events carry the PERSISTED key, not a freshly minted one — and if that
+ *     read settles NON-DURABLE the key is refused outright rather than degraded to the per-launch
+ *     mint. See the `hydrateDeviceIdentity` 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.
  *
@@ -32,7 +33,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 { hydrateDeviceIdentity } from "../context/deviceId";
 import { resolveIdentity } from "../identity/identityRecord";
 import { collectDeviceContext } from "../device/deviceContext";
 import type { WireOnboardingStorage } from "../session/persistedSession";
@@ -50,8 +51,10 @@ export interface LifecycleConfig {
   appVersion?: string;
   /** Tenant/app id — namespaces the first-open flag AND the hook's internal queue storage key. */
   appId?: string;
-  /** Host storage (AsyncStorage subset). Enables the persisted once-ever first-open flag AND the
-   *  offline durability of the hook's internal queue. Omit it and both degrade to in-memory. */
+  /** Host storage (AsyncStorage subset). Enables the persisted once-ever first-open flag, the
+   *  offline durability of the hook's internal queue, AND the auto `device_key` fallback — the last
+   *  one only when the adapter actually persists (one that throws or rejects gets no fallback, the
+   *  same verdict as no storage at all). Omit it and all three degrade to in-memory. */
   storage?: WireOnboardingStorage;
 }
 
@@ -98,6 +101,10 @@ export const useLifecycleEvents = (
   const queueRef = useRef<EventQueue | undefined>(undefined);
 
   useEffect(() => {
+    // Set by the cleanup below: an in-flight storage read must not fire an app-open for a mount
+    // that is already gone. Declared first because every async fire path closes over it.
+    let cancelled = false;
+
     const resolveSink = (): ((event: ClientEvent) => void) | undefined => {
       const { config: cfg, options: opts } = latest.current;
       // Host-owned shared queue wins — one queue across the whole kit.
@@ -130,13 +137,17 @@ export const useLifecycleEvents = (
      * 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.
+     * ONLY WITH `storage` THAT ACTUALLY WORKED: the auto id is per-INSTALL only when it can be
+     * persisted. With no storage — or with an adapter that threw / rejected — it is per-LAUNCH,
+     * which makes every open look like a brand-new device and corrupts `min_sessions` in the other
+     * direction (while inflating distinct-device counts on top). So no storage → no fallback, and a
+     * non-durable read → no fallback either: `openAutoDeviceKey` below hands this function
+     * `undefined` in both cases, and it never reaches for the synchronous mint itself.
      */
     const resolveDeviceKey = (
       cfg: LifecycleConfig | undefined,
       opts: UseLifecycleEventsOptions,
+      autoDeviceKey: string | undefined,
     ): string | undefined => {
       // A HOST-supplied key is recorded on the process provenance registry, so a `<WireOnboarding>`
       // mount that was not given one can tell "this app owns no device id" from "this app owns one
@@ -148,8 +159,33 @@ export const useLifecycleEvents = (
         scope: cfg?.appId,
       })?.value;
       if (host) return host;
-      if (!cfg?.storage) return undefined;
-      return resolveAutoDeviceKey({ appId: cfg.appId, storage: cfg.storage });
+      return autoDeviceKey;
+    };
+
+    /**
+     * Resolve the auto `device_key` for ONE app-open and then fire it, so EVERY fire path (mount and
+     * foreground re-fire alike) goes through the same vetting.
+     *
+     * A host-supplied key or a config with no `storage` fires SYNCHRONOUSLY — there is nothing to
+     * read. Otherwise the fire waits on `hydrateDeviceIdentity`, the provenance-carrying read, and
+     * honours the 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 refusal
+     * 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.
+     */
+    const openAutoDeviceKey = (fire: (autoDeviceKey: string | undefined) => void): void => {
+      const { config: cfg, options: opts } = latest.current;
+      const hostKey =
+        typeof opts.deviceKey === "string" && opts.deviceKey.trim() ? opts.deviceKey : undefined;
+      if (hostKey || !cfg?.storage) {
+        fire(undefined);
+        return;
+      }
+      void hydrateDeviceIdentity({ appId: cfg.appId, storage: cfg.storage }).then((identity) => {
+        if (cancelled) return;
+        fire(identity?.durable ? identity.value : undefined);
+      });
     };
 
     // ONE per-open session id for the MOUNT open, shared by first_open AND session_started below.
@@ -164,7 +200,7 @@ export const useLifecycleEvents = (
     // session_start — the EXISTING emitter routed through the sink (offline-buffered, one guard).
     // Accepts the per-open id so the mount open reuses `mountOpenSessionId`; omit it and the emitter
     // mints a fresh id (a genuinely new open). Either way the once-guard dedupes within the open.
-    const fireSession = (sessionId?: string) => {
+    const fireSession = (sessionId: string | undefined, autoDeviceKey: string | undefined) => {
       const { config: cfg, options: opts } = latest.current;
       if (opts.enabled === false) return;
       if (!cfg?.serverUrl && !opts.sink) return;
@@ -176,7 +212,7 @@ export const useLifecycleEvents = (
         sink: resolveSink(),
         sessionId,
         userId: opts.userId,
-        deviceKey: resolveDeviceKey(cfg, opts),
+        deviceKey: resolveDeviceKey(cfg, opts, autoDeviceKey),
         sessionCount: opts.sessionCount,
         appVersion: cfg?.appVersion ?? device.appVersion,
         platform: Platform.OS,
@@ -189,8 +225,8 @@ export const useLifecycleEvents = (
     // `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);
+    const fireMountOpen = (autoDeviceKey: string | undefined) => {
+      fireSession(mountOpenSessionId, autoDeviceKey);
 
       const { config: cfg, options: opts } = latest.current;
       if (opts.enabled === false) return;
@@ -204,7 +240,7 @@ export const useLifecycleEvents = (
         storage: cfg?.storage,
         appId: cfg?.appId,
         userId: opts.userId,
-        deviceKey: resolveDeviceKey(cfg, opts),
+        deviceKey: resolveDeviceKey(cfg, opts, autoDeviceKey),
         sessionCount: opts.sessionCount,
         appVersion: cfg?.appVersion ?? device.appVersion,
         platform: Platform.OS,
@@ -223,21 +259,12 @@ export const useLifecycleEvents = (
     // 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();
-    }
+    // 0.14.0: awaiting the read was only half of it. The read can settle NON-DURABLE (a locked /
+    // full / permission-denied adapter — it throws or rejects and the id stays process-scoped), and
+    // the `.then` fired regardless, so a degraded store walked the per-launch key straight back onto
+    // the counted events: two launches over a throwing MMKV produced four distinct `wdev_*`. The
+    // outcome is now read through `openAutoDeviceKey`, which refuses a `durable: false` id.
+    openAutoDeviceKey(fireMountOpen);
 
     // Foreground after a real background = a new app-open.
     let backgroundedAt: number | null = null;
@@ -249,7 +276,11 @@ export const useLifecycleEvents = (
       if (state === "active") {
         const since = backgroundedAt;
         backgroundedAt = null;
-        if (since != null && Date.now() - since >= BACKGROUND_SESSION_MS) fireSession();
+        // A new open re-runs the same vetting: the auto key must still be a durable one, and a
+        // degraded read that released its latches gets a fresh attempt rather than a cached verdict.
+        if (since != null && Date.now() - since >= BACKGROUND_SESSION_MS) {
+          openAutoDeviceKey((autoDeviceKey) => fireSession(undefined, autoDeviceKey));
+        }
       }
     };
     const sub = AppState.addEventListener("change", onChange);
@@ -258,6 +289,13 @@ export const useLifecycleEvents = (
       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();
+      // Tear the hook's OWN queue down. This hook re-creates it on every remount against a fixed
+      // explicit storage key, so without a teardown the dead queue keeps a live backoff timer over
+      // the same slot the replacement now owns: it wakes up, drains, empties, and `removeItem`s the
+      // replacement's persisted `app.session_started`. A host-supplied `sink` is NOT touched — that
+      // queue belongs to the host and outlives this mount by design.
+      queueRef.current?.dispose();
+      queueRef.current = undefined;
     };
     // Mount-only effect: firing reads fresh values via `latest`, so no reactive deps.
     // eslint-disable-next-line react-hooks/exhaustive-deps

package/src/session-analytics/useSessionStart.ts

@@ -2,7 +2,10 @@
  * useSessionStart — the optional convenience hook that fires {@link reportSessionStart} for you.
  *
  * Two firing moments, mirroring the reference apps' session-counter semantics:
- *   • ON MOUNT — the app opened (cold start or the provider first rendered).
+ *   • ON MOUNT — the app opened (cold start or the provider first rendered). When the kit's AUTO
+ *     device key is the one in play (no host `deviceKey`, `config.storage` present) the fire waits
+ *     on one storage read, so the event carries the PERSISTED key rather than a fresh per-launch
+ *     mint, and it refuses the key outright if that read settles non-durable (0.14.0).
  *   • ON FOREGROUND after a real background — when AppState returns to `active` having been
  *     backgrounded for at least {@link BACKGROUND_SESSION_MS} (30 min), that's a NEW open, so a
  *     fresh session fires. A quick app-switch (under the threshold) does NOT count as a new open.
@@ -26,7 +29,7 @@ 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 { hydrateDeviceIdentity } from "../context/deviceId";
 import { collectDeviceContext } from "../device/deviceContext";
 import type { WireOnboardingStorage } from "../session/persistedSession";
 import { reportSessionStart } from "./reportSessionStart";
@@ -44,8 +47,9 @@ export interface SessionStartConfig {
   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). */
+  /** Host storage (AsyncStorage subset). Present AND actually persisting → `app.session_started`
+   *  falls back to the kit's persisted auto `device_key` when the host passes none. Absent, or an
+   *  adapter that throws / rejects → no fallback (a per-launch key is worse than none, see below). */
   storage?: WireOnboardingStorage;
 }
 
@@ -78,8 +82,13 @@ export const useSessionStart = (
   latest.current = { config, options };
 
   useEffect(() => {
+    // Set by the cleanup below: an in-flight storage read must not fire an app-open for a mount that
+    // is already gone. Declared first because the async fire path closes over it.
+    let cancelled = false;
+
     /**
-     * The `device_key` this open rides under. A host-supplied id always wins.
+     * The `device_key` this open rides under. A host-supplied id always wins; the auto id arrives
+     * already vetted from `openAutoDeviceKey` below (a non-durable one never gets here).
      *
      * 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
@@ -88,21 +97,50 @@ export const useSessionStart = (
      * 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.
+     * ONLY WITH `storage` THAT ACTUALLY WORKED, for the same reason as the sibling hook: without
+     * persistence — or with an adapter that threw / rejected — 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. Both cases arrive here as `undefined`; this function never mints.
      */
     const resolveDeviceKey = (
-      cfg: SessionStartConfig | undefined,
       opts: UseSessionStartOptions,
+      autoDeviceKey: string | undefined,
     ): 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 });
+      return autoDeviceKey;
+    };
+
+    /**
+     * Resolve the auto `device_key` for ONE app-open, then fire — the fix this hook never got.
+     *
+     * IT USED TO FIRE SYNCHRONOUSLY. `resolveAutoDeviceKey` is synchronous by contract: it returns a
+     * freshly minted id and adopts the persisted one a storage read later. So on a perfectly HEALTHY
+     * store this hook stamped a brand-new `wdev_*` on `app.session_started` every single launch,
+     * while every other kit surface adopted the persisted id milliseconds afterwards — the exact
+     * pre-fix behaviour the sibling hook's mount comment describes. `min_sessions` counts distinct
+     * opens grouped by that key, so it was structurally incapable of exceeding 1.
+     *
+     * The auto path now awaits `hydrateDeviceIdentity` (the provenance-carrying read) and honours the
+     * 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.
+     */
+    const openAutoDeviceKey = (fireOpen: (autoDeviceKey: string | undefined) => void): void => {
+      const { config: cfg, options: opts } = latest.current;
+      const hostKey =
+        typeof opts.deviceKey === "string" && opts.deviceKey.trim() ? opts.deviceKey : undefined;
+      if (hostKey || !cfg?.storage) {
+        fireOpen(undefined);
+        return;
+      }
+      void hydrateDeviceIdentity({ appId: cfg.appId, storage: cfg.storage }).then((identity) => {
+        if (cancelled) return;
+        fireOpen(identity?.durable ? identity.value : undefined);
+      });
     };
 
-    const fire = () => {
+    const fire = (autoDeviceKey: string | undefined) => {
       const { config: cfg, options: opts } = latest.current;
       if (!cfg?.serverUrl) return;
       if (opts.enabled === false) return;
@@ -114,7 +152,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: resolveDeviceKey(cfg, opts),
+        deviceKey: resolveDeviceKey(opts, autoDeviceKey),
         sessionCount: opts.sessionCount,
         appVersion: cfg.appVersion ?? device.appVersion,
         platform: Platform.OS,
@@ -124,7 +162,7 @@ export const useSessionStart = (
     };
 
     // 1) Mount = an app-open.
-    fire();
+    openAutoDeviceKey(fire);
 
     // 2) Foreground after a real background = a new app-open.
     let backgroundedAt: number | null = null;
@@ -137,11 +175,15 @@ export const useSessionStart = (
       if (state === "active") {
         const since = backgroundedAt;
         backgroundedAt = null;
-        if (since != null && Date.now() - since >= BACKGROUND_SESSION_MS) fire();
+        // A new open re-runs the same vetting: the auto key must still be a durable one, and a
+        // degraded read that released its latches gets a fresh attempt rather than a cached verdict.
+        if (since != null && Date.now() - since >= BACKGROUND_SESSION_MS) openAutoDeviceKey(fire);
       }
     };
     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/types.ts

@@ -54,10 +54,11 @@ export type OnboardingResult = {
   /** The raw message thread, for custom downstream parsing. */
   raw: Message[];
   /**
-   * The backend's onboarding plan, when it sent one. Present ONLY on the AI path: a tenant running
-   * the static flow, or any run the server finished without a plan, leaves this `undefined` AND
-   * leaves the key off the result object entirely — so a host written before plans existed sees
-   * byte-identically what it always saw.
+   * The backend's onboarding plan, present when the backend sent one — the kit never infers it
+   * from which flow ran. Whether a plan arrives is the backend's configuration, not the kit's. Any
+   * run the server finished without a plan leaves this `undefined` AND leaves the key off the
+   * result object entirely — so a host written before plans existed sees byte-identically what it
+   * always saw.
    *
    * ⚠️ The kit does NOT interpret this and does NOT validate it. It checks one structural fact (a
    * plan is an object) and hands the payload straight through, unread, unlogged, and never attached
@@ -240,10 +241,19 @@ export type WireOnboardingProps = {
    *
    * ```tsx
    * <WireOnboarding userContext={activationJoinContext(deviceKey)} ... />
-   * // no device id of your own? read the kit's:
-   * <WireOnboarding userContext={activationJoinContext(resolveAutoDeviceKey({ appId, storage }))} ... />
+   * // no device id of your own? pass `storage` and leave this prop alone — the kit injects its
+   * // own key, and only after it has confirmed the key actually persists (see `autoJoinKey`).
+   * <WireOnboarding config={{ ...config, storage }} ... />
    * ```
    *
+   * ⛔ Do NOT hand-build the auto key with `activationJoinContext(resolveAutoDeviceKey({...}))`.
+   * `resolveAutoDeviceKey` is SYNCHRONOUS by contract: it hands back a freshly minted id and adopts
+   * the persisted one a storage read later, and it cannot tell you whether the id survives the
+   * launch at all. A key that differs on every launch corrupts `min_sessions` rather than merely
+   * leaving the join empty. The auto-join path does the awaited, durability-checked read for you;
+   * a host that genuinely wants the value in hand should await `hydrateDeviceIdentity` and refuse a
+   * `durable: false` record, which is exactly what the kit does internally.
+   *
    * 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

package/src/utils/readPlan.ts

@@ -1,10 +1,10 @@
 /**
  * readPlan — lift the backend's onboarding plan off the message thread.
  *
- * WHY IT EXISTS. On the AI path the server appends a SECOND A2A DataPart to the turn it finishes
- * on: `{ kind: "onboarding_plan", plan: {...} }`, alongside the component envelope the renderer
- * already consumes. The kit carries that payload out through `OnboardingResult.plan` and stops
- * there. It does NOT interpret it, does NOT validate its fields, does NOT log it and does NOT
+ * WHY IT EXISTS. When it sends a plan, the server appends a SECOND A2A DataPart to the turn it
+ * finishes on: `{ kind: "onboarding_plan", plan: {...} }`, alongside the component envelope the
+ * renderer already consumes. The kit carries that payload out through `OnboardingResult.plan` and
+ * stops there. It does NOT interpret it, does NOT validate its fields, does NOT log it and does NOT
  * attach it to any event — the plan is user-derived content, and deciding what it MEANS is the
  * host's job (the kit/host boundary in `ai_rules/context_map.md`: the kit ends at the completion
  * CTA).
@@ -19,7 +19,10 @@
  * so a throw here would cost the user the completion of an onboarding they already finished. Every
  * step below is a runtime-guarded read.
  *
- * The static (non-AI) flow carries no plan at all. That path is unchanged and fully supported.
+ * WHICH RUNS CARRY A PLAN IS THE BACKEND'S CONFIGURATION, NOT THE KIT'S. This reader matches the
+ * `kind` MARKER below and never the flow that produced the turn, so it needs no knowledge of how
+ * the tenant is configured. A run that carries no plan yields `undefined`: unchanged, and fully
+ * supported.
  */
 import type { Message } from "wireai-rn";