@wireai/activation 0.13.6 → 0.14.1

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: 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, AI path only) 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. |
+| `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,230 @@
 All notable changes to `@wireai/activation` (formerly `wireai-onboarding`).
 Historical entries below the rename keep the old package name on purpose.
 
+## [0.14.1] - 2026-08-18
+
+Two rulings from the 0.14.0 audit, applied. Both were reproduced there and left for a decision
+rather than guessed at; both decisions came back on 2026-08-18.
+
+**PATCH: no public surface gained, lost or renamed a member.** But read the first entry before you
+upgrade — it is a behaviour change you will see in your funnel, not a silent internal fix.
+
+### Fixed
+
+- **The review/questionnaire gates counted JS PROCESSES, not app-opens, so `minSessions` stalled at
+  1 on iOS.** `useLifecycleEvents` already defines an app-open correctly — a foreground after 30+
+  minutes in the background — and fires a fresh `app.session_started` for it. The device-side
+  counter behind `minSessions` did not follow: it pinned one id for the life of the JS process, and
+  iOS suspends apps rather than killing them. So a user who opened the app every day for a week
+  produced seven server-side opens while `wire_review_<id>_sessions` stayed at 1, and any gate with
+  the fail-closed `minSessions: 2` default could never fire on a phone that is never force-quit —
+  which is most phones. **⚠️ UPGRADE NOTE: gates that have been silently dormant will start firing.**
+  That is the fix, but if you have been reading a flat prompt rate as "users decline", the number
+  will move. The counter still refuses the case it was pinned for in the first place: on a cold
+  start the gate renders (and counts) before the root lifecycle effect registers the session id, and
+  that first registration NAMES the open already counted rather than starting a second one — so the
+  2026-07-16 incident, where `minSessions: 2` became satisfiable inside a user's very first launch,
+  stays closed. One accepted under-count remains, deliberately: if the mount open never registers (a
+  refused non-durable device key over a broken store) and a later foreground is the first
+  registration the launch sees, it is adopted rather than counted. A fail-closed gate may only err
+  toward prompting less.
+
+- **A permission record that could not be READ is no longer read as "nothing settled".** A timed-out
+  or throwing storage read arrived as `[]`, which is indistinguishable from a genuine empty record,
+  and the flow acted on that guess twice: it re-showed a permission screen the user may already have
+  answered — spending the ONE native prompt iOS ever grants — and the answer then persisted a record
+  containing just that one id, OVER whatever the store actually held. A slow adapter could therefore
+  permanently shrink the memory that exists to prevent the re-ask. The read now reports whether the
+  store answered at all; on "it did not", permission screens are suppressed for that session and
+  nothing is written back. A successful read of a corrupt, absent or other-session entry is still a
+  genuine empty and still shows the screen. The trade is stated rather than hidden: on a host whose
+  adapter never answers, configured permission screens silently never show, so it warns in dev
+  naming the adapter.
+
+### Changed
+
+- **`@wireai/activation:processOpenId` is re-declared LIVE (was LATCH).** The governance canary in
+  `test/canary/globalSlotDiscipline.test.tsx` asserted that this slot must NOT follow the session
+  registry, which is what froze the counter above; it now drives the slot through two real opens and
+  requires it to move. The cold-start property it used to guard — the first registration of a launch
+  must not re-pin — is asserted in `src/reviews/sessionCount.test.ts`, alongside the incident it
+  exists for. The slot holds the pinned open id plus the registered id observed when it was pinned,
+  because "is this a new open?" is only answerable against what was last seen.
+
+Tests 808 → 814, all green, and the deferred `todo` reproduction is now a passing assertion.
+Every fix was falsified first: reverting the counter fix reddens exactly the app-open test plus the
+slot canary and leaves the cold-start test green; collapsing the unknown read back to empty reddens
+both unit tests and the end-to-end canary while its positive control stays green.
+
+## [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
@@ -19,7 +243,9 @@ entry. This entry is that debt paid, plus the `variant` half, released together
   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. The static (non-AI) flow carries no plan and is unchanged.
+  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

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: 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, AI path only) 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.** |
+| `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). |
@@ -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). |
 
