@wireai/activation 0.13.6 → 0.14.1

package/llms.txt

@@ -12,8 +12,8 @@
 - **Metro (required):** `module.exports = withWireOnboarding(getDefaultConfig(__dirname))` from `@wireai/activation/metro`, which pins one copy of react/react-native/wireai-rn/zod (prevents the dual-React crash).
 - **Two secrets:** an app `apiKey` (a `wai_…` key that resolves the tenant server-side) and the backend `serverUrl`. Created in the getwireai console or via the backend's `register_<app>.py`. Nothing renders without both.
 - **Render:** drop `<WireOnboarding config={wireConfigFromEnv({ appId })} theme={...} onComplete={persist} fallbackFlow={<YourStaticOnboarding/>} />` into the signup flow.
-- **The join key.** Pass `userContext={activationJoinContext(deviceKey)}` on `<WireOnboarding>` (or `activationJoinContext(resolveAutoDeviceKey({ appId, storage }))` when the app owns no device id). `user_context.device_key` is the ONLY thing that joins an onboarding session to the app's later events; omit it and the `activated` funnel reads zero with no error.
-- **Lifecycle (mount it once):** `useLifecycleEvents(config, { deviceKey?, sessionCount?, userId? })` at the app root, before anything else touches analytics. It is the only path that emits `app.first_open`, it registers the per-open session id `createAnalytics` / `wire.track` / the gates all correlate to, and with `config.storage` it stamps the persisted auto `device_key` on `app.session_started`, which is what the server counts `min_sessions` from. `useSessionStart` / `reportSessionStart` are the alternatives for a host that already owns an open counter; neither emits `first_open`.
+- **The join key.** Pass `userContext={activationJoinContext(deviceKey)}` on `<WireOnboarding>`, or, when the app owns no device id, pass a working `storage` and leave `userContext` alone so the kit injects its own (⛔ never hand-build it from the synchronous `resolveAutoDeviceKey`, which cannot report whether the id survives the launch). `user_context.device_key` is the ONLY thing that joins an onboarding session to the app's later events; omit it and the `activated` funnel reads zero with no error.
+- **Lifecycle (mount it once):** `useLifecycleEvents(config, { deviceKey?, sessionCount?, userId? })` at the app root, before anything else touches analytics. It is the only path that emits `app.first_open`, it registers the per-open session id `createAnalytics` / `wire.track` / the gates all correlate to, and with `config.storage` it stamps the persisted auto `device_key` on `app.session_started`, which is what the server counts `min_sessions` from. Storage that throws or rejects counts as no storage since 0.14.0: the events fire with no auto key rather than a per-launch one. `useSessionStart` / `reportSessionStart` are the alternatives for a host that already owns an open counter; neither emits `first_open`, and `useSessionStart` follows the same auto-key rule since 0.14.0.
 - **Capture is deterministic.** `onComplete` returns an `OnboardingResult`: `answers` and `raw` always, plus (since 0.13.6) `plan` when the backend sent an onboarding plan and `variant` when the tenant runs an experiment and the backend assigned an arm. No second LLM call. Persist all answers through the app's normal profile-update path. Those two extra keys are set ONLY when the backend actually sent them, so a run without them returns exactly the object earlier versions returned, and the kit interprets neither: validate `plan` before applying it.
 - **It can never break onboarding.** Pass `fallbackFlow` (your existing static onboarding) so a backend error/timeout degrades instead of dead-ending.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wireai/activation",
-  "version": "0.13.6",
+  "version": "0.14.1",
   "private": false,
   "description": "Premium, fully-themable drop-in AI onboarding kit for React Native / Expo, on top of the open-source wireai-rn SDK.",
   "author": "Malik Chohra <malik@getwireai.com>",

package/src/OnboardingFlow.tsx

