@wireai/activation 0.13.6-next.0 → 0.14.0

package/dist/{currentSession-Cs3lweFZ.d.mts → currentSession-CUvTOchb.d.mts}

@@ -472,10 +472,11 @@ type OnboardingResult = {
     /** The raw message thread, for custom downstream parsing. */
     raw: Message[];
     /**
-     * The backend's onboarding plan, when it sent one. Present ONLY on the AI path: a tenant running
-     * the static flow, or any run the server finished without a plan, leaves this `undefined` AND
-     * leaves the key off the result object entirely — so a host written before plans existed sees
-     * byte-identically what it always saw.
+     * The backend's onboarding plan, present when the backend sent one — the kit never infers it
+     * from which flow ran. Whether a plan arrives is the backend's configuration, not the kit's. Any
+     * run the server finished without a plan leaves this `undefined` AND leaves the key off the
+     * result object entirely — so a host written before plans existed sees byte-identically what it
+     * always saw.
      *
      * ⚠️ The kit does NOT interpret this and does NOT validate it. It checks one structural fact (a
      * plan is an object) and hands the payload straight through, unread, unlogged, and never attached
@@ -484,6 +485,16 @@ type OnboardingResult = {
      * the host's decision, not the kit's.
      */
     plan?: unknown;
+    /**
+     * The experiment ARM the backend assigned this session, when it is running one. Absent when
+     * the tenant runs no experiment, which is the common case, and absent is NOT an error.
+     * The kit does NOT interpret it, does not log it, does not brand it and never attaches it
+     * to an analytics event. What an arm key MEANS is the host's decision.
+     *
+     * Like {@link plan}, the KEY is set only when an arm was actually seen, so a run with no
+     * experiment leaves the result byte-identical to what every host already reads.
+     */
+    variant?: string;
 };
 /**
  * Lifecycle events emitted as the flow runs, for host-side analytics. The kit owns
@@ -495,7 +506,11 @@ type OnboardingResult = {
  *  - `resumed`: a persisted session was restored after an app kill (fires INSTEAD of
  *               `started`, so host funnels don't double-count the same session). Also carries
  *               `contextId`. Requires the `storage` prop.
- *  - `turn`: a new assistant card arrived (`step` = 1-based index of cards seen).
+ *  - `turn`: a new assistant card arrived (`step` = 1-based index of cards seen). Carries
+ *               `variant`, the backend's experiment arm for this session, from the first card that
+ *               declared one onwards — this is how the arm is available DURING the flow rather than
+ *               only at completion. The key is absent whenever no arm has been seen, which is every
+ *               turn of every tenant running no experiment.
  *  - `error`: the backend errored or the first-card watchdog timed out.
  *  - `retry`: a transient failure is being auto-retried (`attempt` = 1-based).
  *  - `fallback`: retries are exhausted; the kit degraded to the static `fallbackFlow`
@@ -516,6 +531,7 @@ type OnboardingEvent = {
     type: "turn";
     step: number;
     component?: string;
+    variant?: string;
 } | {
     type: "error";
     reason: "backend" | "timeout";
@@ -654,10 +670,19 @@ type WireOnboardingProps = {
      *
      * ```tsx
      * <WireOnboarding userContext={activationJoinContext(deviceKey)} ... />
-     * // no device id of your own? read the kit's:
-     * <WireOnboarding userContext={activationJoinContext(resolveAutoDeviceKey({ appId, storage }))} ... />
+     * // no device id of your own? pass `storage` and leave this prop alone — the kit injects its
+     * // own key, and only after it has confirmed the key actually persists (see `autoJoinKey`).
+     * <WireOnboarding config={{ ...config, storage }} ... />
      * ```
      *
+     * ⛔ Do NOT hand-build the auto key with `activationJoinContext(resolveAutoDeviceKey({...}))`.
+     * `resolveAutoDeviceKey` is SYNCHRONOUS by contract: it hands back a freshly minted id and adopts
+     * the persisted one a storage read later, and it cannot tell you whether the id survives the
+     * launch at all. A key that differs on every launch corrupts `min_sessions` rather than merely
+     * leaving the join empty. The auto-join path does the awaited, durability-checked read for you;
+     * a host that genuinely wants the value in hand should await `hydrateDeviceIdentity` and refuse a
+     * `durable: false` record, which is exactly what the kit does internally.
+     *
      * SINCE 0.12.2, leaving it out no longer silently empties the funnel: when you pass `storage` and
      * this prop carries no `device_key`, the kit injects its OWN per-install key — the same one the
      * analytics surfaces mint and persist — so the default wiring joins. Anything you DO pass wins
@@ -790,6 +815,17 @@ type OnboardingProgress = {
     slot_id?: string;
     /** Whether the CURRENT screen may be skipped (backend-marked; default false → no Skip shown). */
     skippable?: boolean;
