@wireai/activation 0.11.0 → 0.12.1

package/src/WireOnboarding.tsx

@@ -22,6 +22,8 @@ import { OnboardingFlow, DEFAULT_COPY } from "./OnboardingFlow";
 import { onboardingComponents } from "./cards";
 import { makeSessionId, reportClientEvent, type ClientEventTarget } from "./analytics/reportClientEvent";
 import { collectDeviceContext, type DeviceContext } from "./device/deviceContext";
+import { hydrateAutoDeviceKey } from "./context/deviceId";
+import { activationJoinContext } from "./context/userContext";
 import { sanitizeUserId } from "./identity/userIdentity";
 import {
   clearPersistedSession,
@@ -33,6 +35,21 @@ import {
 } from "./session/persistedSession";
 import type { OnboardingResult, WireOnboardingProps } from "./types";
 
+/** RN sets this global; absent under node/SSR. Read defensively via {@link warnInDev}. */
+declare const __DEV__: boolean | undefined;
+
+/** Emit a one-line developer warning, but ONLY in a dev build (RN `__DEV__`). No-op in prod/tests.
+ *  Same idiom as `analytics/analyticsFacade.warnInDev`. */
+const warnInDev = (message: string): void => {
+  if (typeof __DEV__ !== "undefined" && __DEV__ && typeof console !== "undefined" && console.warn) {
+    console.warn(message);
+  }
+};
+
+/** Ceiling on the auto-join-key storage read — a hung adapter degrades to no key, never a stuck
+ *  loader. Matches the persisted-session read's own ceiling. */
+const AUTO_JOIN_HYDRATION_TIMEOUT_MS = 1_500;
+
 export const WireOnboarding: React.FC<WireOnboardingProps> = ({
   config,
   theme,
@@ -56,6 +73,7 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
   retainSessionOnComplete,
   userContext,
   userId,
+  autoJoinKey = true,
 }) => {
   // The host's own opaque user id (trimmed + capped, NO PII) so onboarding sessions can be
   // reconciled to real users later. `sanitizeUserId` is a pure string transform → the memoized
@@ -87,12 +105,125 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
     [userContextKey],
   );
 
+  // THE JOIN KEY, or the absence of it. `user_context.device_key` is the ONLY thing that stitches an
+  // onboarding session to everything the app reports later, and the prop that carries it is optional
+  // and named `userContext` — so forgetting it is the default, and the failure is a silent zero in the
+  // `activated` funnel rather than an error. Two real consumers shipped without it.
+  const missingJoinKey =
+    typeof userContextStable?.device_key !== "string" || !userContextStable.device_key.trim();
+
+  // AUTO-JOIN (0.12.2). When the host supplied no join key, the kit supplies its OWN — the same
+  // per-install `device_key` the analytics surfaces auto-mint and persist — so the default wiring
+  // produces a joined funnel instead of a silent zero. Three conditions, all necessary:
+  //
+  //   • `missingJoinKey` — a host-supplied key ALWAYS wins, verbatim, and is never touched.
+  //   • `autoJoinKey !== false` — the documented opt-out for a host that genuinely wants an
+  //     unlinked onboarding session; opting out restores the pre-0.12.2 behavior exactly.
+  //   • `storage` — WITHOUT persistence `resolveAutoDeviceKey` is process-scoped, so every launch
+  //     would carry a DIFFERENT key. That is worse than no key: the server counts `min_sessions`
+  //     by distinct opens grouped on `device_key`, so a per-launch key corrupts the counter rather
+  //     than leaving it empty. Same reason `useLifecycleEvents` gates its own fallback on storage.
+  //
+  // It resolves through `hydrateAutoDeviceKey`, never the sync `resolveAutoDeviceKey`: the sync
+  // contract returns the freshly minted id and adopts the persisted one milliseconds later, which
+  // is exactly the 0.12.1 H1 defect — the key stamped here must be the one the analytics side
+  // stamps, not a fresh mint per launch. The value is therefore awaited BEHIND THE LOADER GATE
+  // below (the same gate the persisted-session read already holds, and it is only ever open when
+  // `storage` is present anyway), because `userContext` feeds the `llm` memo: swapping it after the
+  // provider mounted would recreate the A2A adapter and drop the server-learned `contextId`.
+  const autoJoinPossible = Boolean(storage) && autoJoinKey !== false;
+  const wantsAutoJoin = missingJoinKey && autoJoinPossible;
+  // `undefined` = the hydration is still in flight (the gate below holds); a string = the key to
+  // inject; `null` = gave up (see the timeout note in the effect) so the gate opens with no key.
+  const [autoJoinValue, setAutoJoinValue] = useState<string | null | undefined>(undefined);
+
+  useEffect(() => {
+    if (!wantsAutoJoin || autoJoinValue !== undefined || !storage) return;
+    let cancelled = false;
+    // Ceiling on the read, the same discipline as `loadPersistedSession`: a hung storage adapter
+    // must degrade to "no auto key", never to a stuck loader over the host's onboarding. Giving up
+    // is deliberately NOT "fall back to the synchronous mint" — that key is per-launch, which is
+    // the corruption this feature is gated on `storage` to avoid.
+    const timer = setTimeout(() => {
+      if (!cancelled) setAutoJoinValue(null);
+    }, AUTO_JOIN_HYDRATION_TIMEOUT_MS);
+    void hydrateAutoDeviceKey({ appId: config.appId, storage }).then((key) => {
+      if (cancelled) return;
+      clearTimeout(timer);
+      setAutoJoinValue(key || null);
+    });
+    return () => {
+      cancelled = true;
+      clearTimeout(timer);
+    };
+  }, [wantsAutoJoin, autoJoinValue, config.appId, storage]);
+
+  const injectedJoinKey = wantsAutoJoin && typeof autoJoinValue === "string" ? autoJoinValue : undefined;
+  const autoJoinPending = wantsAutoJoin && autoJoinValue === undefined;
+
+  // What actually goes on the wire: the host's context, with the auto join key merged in ONLY when
+  // the host left the slot empty. Every other key the host passed survives untouched, and a host
+  // that passed a valid `device_key` gets a byte-identical payload to 0.12.1.
+  const effectiveUserContext = useMemo<Record<string, string | number | boolean> | undefined>(
+    () =>
+      injectedJoinKey
+        ? { ...userContextStable, ...activationJoinContext(injectedJoinKey) }
+        : userContextStable,
+    [userContextStable, injectedJoinKey],
+  );
+
+  // Dev-only warning (never a throw, never a wire change), once per mount, naming the exact fix.
+  // Reconciled with auto-join: it fires only when the gap is still OPEN — injection was impossible
+  // (no `storage`), the host opted out, or the read gave up. When auto-join covered the gap the
+  // session IS joined, so there is nothing to warn about; while it is still in flight, nothing is
+  // decided yet, so it stays quiet.
+  const warnMissingJoinKey = missingJoinKey && !injectedJoinKey && !autoJoinPending;
+  const autoJoinReason =
+    autoJoinKey === false
+      ? "you passed autoJoinKey={false}."
+      : !storage
+        ? "it got no `storage` prop, and without persistence its key would be different on every " +
+          "launch, which corrupts min_sessions instead of merely leaving the join empty."
+        : "your `storage` adapter did not answer in time.";
+  useEffect(() => {
+    if (!warnMissingJoinKey) return;
+    warnInDev(
+      "[wireai] <WireOnboarding> got no user_context.device_key, so this onboarding session can " +
+        "never be joined to the app's later events and the `activated` funnel will read zero. Pass " +
+        "userContext={activationJoinContext(deviceKey)} — and if your app owns no device id, " +
+        "userContext={activationJoinContext(resolveAutoDeviceKey({ appId, storage }))} returns the " +
+        "SAME id the analytics side stamps. Never hand-write userContext={{ deviceKey }}. " +
+        "The kit did NOT auto-inject its own key here because " +
+        autoJoinReason,
+    );
+  }, [warnMissingJoinKey, autoJoinReason]);
+
+  // The one case auto-join would otherwise SILENCE and must not: the host hand-wrote
+  // `userContext={{ deviceKey }}`. That bucket is not the wire key, so the kit injects its own —
+  // but the host demonstrably owns an id, and their app-side events carry THAT one, so the two
+  // families still land in disjoint id spaces. Injection makes the onboarding side self-consistent;
+  // only the host can make it join.
+  const misspelledJoinKey =
+    missingJoinKey &&
+    typeof userContextStable?.deviceKey === "string" &&
+    Boolean(userContextStable.deviceKey.trim());
+  useEffect(() => {
+    if (!misspelledJoinKey || !injectedJoinKey) return;
+    warnInDev(
+      "[wireai] <WireOnboarding> got userContext={{ deviceKey }}, which is NOT the wire key — the " +
+        "server's device lookup reads `device_key`. The kit auto-injected its own device_key so this " +
+        "session is at least self-consistent, but your app's own events carry YOUR id, so the two " +
+        "still will not join and the `activated` funnel stays zero. Pass " +
+        "userContext={activationJoinContext(deviceKey)} instead.",
+    );
+  }, [misspelledJoinKey, injectedJoinKey]);
+
   // The context payload shared by the A2A metadata + client-event paths. `userContext` +
   // `userId` are host-injected and forwarded verbatim (the server sanitizes them). Omitted keys
   // stay absent, so `dropped`/`client_fallback` events carry the user id when it's known.
   const clientContext = useMemo(
-    () => ({ device, userContext: userContextStable, userId: boundUserId }),
-    [device, userContextStable, boundUserId],
+    () => ({ device, userContext: effectiveUserContext, userId: boundUserId }),
+    [device, effectiveUserContext, boundUserId],
   );
   // One stable session id per onboarding SESSION (not per mount). It's used as the
   // client event `session_id` AND forwarded to the backend as `metadata.sessionId` so
@@ -180,7 +311,7 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
         // Device snapshot + host-injected user context ride the session-start metadata so the
         // backend can segment the funnel. Old servers ignore these unknown keys (backward compat).
         device,
-        ...(userContextStable ? { userContext: userContextStable } : {}),
+        ...(effectiveUserContext ? { userContext: effectiveUserContext } : {}),
         // The session-start user id (from the ref) rides the session-start metadata so the
         // server binds the session to a real user at creation. Reading the ref — not
         // `boundUserId` — keeps this memo off the userId dependency, so a mid-session change
@@ -189,7 +320,7 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
       },
       timeoutMs: 60_000,
     };