@@ -381,9 +381,10 @@ export const OnboardingFlow: React.FC<OnboardingFlowProps> = ({
     if (finished.current) return;
     finished.current = true;
     const result: OnboardingResult = { answers: deriveAnswers(messages), raw: messages };
-    // The plan rides a second DataPart on the AI path only; the static flow carries none. Setting
-    // the key ONLY when there is one keeps the no-plan result byte-identical to the pre-plan
-    // object — a host that inspects `Object.keys(result)` or `"plan" in result` sees no change.
+    // The plan rides a second DataPart and is present when the backend sent one — the kit never
+    // infers it from which flow ran. Setting the key ONLY when there is one keeps the no-plan
+    // result byte-identical to the pre-plan object — a host that inspects `Object.keys(result)` or
+    // `"plan" in result` sees no change.
     const plan = readPlan(messages);
     if (plan !== undefined) result.plan = plan;
     // The experiment arm, latched off the render envelopes during the flow. Set under exactly the

package/src/WireOnboarding.tsx

@@ -36,7 +36,7 @@ import {
 } from "./session/persistedSession";
 import {
   clearSettledPermissions,
-  loadSettledPermissions,
+  loadSettledPermissionsOutcome,
   permissionStorageKey,
   saveSettledPermissions,
 } from "./permissions/permissionMemory";
@@ -254,9 +254,10 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
     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 }}. " +
+        "userContext={activationJoinContext(deviceKey)} if your app owns a device id. If it does " +
+        "NOT, do not build one here — leave userContext alone and pass a working `storage` instead: " +
+        "the kit injects the same id the analytics side stamps, and only when it has confirmed the " +
+        "id actually persists. Never hand-write userContext={{ deviceKey }}. " +
         "The kit did NOT auto-inject its own key here because " +
         autoJoinReason,
     );
@@ -383,18 +384,57 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
   // a late arrival cannot recreate the A2A adapter. The flow simply suppresses permission screens
   // while `permissionsPending` is true, and that window closes long before the first card arrives
   // (one timeout-capped storage read against a backend round trip).
+  //
+  // ── AN UNREADABLE RECORD IS NOT AN EMPTY ONE (ruled 2026-08-18: skip, never re-ask) ──────────
+  //
+  // A read that timed out or threw used to arrive here as `[]`, i.e. "this session has settled
+  // nothing", and that guess is wrong in the expensive direction TWICE. The flow re-asks a
+  // permission the OS grants exactly once, AND the first answer then persists a set grown from
+  // that `[]`, overwriting a stored record that may have held several ids with a single one. A
+  // slow adapter could therefore permanently shrink the memory it exists to keep.
+  //
+  // So `unknown` is now its own outcome and it means: leave the memory UNRESOLVED. Because
+  // `permissionsPending` below is exactly `settledPermissions === undefined`, an unresolved memory
+  // suppresses every permission screen for this mount — which is the ruling, and it also closes
+  // the write path for free (no screen renders → nothing settles → `saveSettledPermissions` is
+  // never called → the stored record is left exactly as it was).
+  //
+  // The cost is stated rather than hidden: on a host whose adapter never answers, configured
+  // permission screens silently never show. That is the failure `placement.ts` calls out as the
+  // one a host cannot see, so it warns in dev naming the adapter.
   const wantsPermissionMemory = Boolean(storage) && (permissionScreens?.length ?? 0) > 0;
   const [settledPermissions, setSettledPermissions] = useState<string[] | undefined>(undefined);
+  // LATCHED: without it, a hung or throwing adapter is re-read on every single render — an
+  // unbounded read loop against the storage that is already failing.
+  const [permissionMemoryUnreadable, setPermissionMemoryUnreadable] = useState(false);
   useEffect(() => {
-    if (!wantsPermissionMemory || !storage || !sessionId || settledPermissions !== undefined) return;
+    if (!wantsPermissionMemory || !storage || !sessionId) return;
+    if (settledPermissions !== undefined || permissionMemoryUnreadable) return;
     let cancelled = false;
-    void loadSettledPermissions(storage, permissionsKey, sessionId).then((ids) => {
-      if (!cancelled) setSettledPermissions(ids);
+    void loadSettledPermissionsOutcome(storage, permissionsKey, sessionId).then((outcome) => {
+      if (cancelled) return;
+      if (outcome.status === "read") {
+        setSettledPermissions(outcome.ids);
+        return;
+      }
+      setPermissionMemoryUnreadable(true);
+      warnInDev(
+        "[wireai] the permission-screen memory could not be read (the storage adapter timed out " +
+          "or threw), so permission screens are suppressed for this session rather than re-asking " +
+          "a permission the OS grants once. Check the `storage` adapter passed to WireOnboarding.",
+      );
     });
     return () => {
       cancelled = true;
     };
-  }, [wantsPermissionMemory, storage, permissionsKey, sessionId, settledPermissions]);
+  }, [
+    wantsPermissionMemory,
+    storage,
+    permissionsKey,
+    sessionId,
+    settledPermissions,
+    permissionMemoryUnreadable,
+  ]);
 
   // Persist the settled set as it grows. Fire-and-forget: a failed write only costs a re-ask on a
   // resume, never a broken flow. Without `storage` there is nothing to write to and the

