@wireai/activation 0.13.6-next.0 → 0.14.0

package/AGENTS.md

@@ -51,7 +51,7 @@ subpaths are optional secondary feature modules; import one only if you use it.
 - `WIRE_PERMISSION_EVENTS`, `resolvePermissionCopy(...)`: the canonical permission-funnel names and the shipped rationale copy behind `permissionScreens` (see the prop below). The kit imports no native permission module; the host injects `request`.
 - `createRevenueCatBridge({ analytics, entitlementId })`: the RevenueCat purchase funnel (see "RevenueCat" below).
 - `activationJoinContext(deviceKey)`: builds the `userContext` value that joins an onboarding session to the app's later events. Every `<WireOnboarding>` needs it (see step 7).
-- `resolveAutoDeviceKey({ appId, storage })`: the kit's own persisted per-install `device_key`, for a host that owns none.
+- `resolveAutoDeviceKey({ appId, storage })`: the kit's own per-install `device_key`, read synchronously. Use it for a stamp on an ordinary event, never as the cross-launch join key on `<WireOnboarding>` (it cannot tell you whether the id persists, see the join-key section). `hydrateDeviceIdentity({ appId, storage })` is the awaited, durability-reporting sibling.
 - `useLifecycleEvents(config, options)`: the app-root lifecycle hook (see step 8). `useSessionStart` / `reportSessionStart` are the counter-owning alternatives.
 - Types: `OnboardingTheme`, `OnboardingResult`, `OnboardingEvent`, `WireOnboardingConfig`, `WireOnboardingProps`, `StepValidator`, `OnboardingCopy`, `IllustrationRegistry`.
 
@@ -60,7 +60,7 @@ subpaths are optional secondary feature modules; import one only if you use it.
 | Prop | Type | Required | Notes |
 |---|---|---|---|
 | `config` | `WireOnboardingConfig` | yes | A2A transport + tenant. See the `config` fields table below. |