+    /**
+     * The EXPERIMENT ARM the backend assigned this session, when the tenant is running one. Rides the
+     * render envelope as a sibling of {@link step}/{@link total}/{@link key}/{@link slot_id}, and is
+     * OMITTED entirely for a tenant running no experiment — which is the common case, and is not an
+     * error. The assignment is sticky for the session, so a later card that omits it does not
+     * un-assign it.
+     *
+     * The kit does NOT interpret this. It is whitelisted, latched and handed to the host exactly as
+     * received; what an arm key MEANS is the host's decision. See {@link OnboardingResult.variant}.
+     */
+    variant?: string;
 };
 
 /**
@@ -958,6 +994,19 @@ 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;
 };
 /** 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.
@@ -1349,6 +1398,12 @@ declare const resolveAutoDeviceKey: (opts?: ResolveAutoDeviceKeyOptions) => stri
  *
  * 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.
  */
 declare const hydrateAutoDeviceKey: (opts?: ResolveAutoDeviceKeyOptions) => Promise<string>;
 /**

package/dist/{currentSession-DD6dKB0i.d.ts → currentSession-CW_5Mq4O.d.ts}

@@ -472,10 +472,11 @@ type OnboardingResult = {
     /** The raw message thread, for custom downstream parsing. */
     raw: Message[];
     /**
-     * The backend's onboarding plan, when it sent one. Present ONLY on the AI path: a tenant running
-     * the static flow, or any run the server finished without a plan, leaves this `undefined` AND
-     * leaves the key off the result object entirely — so a host written before plans existed sees
-     * byte-identically what it always saw.
+     * The backend's onboarding plan, present when the backend sent one — the kit never infers it
+     * from which flow ran. Whether a plan arrives is the backend's configuration, not the kit's. Any
+     * run the server finished without a plan leaves this `undefined` AND leaves the key off the
+     * result object entirely — so a host written before plans existed sees byte-identically what it
+     * always saw.
      *
      * ⚠️ The kit does NOT interpret this and does NOT validate it. It checks one structural fact (a
      * plan is an object) and hands the payload straight through, unread, unlogged, and never attached
@@ -484,6 +485,16 @@ type OnboardingResult = {
      * the host's decision, not the kit's.
      */
     plan?: unknown;