package/src/activation/useWireActivation.ts

@@ -16,7 +16,7 @@
  * `useScreenTracking`) split: the factory stays React-free; this is the glue. The instance is built
  * once per mount and held in a ref, so re-renders never rebuild it or re-resolve the device key.
  */
-import { useRef, useSyncExternalStore } from "react";
+import { useEffect, useRef, useSyncExternalStore } from "react";
 
 import {
   getActivationRevalidationVersion,
@@ -73,9 +73,22 @@ export const useWireActivation = (config: WireActivationConfig): UseWireActivati
   ].join("|");
   if (!ref.current || prevKeys.current !== currentKeys) {
     prevKeys.current = currentKeys;
+    // Hand back the instance being replaced: a `track()` that failed while offline may have opened a
+    // durability queue, which owns a storage claim and a backoff timer. See `WireActivation.dispose`.
+    ref.current?.dispose();
     ref.current = createWireActivation(config);
   }
 
+  // UNMOUNT: same reason. A per-screen instance that buffered a failed action must not leave its
+  // queue holding the slot the next instance needs.
+  useEffect(
+    () => () => {
+      ref.current?.dispose();
+      ref.current = undefined;
+    },
+    [],
+  );
+
   const revalidation = useActivationRevalidation();
   return { track: ref.current.track, sessionId: ref.current.sessionId, revalidation };
 };

package/src/activation/wireActivation.ts

@@ -24,10 +24,11 @@
  */
 import { ensureCurrentSessionId, getCurrentSessionId } from "../analytics/currentSession";
 import {
-  reportClientEventAwait,
+  reportClientEventsOutcome,
   type ClientEvent,
   type ClientEventTarget,
 } from "../analytics/reportClientEvent";
+import { createEventQueue, type EventQueue } from "../analytics/eventQueue";
 import { resolveAutoDeviceKey, type ResolveAutoDeviceKeyOptions } from "../context/deviceId";
 import { cleanString, resolveUserContext, type WireUserContext } from "../context/userContext";
 import { resolveIdentity } from "../identity/identityRecord";
@@ -69,6 +70,15 @@ export type WireActivationConfig = {
   appVersion?: string;
   /** Host persistence (AsyncStorage-compatible subset) so the auto-minted device key survives launches. */
   storage?: WireOnboardingStorage;
+  /**
+   * Where a FAILED `track()` goes instead of being dropped: your existing offline queue's `enqueue`
+   * (the same wiring `useLifecycleEvents` takes). Pass it when you already run one queue for the app
+   * and you want one backlog, one retry schedule, one storage slot.
+   *
+   * Omit it and the instance opens its OWN queue the first time a POST fails — never before, so an
+   * app that is online the whole time allocates nothing. A successful `track()` never touches either.
+   */
+  sink?: (event: ClientEvent) => void;
 };
 
 /** The kit-owned activation surface. `sessionId` is a live getter (reads `getCurrentSessionId()`). */
@@ -92,6 +102,12 @@ export type WireActivation = {
   subscribeRevalidation(listener: () => void): () => void;
   /** The current revalidation version — include in a decision-fetch effect's deps to re-fetch on bump. */
   getRevalidationVersion(): number;
+  /**
+   * Tear down the durability queue a failed `track()` may have opened (see
+   * {@link EventQueue.dispose}). Idempotent, never throws, and a no-op on an instance that never had
+   * a failure. Call it when you build an instance per mount; `useWireActivation` does it for you.
+   */
+  dispose(): void;
 };
 
 /**
@@ -147,6 +163,36 @@ export const createWireActivation = (config: WireActivationConfig): WireActivati
     if (resolved.userId && !event.user_id) event.user_id = resolved.userId;
   };
 
+  /**
+   * The durability path for a FAILED `track()`, built on the first failure and never before.
+   *
+   * WHY LAZY: an app that is online the whole time should allocate no queue, claim no storage slot
+   * and arm no timer. The queue exists to catch the events a bare POST used to destroy.
+   *
+   * WHY AN EXPLICIT KEY: it is a slot this instance OWNS, distinct from the façade's
+   * `wireai:evtq:<appId>`, and an explicit key is rotation-exempt — a remount's replacement instance
+   * addresses the same backlog instead of a `…#2` nobody drains. `dispose()` hands it back.
+   *
+   * AT-LEAST-ONCE, deliberately: a POST whose response was lost (an abort, a 15s timeout) may have
+   * reached the server, so a retry can duplicate it. That is the trade this kit already makes on
+   * every other event family, and the direction to fail in for a trigger that must not undercount.
+   */
+  let durability: EventQueue | undefined;
+  const bufferFailedEvent = (event: ClientEvent): void => {
+    if (config.sink) {
+      config.sink(event);
+      return;
+    }
+    if (!durability) {
+      durability = createEventQueue({
+        target,
+        storage: config.storage,
+        storageKey: `wireai:evtq:activation:${config.appId ?? "default"}`,
+      });
+    }
+    durability.enqueue(event);
+  };
+
   const track = async (name: string, meta?: Record<string, unknown>): Promise<boolean> => {
     // 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
@@ -164,9 +210,25 @@ export const createWireActivation = (config: WireActivationConfig): WireActivati
     };
     if (meta && Object.keys(meta).length > 0) event.meta = JSON.stringify(meta);
     applyContext(event);