-  }, [config.serverUrl, config.appId, config.apiKey, metadataStable, sessionId, componentsStable, device, userContextStable]);
+  }, [config.serverUrl, config.appId, config.apiKey, metadataStable, sessionId, componentsStable, device, effectiveUserContext]);
 
   // Where client-reported events are POSTed (`/v1/events`). Same tenant creds as the flow.
   const reportTarget = useMemo<ClientEventTarget>(
@@ -228,7 +359,11 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
   // the provider with a throwaway id and swapping later would re-init it mid-flight.
   // The read is timeout-capped in loadPersistedSession, so this gate is one storage
   // read (~a frame), never an indefinite hold.
-  if (!session) {
+  //
+  // The auto join key rides the SAME gate for the same reason (`effectiveUserContext` is also an
+  // `llm` dependency). It costs no extra hold in practice: auto-join requires `storage`, and with
+  // `storage` this gate is already closed on the persisted-session read.
+  if (!session || autoJoinPending) {
     return (
       <OnboardingThemeProvider theme={theme}>
         <LoadingScreen

package/src/activation/useWireActivation.ts

@@ -59,7 +59,18 @@ export const useWireActivation = (config: WireActivationConfig): UseWireActivati
   const ref = useRef<WireActivation | undefined>(undefined);
   const prevKeys = useRef<string>("");
 
-  const currentKeys = `${config.serverUrl}|${config.apiKey}|${config.appId}|${config.deviceKey}`;
+  // The identity of the built instance. `userContext.deviceKey` MUST be in here: `createWireActivation`
+  // honors it as an explicit device key (`config.deviceKey ?? config.userContext?.deviceKey`), so a host
+  // that hydrates its device id asynchronously and passes it only inside `userContext` would otherwise
+  // keep an instance frozen on the first render's `undefined` — the stale-static-ref failure this repo
+  // has already been bitten by (see .memory/70-knowledge.md, "Stale Option Closures in Static Refs").
+  const currentKeys = [
+    config.serverUrl,
+    config.apiKey,
+    config.appId,
+    config.deviceKey,
+    config.userContext?.deviceKey,
+  ].join("|");
   if (!ref.current || prevKeys.current !== currentKeys) {
     prevKeys.current = currentKeys;
     ref.current = createWireActivation(config);

package/src/activation/wireActivation.ts

@@ -12,7 +12,7 @@
  *   await wire.track("journal_done");                            // awaitable POST + auto-revalidate
  *
  * `track` POSTs `event_type='app_event'`, `question_key=<name>` (the EXACT string a review /
- * questionnaire firing TRIGGER matches on) under the CURRENT `getCurrentSessionId()` — the same id
+ * questionnaire firing TRIGGER matches on) under the CURRENT `ensureCurrentSessionId()` — the same id
  * the gates pass to their `/decision` fetch, so the server's session-scoped trigger rule agrees —
  * with `user_context.device_key` for the min-sessions / arm-assignment lookups. On a successful POST
  * it bumps decision revalidation so a subscribed gate re-fetches and can fire.
@@ -22,14 +22,15 @@
  * and `getCurrentSessionId` — it introduces NO second session concept and duplicates no POST path.
  * React-free (the optional React glue is the thin `useWireActivation` hook).
  */
-import { getCurrentSessionId } from "../analytics/currentSession";
+import { ensureCurrentSessionId, getCurrentSessionId } from "../analytics/currentSession";
 import {
   reportClientEventAwait,
   type ClientEvent,
   type ClientEventTarget,
 } from "../analytics/reportClientEvent";
-import { deviceIdStorageKey, mintDeviceId } from "../context/deviceId";
+import { resolveAutoDeviceKey, type ResolveAutoDeviceKeyOptions } from "../context/deviceId";
 import { resolveUserContext, type WireUserContext } from "../context/userContext";
+import { detectAppVersion } from "../device/appVersion";
 import type { WireOnboardingStorage } from "../session/persistedSession";
 import {
   bumpActivationRevalidation,
@@ -78,8 +79,14 @@ export type WireActivation = {
   /**
    * Awaitable action report: POST `event_type='app_event'`, `question_key=<name>`, optional `meta`,
    * under the CURRENT session id + `user_context.device_key`. Resolves `true` once the server has
-   * stored it (2xx) and THEN bumps decision revalidation; resolves `false` (no bump) when there is no
-   * current session, a blank name, or the POST fails. Never throws.
+   * stored it (2xx) and THEN bumps decision revalidation; resolves `false` (no bump) for a blank
+   * name or a failed POST. Never throws.
+   *
+   * It no longer refuses when no app-open has been registered: the session id is resolved through
+   * `ensureCurrentSessionId()`, which mints and registers one in that case (the server requires a
+   * non-empty `session_id` and silently drops an event without one, so bailing lost the action
+   * entirely). A host that fires `reportSessionStart` / `useLifecycleEvents` first is unaffected —
+   * the real per-open id is already registered and gets used exactly as before.
    */
   track(name: string, meta?: Record<string, unknown>): Promise<boolean>;
   /** The CURRENT per-open session id (the kit's canonical `getCurrentSessionId()`), or `undefined`. */
@@ -98,28 +105,35 @@ export const createWireActivation = (config: WireActivationConfig): WireActivati
   const target: ClientEventTarget = { serverUrl: config.serverUrl, apiKey: config.apiKey };
 
   // Device key: an explicit id (top-level or in userContext) wins and is never overwritten; otherwise
-  // auto-mint ONE and persist via storage (reused every open) so `device_key` is always present.
+  // read the ONE process-wide auto id (`resolveAutoDeviceKey`) so this instance and a sibling
+  // `createAnalytics` instance carry the SAME `device_key` for the same install. Minting locally here
+  // gave one install two auto ids — see the registry note in context/deviceId.ts.
   const explicitDeviceKey = clean(config.deviceKey) ?? clean(config.userContext?.deviceKey);
-  let autoDeviceKey = explicitDeviceKey ?? mintDeviceId();
-  if (config.storage && !explicitDeviceKey) {
-    const storage = config.storage;
-    const key = deviceIdStorageKey(config.appId);
-    void storage
-      .getItem(key)
-      .then((saved) => {
-        const persisted = clean(saved ?? undefined);
-        if (persisted) autoDeviceKey = persisted;
-        else void storage.setItem(key, autoDeviceKey).catch(() => {});
-      })
-      .catch(() => {});
-  }
+  const autoDeviceKeyOptions: ResolveAutoDeviceKeyOptions = {
+    appId: config.appId,
+    // An explicit key opts out of minting AND persisting (unchanged contract).
+    storage: explicitDeviceKey ? undefined : config.storage,
+  };
+  // Start hydration AT CONSTRUCTION (not at the first `track`) so the persisted id is adopted as early
+  // as it used to be. The return value is deliberately discarded — every event re-resolves.
+  if (!explicitDeviceKey) resolveAutoDeviceKey(autoDeviceKeyOptions);
+
+  // The auto-detected host app version, read ONCE (cheap, sync, never throws) — same as the facade.
+  // Without it this path had NO `app_version` fallback at all, so every `wire.track` event from a host
+  // that passed no `config.appVersion` (which `wireConfigFromEnv` could not even carry) shipped
+  // without one, while the facade and lifecycle families both had theirs.
+  const detectedAppVersion = detectAppVersion();
 
   // Stamp the resolved rich context onto the event: `user_context` bucket (device_key always, plus any
   // app_version / opt-in user_email / namespaced extra) and the top-level opaque `user_id`.
   const applyContext = (event: ClientEvent): void => {
     const resolved = resolveUserContext(
-      { ...(config.userContext ?? {}), deviceKey: explicitDeviceKey ?? autoDeviceKey },
-      { autoAppVersion: config.appVersion },
+      // `??` is lazy on purpose: an explicit key must never even touch the auto registry.
+      {
+        ...(config.userContext ?? {}),
+        deviceKey: explicitDeviceKey ?? resolveAutoDeviceKey(autoDeviceKeyOptions),
+      },
+      { autoAppVersion: config.appVersion ?? detectedAppVersion },
     );
     if (resolved.userContext) {
       event.user_context = { ...resolved.userContext, ...(event.user_context ?? {}) };
@@ -128,10 +142,15 @@ export const createWireActivation = (config: WireActivationConfig): WireActivati
   };
 
   const track = async (name: string, meta?: Record<string, unknown>): Promise<boolean> => {
-    const sessionId = getCurrentSessionId();
-    // No current session (no app-open registered yet) or a blank name → nothing to correlate; bail
-    // WITHOUT bumping (a bump with no posted event would only make the gate re-fetch for nothing).
-    if (!clean(name) || !sessionId) return false;
+    // A blank name is the only thing left to refuse on: there is no `question_key` to match a
+    // firing trigger against, so bail WITHOUT bumping (a bump with no posted event would only make
+    // the gate re-fetch for nothing).
+    if (!clean(name)) return false;
+    // No app-open registered is NOT a reason to drop the action. `ensureCurrentSessionId` returns
+    // the registered per-open id when there is one (the unchanged path) and otherwise mints +
+    // registers one, so the POST always carries the non-empty `session_id` the server requires
+    // instead of being accepted with a 200 and discarded.
+    const sessionId = ensureCurrentSessionId();
     const event: ClientEvent = {
       event_type: "app_event",
       session_id: sessionId,

package/src/analytics/analyticsFacade.ts

@@ -27,16 +27,17 @@
  * FIRE-AND-FORGET: no method throws into the UI or blocks — the queue already guarantees that.
  */
 import { buildContextEnvelope, type ContextEnvelope } from "./contextEnvelope";
-import { getCurrentSessionId } from "./currentSession";
+import { ensureCurrentSessionId } from "./currentSession";
 import { createEventQueue, type EventQueue, type EventQueueOptions } from "./eventQueue";
-import { makeSessionId, type ClientEvent } from "./reportClientEvent";
+import type { ClientEvent } from "./reportClientEvent";
 import {
   analyticsUserIdStorageKey,
   clearPiiFromContext,
   resolveUserContext,
   type WireUserContext,
 } from "../context/userContext";
-import { mintDeviceId, deviceIdStorageKey } from "../context/deviceId";
+import { resolveAutoDeviceKey, type ResolveAutoDeviceKeyOptions } from "../context/deviceId";
+import { detectAppVersion } from "../device/appVersion";
 import { looksLikeEmail, sanitizeUserId } from "../identity/userIdentity";
 
 /** RN sets this global; absent under node/SSR. Read defensively via {@link warnInDev}. */
@@ -63,8 +64,15 @@ export type CreateAnalyticsConfig = {
   /** Tenant API key; sent as `Authorization: Bearer`. */
   apiKey: string;
   /**
-   * Correlation id shared by every event from this instance (and the `identify` event). Defaults
-   * to a fresh `makeSessionId()` at creation so all events agree on one id per analytics instance.
+   * ⚠️ OPT-OUT KNOB, not a default. Supplying a `sessionId` FREEZES the correlation id: every event
+   * this instance ever sends (including `identify`) is pinned to that one id, and the instance stops
+   * following the LIVE per-open session the server registered via `app.session_started`. Lifecycle
+   * analytics then collapse onto a single device-scoped session — one "first open", forever.
+   *
+   * OMIT IT — that is the correct default. Without it the kit reuses the live per-open session, and
+   * when no open has been registered yet it mints one AND registers it, so every later surface joins
+   * the same session instead of each inventing its own. Pass one ONLY if your host runs its own
+   * session lifecycle and owns the id the server should correlate on.
    */
   sessionId?: string;
   /** Tenant/app id used to namespace the queue's default storage key (`wireai:evtq:<appId>`). */
@@ -151,16 +159,35 @@ export const createAnalytics = (
   config: CreateAnalyticsConfig,
   options: AnalyticsOptions = {},
 ): Analytics => {
-  // A STABLE per-instance fallback id, used only when no explicit `config.sessionId` was given AND
-  // no per-open session has been registered yet (see `resolveSessionId`).
-  const instanceSessionId = config.sessionId ?? makeSessionId();
-
   // The session id every event correlates to. Precedence: an explicit `config.sessionId` freezes the
   // id (opt-out of the reuse); otherwise reuse the LIVE per-open session the server saw (via
   // `app.session_started`) so `identify`/app-events don't mint a fresh id the server back-fills into a
-  // phantom session; finally fall back to the stable per-instance id when no open is registered yet.
-  const resolveSessionId = (): string =>
-    config.sessionId ?? getCurrentSessionId() ?? instanceSessionId;
+  // phantom session.
+  //
+  // `ensureCurrentSessionId` (not the bare `getCurrentSessionId`) is what closes the facade-first
+  // ordering hole: a `track` that runs BEFORE the root lifecycle effect used to fall back to a
+  // per-instance id this facade never REGISTERED, so the server saw a session it had no
+  // `session_started` for and back-filled a phantom one. The two paths that already mint on the wire
+  // (`wire.track`, `reportAppEvent`) both register; this one only read. Registering makes the
+  // fallback id the id every LATER surface joins on, and when an open IS registered this is exactly
+  // `getCurrentSessionId()` — so nothing changes for a host that mounts lifecycle first.
+  const resolveSessionId = (): string => config.sessionId ?? ensureCurrentSessionId();
+
+  // A frozen id is almost always a mistake (it silently flattens every open into ONE session), so
+  // name it once at construction — same dev-only channel as the email-shape guard below.
+  if (config.sessionId) {
+    warnInDev(
+      "[wireai] createAnalytics({ sessionId }) PINS every event from this instance to that one " +
+        "frozen id and opts out of the live per-open session (app.session_started) — lifecycle " +
+        "analytics collapse onto a single device-scoped id. Remove it unless your host runs its " +
+        "own session lifecycle.",
+    );
+  }
+
+  // The auto-detected host app version, read ONCE here (cheap, sync, never throws). It backs the
+  // `user_context.app_version` fallback below: without it a host that passes no `config.appVersion`
+  // got the detected version on `device.appVersion` only, leaving the user_context field absent.
+  const detectedAppVersion = detectAppVersion();
 
   // The mutable rich user-context: seeded at init, updated via `setUserContext`. Resolved fresh on
   // every event so a post-mount update (login) takes effect immediately. Declared before the envelope
@@ -177,21 +204,18 @@ export const createAnalytics = (
     typeof config.userContext?.deviceKey === "string" && config.userContext.deviceKey.trim()
       ? config.userContext.deviceKey.trim()
       : undefined;
-  // Minted synchronously so `device_key` is never missing, even before the async storage read resolves.
-  let autoDeviceKey = mintDeviceId();
-  if (config.storage && !hostDeviceKeyAtInit) {
-    const storage = config.storage;
-    const deviceKey = deviceIdStorageKey(config.appId);
-    void storage
-      .getItem(deviceKey)
-      .then((saved) => {
-        const persisted = typeof saved === "string" && saved.trim() ? saved.trim() : undefined;
-        // Reuse the persisted per-install id across opens; on first run persist the freshly minted one.
-        if (persisted) autoDeviceKey = persisted;
-        else void storage.setItem(deviceKey, autoDeviceKey).catch(() => {});
-      })
-      .catch(() => {});
-  }
+  // The auto id comes from the ONE process-wide registry (`resolveAutoDeviceKey`), NOT a mint local to
+  // this instance. A host that also builds a `createWireActivation` instance used to get a SECOND,
+  // different auto id for the same install, splitting `device_key` across two id spaces — see the
+  // registry note in context/deviceId.ts. Resolved lazily per event so hydration is picked up.
+  const autoDeviceKeyOptions: ResolveAutoDeviceKeyOptions = {
+    appId: config.appId,
+    // A host-supplied deviceKey opts out of minting AND persisting (unchanged contract).
+    storage: hostDeviceKeyAtInit ? undefined : config.storage,
+  };
+  // Start hydration AT CONSTRUCTION (not at the first event) so the persisted id is adopted as early
+  // as it used to be. The return value is deliberately discarded — every event re-resolves.
+  if (!hostDeviceKeyAtInit) resolveAutoDeviceKey(autoDeviceKeyOptions);
 
   // A provider (not a fixed value) so `networkType`, the current session id, AND the effective app
   // version are evaluated fresh on every enqueue. An explicit `WireUserContext.appVersion` (a host that
@@ -241,8 +265,9 @@ export const createAnalytics = (
         ? userContext.deviceKey
         : undefined;
     const resolved = resolveUserContext(
-      { ...userContext, deviceKey: hostDeviceKey ?? autoDeviceKey },
-      { autoAppVersion: config.appVersion },
+      // `??` is lazy on purpose: a host-supplied key must never even touch the auto registry.
+      { ...userContext, deviceKey: hostDeviceKey ?? resolveAutoDeviceKey(autoDeviceKeyOptions) },
+      { autoAppVersion: config.appVersion ?? detectedAppVersion },
     );
     if (resolved.userContext) {
       event.user_context = { ...resolved.userContext, ...(event.user_context ?? {}) };

package/src/analytics/currentSession.ts

@@ -32,7 +32,22 @@
  * PROCESS-LOCAL, NOT PERSISTED: the slot lives on the runtime global, so it tracks the CURRENT
  * process's open and a fresh open overwrites it. There is no cross-launch state.
  * `resetCurrentSessionId` clears the slot so a unit test starts from a clean registry.
+ *
+ * ── WHY `ensureCurrentSessionId` EXISTS (the silent-drop contract) ─────────────────────────────
+ * The server's event model declares `session_id: str = Field(min_length=1)` — REQUIRED, non-empty.
+ * `POST /v1/events` validates each event inside a try/except that increments a `skipped` counter and
+ * still returns HTTP 200. So an event posted without a `session_id` is accepted by the wire and
+ * DISCARDED by the server, and a fire-and-forget client can never learn it happened. That is the
+ * worst of both: no error, no data. Screen tracking in a host that never mounted the lifecycle hook
+ * fell into exactly that hole — every screen view posted, 200'd, and dropped.
+ *
+ * `ensureCurrentSessionId` closes it: it returns the registered id when an open HAS been registered
+ * (unchanged behaviour for every host that fires `reportSessionStart` first), and otherwise mints one,
+ * REGISTERS it, and returns it — so every later event in the process correlates to that same id
+ * instead of each emitting its own orphan. A minted id is a fallback, not a substitute for a real
+ * app-open: it warns once in dev, naming the fix.
  */
+import { makeSessionId } from "./reportClientEvent";
 
 /**
  * Well-known key into the runtime-global symbol registry. `Symbol.for` (NOT a plain `Symbol()`) is
@@ -67,3 +82,71 @@ export const getCurrentSessionId = (): string | undefined =>
 export const resetCurrentSessionId = (): void => {
   globalSlot[CURRENT_SESSION_ID_SLOT] = undefined;
 };
+
+/** RN sets this global; absent under node/SSR. Read defensively via {@link warnInDev}. */
+declare const __DEV__: boolean | undefined;
+
+/**
+ * Emit a one-line developer warning, but ONLY in a dev build (RN `__DEV__`). No-op in prod/tests.
+ * Same idiom as `analyticsFacade.warnInDev` — deliberately duplicated rather than imported, so this
+ * module keeps its zero-import-weight for the tree-shaken analytics bundle.
+ *
+ * Returns whether it ACTUALLY warned, so the caller's once-flag is spent on a warning a developer
+ * saw. Marking "already warned" after a no-op would burn the single warning in prod, and the one
+ * dev build that needed it would then run silent.
+ */
+const warnInDev = (message: string): boolean => {
+  if (typeof __DEV__ !== "undefined" && __DEV__ && typeof console !== "undefined" && console.warn) {
+    console.warn(message);
+    return true;
+  }
+  return false;
+};
+
+/** The one-time message. Hoisted so a prod mint does not rebuild a string nobody will read. */
+const MINT_WARNING =
+  "[wireai] No app-open session was registered, so a session id was minted for this event " +
+  "(the server drops an event that has no session_id, and still answers 200). Mount " +
+  "useLifecycleEvents at your app root so events correlate to a real app-open.";
+
+/**
+ * "Have we already warned about a minted session id?" — its OWN `Symbol.for` slot, for the same
+ * cross-bundle reason as the id itself: a plain module `let` would warn once per inlined copy, i.e.
+ * once per bundle, not once per process. NOT cleared by `resetCurrentSessionId`: "warn once" is a
+ * process-lifetime promise, and a test that resets the id between mints is still one process.
+ */
+const MINT_WARNED_SLOT: unique symbol = Symbol.for(
+  "@wireai/activation:currentSessionIdMintWarned",
+);
+
+type GlobalWithWarnSlot = typeof globalThis & { [MINT_WARNED_SLOT]?: boolean };
+
+const warnSlot = globalThis as GlobalWithWarnSlot;
+
+/**
+ * The current per-open `session_id`, MINTING and registering one when no app-open has been
+ * registered yet. Always returns a non-empty string. Idempotent (a second call returns the same id)
+ * and never throws.
+ *
+ * Use this on every path that puts a `session_id` on the wire. The server REQUIRES a non-empty
+ * `session_id` and drops the event otherwise while still answering 200 (see the module header), so
+ * "no id yet" must never mean "send it without one".
+ *
+ * BACKWARD-COMPATIBLE BY CONSTRUCTION: when `reportSessionStart` / `useLifecycleEvents` has already
+ * registered the real per-open id, this is `getCurrentSessionId()` and nothing changes. It only ever
+ * mints in the case that used to produce a silently discarded event.
+ *
+ * A mint means the host never registered an app-open, so the minted id is one the server has not
+ * seen a `session_started` for — the events land, but the session is thinner than a real open.
+ * Hence the one-time dev warning naming the fix (mount `useLifecycleEvents` at the app root).
+ */
+export const ensureCurrentSessionId = (): string => {
+  const existing = globalSlot[CURRENT_SESSION_ID_SLOT];
+  if (typeof existing === "string" && existing.length > 0) return existing;
+  const minted = makeSessionId();
+  globalSlot[CURRENT_SESSION_ID_SLOT] = minted;
+  if (!warnSlot[MINT_WARNED_SLOT] && warnInDev(MINT_WARNING)) {
+    warnSlot[MINT_WARNED_SLOT] = true;
+  }
+  return minted;
+};

package/src/analytics/eventQueue.ts

@@ -24,7 +24,12 @@
  * `notifyOnline()`; persistence is the host-injected AsyncStorage-compatible subset.
  */
 import type { ContextEnvelope } from "./contextEnvelope";
-import { buildEventsRequest, type ClientEvent, type ClientEventTarget } from "./reportClientEvent";
+import {
+  buildEventsRequest,
+  warnOnSkippedEvents,
+  type ClientEvent,
+  type ClientEventTarget,
+} from "./reportClientEvent";
 import type { WireOnboardingStorage } from "../session/persistedSession";
 
 /** Envelope source: a fixed envelope or a provider evaluated at enqueue time (fresh network type). */
@@ -241,6 +246,9 @@ export const createEventQueue = (options: EventQueueOptions): EventQueue => {
     const timer = setTimeout(() => controller?.abort(), 15_000);
     try {
       const res = await fetch(req.url, { ...req.init, signal: controller?.signal });
+      // A 200 can still carry `skipped:N` — events the server threw away. Log-only: the ack below
+      // stays `res.ok`, so retry/dequeue behaviour is unchanged.
+      warnOnSkippedEvents(res);
       return !!(res && (res as { ok?: boolean }).ok);
     } catch {
       return false;

package/src/analytics/index.ts

@@ -73,5 +73,24 @@ export {
 export type { ClearUserContextOptions } from "../context/userContext";
 export { looksLikeEmail } from "../identity/userIdentity";
 
+// ─── The ONE auto-minted, persisted per-install `device_key` (the join key) ────
+// Public so an analytics-only consumer can read the SAME id the façade stamps and forward it to the
+// onboarding side via `activationJoinContext(deviceKey)`. Without it the join has no reachable key.
+export {
+  resolveAutoDeviceKey,
+  resetAutoDeviceKeys,
+  deviceIdStorageKey,
+  AUTO_DEVICE_ID_PREFIX,
+} from "../context/deviceId";
+export type { DeviceKeyStorage, ResolveAutoDeviceKeyOptions } from "../context/deviceId";
+
 // ─── Current per-open session registry (identify/app-events reuse the live session) ───
-export { getCurrentSessionId, setCurrentSessionId, resetCurrentSessionId } from "./currentSession";
+export {
+  getCurrentSessionId,
+  // The write-through read every wire path uses: returns the registered per-open id, minting +
+  // registering one when no app-open has been registered (the server drops an event with no
+  // `session_id` and still answers 200).
+  ensureCurrentSessionId,
+  setCurrentSessionId,
+  resetCurrentSessionId,
+} from "./currentSession";