@wireai/activation 0.13.6 → 0.14.1

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";