-| `onComplete` | `(result: { answers, raw }) => void` | yes | Terminal recap CTA tapped. Persist `answers` via your profile-update path, then navigate on. |
+| `onComplete` | `(result: OnboardingResult) => void` | yes | Terminal recap CTA tapped. Persist `answers` via your profile-update path, then navigate on. `result` always has `answers` + `raw`; since 0.13.6 it also carries `plan` (the backend's onboarding plan, whenever the backend sends one; the kit never infers it from the flow type) and `variant` (the assigned experiment arm) when the backend sent them. Both keys are ABSENT otherwise, so an integration written before 0.13.6 sees no change. The kit does not interpret either one: validate `plan` before applying it. |
 | `theme` | `Partial<OnboardingTheme>` | no | Colors + font family names + radius/spacing, deep-merged over a neutral default. For dark/light, pass a different theme per app theme-state. |
 | `components` | `WireAIComponent[]` | no | Override registered cards (default `onboardingComponents`). |
 | `illustrations` | `Record<string, ReactNode>` | no | Host artwork for `InterstitialCard`, keyed by name. `{ ...defaultIllustrations, ...myArt }`. |
@@ -112,8 +112,8 @@ FACADE (`createAnalytics` and friends) is a different surface and lives on `@wir
 4. **Config**: set `EXPO_PUBLIC_WIREAI_API_KEY` / `_SERVER_URL` / `_APP_ID`; build via `wireConfigFromEnv({ appId })`.
 5. **Fonts**: host must load the font families named in `theme.fonts.regular/medium/bold` (e.g. `expo-font`), else text falls back to system font.
 6. **Theme**: `themeFromBrand({ primary })` or a full `Partial<OnboardingTheme>`; for dark/light, pick the theme by the app's theme state.
-7. **Render + continuation**: drop `<WireOnboarding>` into the signup flow; `onComplete` → persist + navigate, `onSkip` → navigate. Pass the join key: `userContext={activationJoinContext(deviceKey)}`, or `activationJoinContext(resolveAutoDeviceKey({ appId, storage }))` when the app owns no device id. Skipping it leaves the `activated` funnel permanently empty and reports no error.
-8. **Lifecycle (do not skip)**: mount `useLifecycleEvents(config, { deviceKey?, sessionCount?, userId? })` ONCE 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 that `createAnalytics` / `wire.track` / the gates all correlate to, and with `config.storage` it stamps the kit's persisted auto `device_key` on `app.session_started`, which is what the server's `min_sessions` rule counts. `useSessionStart` / `reportSessionStart` are the alternatives for a host that already owns an open counter; neither emits `first_open`.
+7. **Render + continuation**: drop `<WireOnboarding>` into the signup flow; `onComplete` → persist + navigate, `onSkip` → navigate. Pass the join key: `userContext={activationJoinContext(deviceKey)}`, 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 `resolveAutoDeviceKey`, see the join-key section). Skipping both leaves the `activated` funnel permanently empty and reports no error.
+8. **Lifecycle (do not skip)**: mount `useLifecycleEvents(config, { deviceKey?, sessionCount?, userId? })` ONCE 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 that `createAnalytics` / `wire.track` / the gates all correlate to, and with `config.storage` it stamps the kit's persisted auto `device_key` on `app.session_started`, which is what the server's `min_sessions` rule counts. That last part needs storage that actually persists: since 0.14.0 an adapter that throws or rejects is treated exactly like no storage, so the events fire with no auto key rather than a per-launch one that corrupts the count. `useSessionStart` / `reportSessionStart` are the alternatives for a host that already owns an open counter; neither emits `first_open`, and since 0.14.0 `useSessionStart` follows the same auto-key rule.
 9. **Gate**: wrap behind a flag (env for dev, remote config for prod) **AND** `config != null`; fall through to existing onboarding when off/unconfigured. Decide who sees it (e.g. new signups only) in host nav logic.
 
 ## Review firing (do not hand-roll the decision fetch)
@@ -174,17 +174,29 @@ and activation surfaces auto-mint and stamp it on every event, and onboarding ge
 `userContext={{ deviceKey }}`, because the server's device lookup reads `device_key` and a
 misspelled bucket produces an empty funnel instead of an error.
 
-**If the host owns no device id, read the kit's.** Do not leave the onboarding side blank.
-`resolveAutoDeviceKey({ appId, storage })` returns the exact id `createAnalytics` /
-`createWireActivation` auto-mint and persist for this install, so both halves of the join agree:
+**If the host owns no device id, let the kit supply it.** Do not leave the onboarding side blank and
+do not build the key yourself. Pass a working `storage` and the kit injects the exact id
+`createAnalytics` / `createWireActivation` auto-mint and persist for this install, so both halves of
+the join agree:
 
 ```tsx
-import { resolveAutoDeviceKey, activationJoinContext } from "@wireai/activation";
+import { activationJoinContext } from "@wireai/activation";
 
-const deviceKey = resolveAutoDeviceKey({ appId, storage });   // the SAME id the analytics side stamps
+// The app owns a device id: pass it.
 <WireOnboarding config={config} userContext={activationJoinContext(deviceKey)} ... />
+
+// The app owns none: pass `storage` and leave `userContext` alone. The kit injects the same id the
+// analytics side stamps, after awaiting the storage read AND confirming the id actually persists.
+<WireOnboarding config={{ ...config, storage }} ... />
 ```
 
+⛔ Do NOT hand-build that key with `activationJoinContext(resolveAutoDeviceKey({ appId, storage }))`.
+`resolveAutoDeviceKey` is synchronous by contract, so it returns a freshly minted id and adopts the
+persisted one a storage read later, and it cannot report whether the id survives the launch at all.
+Since 0.14.0 every kit surface that puts a device key on the wire as a cross-launch join awaits
+`hydrateDeviceIdentity` and refuses a non-durable record; a host that really wants the value in hand
+should do the same rather than the sync call.
+
 Always pass `storage`. Without it the id is per-LAUNCH, not per-install, and a per-launch key makes
 every open look like a new device, which breaks `min_sessions` and A/B arm stickiness as surely as
 no key breaks the join. The same rule governs the lifecycle wiring: `useLifecycleEvents` falls back

package/CHANGELOG.md

@@ -3,6 +3,252 @@
 All notable changes to `@wireai/activation` (formerly `wireai-onboarding`).
 Historical entries below the rename keep the old package name on purpose.
 
+## [0.14.0] - 2026-08-17
+
+A durability release, in two rounds. Round 1 stopped the two counted lifecycle events from riding a
+per-launch device key. Round 2 came out of a fresh-eyes audit of the whole package under a
+reproduction-first rule: eight findings, seven reproduced with a failing test before anything was
+changed, one reproduced and deliberately left unfixed because its fix is a design ruling.
+
+**MINOR, not patch, and only because of new API.** Every behaviour change here is a bug fix; the
+version moved because four public surfaces gained members: `EventQueue.dispose()`,
+`Analytics.dispose()`, `WireActivation.dispose()` and `WireActivationConfig.sink`. Nothing was
+removed, nothing was renamed, and no existing call signature changed.
+
+### Fixed
+
+- **The event queue has a teardown, and needs one.** A queue claimed a persisted storage slot and
+  armed a backoff timer, and nothing ever gave either back — "already claimed" was read as "held by
+  a LIVE one", which is liveness nothing tracked. Two consequences, both silent. A remount (nav,
+  Fast Refresh, StrictMode's double-invoke, an `appId` that arrives async) rotated the replacement
+  onto `…#2`, so the whole launch persisted into a slot the NEXT launch never reads, and the `#N`
+  keys grew without bound. Worse, on the explicit-key path both queues address the SAME slot: the
+  dead one's retry timer woke up, drained, emptied, and `removeItem`d the live queue's persisted
+  `app.session_started`. (`unrefTimer` is a Node affordance; under Hermes that timer is fully
+  alive.) `dispose()` clears the timer, releases the claim and makes the queue inert;
+  `useLifecycleEvents`, `useAnalytics` and `useWireActivation` all call it on unmount and before
+  replacing an instance.
+
+- **A storage read that TIMED OUT is no longer read as "nothing stored".** `withTimeout` resolved
+  `undefined` at the ceiling, which is byte-identical to a genuine empty read, and two callers then
+  did something irreversible with the guess. `loadPersistedSession` minted a new session id and
+  wrote it OVER the still-valid one it had not managed to read (the server then sees a second
+  `session_started` and back-fills the first as a phantom drop, the exact inflation that module
+  exists to prevent). `reportFirstOpen` treated the unread flag as "never fired" and emitted
+  `app.first_open` again on an install that already had one. Both now carry the distinct
+  `READ_TIMED_OUT` sentinel the event queue already had, and do nothing destructive on a timeout.
+
+  The same rule now covers an UNREADABLE flag (a locked / full / permission-denied adapter): that
+  fails on every launch, so emitting made `app.first_open` fire on every launch of that install,
+  counting one device as an unbounded number of installs. The kit's standing rule for an
+  unverifiable persistence answer, set in 0.13.0 and re-applied throughout this release, is to
+  decline rather than emit something that corrupts a metric. A host that wants `first_open` on a
+  device with no working storage should pass no `storage` at all, which is the documented degraded
+  mode and still fires once per process.
+
+- **`Analytics.reset()` can no longer be undone by the read that was already in flight.** The
+  construction-time user-id hydration adopted its answer under `if (saved && !boundUserId)`, and a
+  logout is the one case where an empty binding is deliberate — so a read landing after `reset()`
+  re-bound the user who had just logged out, onto every subsequent event. `reset()` now marks the
+  hydration superseded.
+
+- **The offline size cap no longer spends the funnel-denominator events first.** The buffer is
+  drop-oldest at 200, and at an app-open the oldest events in it are exactly `app.first_open` and
+  `app.session_started`. A host on the documented shared-sink wiring that went offline for a long
+  session pushed past the cap on screen views alone and evicted the open itself. Eviction now spends
+  ORDINARY events first; the cap stays a hard ceiling, so a buffer of nothing but `app.*` events
+  still evicts oldest-first rather than growing.
+
+- **`wire.track()` no longer throws the event away when the POST fails.** It is the ACTION reporter,
+  called at exactly the moments a phone is offline, and a failed POST used to be the end of that
+  event's life — so the server-side trigger keyed on that `question_key` simply never fired for that
+  user. A failed send now goes to a durable buffer: your queue if you pass the new `sink`, otherwise
+  one this instance opens on the FIRST failure and never before. `track` still resolves `false` and
+  still does not revalidate, because the caller asked whether the server has it now.
+
+  ⛔ Only a TRANSPORT failure is buffered. An event the server READ and refused (HTTP 200 carrying
+  `skipped`) is not retried: a retry is a re-decline, and it would park a poison event in a
+  persisted backlog that fails on every drain and every launch. `reportClientEventsOutcome` is the
+  internal seam that tells the two apart.
+
+- **The unread-backlog guard is armed at construction, not 1500ms later.** It was only set in the
+  timeout branch, so for the first 1500ms of every launch the queue wrote freely over a blob it had
+  not read, and a drain that emptied in that window `removeItem`d it outright. An adapter that
+  resolves a read against its current state then answers `null` and the backlog is gone. The comment
+  claiming writes were suppressed "until the read lands" is now true.
+
+- **`reportSessionStart`'s direct-POST fallback goes through `buildEventsRequest`.** It hand-built
+  its own url, headers and body, so it was the one send path of five that skipped the epoch-ms →
+  ISO8601 `ts` conversion — on the event `min_sessions` is counted from, where the failure shape is
+  HTTP 200 with `{written: 0, skipped: N}` and no client-visible error. Harmless today (that event
+  carries no `ts`), latent tomorrow. The "single choke point" claim in `reportClientEvent.ts` is now
+  held to the code by a test rather than by prose.
+
+### Known, reproduced, NOT fixed
+
+- **The review/questionnaire gates count PROCESSES, while an app-open is a 30-minute foreground.**
+  `currentOpenId()` is pinned for the life of the JS process. On iOS an app is suspended, not
+  killed, so a user opening the app daily for a week produces seven `app.session_started` events
+  (the SERVER's `min_sessions` advances to 7) while the on-device `wire_review_<id>_sessions` stays
+  at 1 forever, and a LOCAL `minSessions: 2` rule can never be met on a phone that is never
+  force-quit. It fails in the safe direction (a prompt that never shows), which is why it is not
+  being rushed.
+
+  Reproduced in `src/reviews/sessionCountAcrossOpens.test.ts`, marked `todo`, with the smallest
+  coherent fix written out next to it. It is deferred because that fix requires re-declaring the
+  `processOpenId` global slot LIVE and rewriting the `globalSlotDiscipline` canary exercise that
+  currently asserts this behaviour is correct — a canary written to guard the 2026-07-16 one-star
+  incident. Re-ruling it is a design decision, not an implementation detail.
+
+- **`loadSettledPermissions` has the same timed-out-read class**, and its caller then persists a set
+  grown from `[]`, which can shrink the stored one. Made explicit in code rather than left to an
+  accident, but not changed: the fix needs a UX ruling (on an unknown set, does a resumed flow
+  re-ask a permission or skip it?), and guessing at that is how a user gets asked twice.
+
+### Changed (docs)
+
+- Every host-facing surface stopped recommending the defect class this release fixes. The README
+  prop table, `AGENTS.md`, `llms.txt`, `INTEGRATION_PROMPT.md`, the `WireOnboardingProps.userContext`
+  docstring and the `__DEV__` missing-join-key warning all told a host with no device id of its own
+  to write `userContext={activationJoinContext(resolveAutoDeviceKey({ appId, storage }))}`. That is
+  the synchronous, durability-blind read, used as a cross-launch join key. They now say to pass a
+  working `storage` and let the kit inject the key it has confirmed persists.
+- `ai_rules/context_map.md` gained the four module rows it was missing (`src/analytics/`,
+  `src/session-analytics/`, `src/context/`, `src/device/`). The map is the file the repo's own rules
+  tell an agent to read instead of grepping `src/`, and it was silent on the directories this whole
+  release lives in.
+
+## [0.13.7] — superseded by 0.14.0, never published
+
+The round-1 device-key fixes below shipped as part of **0.14.0**. The entry is kept because it is the
+detailed record of that half of the work.
+
+The two events the server counts the funnel DENOMINATOR from stopped riding a per-launch device key.
+`app.first_open` and `app.session_started` are the only events `min_sessions` is computed from (the
+server counts distinct opens grouped by `user_context.device_key`), so a key that differs on every
+launch does not merely leave that counter empty, it caps it at 1 and inflates distinct-device counts
+at the same time. Both lifecycle hooks were doing exactly that, in two different ways.
+
+Nothing on the wire changed shape, no export was added or removed, and a host-supplied `deviceKey` is
+byte-identical to 0.13.6 on every path.
+
+### Fixed
+
+- **`useLifecycleEvents(...)` no longer stamps the in-memory mint when the storage read settles
+  NON-DURABLE.** It already awaited hydration before the mount fire, so a healthy store was correct.
+  A locked / full / permission-denied adapter is the case it missed: the read settles degraded, the
+  `.then` fired anyway, and the synchronous auto id went onto both counted events. Measured on
+  0.13.6: two launches over a throwing MMKV produced four distinct `wdev_*`.
+
+  The auto path now resolves through `hydrateDeviceIdentity(...)`, the provenance-carrying read, and
+  refuses a `durable: false` outcome, which is the rule `src/context/deviceId.ts` has stated for
+  these callers since 0.13.0 and `<WireOnboarding>`'s `autoJoinKey` has obeyed since then. A refusal
+  emits both events with NO auto `device_key`, the same branch a config with no `storage` already
+  took, never a silenced event. **Every fire path obeys it**, not just the mount one: the foreground
+  re-fire after a real background re-runs the same read, so a transient cold-boot storage lock gets a
+  fresh attempt on the next open instead of a verdict cached for the process lifetime.
+
+- **`useSessionStart(...)` waits for the persisted key before its mount fire.** This hook never got
+  the 0.13.3 hydration fix its sibling did, so it stamped a brand-new `wdev_*` on `app.session_started`
+  on every launch even on a perfectly HEALTHY store, while every other kit surface adopted the
+  persisted id milliseconds later. Any host wiring this path had a structurally unsatisfiable
+  `min_sessions` and no error anywhere. It now takes the same awaited, durability-checked auto path as
+  `useLifecycleEvents(...)`, on the mount fire and on the foreground re-fire.
+
+  It is not deprecated and its contract is otherwise unchanged: a host-supplied `deviceKey` and a
+  config with no `storage` both still fire synchronously, because there is nothing to read.
+
+### Unchanged
+
+- `createAnalytics(...)` / `createWireActivation(...)` keep stamping the synchronous
+  `resolveAutoDeviceKey(...)` per event, deliberately. Their documented contract is that they never
+  throw and degrade to the in-memory id, they are numerator paths rather than the counted opens, and
+  they re-read the registry per event so they adopt the persisted id as soon as it lands.
+- `hydrateAutoDeviceKey(...)` stays exported and behaves identically. No kit surface uses it any more:
+  it returns a bare string, and a string cannot say whether it survives the launch, which is the whole
+  reason `hydrateDeviceIdentity(...)` exists.
+- Docs swept for the claim this changes: the README lifecycle section, `AGENTS.md` step 8, `llms.txt`
+  and `INTEGRATION_PROMPT.md` all said "with `config.storage` it stamps the persisted auto
+  `device_key`". Presence of the prop was never the condition. It is now written as what it is: a
+  storage adapter that throws or rejects counts as no storage.
+
+## [0.13.6] - 2026-08-09
+
+Two things the backend already decides, handed to the host instead of guessed at. Both ride the
+same boundary: the kit reads a payload the server sent, carries it out through `onComplete`, and
+stops. It does not interpret either one, does not validate their contents, does not log them and
+never attaches them to an analytics event.
+
+The `plan` half of this release was published as `0.13.6-next.0` on 2026-08-08 with no changelog
+entry. This entry is that debt paid, plus the `variant` half, released together as 0.13.6.
+
+### Added
+
+- **`OnboardingResult.plan`, the backend's onboarding plan reaching the host uninterpreted.**
+  On the AI path the server appends a SECOND A2A DataPart to the turn it finishes on,
+  `{ kind: "onboarding_plan", plan: {...} }`, alongside the component envelope the renderer already
+  consumes. A new pure reader, `src/utils/readPlan.ts`, lifts it off the thread and `handleFinish`
+  puts it on the result. A run the server finishes without a plan is unchanged: the key stays off
+  the result object entirely. Which runs carry a plan is the backend's configuration, and the
+  reader never infers it from the flow type.
+
+  The one thing the reader is allowed to reject is a structural fact: a plan is an object. A scalar,
+  an array, a misspelled marker or a missing payload yields `undefined` and the host falls back to
+  exactly its pre-plan behaviour. No field is required and no unknown field is stripped, because a
+  kit-side schema would make the kit the thing that rejects a plan the host could have used, and the
+  server's lenient path adds markers the kit must neither read nor strip. **The host must validate
+  the payload before applying it.**
+
+  **It finds the plan by MARKER, never by position**, and that is the load-bearing part of the read.
+  The kit walks the thread newest turn first and, inside a turn, returns the first part whose `kind`
+  is `onboarding_plan` and whose payload is an object. Anything else is skipped rather than treated
+  as a terminator, so a thread carrying two plans resolves to the last one, the turn the flow
+  completes on, and a malformed part can never shadow a good one. Position would be the wrong tool
+  here: the SDK collects a task's parts across agent messages LATEST-FIRST, so on a task that
+  carries history a previous turn's envelope can sit in the same array as this turn's plan. The
+  marker makes that harmless, and it is also why nothing in this pipe promises wire order.
+
+  It needs an SDK that surfaces the DataParts PAST the first one. The first DataPart is the
+  component envelope the renderer already consumes, and it is the one the SDK turns into the string
+  it returns for the turn, so the plan is one of the parts left behind after it.
+  `wireai-rn@0.2.5-next.1` hands those over on `Message.dataParts`, and a turn that carried nothing
+  but the envelope leaves the member ABSENT rather than an empty array (checked against the
+  published tarball, not against a paraphrase of it). The peer range here is unchanged at `>=0.2.3`,
+  so this degrades rather than breaks: an older SDK, `0.2.4` included, sets no `dataParts`, the kit
+  reads no plan, and the host lands on exactly the path a tenant that sends none already takes.
+
+- **`OnboardingResult.variant`, the experiment arm the backend assigned, surfaced to the host.**
+  The server rides the arm key on the render envelope at `props.progress.variant`, a sibling of
+  `step` / `total` / `key` / `slot_id`. The kit had no way to hand it over, so a host that wanted to
+  branch on the arm had to INFER it from the shape of the flow (counting answers against a
+  hard-coded maximum), an inference that goes silently wrong the day the server changes a flow
+  length.
+
+  `readProgress` whitelists `variant` exactly the way it already whitelists `slot_id`: a non-string
+  or absent key reads as "no experiment", never as an error. `OnboardingFlow` latches the arm at
+  first sight into a ref that is never cleared, because the assignment is sticky per session but
+  only rides the render envelope, and a later card that omits it must not un-assign it.
+
+  It is also available DURING the flow: the `turn` event carries `variant` from the first card that
+  declares one onwards, reusing an event hosts already subscribe to instead of adding a prop for a
+  scalar. What an arm key MEANS is the host's decision; the kit does not map it to a name, brand it,
+  default it or log it. **It is deliberately never attached to an analytics event either**, on
+  either surface, so a host that wants arm-segmented funnels has to put the arm on its own events.
+
+### Unchanged
+
+- **Both keys are byte-identical no-ops when the backend sends nothing.** `plan` and `variant` are
+  each set on the result ONLY when one was actually seen, so a run without them leaves
+  `Object.keys(result)` as `["answers", "raw"]` and `"plan" in result` / `"variant" in result`
+  false. Setting a key to `undefined` would pass an `=== undefined` check while breaking every host
+  deep-equality assertion, so the canaries assert the KEY SET, not the value. The same rule governs
+  the `turn` event.
+- **Neither read can throw.** Both sit on the single code path to `onComplete`, where a throw would
+  cost the user the completion of an onboarding they already finished. Every read is runtime-guarded
+  and `readPlan` declares its own structural type rather than casting: an `as` cast silences the
+  compiler in both directions, including the day the published SDK type disagrees.
+- No new runtime dependency, no export renamed or removed, no change to the exports map.
+
 ## [0.13.5] - 2026-08-03
 
 Two halves of one idea: stop finding out about a broken events integration from a funnel report.
@@ -866,7 +1112,11 @@ true, and pins the wire with tests.
 - Version reset to `0.1.0` to mark the start of the new package line. The GitHub repository
   stays `chohra-med/wireai-onboarding`.
 
-## [Unreleased]
+## [0.9.0] — 2026-07-17
+
+*This section carried the title `[Unreleased]` until 2026-08-09, long after it shipped. Everything
+below went out in 0.9.0; the three analytics/device items it also held belong to 0.8.0 and have been
+moved to their own section under this one.*
 
 ### Added: `fetchReviewDecision` — the kit now owns the review firing decision (live user harm)
 
@@ -1025,6 +1275,11 @@ All four from Malik's on-device test, 2026-07-16. The **review** gate's chrome i
   button. The 5-star → native store review route (`routeRating`) is untouched.
 - `theme/mergeThemeOver` extracts the helper both gates had copy-pasted.
 
+## [0.8.0] — 2026-07-15
+
+*Also mis-filed under `[Unreleased]` until 2026-08-09. These three items shipped in 0.8.0, one
+release before everything in the section above.*
+
 ### Added: "device" is now fully automatic — auto-minted, persisted per-install `device_key`
 
 - The analytics façade (`createAnalytics`) now auto-mints a stable, NON-PII per-install `device_key`
@@ -1058,7 +1313,7 @@ All four from Malik's on-device test, 2026-07-16. The **review** gate's chrome i
 - Backward compatible: no existing export renamed or removed; zero new dependencies. The one
   behavior change is intentional — events now carry an auto `device_key` when the host omits one.
 
-## [0.7.0] — Unreleased
+## [0.7.0] — 2026-07-15
 
 ### Added: `WireUserContext` — one rich user-context object → every event's `user_context`
 
@@ -1439,7 +1694,7 @@ All four from Malik's on-device test, 2026-07-16. The **review** gate's chrome i
   `showcaseColorsFromTheme(theme, accent)` (new `src/showcase/showcaseColors.ts`) with a
   regression test asserting the primary button is the accent and never the background.
 
-## [0.3.0] — Unreleased
+## [0.3.0] — 2026-07-12
 
 > Pending release. `0.2.1` is already published on npm (coachmarks + showcase, no
 > identity API), so this identity surface — alongside the unpublished `/reviews`

package/INTEGRATION_PROMPT.md

@@ -41,9 +41,10 @@ STEPS (do them in order, stop and ask if a convention is ambiguous):
      dead-ends.
    - Forward install attribution if I have it: `wireConfigFromEnv({ appId, metadata: attributionMetadata({...}) })`.
    - THE JOIN KEY: pass `userContext={activationJoinContext(deviceKey)}`. If my app owns no stable
-     device id, use `activationJoinContext(resolveAutoDeviceKey({ appId, storage }))`, which returns
-     the same id the analytics side stamps. Leaving it out makes the `activated` funnel read zero
-     forever and reports no error.
+     device id, pass a working `storage` and leave `userContext` alone: the kit injects the same id
+     the analytics side stamps, after confirming it actually persists. Do NOT hand-build it from
+     `resolveAutoDeviceKey` (synchronous, and it cannot report durability). Leaving both out makes
+     the `activated` funnel read zero forever and reports no error.
    - Analytics: log via `toAnalyticsEvent(e)` → my logger, using the canonical `wire_onboarding_*` names.
 7. Navigation: mount the screen in my first-run/signup flow; branch to the static flow when the gate
    is off or config is missing.
@@ -51,7 +52,9 @@ STEPS (do them in order, stop and ask if a convention is ambiguous):
    ONCE at my app root, above the navigator, before anything else touches analytics. Pass
    `config.storage`. It is the only path that emits `app.first_open`, it registers the per-open
    session id every other surface correlates to, and with storage it stamps the kit's persisted auto
-   `device_key` on `app.session_started`, which is what the server counts `min_sessions` from.
+   `device_key` on `app.session_started`, which is what the server counts `min_sessions` from. If my
+   storage adapter throws or rejects, the kit treats it as no storage and stamps no auto key at all
+   (0.14.0), because a key that changes every launch corrupts that count.
    `useSessionStart` / `reportSessionStart` are only for a host that already owns an open counter;
    neither emits `first_open`.
 9. Event triggers (only if I asked to fire a review/questionnaire off an in-app action): pick the

package/README.md

@@ -231,7 +231,7 @@ import { WireOnboarding } from "@wireai/activation";
 | Prop | Type | Notes |
 |---|---|---|
 | `config` | `{ apiKey, serverUrl, appId, metadata?, appVersion? }` | A2A transport; the key resolves the tenant server-side. `appVersion` is host-injected (e.g. `Constants.expoConfig?.version`) and forwarded for analytics segmentation. **Required.** |
-| `onComplete` | `(result: { answers, raw }) => void` | Fires when the user taps the terminal recap's CTA. **Required.** |
+| `onComplete` | `(result: OnboardingResult) => void` | Fires when the user taps the terminal recap's CTA. `result` always carries `answers` and `raw`. Since 0.13.6 it may also carry `plan` (the backend's onboarding plan, present whenever the backend sends one; the kit never infers it from the flow type) and `variant` (the experiment arm the backend assigned, when the tenant runs one). Each of those two keys is set ONLY when the backend actually sent one, so a run without them returns exactly the object earlier versions returned: `"plan" in result` and `"variant" in result` both stay false. The kit does not interpret either: **validate `plan` before you apply it.** **Required.** |
 | `theme` | `Partial<OnboardingTheme>` | Brand colors/fonts/radius/spacing, deep-merged over a neutral default. |
 | `illustrations` | `Record<string, ReactNode>` | App artwork for `InterstitialCard`, keyed by name. |
 | `icons` | `Record<string, ReactNode>` | Your own icon nodes, keyed by the semantic name the AI emits (`{ instagram: <BrandIg/> }`). Checked first, so use it to put your brand mark on a choice card, to add names the vocabulary does not carry, or to get icons at all without installing `@expo/vector-icons`. Anything you leave out falls back to that optional peer, then to no icon. Never a crash. See [Icons](#icons). |
@@ -241,7 +241,7 @@ import { WireOnboarding } from "@wireai/activation";
 | `onError` | `(err) => void` | Backend error or first-card timeout, fired **after retries are exhausted**, not on the first failure. When `fallbackFlow` is not supplied, the host owns recovery (e.g. route to a static flow). With neither, the kit shows an inline retry. `fallbackFlow` takes precedence over this. |
 | `fallbackFlow` | `ReactNode` | Your predefined STATIC onboarding, rendered in place once the AI flow fails and retries are exhausted. **Takes precedence over `onError`.** This is the "it can never break your onboarding" guarantee: pass the same flow you shipped before adding Wire AI and the user always keeps moving. |
 | `maxRetries` | `number` | Consecutive failures to auto-retry before degrading to `fallbackFlow`/`onError`. Default `1` (one silent retry, then degrade). `0` degrades on the first failure. Budget it deliberately: each retry restarts the flow, so with `startTimeoutMs` at its `15000` default the default `maxRetries` puts 30s of loader in front of a user before they see the fallback. A retry also sends a skip sentinel, so the user loses one question and a retry is never recorded as their first answer. |
-| `onEvent` | `(e: OnboardingEvent) => void` | `started` / `turn` / `error` — recover per-turn analytics since the kit owns the loop. |
+| `onEvent` | `(e: OnboardingEvent) => void` | `started` / `resumed` / `turn` / `error` / `retry` / `fallback` / `permission`, the full union in `OnboardingEvent`. Recover per-turn analytics since the kit owns the loop. See the note under the helpers table. |
 | `copy` | `Partial<OnboardingCopy>` | Localize the kit's built-in English loader/completion strings. |
 | `approxScreens` | `number` | Approx total screens — paces the bar as `step/total` (capped, never shown). A backend `progress.total` (the screen budget, sent every turn incl. init) wins, so usually unnecessary. |
 | `components` | `WireAIComponent[]` | Override the registered cards (defaults to `onboardingComponents`). |
@@ -251,7 +251,7 @@ import { WireOnboarding } from "@wireai/activation";
 | `sessionTtlMs` | `number` | How long a persisted session id stays resumable. Default `3600000` (1h, the backend's session TTL). With `storage` only. |
 | `persistKey` | `string` | Override the storage key (default `wireai:session:<appId>`). Scope per-user if one device can onboard multiple accounts mid-flow. With `storage` only. |
 | `retainSessionOnComplete` | `boolean` | Opt IN: keep the persisted session seed alive across completion. A multi-stage signup that re-enters onboarding (typically a `key=` remount) then resumes the SAME session instead of minting a fresh `metadata.sessionId`, which the backend adopts as a second `contextId` and double-counts as a `session_started`. Omitted or `false` clears the seed on completion, the legacy single-stage behavior, so leaving it unset changes nothing. With `true`, freshness comes from `sessionTtlMs` plus an explicit new-run signal (scope a new `persistKey`, e.g. a per-signup id). With `storage` only. |
-| `userContext` | `Record<string, string \| number \| boolean>` | **This is where the join key goes.** `user_context.device_key` is the only thing that joins this onboarding session to the app's later events, so pass `userContext={activationJoinContext(deviceKey)}` (or `activationJoinContext(resolveAutoDeviceKey({ appId, storage }))` if your app owns no device id). Since 0.12.2, omitting it no longer empties the funnel silently: with `storage`, the kit injects its own key (see [The join key](#the-join-key-device_key-never-session_id) and `autoJoinKey` below). Second job: any other non-PII context the app already knows (signup method, referral, plan, a HASHED user id), forwarded on session metadata + client events for funnel segmentation. **No PII on THIS prop** (no raw emails/names); primitives only; the server caps size/keys. See [Device & user context](#device--user-context). ⚠️ Distinct from the analytics/activation **`WireUserContext`** object (`createAnalytics` / `useWireActivation`), which additionally accepts an opt-in raw `userEmail` — see [Rich user context & PII](#rich-user-context--pii). |
+| `userContext` | `Record<string, string \| number \| boolean>` | **This is where the join key goes.** `user_context.device_key` is the only thing that joins this onboarding session to the app's later events, so pass `userContext={activationJoinContext(deviceKey)}`. If your app owns no device id, pass a working `storage` and leave this prop alone: the kit injects its own key, and only after it has confirmed the key actually persists. ⛔ Do not hand-build that key with `activationJoinContext(resolveAutoDeviceKey({ appId, storage }))`, because `resolveAutoDeviceKey` is synchronous by contract (it hands back a fresh mint and adopts the persisted id a storage read later) and it cannot tell you whether the id survives the launch at all. Since 0.12.2, omitting it no longer empties the funnel silently: with `storage`, the kit injects its own key (see [The join key](#the-join-key-device_key-never-session_id) and `autoJoinKey` below). Second job: any other non-PII context the app already knows (signup method, referral, plan, a HASHED user id), forwarded on session metadata + client events for funnel segmentation. **No PII on THIS prop** (no raw emails/names); primitives only; the server caps size/keys. See [Device & user context](#device--user-context). ⚠️ Distinct from the analytics/activation **`WireUserContext`** object (`createAnalytics` / `useWireActivation`), which additionally accepts an opt-in raw `userEmail` — see [Rich user context & PII](#rich-user-context--pii). |
 | `autoJoinKey` | `boolean` | Opt OUT of the automatic join key. Default `true`. When this prop is left alone, `storage` is present **and actually persists** (0.13.0: a `storage` adapter that rejects or throws is treated exactly like no `storage` — the kit declines and says so, because a key it cannot persist is a different key on every launch, which corrupts `min_sessions` rather than merely leaving the join empty), and `userContext` carries no `device_key`, the kit injects its own per-install key (the same id `createAnalytics` / `createWireActivation` mint and persist), so the `activated` funnel joins with no host wiring. Pass `autoJoinKey={false}` if you genuinely want an UNLINKED onboarding session: that restores the pre-0.12.2 behavior exactly, and the dev warning fires again. It never overrides a `device_key` you passed, and it cannot inject without `storage` (see [The join key](#the-join-key-device_key-never-session_id)). |
 | `userId` | `string` | Your own OPAQUE user id, so onboarding sessions reconcile to real users later (console sessions to your user table / GA4 users). Optional and supports **late binding**: present at mount it rides the session-start metadata; if it changes mid-session (the user just registered) the kit emits an `identify` event; available only after the flow, use `identifyOnboarding(...)`. **No PII** (not an email/name/phone); trimmed and capped at 128 chars. See [User identity](#user-identity). |
 
@@ -271,7 +271,7 @@ You rarely hand-roll config, gating, analytics, or attribution — the kit ships
 | `themeFromBrand({ primary })` · `defaultIllustrations` | One-color theme; dependency-free fallback artwork. |
 | `motionSpec` | The motion constants behind every kit animation (durations, springs, the design ease). Read-only for hosts. `setMotionDurationScale` / `getMotionDurationScale` are QA tools for the playground's animation-speed knob: never call them in production code. |
 
-> **`onEvent`** fires `started` / `resumed` / `turn` / `error` / `retry` / `fallback` (the kit owns the loop, so this is how you recover per-turn analytics). `resumed` fires INSTEAD of `started` when a persisted session was restored (see the `storage` prop) — don't count both as flow starts. Completion is signalled via `onComplete`, not `onEvent` — log `WIRE_ONBOARDING_EVENTS.completed` there. `started` and `resumed` also carry a `contextId` (the A2A session id): capture it if you might bind a `userId` after the flow finishes (see [User identity](#user-identity)).
+> **`onEvent`** fires `started` / `resumed` / `turn` / `error` / `retry` / `fallback` / `permission` (the kit owns the loop, so this is how you recover per-turn analytics). `resumed` fires INSTEAD of `started` when a persisted session was restored (see the `storage` prop) — don't count both as flow starts. Since 0.13.6 the `turn` event also carries `variant`, the experiment arm the backend assigned, from the first card that declares one onwards; that is how you read the arm DURING the flow rather than waiting for `onComplete`. The key is absent when no experiment is running, and the kit never attaches the arm to an analytics event, so arm-segmented funnels are the host's job. Completion is signalled via `onComplete`, not `onEvent` — log `WIRE_ONBOARDING_EVENTS.completed` there. `started` and `resumed` also carry a `contextId` (the A2A session id): capture it if you might bind a `userId` after the flow finishes (see [User identity](#user-identity)).
 
 **Integrating with an AI agent?** See [`INTEGRATION_PROMPT.md`](./INTEGRATION_PROMPT.md) (copy-paste prompt for Claude Code) and [`llms.txt`](./llms.txt). Fastest of all: the `wire-rn-integration` Claude skill.
 
@@ -421,6 +421,14 @@ none, and waits for that key to be read back before it fires, so the events the
 `min_sessions` from carry the id this install keeps. Without storage the id would be per-launch, which
 would make every open look like a new device, so the fallback deliberately does not engage.
 
+Since 0.14.0 that also covers a `storage` adapter that is present but cannot persist (locked, full,
+permission denied, so it throws or rejects). The read settles non-durable and the hook declines the
+key rather than stamping the in-memory one. Both events still fire, they just carry no auto
+`device_key`. That is the same verdict `autoJoinKey` reaches on `<WireOnboarding>`, for the same
+reason: a key that changes on every launch corrupts `min_sessions` and inflates distinct-device
+counts, where an absent key only leaves the join empty. A `deviceKey` you supply yourself is never
+touched by any of this.
+
 The two alternatives below are for a host that already owns an open counter. Both emit
 `app.session_started` only, so `app.first_open` stays empty forever on those paths.
 
@@ -1310,49 +1318,47 @@ then *improve* Wire AI, not just eyeball it.
 
 ### MCP server (`mcp/`)
 
-A local Model Context Protocol server (`@wireai/mcp`, stdio, TypeScript). It is a
-repo-local dev tool — **not** published to npm (excluded from the package `files`
-allowlist). Build it in place:
-
-```bash
-cd mcp && npm install && npm run build
-```
+A Model Context Protocol server (`@wireai/mcp`, TypeScript) that exposes the whole
+onboarding control plane as agent tools. It runs two ways, same tools either way:
 
-Then add it to your agent client's MCP config:
+1. **Hosted, and this is the default.** `https://wireai-mcp.fly.dev/mcp` over Streamable
+   HTTP. You authenticate per request with an `Authorization: Bearer` header, so there is
+   no build step, no login step, and nothing on disk.
+2. **Local stdio.** `cd mcp && npm install && npm run build`, then point your client at
+   `mcp/dist/index.js`. Auth is a one-time `node dist/index.js login`, or raw keys via
+   `WIREAI_SERVER_URL` / `WIREAI_API_KEY` / `WIREAI_ADMIN_KEY`. This package is repo-local
+   and **not** published to npm (it is excluded from the kit's `files` allowlist).
 
 ```json
 {
   "mcpServers": {
     "wireai": {
-      "command": "node",
-      "args": ["<abs-path>/@wireai/activation/mcp/dist/index.js"],
-      "env": {
-        "WIREAI_SERVER_URL": "https://<your-backend>.fly.dev",
-        "WIREAI_API_KEY": "wai_<tenant-key>",
-        "WIREAI_ADMIN_KEY": "wai_admin_<operator-key>"
-      }
+      "type": "http",
+      "url": "https://wireai-mcp.fly.dev/mcp",
+      "headers": { "Authorization": "Bearer <your-token>" }
     }
   }
 }
 ```
 
-Tools (P1 is read-biased; the only writes are the existing register/update):
+**Three credential classes, and you probably want the third.** A tenant `wai_` key reads
+your own app's funnel and files learning reports. The operator admin key reaches the
+cross-tenant management surface. A **client console token** (minted from a Wire console
+session) drives your own apps over the `/v1/me/*` console routes, which means a customer
+runs the full management surface from an agent *without* holding the platform admin key.
 
-| Tool | Auth key | Does |
-|---|---|---|
-| `wireai_get_integration_guide` | none | the current integration recipe |
-| `wireai_list_components` | none | the card vocabulary |
-| `wireai_get_insights` | tenant `WIREAI_API_KEY` | **read** the funnel brief (`/v1/insights.md`), app resolved from the key; a valid "no data yet" brief when empty |
-| `wireai_get_onboarding_config` | admin `WIREAI_ADMIN_KEY` | **read** the live generation config (context, first question, allowed components) |
-| `wireai_register_onboarding_app` | admin `WIREAI_ADMIN_KEY` | create an app + get its key |
-| `wireai_list_onboarding_apps` | admin `WIREAI_ADMIN_KEY` | list apps |
-| `wireai_get_onboarding_app` | admin `WIREAI_ADMIN_KEY` | one app's raw record |
-| `wireai_update_onboarding_app` | admin `WIREAI_ADMIN_KEY` | patch config, no release |
-| `wireai_get_onboarding_analytics` | admin `WIREAI_ADMIN_KEY` | funnel JSON |
-| `wireai_list_reviews` | admin `WIREAI_ADMIN_KEY` | **read** in-app reviews across tenants (stars, feedback, contact) |
-
-Least privilege: for the read-only loop, hand the agent just `WIREAI_SERVER_URL` +
-`WIREAI_API_KEY` (tenant) and skip the admin key. Full detail: [`mcp/README.md`](./mcp/README.md).
+**Where the tool list lives.** Ask the server: a connected client's `tools/list` is the
+only copy that is current by construction, and it is already scoped to the credential you
+presented. `wireai_get_integration_guide` needs no auth at all and returns the recipe.
+Inside the repo the written table is `mcp/README.md`, and `mcp/src/toolAccess.test.ts`
+re-derives it from the handlers and goes red when the two disagree.
+
+This section deliberately does not restate that table. It used to, and the copy drifted to
+10 tools of 21 with a "the only writes are register/update" line the code had stopped
+honouring, because nothing gated it. A duplicated list with no test on it goes stale.
+
+Least privilege still applies: for the read-only improve loop, hand the agent a tenant
+credential and skip the admin key entirely.
 
 ### `wire-ai` skill (`.claude/skills/wire-ai`)
 

package/dist/analytics/index.d.mts

@@ -1,6 +1,6 @@
 export { R as ReportAppEventOptions, r as reportAppEvent } from '../transport-j5gFfJhK.mjs';
-import { C as ClientEventTarget, W as WireUserContext, E as EventQueueOptions } from '../currentSession-Cs3lweFZ.mjs';
-export { A as AUTO_DEVICE_ID_PREFIX, a as AnalyticsEvent, b as ClearUserContextOptions, c as ClientEvent, d as ClientEventType, e as ContextEnvelope, f as ContextEnvelopeInput, D as DeviceKeyStorage, g as EnvelopeSource, h as EventQueue, R as ResolveAutoDeviceKeyOptions, i as WIRE_ONBOARDING_EVENTS, j as WireOnboardingEventName, k as analyticsUserIdStorageKey, l as buildContextEnvelope, m as clearPiiFromContext, n as clearUserContext, o as createEventQueue, p as deviceIdStorageKey, q as ensureCurrentSessionId, r as getCurrentSessionId, s as looksLikeEmail, t as makeSessionId, u as reportClientEvent, v as reportClientEventAwait, w as reportClientEvents, x as reportClientEventsAwait, y as resetAutoDeviceKeys, z as resetCurrentSessionId, B as resetEventQueueKeys, F as resolveAutoDeviceKey, G as setCurrentSessionId, H as toAnalyticsEvent } from '../currentSession-Cs3lweFZ.mjs';
+import { C as ClientEventTarget, W as WireUserContext, E as EventQueueOptions } from '../currentSession-CUvTOchb.mjs';
+export { A as AUTO_DEVICE_ID_PREFIX, a as AnalyticsEvent, b as ClearUserContextOptions, c as ClientEvent, d as ClientEventType, e as ContextEnvelope, f as ContextEnvelopeInput, D as DeviceKeyStorage, g as EnvelopeSource, h as EventQueue, R as ResolveAutoDeviceKeyOptions, i as WIRE_ONBOARDING_EVENTS, j as WireOnboardingEventName, k as analyticsUserIdStorageKey, l as buildContextEnvelope, m as clearPiiFromContext, n as clearUserContext, o as createEventQueue, p as deviceIdStorageKey, q as ensureCurrentSessionId, r as getCurrentSessionId, s as looksLikeEmail, t as makeSessionId, u as reportClientEvent, v as reportClientEventAwait, w as reportClientEvents, x as reportClientEventsAwait, y as resetAutoDeviceKeys, z as resetCurrentSessionId, B as resetEventQueueKeys, F as resolveAutoDeviceKey, G as setCurrentSessionId, H as toAnalyticsEvent } from '../currentSession-CUvTOchb.mjs';
 import { W as WireOnboardingStorage } from '../types-BpwiRpA8.mjs';
 import '../types-Cju-1_jT.mjs';
 import '../types-BKfpdZzX.mjs';
@@ -268,6 +268,13 @@ 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;
 };
 /**
  * Create a bound analytics instance. Seeds one correlation `sessionId`, builds an offline-first

package/dist/analytics/index.d.ts

@@ -1,6 +1,6 @@
 export { R as ReportAppEventOptions, r as reportAppEvent } from '../transport-B_0SgCBe.js';
-import { C as ClientEventTarget, W as WireUserContext, E as EventQueueOptions } from '../currentSession-DD6dKB0i.js';
-export { A as AUTO_DEVICE_ID_PREFIX, a as AnalyticsEvent, b as ClearUserContextOptions, c as ClientEvent, d as ClientEventType, e as ContextEnvelope, f as ContextEnvelopeInput, D as DeviceKeyStorage, g as EnvelopeSource, h as EventQueue, R as ResolveAutoDeviceKeyOptions, i as WIRE_ONBOARDING_EVENTS, j as WireOnboardingEventName, k as analyticsUserIdStorageKey, l as buildContextEnvelope, m as clearPiiFromContext, n as clearUserContext, o as createEventQueue, p as deviceIdStorageKey, q as ensureCurrentSessionId, r as getCurrentSessionId, s as looksLikeEmail, t as makeSessionId, u as reportClientEvent, v as reportClientEventAwait, w as reportClientEvents, x as reportClientEventsAwait, y as resetAutoDeviceKeys, z as resetCurrentSessionId, B as resetEventQueueKeys, F as resolveAutoDeviceKey, G as setCurrentSessionId, H as toAnalyticsEvent } from '../currentSession-DD6dKB0i.js';
+import { C as ClientEventTarget, W as WireUserContext, E as EventQueueOptions } from '../currentSession-CW_5Mq4O.js';
+export { A as AUTO_DEVICE_ID_PREFIX, a as AnalyticsEvent, b as ClearUserContextOptions, c as ClientEvent, d as ClientEventType, e as ContextEnvelope, f as ContextEnvelopeInput, D as DeviceKeyStorage, g as EnvelopeSource, h as EventQueue, R as ResolveAutoDeviceKeyOptions, i as WIRE_ONBOARDING_EVENTS, j as WireOnboardingEventName, k as analyticsUserIdStorageKey, l as buildContextEnvelope, m as clearPiiFromContext, n as clearUserContext, o as createEventQueue, p as deviceIdStorageKey, q as ensureCurrentSessionId, r as getCurrentSessionId, s as looksLikeEmail, t as makeSessionId, u as reportClientEvent, v as reportClientEventAwait, w as reportClientEvents, x as reportClientEventsAwait, y as resetAutoDeviceKeys, z as resetCurrentSessionId, B as resetEventQueueKeys, F as resolveAutoDeviceKey, G as setCurrentSessionId, H as toAnalyticsEvent } from '../currentSession-CW_5Mq4O.js';
 import { W as WireOnboardingStorage } from '../types-BpwiRpA8.js';
 import '../types-h2BZvl1t.js';
 import '../types-BKfpdZzX.js';
@@ -268,6 +268,13 @@ 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;
 };
 /**
  * Create a bound analytics instance. Seeds one correlation `sessionId`, builds an offline-first