@wireai/activation 0.12.2 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wireai/activation",
-  "version": "0.12.2",
+  "version": "0.13.0",
   "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

@@ -356,8 +356,15 @@ export const OnboardingFlow: React.FC<OnboardingFlowProps> = ({
   const wrappedActions = useCallback(
     (messageId: string) => {
       const base = makeActions(messageId);
-      const key = progress.key;
-      const validator = key ? validatorsRef.current?.[key] : undefined;
+      // ⚠️ HOST VALIDATORS LIVE IN THE SAME KEY NAMESPACE `deriveAnswers` files answers under, so
+      // moving the answer key to `slot_id` without moving this lookup would silently UNBIND every
+      // host validator — no error, no warning, values just stop being checked. Try the slot first
+      // (matching the answer key), then fall back to the question key, so a host that has not yet
+      // renamed its validator map keeps working while a server rolls slots out.
+      const validators = validatorsRef.current;
+      const validator =
+        (progress.slot_id ? validators?.[progress.slot_id] : undefined) ??
+        (progress.key ? validators?.[progress.key] : undefined);
       if (!validator) return base;
 
       const out: Record<string, (...args: unknown[]) => void> = { ...base };
@@ -387,7 +394,7 @@ export const OnboardingFlow: React.FC<OnboardingFlowProps> = ({
       }
       return out;
     },
-    [makeActions, progress.key],
+    [makeActions, progress.key, progress.slot_id],
   );
 
   // ── Render ────────────────────────────────────────────────────────────────

package/src/WireOnboarding.tsx

@@ -22,8 +22,9 @@ 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 { hydrateDeviceIdentity } from "./context/deviceId";
 import { activationJoinContext } from "./context/userContext";
+import { hostIdentity, resolveIdentity } from "./identity/identityRecord";
 import { sanitizeUserId } from "./identity/userIdentity";
 import {
   clearPersistedSession,
@@ -34,22 +35,17 @@ import {
   type LoadedSession,
 } 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);
-  }
-};
+import { warnInDev } from "./utils/warnInDev";
 
 /** 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;
 
+/** The settled result of the auto-join read: a key to inject, or `null` plus WHY the kit declined.
+ *  `timeout` = the adapter never answered; `not-durable` = it answered but did not persist the id,
+ *  so injecting it would mean a different key on every launch. */
+type AutoJoinOutcome = { key: string } | { key: null; reason: "timeout" | "not-durable" };
+
 export const WireOnboarding: React.FC<WireOnboardingProps> = ({
   config,
   theme,
@@ -109,8 +105,23 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
   // 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();
+  //
+  // A host-supplied key is also RECORDED on the process-wide provenance registry, so a sibling
+  // surface can later ask "does this app own a device id?" — see the K9 warning below. The registry
+  // write is idempotent (same key, same value), so running it from a memo is safe under StrictMode's
+  // double-invoke; it lives here rather than in an effect so the answer is already true for any
+  // surface constructed later in the same tick.
+  const hostJoinIdentity = useMemo(
+    () =>
+      resolveIdentity({
+        value: userContextStable?.device_key,
+        space: "device",
+        source: "host",
+        scope: config.appId,
+      }),
+    [userContextStable, config.appId],
+  );
+  const missingJoinKey = !hostJoinIdentity;
 
   // 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
@@ -119,12 +130,21 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
   //   • `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.
+  //   • `storage` that actually WORKS — without persistence the auto id 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, and it inflates distinct-device counts on top. Same
+  //     reason `useLifecycleEvents` gates its own fallback on storage.
   //
-  // It resolves through `hydrateAutoDeviceKey`, never the sync `resolveAutoDeviceKey`: the sync
+  // ⚠️ 0.13.0 (K1): the third condition used to be `Boolean(storage)` — the PRESENCE of the prop,
+  // never the SUCCESS of the write. A REJECTING adapter (a locked / full / permission-denied
+  // AsyncStorage, the most common real breakage) therefore walked the per-launch key in through the
+  // front door: `hydrateAutoDeviceKey` resolves to the in-memory mint on every failure branch, and a
+  // string is a string. The gate now reads `IdentityRecord.durable`, which is `true` ONLY when the id
+  // was adopted from storage or written to it successfully — so a broken adapter lands on exactly the
+  // same "declined, and here is why" path as no adapter at all.
+  //
+  // It resolves through `hydrateDeviceIdentity`, 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
@@ -133,33 +153,35 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
   // 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);
+  // `undefined` = the hydration is still in flight (the gate below holds). Otherwise a settled
+  // outcome: a `key` to inject, or `null` plus the reason the kit declined, which the warning names.
+  const [autoJoinOutcome, setAutoJoinOutcome] = useState<AutoJoinOutcome | undefined>(undefined);
 
   useEffect(() => {
-    if (!wantsAutoJoin || autoJoinValue !== undefined || !storage) return;
+    if (!wantsAutoJoin || autoJoinOutcome !== 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);
+      if (!cancelled) setAutoJoinOutcome({ key: null, reason: "timeout" });
     }, AUTO_JOIN_HYDRATION_TIMEOUT_MS);
-    void hydrateAutoDeviceKey({ appId: config.appId, storage }).then((key) => {
+    void hydrateDeviceIdentity({ appId: config.appId, storage }).then((identity) => {
       if (cancelled) return;
       clearTimeout(timer);
-      setAutoJoinValue(key || null);
+      setAutoJoinOutcome(
+        identity?.durable ? { key: identity.value } : { key: null, reason: "not-durable" },
+      );
     });
     return () => {
       cancelled = true;
       clearTimeout(timer);
     };
-  }, [wantsAutoJoin, autoJoinValue, config.appId, storage]);
+  }, [wantsAutoJoin, autoJoinOutcome, config.appId, storage]);
 
-  const injectedJoinKey = wantsAutoJoin && typeof autoJoinValue === "string" ? autoJoinValue : undefined;
-  const autoJoinPending = wantsAutoJoin && autoJoinValue === undefined;
+  const injectedJoinKey = wantsAutoJoin ? (autoJoinOutcome?.key ?? undefined) : undefined;
+  const autoJoinPending = wantsAutoJoin && autoJoinOutcome === 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
@@ -172,6 +194,36 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
     [userContextStable, injectedJoinKey],
   );
 