-    const ok = await reportClientEventAwait(target, event);
+    const outcome = await reportClientEventsOutcome(target, [event]);
+    const ok = outcome === "delivered";
     // Only revalidate once the event is actually in the stream — a failed POST leaves the gate as-is.
     if (ok) bumpActivationRevalidation();
+    // A failed POST used to end the event's life right here. `track` is the ACTION reporter, and it
+    // is called at exactly the moments a phone is offline (a purchase on a train, a trial in a lift),
+    // so the server-side trigger keyed on that `question_key` simply never fired for that user. The
+    // event now goes to a durable buffer instead, and rides the same retry + persistence every other
+    // event family in this kit already gets.
+    //
+    // The RETURN VALUE stays `false`, deliberately: the caller asked whether the server has it NOW,
+    // and it does not. Revalidation stays conservative for the same reason — a deferred delivery does
+    // not bump it, so a gate re-fetch is never triggered by an event the server may still reject.
+    //
+    // ⛔ ONLY `unreachable`. A `refused` event is one the server READ and declined (a 200 carrying
+    // `skipped`), so re-sending it is a re-decline: it would sit in the PERSISTED backlog and be
+    // rejected again on every drain and every launch, forever. Durability is for the events the
+    // network lost, never for the ones the server rejected.
+    if (outcome === "unreachable") bufferFailedEvent(event);
     return ok;
   };
 
@@ -177,5 +239,9 @@ export const createWireActivation = (config: WireActivationConfig): WireActivati
     },
     subscribeRevalidation: subscribeActivationRevalidation,
     getRevalidationVersion: getActivationRevalidationVersion,
+    dispose: () => {
+      durability?.dispose();
+      durability = undefined;
+    },
   };
 };

package/src/analytics/analyticsFacade.ts