+    /**
+     * The experiment ARM the backend assigned this session, when it is running one. Absent when
+     * the tenant runs no experiment, which is the common case, and absent is NOT an error.
+     * The kit does NOT interpret it, does not log it, does not brand it and never attaches it
+     * to an analytics event. What an arm key MEANS is the host's decision.
+     *
+     * Like {@link plan}, the KEY is set only when an arm was actually seen, so a run with no
+     * experiment leaves the result byte-identical to what every host already reads.
+     */
+    variant?: string;
 };
 /**
  * Lifecycle events emitted as the flow runs, for host-side analytics. The kit owns
@@ -495,7 +506,11 @@ type OnboardingResult = {
  *  - `resumed`: a persisted session was restored after an app kill (fires INSTEAD of
  *               `started`, so host funnels don't double-count the same session). Also carries
  *               `contextId`. Requires the `storage` prop.
- *  - `turn`: a new assistant card arrived (`step` = 1-based index of cards seen).
+ *  - `turn`: a new assistant card arrived (`step` = 1-based index of cards seen). Carries
+ *               `variant`, the backend's experiment arm for this session, from the first card that
+ *               declared one onwards — this is how the arm is available DURING the flow rather than
+ *               only at completion. The key is absent whenever no arm has been seen, which is every
+ *               turn of every tenant running no experiment.
  *  - `error`: the backend errored or the first-card watchdog timed out.
  *  - `retry`: a transient failure is being auto-retried (`attempt` = 1-based).
  *  - `fallback`: retries are exhausted; the kit degraded to the static `fallbackFlow`
@@ -516,6 +531,7 @@ type OnboardingEvent = {
     type: "turn";
     step: number;
     component?: string;
+    variant?: string;
 } | {
     type: "error";
     reason: "backend" | "timeout";
@@ -654,10 +670,19 @@ type WireOnboardingProps = {
      *
      * ```tsx
      * <WireOnboarding userContext={activationJoinContext(deviceKey)} ... />
-     * // no device id of your own? read the kit's:
-     * <WireOnboarding userContext={activationJoinContext(resolveAutoDeviceKey({ appId, storage }))} ... />
+     * // no device id of your own? pass `storage` and leave this prop alone — the kit injects its
+     * // own key, and only after it has confirmed the key actually persists (see `autoJoinKey`).
+     * <WireOnboarding config={{ ...config, storage }} ... />
      * ```
      *
+     * ⛔ Do NOT hand-build the auto key with `activationJoinContext(resolveAutoDeviceKey({...}))`.
+     * `resolveAutoDeviceKey` is SYNCHRONOUS by contract: it hands back a freshly minted id and adopts
+     * the persisted one a storage read later, and it cannot tell you whether the id survives the
+     * launch at all. A key that differs on every launch corrupts `min_sessions` rather than merely
+     * leaving the join empty. The auto-join path does the awaited, durability-checked read for you;
+     * a host that genuinely wants the value in hand should await `hydrateDeviceIdentity` and refuse a
+     * `durable: false` record, which is exactly what the kit does internally.
+     *
      * SINCE 0.12.2, leaving it out no longer silently empties the funnel: when you pass `storage` and
      * this prop carries no `device_key`, the kit injects its OWN per-install key — the same one the
      * analytics surfaces mint and persist — so the default wiring joins. Anything you DO pass wins
@@ -790,6 +815,17 @@ type OnboardingProgress = {
     slot_id?: string;
     /** Whether the CURRENT screen may be skipped (backend-marked; default false → no Skip shown). */
     skippable?: boolean;