+  // THE JOIN DECISION IS FROZEN AT THE MOMENT THE GATE OPENS (K5), exactly as `startupUserIdRef`
+  // below freezes the user id, and for the identical reason: `userContext` feeds the `llm` memo, and
+  // wireai-rn recreates its A2A adapter whenever the `llm` identity changes — the adapter ctor resets
+  // `contextId` (`this.contextId = void 0`), so the server-learned session id is dropped.
+  //
+  // THE TEARDOWN THIS PREVENTS: a host that resolves its device key ASYNCHRONOUSLY renders once
+  // without it → auto-join injects `wdev_*` → the host key lands a tick later → `effectiveUserContext`
+  // flips → the memo rebuilds → the adapter is recreated → the user restarts onboarding mid-flow and
+  // the server is left holding an orphaned session. It is not a hypothetical shape: it is the default
+  // shape of any host that reads its device id out of async storage.
+  //
+  // Frozen at gate-open rather than at first render because the auto-join key itself arrives
+  // asynchronously — freezing earlier would freeze `undefined`. The value is carried as a JSON STRING
+  // so it can sit in a dependency array by value; a ref alone would not re-run the memo when it fills.
+  // Client events deliberately keep reading the LIVE `effectiveUserContext`: they are posted one at a
+  // time and carry no adapter, so late host context enriches them at no risk — the same split the
+  // user id already uses (frozen in session-start metadata, live via the `identify` event).
+  const frozenWireContextRef = useRef<string | null>(null);
+  if (!autoJoinPending && frozenWireContextRef.current === null) {
+    frozenWireContextRef.current = effectiveUserContext ? JSON.stringify(effectiveUserContext) : "";
+  }
+  const startupUserContextKey = frozenWireContextRef.current ?? "";
+  const startupUserContext = useMemo<Record<string, string | number | boolean> | undefined>(
+    () =>
+      startupUserContextKey
+        ? (JSON.parse(startupUserContextKey) as Record<string, string | number | boolean>)
+        : undefined,
+    [startupUserContextKey],
+  );
+
   // 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
@@ -184,7 +236,11 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
       : !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.";
+        : autoJoinOutcome?.key === null && autoJoinOutcome.reason === "not-durable"
+          ? "your `storage` adapter answered but could not persist the key (the read or the write " +
+            "failed), so the key would be different on every launch, which corrupts min_sessions " +
+            "instead of merely leaving the join empty. Check the adapter you passed as `storage`."
+          : "your `storage` adapter did not answer in time.";
   useEffect(() => {
     if (!warnMissingJoinKey) return;
     warnInDev(
@@ -198,6 +254,31 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
     );
   }, [warnMissingJoinKey, autoJoinReason]);
 