@@ -140,6 +140,13 @@ export type Analytics = {
   notifyOnline(): void;
   /** Current pending (in-memory) count. */
   size(): number;
+  /**
+   * Tear the instance's event queue down when its owner goes away (see {@link EventQueue.dispose}).
+   * Idempotent, never throws. Call it if you build an instance per screen / per mount: the queue
+   * claims a persisted storage slot, and a replacement built before the old one released it lands on
+   * a rotated `…#2` key that no later launch ever reads. `useAnalytics` does this for you.
+   */
+  dispose(): void;
 };
 
 /**
@@ -245,10 +252,22 @@ export const createAnalytics = (
   let boundUserId: string | undefined = sanitizeUserId(config.userContext?.userId);
   const storageKey = analyticsUserIdStorageKey(config.appId);
 
+  // SUPERSESSION LATCH for the construction-time hydration below.
+  //
+  // The read's guard used to be `saved && !boundUserId` alone, which asks "did something bind an id
+  // while I was reading?". A LOGOUT is the one case where the answer is a deliberate `undefined`, so
+  // a read that landed after `reset()` sailed through the guard and re-bound the user who had just
+  // logged out — onto every subsequent event, which is precisely what `reset()` promises cannot
+  // happen. The window is the first storage read of a cold start, and a logout inside it is a real
+  // sequence, not a contrived one. An empty binding must be able to mean "cleared on purpose".
+  let hydrationSuperseded = false;
+
   if (config.storage) {
     void config.storage
       .getItem(storageKey)
       .then((saved) => {
+        // A `reset()` that already ran wins, whatever this read says.
+        if (hydrationSuperseded) return;
         // Don't clobber an explicit init-context user id with a stale persisted one.
         if (saved && !boundUserId) boundUserId = saved;
       })
@@ -311,6 +330,10 @@ export const createAnalytics = (
   };
 
   const reset = (): void => {
+    // Supersede any construction-time hydration still in flight, BEFORE clearing the binding: the
+    // read cannot tell "nobody bound anything yet" from "the user just logged out", so the answer
+    // has to come from here. Without this the read re-binds the logged-out user.
+    hydrationSuperseded = true;
     // In-memory binding cleared: subsequent events carry no user_id until the next identify.
     boundUserId = undefined;
     // Strip PII from the rich context but keep the device-scope fields (device_key / app_version).
@@ -377,5 +400,6 @@ export const createAnalytics = (
     flush: queue.flush,
     notifyOnline: queue.notifyOnline,
     size: queue.size,
+    dispose: queue.dispose,
   };
 };

package/src/analytics/currentSession.ts

@@ -63,8 +63,9 @@ import { warnInDev } from "../utils/warnInDev";
  * @globalSlot LIVE — every app-open overwrites this with that open's id, so a reader that captures
  * it into a module-local (or a `const` taken once at mount) posts the PREVIOUS open's session to a
  * server that has already moved on. Read it at the moment of use, through `getCurrentSessionId()` /
- * `ensureCurrentSessionId()`. `reviews/runtime`'s `currentOpenId()` deliberately pins one sample of
- * it for the launch; that is a documented latch DERIVED from this slot, not a cache of it.
+ * `ensureCurrentSessionId()`. `reviews/runtime`'s `currentOpenId()` derives its own pinned value
+ * from this slot: it holds one sample for the duration of an app-open and re-pins when a genuinely
+ * NEW open is registered here, so it follows this slot deliberately and late, never eagerly.
  */
 const CURRENT_SESSION_ID_SLOT: unique symbol = Symbol.for(
   "@wireai/activation:currentSessionId",

package/src/analytics/eventQueue.ts

@@ -73,6 +73,19 @@ export type EventQueue = {
   notifyOnline(): void;
   /** Current pending (in-memory) count. */
   size(): number;
+  /**
+   * Tear this queue down when its owner goes away (a hook's effect cleanup, a host disposing its
+   * own instance). Idempotent, never throws, and REQUIRED for any queue that can be re-created:
+   * a remount builds a second queue while the first is still holding the storage claim and a live
+   * backoff timer, and the two then fight over one persisted slot.
+   *
+   * It clears the retry timer, releases the claimed storage key so a replacement gets the SAME slot
+   * instead of a rotated `…#2` nobody reads next launch, and makes the queue inert — `enqueue`,
+   * `flush` and every write become no-ops, so a timer that already fired cannot `removeItem` the
+   * slot the live queue owns. Anything still buffered in memory at that point stays on disk under
+   * the released key, which is exactly where the replacement queue looks for it.
+   */
+  dispose(): void;
 };
 
 const DEFAULTS = {
@@ -146,6 +159,21 @@ const claimQueueKey = (preferred: string, explicit: boolean): string => {
   return key;
 };
 
+/**
+ * Give a claimed key back, so the NEXT queue for the same appId gets the real slot instead of a
+ * rotated one. Called only from {@link EventQueue.dispose}.
+ *
+ * WHY THIS HAS TO EXIST: the claim was write-only, and "already claimed" was read as "held by a LIVE
+ * one" — liveness nothing ever tracked. A remount (nav, Fast Refresh, StrictMode's double-invoke, an
+ * appId that arrives async) therefore rotated the replacement onto `…#2`, and from then on the whole
+ * launch persisted into a slot the next launch never reads: it claims the base key, finds the older
+ * blob, and the `#N` ones accumulate forever. Releasing on teardown makes the claim mean what its
+ * warning already claimed it meant.
+ */
+const releaseQueueKey = (key: string): void => {
+  claimedQueueKeys().delete(key);
+};
+
 /** Test-only: forget every claimed queue key. A real RELAUNCH is a new process, so a test that
  *  simulates one in-process must call this or its second queue reads as a concurrent sibling.
  *  Exported from `@wireai/activation/analytics`, matching `resetAutoDeviceKeys` / `resetCurrentSessionId`. */
@@ -231,13 +259,23 @@ export const createEventQueue = (options: EventQueueOptions): EventQueue => {
   let flushing = false;
   let attempt = 0;
   let retryTimer: ReturnType<typeof setTimeout> | undefined;
-  // The persisted blob exists but has NOT been read yet (the cold-start read blew its deadline and
-  // is still in flight). While this is true every write is suppressed: the only thing the queue
-  // could write is a view of `pending` that does not include the backlog it has not seen, and
-  // `setItem`/`removeItem` would destroy it. Cleared as soon as the slow read settles, whichever
-  // way it settles, so a read that ultimately fails resumes normal persistence rather than
-  // suppressing it for the life of the process.
-  let backlogUnread = false;
+  // Set by `dispose()`. Every write path and the drain check it, because a queue whose owner is
+  // gone must not touch a storage slot a replacement queue now owns.
+  let disposed = false;
+  // The persisted blob may exist and has NOT been read yet. While this is true every write is
+  // suppressed: the only thing the queue could write is a view of `pending` that does not include
+  // the backlog it has not seen, and `setItem`/`removeItem` would destroy it. Cleared as soon as the
+  // read settles, whichever way it settles, so a read that ultimately fails resumes normal
+  // persistence rather than suppressing it for the life of the process.
+  //
+  // ARMED AT CONSTRUCTION, not when the 1500ms timeout fires. It used to be set ONLY in the timeout
+  // branch, so for the first 1500ms of every launch the comment above was false and the queue wrote
+  // freely over a blob it had not read. The sharp form is not the overwrite but the DELETE: a queue
+  // that drains to empty inside that window calls `removeItem` on the slot, and an adapter that
+  // resolves a read against its current state (a bridge that queues operations and runs them in
+  // order — not every adapter snapshots at call time) then answers `null`. The whole backlog is
+  // gone, with no error anywhere.
+  let backlogUnread = storage !== undefined;
 
   const resolveEnvelope = (): ContextEnvelope | undefined => {
     try {
@@ -275,6 +313,8 @@ export const createEventQueue = (options: EventQueueOptions): EventQueue => {
 
   const persist = (): void => {
     if (!storage) return;
+    // A disposed queue no longer owns this slot — a replacement may. See `dispose`.
+    if (disposed) return;
     // NEVER write over a blob that has not been read yet. See `backlogUnread`.
     if (backlogUnread) return;
     try {
@@ -289,9 +329,36 @@ export const createEventQueue = (options: EventQueueOptions): EventQueue => {
     }
   };
 
+  /**
+   * The two lifecycle events are the funnel's DENOMINATOR: the server computes `min_sessions` by
+   * counting distinct `app.session_started` grouped by `device_key`, and `app.first_open` is the top
+   * of the activation funnel. Losing one is not "an event fewer", it is an app-open that never
+   * happened as far as every rule reading them is concerned.
+   */
+  const isCountedOpenEvent = (event: ClientEvent): boolean =>
+    typeof event.question_key === "string" && event.question_key.startsWith("app.");
+
   const enforceSizeCap = (): void => {
-    // Drop the OLDEST first so the newest events are never the ones lost under pressure.
-    if (pending.length > maxSize) pending.splice(0, pending.length - maxSize);
+    let overflow = pending.length - maxSize;
+    if (overflow <= 0) return;
+    // Drop the OLDEST first so the newest events are never the ones lost under pressure — but spend
+    // ORDINARY events first, because at an app-open the lifecycle pair IS the oldest thing in the
+    // buffer. A host on the documented shared-sink wiring that goes offline for a long session
+    // pushes past the cap on screen views alone, and pure drop-oldest evicted `app.first_open` +
+    // `app.session_started` before anything else — deleting the open from the funnel while 200
+    // screen views survived.
+    const kept: QueuedItem[] = [];
+    for (const item of pending) {
+      if (overflow > 0 && !isCountedOpenEvent(item.event)) {
+        overflow--;
+        continue;
+      }
+      kept.push(item);
+    }
+    // Only when the buffer is NOTHING BUT counted events does the cap fall on them, oldest first.
+    // The cap is a hard ceiling: protecting a class must never turn it into an unbounded buffer.
+    if (overflow > 0) kept.splice(0, overflow);
+    pending = kept;
   };
 
   const safeSig = (event: ClientEvent): string => {
@@ -366,9 +433,18 @@ export const createEventQueue = (options: EventQueueOptions): EventQueue => {
           });
         return;
       }
+      backlogUnread = false;
       mergePersisted(parsePersisted(raced));
+      // Persist explicitly: writes were suppressed for the whole read window, and `mergePersisted`
+      // returns early (without persisting) when the backlog was empty — so without this an event
+      // enqueued during the window would sit in memory undurable until the next enqueue.
+      persist();
     } catch {
-      // Unreadable backlog → start empty; nothing enqueued in-memory is lost.
+      // Unreadable backlog → start empty; nothing enqueued in-memory is lost. Writes must resume,
+      // or the suppression that protected the unread blob would outlive the read for the whole
+      // process and nothing would ever persist again.
+      backlogUnread = false;
+      persist();
     }
   })();
 
@@ -417,11 +493,15 @@ export const createEventQueue = (options: EventQueueOptions): EventQueue => {
   };
 
   const drain = async (): Promise<void> => {
+    if (disposed) return;
     try {
       await loadPromise;
     } catch {
       // load already swallows; guard the await defensively.
     }
+    // Re-checked AFTER the await: the owner can go away while the cold-start read is in flight, and
+    // a drain that resumes then would send and dequeue under a key another queue now owns.
+    if (disposed) return;
     if (flushing) return;
     flushing = true;
     try {
@@ -453,6 +533,9 @@ export const createEventQueue = (options: EventQueueOptions): EventQueue => {
   };
 
   const enqueue = (event: ClientEvent): void => {
+    // A disposed queue is inert: it cannot persist (the slot belongs to its replacement) and must
+    // not send, so buffering here would only pretend to accept the event.
+    if (disposed) return;
     try {
       const stamped = stamp(event);
       const sig = safeSig(stamped);
@@ -479,5 +562,17 @@ export const createEventQueue = (options: EventQueueOptions): EventQueue => {
 
   const size = (): number => pending.length;
 
-  return { enqueue, flush, notifyOnline, size };
+  const dispose = (): void => {
+    if (disposed) return;
+    disposed = true;
+    // The retry is the dangerous half: `unrefTimer` is a Node-only affordance (Hermes has no
+    // `unref`), so on a device the backoff timer of an unmounted queue is fully alive, up to six
+    // attempts and a 30s ceiling. Left running it wakes up, drains, empties, and `removeItem`s a
+    // slot the live queue is using.
+    clearRetry();
+    // Only claimed when there IS storage (see the claim above), so only released then.
+    if (storage) releaseQueueKey(key);
+  };
+
+  return { enqueue, flush, notifyOnline, size, dispose };
 };

package/src/analytics/reportClientEvent.ts

@@ -341,22 +341,46 @@ export const reportClientEvent = (
 export const reportClientEventsAwait = async (
   target: ClientEventTarget | undefined,
   events: ClientEvent[],
-): Promise<boolean> => {
+): Promise<boolean> => (await reportClientEventsOutcome(target, events)) === "delivered";
+
+/**
+ * WHY a failed send is not one thing. `false` collapses two situations that call for OPPOSITE
+ * responses, and a caller that wants to make the event durable has to tell them apart:
+ *
+ *   • `unreachable` — the request never got an answer (no `fetch`, a network error, a non-2xx).
+ *     Nothing is wrong with the EVENT. Retrying later is exactly right, and is what every
+ *     offline-first path in this kit does.
+ *   • `refused`     — the server READ the event and threw it away (HTTP 200 with `skipped > 0`,
+ *     a per-event validation failure), or there is no transport to build a request from at all.
+ *     Retrying cannot change the answer: buffering here would park a poison event in a PERSISTED
+ *     backlog that re-sends and is re-refused on every drain and every launch, forever.
+ *
+ * The boolean sibling above is this function with the two collapsed back together, so there is one
+ * implementation and the two can never drift.
+ */
+export type SendOutcome = "delivered" | "refused" | "unreachable";
+
+export const reportClientEventsOutcome = async (
+  target: ClientEventTarget | undefined,
+  events: ClientEvent[],
+): Promise<SendOutcome> => {
   try {
     const req = buildEventsRequest(target, events);
-    if (!req) return false;
+    // No target / nothing serializable: there is no endpoint to retry against.
+    if (!req) return "refused";
     const res = await fetch(req.url, req.init);
-    if (!res || !res.ok) return false;
+    if (!res || !res.ok) return "unreachable";
     // ONE body read, used for both the verdict and the dev warning — it can only be read once.
     const ack = await readEventsAck(res);
-    if (!ack || ack.skipped <= 0) return true;
+    if (!ack || ack.skipped <= 0) return "delivered";
     if (typeof __DEV__ !== "undefined" && __DEV__ && typeof console !== "undefined" && console.warn) {
       console.warn(describeDiscarded(ack));
     }
-    return false;
+    // The server answered and declined THIS event. A retry is a re-decline.
+    return "refused";
   } catch {
-    // Unreachable / missing-fetch / network — best-effort, report failure.
-    return false;
+    // Unreachable / missing-fetch / network — best-effort, and retryable.
+    return "unreachable";
   }
 };
 

package/src/analytics/useAnalytics.ts

@@ -36,6 +36,11 @@ export const useAnalytics = (
   const currentKeys = `${config.serverUrl}|${config.apiKey}|${config.appId}`;
   if (!ref.current || prevKeys.current !== currentKeys) {
     prevKeys.current = currentKeys;
+    // The instance being REPLACED (credentials changed, or an `appId` that arrived async) owns a
+    // claimed storage slot and a live backoff timer. Hand them back before building the replacement,
+    // or the new instance rotates onto a `…#2` key that no later launch reads, and the old one's
+    // retry can still wake up and `removeItem` the slot the new one is using.
+    ref.current?.dispose();
     ref.current = createAnalytics(config, options);
   }
 
@@ -59,5 +64,17 @@ export const useAnalytics = (
     if (hostDeviceKey) ref.current?.setUserContext({ deviceKey: hostDeviceKey });
   }, [hostDeviceKey]);
 
+  // UNMOUNT: give the storage claim and the retry timer back. A screen that mounts this hook is
+  // built and torn down repeatedly (navigation, Fast Refresh, StrictMode's double-invoke), and each
+  // rebuild used to leave the previous queue holding the appId's slot — so every remount after the
+  // first persisted into `…#2`, `…#3`, and the next launch read none of them.
+  useEffect(
+    () => () => {
+      ref.current?.dispose();
+      ref.current = undefined;
+    },
+    [],
+  );
+
   return ref.current;
 };

package/src/context/deviceId.ts

@@ -64,9 +64,10 @@ export const mintDeviceId = (): string => {
 // RESIDUAL WINDOW: the storage read is async, so an event emitted in the milliseconds before
 // hydration completes carries the freshly minted id rather than the persisted one. The registry makes
 // every surface agree on WHICH id that is; it does not make the read sync. A caller that can afford to
-// wait (the lifecycle hook's mount effect — see `hydrateAutoDeviceKey`) should await instead: its two
-// events are the ONLY ones the server counts `min_sessions` from, so a per-launch id there is not a
-// millisecond of noise, it is a counter that can never exceed 1.
+// wait (`useLifecycleEvents` / `useSessionStart`, both app-open paths — see `hydrateDeviceIdentity`)
+// must await instead: their events are the ONLY ones the server counts `min_sessions` from, so a
+// per-launch id there is not a millisecond of noise, it is a counter that can never exceed 1. Waiting
+// is only half of it — the settled outcome can still be NON-DURABLE, and those callers refuse it.
 
 /**
  * Well-known key into the runtime-global symbol registry — one auto-id registry across every bundle.
@@ -238,6 +239,12 @@ export const resolveAutoDeviceKey = (opts: ResolveAutoDeviceKeyOptions = {}): st
  *
  * Never throws or rejects: a missing, hung, or rejecting adapter resolves to the in-memory id, and
  * with no `storage` it resolves immediately (there is nothing to hydrate from).
+ *
+ * ⚠️ IT RETURNS A BARE STRING, so it CANNOT say whether the id survives the launch — a degraded
+ * adapter resolves to the in-memory mint and reads identically to a persisted one. No kit surface
+ * uses it any more (0.14.0 moved the two lifecycle hooks off it): a caller writing a cross-launch
+ * join key wants {@link hydrateDeviceIdentity} and its `durable` flag. Kept as public API for a host
+ * that only wants "the id", never as the way to decide whether to stamp one.
  */
 export const hydrateAutoDeviceKey = async (
   opts: ResolveAutoDeviceKeyOptions = {},