+    /**
+     * The EXPERIMENT ARM the backend assigned this session, when the tenant is running one. Rides the
+     * render envelope as a sibling of {@link step}/{@link total}/{@link key}/{@link slot_id}, and is
+     * OMITTED entirely for a tenant running no experiment — which is the common case, and is not an
+     * error. The assignment is sticky for the session, so a later card that omits it does not
+     * un-assign it.
+     *
+     * The kit does NOT interpret this. It is whitelisted, latched and handed to the host exactly as
+     * received; what an arm key MEANS is the host's decision. See {@link OnboardingResult.variant}.
+     */
+    variant?: string;
 };
 
 /**
@@ -958,6 +994,19 @@ 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;
 };
 /** 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.
@@ -1349,6 +1398,12 @@ declare const resolveAutoDeviceKey: (opts?: ResolveAutoDeviceKeyOptions) => stri
  *
  * 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.
  */
 declare const hydrateAutoDeviceKey: (opts?: ResolveAutoDeviceKeyOptions) => Promise<string>;
 /**

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 import * as React from 'react';
 import React__default, { ReactNode } from 'react';
-import { I as WireOnboardingProps, J as WireOnboardingConfig, O as OnboardingResult, K as WirePermissionStatus, P as PermissionStage, L as WirePermissionOutcome, S as StepValidator, M as OnboardingEvent, N as OnboardingCopy, C as ClientEventTarget, Q as DeviceContext, T as PermissionScreenConfig, W as WireUserContext, U as PermissionPlacement, c as ClientEvent, g as EnvelopeSource } from './currentSession-Cs3lweFZ.mjs';
-export { A as AUTO_DEVICE_ID_PREFIX, a as AnalyticsEvent, b as ClearUserContextOptions, d as ClientEventType, V as DEFAULT_PERMISSION_COPY, X as DeviceFormFactor, D as DeviceKeyStorage, Y as EXTRA_KEY_PREFIX, Z as GENERIC_PERMISSION_COPY, _ as IdentifyOnboardingBinding, $ as IdentifyOnboardingOptions, a0 as IdentityRecord, a1 as IdentitySource, a2 as IdentitySpace, a3 as NOTIFICATIONS_PERMISSION_COPY, a4 as OnboardingProgress, a5 as PermissionScreenCopy, R as ResolveAutoDeviceKeyOptions, a6 as ResolveUserContextOptions, a7 as ResolvedUserContext, a8 as USER_ID_MAX_LENGTH, i as WIRE_ONBOARDING_EVENTS, a9 as WIRE_PERMISSION_EVENTS, j as WireOnboardingEventName, aa as WirePermissionEventName, ab as WirePermissionKind, ac as activationJoinContext, k as analyticsUserIdStorageKey, m as clearPiiFromContext, n as clearUserContext, ad as collectDeviceContext, p as deviceIdStorageKey, q as ensureCurrentSessionId, r as getCurrentSessionId, ae as hashEmailFnv1a, af as hostIdentity, ag as hydrateAutoDeviceKey, ah as hydrateDeviceIdentity, ai as identifyOnboarding, aj as isWireScalar, s as looksLikeEmail, t as makeSessionId, ak as mintDeviceId, al as namespaceExtra, am as normalizePermissionStatus, an as permissionEventName, ao as permissionEventProps, u as reportClientEvent, v as reportClientEventAwait, w as reportClientEvents, x as reportClientEventsAwait, y as resetAutoDeviceKeys, z as resetCurrentSessionId, ap as resetIdentityProvenance, F as resolveAutoDeviceKey, aq as resolveIdentity, ar as resolvePermissionCopy, as as resolveUserContext, at as sanitizeUserId, G as setCurrentSessionId, H as toAnalyticsEvent } from './currentSession-Cs3lweFZ.mjs';
+import { I as WireOnboardingProps, J as WireOnboardingConfig, O as OnboardingResult, K as WirePermissionStatus, P as PermissionStage, L as WirePermissionOutcome, S as StepValidator, M as OnboardingEvent, N as OnboardingCopy, C as ClientEventTarget, Q as DeviceContext, T as PermissionScreenConfig, W as WireUserContext, c as ClientEvent, U as PermissionPlacement, g as EnvelopeSource } from './currentSession-CUvTOchb.mjs';
+export { A as AUTO_DEVICE_ID_PREFIX, a as AnalyticsEvent, b as ClearUserContextOptions, d as ClientEventType, V as DEFAULT_PERMISSION_COPY, X as DeviceFormFactor, D as DeviceKeyStorage, Y as EXTRA_KEY_PREFIX, Z as GENERIC_PERMISSION_COPY, _ as IdentifyOnboardingBinding, $ as IdentifyOnboardingOptions, a0 as IdentityRecord, a1 as IdentitySource, a2 as IdentitySpace, a3 as NOTIFICATIONS_PERMISSION_COPY, a4 as OnboardingProgress, a5 as PermissionScreenCopy, R as ResolveAutoDeviceKeyOptions, a6 as ResolveUserContextOptions, a7 as ResolvedUserContext, a8 as USER_ID_MAX_LENGTH, i as WIRE_ONBOARDING_EVENTS, a9 as WIRE_PERMISSION_EVENTS, j as WireOnboardingEventName, aa as WirePermissionEventName, ab as WirePermissionKind, ac as activationJoinContext, k as analyticsUserIdStorageKey, m as clearPiiFromContext, n as clearUserContext, ad as collectDeviceContext, p as deviceIdStorageKey, q as ensureCurrentSessionId, r as getCurrentSessionId, ae as hashEmailFnv1a, af as hostIdentity, ag as hydrateAutoDeviceKey, ah as hydrateDeviceIdentity, ai as identifyOnboarding, aj as isWireScalar, s as looksLikeEmail, t as makeSessionId, ak as mintDeviceId, al as namespaceExtra, am as normalizePermissionStatus, an as permissionEventName, ao as permissionEventProps, u as reportClientEvent, v as reportClientEventAwait, w as reportClientEvents, x as reportClientEventsAwait, y as resetAutoDeviceKeys, z as resetCurrentSessionId, ap as resetIdentityProvenance, F as resolveAutoDeviceKey, aq as resolveIdentity, ar as resolvePermissionCopy, as as resolveUserContext, at as sanitizeUserId, G as setCurrentSessionId, H as toAnalyticsEvent } from './currentSession-CUvTOchb.mjs';
 import { O as OnboardingTheme } from './types-BKfpdZzX.mjs';
 export { a as OnboardingButtonStyle, b as OnboardingColors, c as OnboardingFonts, d as OnboardingRadius, e as OnboardingSpacing } from './types-BKfpdZzX.mjs';
 export { C as CenteredModal, a as CenteredModalHandle, b as CenteredModalProps } from './CenteredModal-C3qQBHsA.mjs';
@@ -1286,6 +1286,8 @@ type PartialProgress = {
     /** The stable per-slot identity, when the backend sends one. See `OnboardingProgress.slot_id`. */
     slot_id?: string;
     skippable?: boolean;