+  // THE SECOND CASE AUTO-JOIN WOULD OTHERWISE SILENCE (K9). 0.12.2 suppressed the missing-join-key
+  // warning whenever injection succeeded, which is right when the host genuinely owns no device id —
+  // and wrong when it owns one and simply forgot it HERE. That host used to get a loud warning and
+  // now gets a silent third id space: its app events under its own key, this onboarding session under
+  // `wdev_*`, and `activated` still zero. Nothing a single mount can see distinguishes the two cases,
+  // which is why the provenance registry exists: any surface constructed with a HOST-supplied device
+  // key records it, so this mount can ask whether the process demonstrably owns one.
+  //
+  // It WARNS rather than declining to inject: declining would leave the onboarding side with no key
+  // at all, which is strictly worse than a self-consistent one. It also does not silently ADOPT the
+  // other surface's key — that would be the kit guessing which of two ids a host meant, on the
+  // strength of construction order, and quietly changing what lands on the wire.
+  const hostKeyElsewhere = missingJoinKey ? hostIdentity("device", config.appId) : undefined;
+  const warnHostKeyElsewhere = Boolean(hostKeyElsewhere) && Boolean(injectedJoinKey);
+  useEffect(() => {
+    if (!warnHostKeyElsewhere) return;
+    warnInDev(
+      "[wireai] <WireOnboarding> got no user_context.device_key, so the kit injected its own — but " +
+        "another surface in this app was constructed WITH a host-supplied device key " +
+        `("${hostKeyElsewhere}"). Your app events carry that id and this onboarding session carries ` +
+        "the kit's, so the two land in disjoint id spaces and the `activated` funnel still reads " +
+        "zero. Pass the SAME id here: userContext={activationJoinContext(deviceKey)}.",
+    );
+  }, [warnHostKeyElsewhere, hostKeyElsewhere]);
+
   // 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
@@ -311,7 +392,9 @@ 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,
-        ...(effectiveUserContext ? { userContext: effectiveUserContext } : {}),
+        // The FROZEN wire context, never the live one — see the freeze note above. A change here
+        // recreates the A2A adapter and drops `contextId`.
+        ...(startupUserContext ? { userContext: startupUserContext } : {}),
         // 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
@@ -320,7 +403,7 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
       },
       timeoutMs: 60_000,
     };