@@ -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.
 
@@ -1154,6 +1162,11 @@ const gate = useReviewGate({ config: { id: "home", minSessions: 2 }, decision, s
 await track("journal_done"); // POST stored → revalidation bumps → effect re-fetches → gate can fire
 ```
 
+`minSessions` counts **app-opens**, not mounts and not launches: a foreground after 30+ minutes in
+the background is a new one. That matters on iOS, where an app is suspended rather than killed — a
+user who never force-quits still advances the counter. (Before 0.14.1 it counted JS processes, so
+on those devices it stayed at 1 forever and a `minSessions: 2` gate could never fire.)
+
 The questionnaire gate uses the identical shape: swap `fetchReviewDecision` / `useReviewGate`
 for `fetchQuestionnaireDecision` / `useQuestionnaireGate` from `@wireai/activation/questionnaire`
 (both take a `decision` prop). One `wire.track` call feeds every subscribed gate.

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-DngW-QoD.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-DngW-QoD.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-C5976akx.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-C5976akx.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

package/dist/analytics/index.js

@@ -76,20 +76,21 @@ var reportClientEvents = (target, events) => {
   }
 };
 var reportClientEvent = (target, event) => reportClientEvents(target, [event]);
-var reportClientEventsAwait = async (target, events) => {
+var reportClientEventsAwait = async (target, events) => await reportClientEventsOutcome(target, events) === "delivered";
+var reportClientEventsOutcome = async (target, events) => {
   try {
     const req = buildEventsRequest(target, events);
-    if (!req) return false;
+    if (!req) return "refused";
     const res = await fetch(req.url, req.init);
-    if (!res || !res.ok) return false;
+    if (!res || !res.ok) return "unreachable";
     const ack = await readEventsAck(res);
-    if (!ack || ack.skipped <= 0) return true;
+    if (!ack || ack.skipped <= 0) return "delivered";
     if (typeof __DEV__ !== "undefined" && __DEV__ && typeof console !== "undefined" && console.warn) {
       console.warn(describeDiscarded(ack));
     }
-    return false;
+    return "refused";
   } catch {
-    return false;
+    return "unreachable";
   }
 };
 var reportClientEventAwait = (target, event) => reportClientEventsAwait(target, [event]);
@@ -692,6 +693,9 @@ var claimQueueKey = (preferred, explicit) => {
   );
   return key;
 };
+var releaseQueueKey = (key) => {
+  claimedQueueKeys().delete(key);
+};
 var resetEventQueueKeys = () => claimedQueueKeys().clear();
 var READ_TIMED_OUT = /* @__PURE__ */ Symbol("wireai:storage-read-timeout");
 var withTimeout = (p, ms) => {
@@ -737,7 +741,8 @@ var createEventQueue = (options) => {
   let flushing = false;
   let attempt = 0;
   let retryTimer;
-  let backlogUnread = false;
+  let disposed = false;
+  let backlogUnread = storage !== void 0;
   const resolveEnvelope = () => {
     try {
       return typeof options.envelope === "function" ? options.envelope() : options.envelope;
@@ -762,6 +767,7 @@ var createEventQueue = (options) => {
   };
   const persist = () => {
     if (!storage) return;
+    if (disposed) return;
     if (backlogUnread) return;
     try {
       if (pending.length === 0) {
@@ -775,8 +781,20 @@ var createEventQueue = (options) => {
     } catch {
     }
   };
+  const isCountedOpenEvent = (event) => typeof event.question_key === "string" && event.question_key.startsWith("app.");
   const enforceSizeCap = () => {
-    if (pending.length > maxSize) pending.splice(0, pending.length - maxSize);
+    let overflow = pending.length - maxSize;
+    if (overflow <= 0) return;
+    const kept = [];
+    for (const item of pending) {
+      if (overflow > 0 && !isCountedOpenEvent(item.event)) {
+        overflow--;
+        continue;
+      }
+      kept.push(item);
+    }
+    if (overflow > 0) kept.splice(0, overflow);
+    pending = kept;
   };
   const safeSig = (event) => {
     try {
@@ -822,8 +840,12 @@ var createEventQueue = (options) => {
         });
         return;
       }
+      backlogUnread = false;
       mergePersisted(parsePersisted(raced));
+      persist();
     } catch {
+      backlogUnread = false;
+      persist();
     }
   })();
   const postBatch = async (events) => {
@@ -859,10 +881,12 @@ var createEventQueue = (options) => {
     unrefTimer(retryTimer);
   };
   const drain = async () => {
+    if (disposed) return;
     try {
       await loadPromise;
     } catch {
     }
+    if (disposed) return;
     if (flushing) return;
     flushing = true;
     try {
@@ -890,6 +914,7 @@ var createEventQueue = (options) => {
     }
   };
   const enqueue = (event) => {
+    if (disposed) return;
     try {
       const stamped = stamp(event);
       const sig = safeSig(stamped);
@@ -909,7 +934,13 @@ var createEventQueue = (options) => {
     flush();
   };
   const size = () => pending.length;
-  return { enqueue, flush, notifyOnline, size };
+  const dispose = () => {
+    if (disposed) return;
+    disposed = true;
+    clearRetry();
+    if (storage) releaseQueueKey(key);
+  };
+  return { enqueue, flush, notifyOnline, size, dispose };
 };
 
 // src/identity/userIdentity.ts
@@ -1147,8 +1178,10 @@ var createAnalytics = (config, options = {}) => {
   });
   let boundUserId = sanitizeUserId((_c = config.userContext) == null ? void 0 : _c.userId);
   const storageKey = analyticsUserIdStorageKey(config.appId);
+  let hydrationSuperseded = false;
   if (config.storage) {
     void config.storage.getItem(storageKey).then((saved) => {
+      if (hydrationSuperseded) return;
       if (saved && !boundUserId) boundUserId = saved;
     }).catch(() => {
     });
@@ -1190,6 +1223,7 @@ var createAnalytics = (config, options = {}) => {
     }
   };
   const reset = () => {
+    hydrationSuperseded = true;
     boundUserId = void 0;
     userContext = clearPiiFromContext(userContext);
     if (config.storage) void config.storage.removeItem(storageKey).catch(() => {
@@ -1247,23 +1281,33 @@ var createAnalytics = (config, options = {}) => {
     reset,
     flush: queue.flush,
     notifyOnline: queue.notifyOnline,
-    size: queue.size
+    size: queue.size,
+    dispose: queue.dispose
   };
 };
 var useAnalytics = (config, options = {}) => {
-  var _a;
+  var _a, _b;
   const ref = react.useRef(void 0);
   const prevKeys = react.useRef("");
   const currentKeys = `${config.serverUrl}|${config.apiKey}|${config.appId}`;
   if (!ref.current || prevKeys.current !== currentKeys) {
     prevKeys.current = currentKeys;
+    (_a = ref.current) == null ? void 0 : _a.dispose();
     ref.current = createAnalytics(config, options);
   }
-  const hostDeviceKey = typeof ((_a = config.userContext) == null ? void 0 : _a.deviceKey) === "string" && config.userContext.deviceKey.trim() ? config.userContext.deviceKey.trim() : void 0;
+  const hostDeviceKey = typeof ((_b = config.userContext) == null ? void 0 : _b.deviceKey) === "string" && config.userContext.deviceKey.trim() ? config.userContext.deviceKey.trim() : void 0;
   react.useEffect(() => {
     var _a2;
     if (hostDeviceKey) (_a2 = ref.current) == null ? void 0 : _a2.setUserContext({ deviceKey: hostDeviceKey });
   }, [hostDeviceKey]);
+  react.useEffect(
+    () => () => {
+      var _a2;
+      (_a2 = ref.current) == null ? void 0 : _a2.dispose();
+      ref.current = void 0;
+    },
+    []
+  );
   return ref.current;
 };