+    /** The experiment arm assigned to this session, when the tenant runs one. See `OnboardingProgress.variant`. */
+    variant?: string;
 };
 declare const readProgress: (response?: WireAIResponse) => PartialProgress;
 
@@ -1570,6 +1572,15 @@ 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()`). */
 type WireActivation = {
@@ -1592,6 +1603,12 @@ 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;
 };
 /**
  * Create a bound activation instance for a tenant transport. Resolves the device key once (explicit >
@@ -2031,8 +2048,9 @@ interface SessionStartConfig {
     appVersion?: string;
     /** Tenant/app id — namespaces the auto `device_key` fallback below. */
     appId?: string;
-    /** Host storage (AsyncStorage subset). Present → `app.session_started` falls back to the kit's
-     *  persisted auto `device_key` when the host passes none. Absent → no fallback (see below). */
+    /** Host storage (AsyncStorage subset). Present AND actually persisting → `app.session_started`
+     *  falls back to the kit's persisted auto `device_key` when the host passes none. Absent, or an
+     *  adapter that throws / rejects → no fallback (a per-launch key is worse than none, see below). */
     storage?: WireOnboardingStorage;
 }
 /** Per-open identity the host supplies. All optional: a pre-auth open is device-only. */
@@ -2165,8 +2183,10 @@ interface LifecycleConfig {
     appVersion?: string;
     /** Tenant/app id — namespaces the first-open flag AND the hook's internal queue storage key. */
     appId?: string;
-    /** Host storage (AsyncStorage subset). Enables the persisted once-ever first-open flag AND the
-     *  offline durability of the hook's internal queue. Omit it and both degrade to in-memory. */
+    /** Host storage (AsyncStorage subset). Enables the persisted once-ever first-open flag, the
+     *  offline durability of the hook's internal queue, AND the auto `device_key` fallback — the last
+     *  one only when the adapter actually persists (one that throws or rejects gets no fallback, the
+     *  same verdict as no storage at all). Omit it and all three degrade to in-memory. */
     storage?: WireOnboardingStorage;
 }
 /** Per-open identity + wiring the host supplies. All optional: a pre-auth open is device-only. */

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import * as React from 'react';
 import React__default, { ReactNode } from 'react';
-import { I as WireOnboardingProps, J as WireOnboardingConfig, O as OnboardingResult, K as WirePermissionStatus, P as PermissionStage, L as WirePermissionOutcome, S as StepValidator, M as OnboardingEvent, N as OnboardingCopy, C as ClientEventTarget, Q as DeviceContext, T as PermissionScreenConfig, W as WireUserContext, U as PermissionPlacement, c as ClientEvent, g as EnvelopeSource } from './currentSession-DD6dKB0i.js';
-export { A as AUTO_DEVICE_ID_PREFIX, a as AnalyticsEvent, b as ClearUserContextOptions, d as ClientEventType, V as DEFAULT_PERMISSION_COPY, X as DeviceFormFactor, D as DeviceKeyStorage, Y as EXTRA_KEY_PREFIX, Z as GENERIC_PERMISSION_COPY, _ as IdentifyOnboardingBinding, $ as IdentifyOnboardingOptions, a0 as IdentityRecord, a1 as IdentitySource, a2 as IdentitySpace, a3 as NOTIFICATIONS_PERMISSION_COPY, a4 as OnboardingProgress, a5 as PermissionScreenCopy, R as ResolveAutoDeviceKeyOptions, a6 as ResolveUserContextOptions, a7 as ResolvedUserContext, a8 as USER_ID_MAX_LENGTH, i as WIRE_ONBOARDING_EVENTS, a9 as WIRE_PERMISSION_EVENTS, j as WireOnboardingEventName, aa as WirePermissionEventName, ab as WirePermissionKind, ac as activationJoinContext, k as analyticsUserIdStorageKey, m as clearPiiFromContext, n as clearUserContext, ad as collectDeviceContext, p as deviceIdStorageKey, q as ensureCurrentSessionId, r as getCurrentSessionId, ae as hashEmailFnv1a, af as hostIdentity, ag as hydrateAutoDeviceKey, ah as hydrateDeviceIdentity, ai as identifyOnboarding, aj as isWireScalar, s as looksLikeEmail, t as makeSessionId, ak as mintDeviceId, al as namespaceExtra, am as normalizePermissionStatus, an as permissionEventName, ao as permissionEventProps, u as reportClientEvent, v as reportClientEventAwait, w as reportClientEvents, x as reportClientEventsAwait, y as resetAutoDeviceKeys, z as resetCurrentSessionId, ap as resetIdentityProvenance, F as resolveAutoDeviceKey, aq as resolveIdentity, ar as resolvePermissionCopy, as as resolveUserContext, at as sanitizeUserId, G as setCurrentSessionId, H as toAnalyticsEvent } from './currentSession-DD6dKB0i.js';
+import { I as WireOnboardingProps, J as WireOnboardingConfig, O as OnboardingResult, K as WirePermissionStatus, P as PermissionStage, L as WirePermissionOutcome, S as StepValidator, M as OnboardingEvent, N as OnboardingCopy, C as ClientEventTarget, Q as DeviceContext, T as PermissionScreenConfig, W as WireUserContext, c as ClientEvent, U as PermissionPlacement, g as EnvelopeSource } from './currentSession-CW_5Mq4O.js';
+export { A as AUTO_DEVICE_ID_PREFIX, a as AnalyticsEvent, b as ClearUserContextOptions, d as ClientEventType, V as DEFAULT_PERMISSION_COPY, X as DeviceFormFactor, D as DeviceKeyStorage, Y as EXTRA_KEY_PREFIX, Z as GENERIC_PERMISSION_COPY, _ as IdentifyOnboardingBinding, $ as IdentifyOnboardingOptions, a0 as IdentityRecord, a1 as IdentitySource, a2 as IdentitySpace, a3 as NOTIFICATIONS_PERMISSION_COPY, a4 as OnboardingProgress, a5 as PermissionScreenCopy, R as ResolveAutoDeviceKeyOptions, a6 as ResolveUserContextOptions, a7 as ResolvedUserContext, a8 as USER_ID_MAX_LENGTH, i as WIRE_ONBOARDING_EVENTS, a9 as WIRE_PERMISSION_EVENTS, j as WireOnboardingEventName, aa as WirePermissionEventName, ab as WirePermissionKind, ac as activationJoinContext, k as analyticsUserIdStorageKey, m as clearPiiFromContext, n as clearUserContext, ad as collectDeviceContext, p as deviceIdStorageKey, q as ensureCurrentSessionId, r as getCurrentSessionId, ae as hashEmailFnv1a, af as hostIdentity, ag as hydrateAutoDeviceKey, ah as hydrateDeviceIdentity, ai as identifyOnboarding, aj as isWireScalar, s as looksLikeEmail, t as makeSessionId, ak as mintDeviceId, al as namespaceExtra, am as normalizePermissionStatus, an as permissionEventName, ao as permissionEventProps, u as reportClientEvent, v as reportClientEventAwait, w as reportClientEvents, x as reportClientEventsAwait, y as resetAutoDeviceKeys, z as resetCurrentSessionId, ap as resetIdentityProvenance, F as resolveAutoDeviceKey, aq as resolveIdentity, ar as resolvePermissionCopy, as as resolveUserContext, at as sanitizeUserId, G as setCurrentSessionId, H as toAnalyticsEvent } from './currentSession-CW_5Mq4O.js';
 import { O as OnboardingTheme } from './types-BKfpdZzX.js';
 export { a as OnboardingButtonStyle, b as OnboardingColors, c as OnboardingFonts, d as OnboardingRadius, e as OnboardingSpacing } from './types-BKfpdZzX.js';
 export { C as CenteredModal, a as CenteredModalHandle, b as CenteredModalProps } from './CenteredModal-Cdgns6--.js';
@@ -1286,6 +1286,8 @@ type PartialProgress = {
     /** The stable per-slot identity, when the backend sends one. See `OnboardingProgress.slot_id`. */
     slot_id?: string;
     skippable?: boolean;
+    /** The experiment arm assigned to this session, when the tenant runs one. See `OnboardingProgress.variant`. */
+    variant?: string;
 };
 declare const readProgress: (response?: WireAIResponse) => PartialProgress;
 
@@ -1570,6 +1572,15 @@ 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()`). */
 type WireActivation = {
@@ -1592,6 +1603,12 @@ 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;
 };
 /**
  * Create a bound activation instance for a tenant transport. Resolves the device key once (explicit >
@@ -2031,8 +2048,9 @@ interface SessionStartConfig {
     appVersion?: string;
     /** Tenant/app id — namespaces the auto `device_key` fallback below. */
     appId?: string;