-  }, [config.serverUrl, config.appId, config.apiKey, metadataStable, sessionId, componentsStable, device, effectiveUserContext]);
+  }, [config.serverUrl, config.appId, config.apiKey, metadataStable, sessionId, componentsStable, device, startupUserContext]);
 
   // Where client-reported events are POSTed (`/v1/events`). Same tenant creds as the flow.
   const reportTarget = useMemo<ClientEventTarget>(

package/src/activation/wireActivation.ts

@@ -29,7 +29,8 @@ import {
   type ClientEventTarget,
 } from "../analytics/reportClientEvent";
 import { resolveAutoDeviceKey, type ResolveAutoDeviceKeyOptions } from "../context/deviceId";
-import { resolveUserContext, type WireUserContext } from "../context/userContext";
+import { cleanString, resolveUserContext, type WireUserContext } from "../context/userContext";
+import { resolveIdentity } from "../identity/identityRecord";
 import { detectAppVersion } from "../device/appVersion";
 import type { WireOnboardingStorage } from "../session/persistedSession";
 import {
@@ -38,12 +39,8 @@ import {
   subscribeActivationRevalidation,
 } from "./revalidation";
 
-/** Trim a candidate string; return `undefined` for a non-string / blank so callers can `if`-gate. */
-const clean = (value: unknown): string | undefined => {
-  if (typeof value !== "string") return undefined;
-  const trimmed = value.trim();
-  return trimmed.length > 0 ? trimmed : undefined;
-};
+/** The shared trim helper (was a byte-identical private copy named `clean` in this file). */
+const clean = cleanString;
 
 /**
  * Tenant transport + context inputs for {@link createWireActivation}. `serverUrl`/`apiKey` are the
@@ -109,6 +106,15 @@ export const createWireActivation = (config: WireActivationConfig): WireActivati
   // `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);
+  // Record a HOST-supplied key on the process provenance registry, so a `<WireOnboarding>` mount that
+  // was NOT given one can tell "this app owns no device id" (fine, inject) from "this app owns one
+  // and forgot it here" (the silent third id space — K9). Recording only; nothing reads it on this path.
+  resolveIdentity({
+    value: explicitDeviceKey,
+    space: "device",
+    source: "host",
+    scope: config.appId,
+  });
   const autoDeviceKeyOptions: ResolveAutoDeviceKeyOptions = {
     appId: config.appId,
     // An explicit key opts out of minting AND persisting (unchanged contract).

package/src/analytics/analyticsFacade.ts

@@ -38,17 +38,9 @@ import {
 } from "../context/userContext";
 import { resolveAutoDeviceKey, type ResolveAutoDeviceKeyOptions } from "../context/deviceId";
 import { detectAppVersion } from "../device/appVersion";
+import { resolveIdentity } from "../identity/identityRecord";
 import { looksLikeEmail, sanitizeUserId } from "../identity/userIdentity";
-
-/** 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. */
-const warnInDev = (message: string): void => {
-  if (typeof __DEV__ !== "undefined" && __DEV__ && typeof console !== "undefined" && console.warn) {
-    console.warn(message);
-  }
-};
+import { warnInDev } from "../utils/warnInDev";
 
 /** Arbitrary non-PII event properties. Serialized to the event's `meta` (a JSON string) on the wire. */
 export type AnalyticsProps = Record<string, unknown>;
@@ -204,6 +196,15 @@ export const createAnalytics = (
     typeof config.userContext?.deviceKey === "string" && config.userContext.deviceKey.trim()
       ? config.userContext.deviceKey.trim()
       : undefined;
+  // Record a HOST-supplied key on the process provenance registry, so a `<WireOnboarding>` mount that
+  // was NOT given one can tell "this app owns no device id" (fine, inject) from "this app owns one
+  // and forgot it here" (the silent third id space — K9). Recording only; nothing reads it here.
+  resolveIdentity({
+    value: hostDeviceKeyAtInit,
+    space: "device",
+    source: "host",
+    scope: config.appId,
+  });
   // 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

package/src/analytics/currentSession.ts

@@ -48,6 +48,12 @@
  * app-open: it warns once in dev, naming the fix.
  */
 import { makeSessionId } from "./reportClientEvent";
+// The shared primitive returns whether it ACTUALLY warned, which the once-flag below depends on:
+// marking "already warned" after a prod no-op would burn the single warning and leave the one dev
+// build that needed it silent. (The old local copy justified itself as keeping this module
+// import-free for the tree-shaken analytics bundle; that had already lapsed — it imports
+// `makeSessionId` right here — and `utils/warnInDev` has no imports of its own.)
+import { warnInDev } from "../utils/warnInDev";
 
 /**
  * Well-known key into the runtime-global symbol registry. `Symbol.for` (NOT a plain `Symbol()`) is
@@ -83,26 +89,6 @@ 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 " +

package/src/analytics/eventQueue.ts

@@ -31,6 +31,7 @@ import {
   type ClientEventTarget,
 } from "./reportClientEvent";
 import type { WireOnboardingStorage } from "../session/persistedSession";
+import { warnInDev } from "../utils/warnInDev";
 
 /** Envelope source: a fixed envelope or a provider evaluated at enqueue time (fresh network type). */
 export type EnvelopeSource = ContextEnvelope | (() => ContextEnvelope | undefined);
@@ -85,6 +86,66 @@ const DEFAULTS = {
 /** Ceiling on the persisted-backlog read — a hung adapter degrades to an empty start, never a stall. */
 const READ_TIMEOUT_MS = 1500;
 
+// ── One storage slot per QUEUE, not per appId (K4) ───────────────────────────────────────────────
+//
+// The default key was derived from `appId` alone, so two `createAnalytics` instances for one tenant —
+// the documented double-wiring, a façade for `track`/`screen` plus an activation instance — shared ONE
+// persisted backlog while keeping SEPARATE in-memory buffers. Every symptom of that is silent:
+// each `persist()` overwrites the other's blob with its own view of "pending"; a queue that drains to
+// empty calls `removeItem` and DELETES a sibling's still-pending events; and on relaunch whatever
+// survived is loaded by both instances and sent twice. `useLifecycleEvents` already avoided all of it
+// by handing its queue a dedicated explicit key — this generalizes that.
+//
+// A `Symbol.for` slot for the same reason as every other registry here: tsup inlines a copy of this
+// module into each bundle, and a plain module `let` would let the `.` and `./analytics` copies each
+// think they were the first claimant of the same key.
+const QUEUE_KEY_SLOT: unique symbol = Symbol.for("@wireai/activation:eventQueueKeys");
+
+type GlobalWithQueueKeys = typeof globalThis & { [QUEUE_KEY_SLOT]?: Set<string> };
+
+const queueKeyGlobal = globalThis as GlobalWithQueueKeys;
+
+const claimedQueueKeys = (): Set<string> => {
+  const existing = queueKeyGlobal[QUEUE_KEY_SLOT];
+  if (existing) return existing;
+  const created = new Set<string>();
+  queueKeyGlobal[QUEUE_KEY_SLOT] = created;
+  return created;
+};
+
+/**
+ * Claim `preferred` for this queue, or the next free `preferred#N` when a live queue already holds it.
+ *
+ * ONLY the appId-derived DEFAULT is ever rotated. An EXPLICIT `storageKey` is the host (or
+ * `useLifecycleEvents`) declaring which slot a queue owns, and that hook re-creates its queue on every
+ * remount — rotating there would silently walk it off its own backlog once per remount, which is a
+ * worse bug than the one being fixed.
+ */
+const claimQueueKey = (preferred: string, explicit: boolean): string => {
+  const claimed = claimedQueueKeys();
+  if (explicit || !claimed.has(preferred)) {
+    claimed.add(preferred);
+    return preferred;
+  }
+  let ordinal = 2;
+  while (claimed.has(`${preferred}#${ordinal}`)) ordinal++;
+  const key = `${preferred}#${ordinal}`;
+  claimed.add(key);
+  warnInDev(
+    `[wireai] a second event queue was created for the same appId, and "${preferred}" is already ` +
+      "claimed by a live one. Two queues sharing one storage slot overwrite each other's backlog, " +
+      "delete each other's pending events when one drains to empty, and double-send on relaunch, so " +
+      `this queue was given "${key}" instead. Prefer ONE analytics instance per app; if you really ` +
+      "need two, pass an explicit `storageKey` to each so the slots are yours to reason about.",
+  );
+  return 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`. */
+export const resetEventQueueKeys = (): void => claimedQueueKeys().clear();
+
 /** Internal buffered item. `id` is a local monotonic handle for deterministic dequeue-after-ack;
  *  it is NEVER sent to the server. `sig` is the de-dup signature (serialized stamped event). */
 type QueuedItem = { id: number; event: ClientEvent; sig: string };
@@ -137,7 +198,14 @@ const parsePersisted = (raw: string | null | undefined): PersistedItem[] => {
 export const createEventQueue = (options: EventQueueOptions): EventQueue => {
   const target = options.target;
   const storage = options.storage;
-  const key = options.storageKey ?? `wireai:evtq:${options.appId ?? "default"}`;
+  // One slot per QUEUE (K4): an explicit key is taken verbatim; the appId-derived default is rotated
+  // to `…#2` when a live queue already holds it, so two instances can never share one backlog.
+  //
+  // Only claimed when there IS storage. The defect is entirely about the persisted slot, and a
+  // storage-less queue (the documented degraded in-memory mode) never reads or writes the key — so
+  // claiming there would warn about a collision that cannot happen.
+  const defaultKey = options.storageKey ?? `wireai:evtq:${options.appId ?? "default"}`;
+  const key = storage ? claimQueueKey(defaultKey, options.storageKey !== undefined) : defaultKey;
   const maxSize = options.maxSize ?? DEFAULTS.maxSize;
   const batchSize = options.batchSize ?? DEFAULTS.batchSize;
   const baseBackoffMs = options.baseBackoffMs ?? DEFAULTS.baseBackoffMs;

package/src/analytics/index.ts

@@ -49,7 +49,7 @@ export { buildContextEnvelope } from "./contextEnvelope";
 export type { ContextEnvelope, ContextEnvelopeInput } from "./contextEnvelope";
 
 // ─── Offline-first, persistent, batched + retried event queue (dependency-free) ─
-export { createEventQueue } from "./eventQueue";
+export { createEventQueue, resetEventQueueKeys } from "./eventQueue";
 export type { EventQueue, EventQueueOptions, EnvelopeSource } from "./eventQueue";
 
 // ─── Developer-facing analytics façade (track / screen / identify) over the queue ─