-    /** Host storage (AsyncStorage subset). Present → `app.session_started` falls back to the kit's
-     *  persisted auto `device_key` when the host passes none. Absent → no fallback (see below). */
+    /** Host storage (AsyncStorage subset). Present AND actually persisting → `app.session_started`
+     *  falls back to the kit's persisted auto `device_key` when the host passes none. Absent, or an
+     *  adapter that throws / rejects → no fallback (a per-launch key is worse than none, see below). */
     storage?: WireOnboardingStorage;
 }
 /** Per-open identity the host supplies. All optional: a pre-auth open is device-only. */
@@ -2165,8 +2183,10 @@ interface LifecycleConfig {
     appVersion?: string;
     /** Tenant/app id — namespaces the first-open flag AND the hook's internal queue storage key. */
     appId?: string;
-    /** Host storage (AsyncStorage subset). Enables the persisted once-ever first-open flag AND the
-     *  offline durability of the hook's internal queue. Omit it and both degrade to in-memory. */
+    /** Host storage (AsyncStorage subset). Enables the persisted once-ever first-open flag, the
+     *  offline durability of the hook's internal queue, AND the auto `device_key` fallback — the last
+     *  one only when the adapter actually persists (one that throws or rejects gets no fallback, the
+     *  same verdict as no storage at all). Omit it and all three degrade to in-memory. */
     storage?: WireOnboardingStorage;
 }
 /** Per-open identity + wiring the host supplies. All optional: a pre-auth open is device-only. */