@wireai/activation 0.14.3 → 0.16.0

package/dist/{transport-j5gFfJhK.d.mts → transport-s5QxA-ci.d.mts}

@@ -1,4 +1,4 @@
-import { k as ReviewTarget, S as SubmitResult, g as ReviewDecisionResponse, j as ReviewSubmission } from './types-Cju-1_jT.mjs';
+import { k as ReviewTarget, S as SubmitResult, g as ReviewDecisionResponse, j as ReviewSubmission } from './types-Byx306Kv.mjs';
 
 /**
  * What became of a review POST — the SHARED three-outcome verdict, re-exported under the name the
@@ -25,23 +25,28 @@ type ReviewSubmitResult = SubmitResult;
  *
  * It was, for exactly one unpublished release, and the boolean was the bug. `false` meant both
  * "nothing reached the server" and "the server answered non-2xx", and the one caller that reads
- * this (`ReviewGate.postOnce`) treats `false` as "still owed" and re-posts. But the server mints
- * its own row id (`create_review` / `_new_id()`) and `CreateReviewRequest` carries no id, so there
- * is NO idempotency key on the wire: a 502 returned AFTER the insert commits means the re-post
- * writes a SECOND row, double-counting `count` and corrupting `avg` — the precise corruption the
- * one-row latch exists to prevent. A response of any status proves the server was reached, and
- * that is a different question from whether it liked the row. So the two are different values.
+ * this (`ReviewGate.postOnce`) treats `false` as "still owed" and re-posts. At the time there was
+ * no idempotency key on the wire at all, so a 502 returned AFTER the insert commits meant the
+ * re-post wrote a SECOND row, double-counting `count` and corrupting `avg` — the precise corruption
+ * the one-row latch exists to prevent. A response of any status proves the server was reached, and
+ * that is a different question from whether it liked the row. So the two are different values, and
+ * they stay different: the split is what lets the caller decide, and the retry-on-`rejected`
+ * question is a recovery-budget decision the key does not answer on its own.
  *
  * ── THE RESIDUAL, STATED HONESTLY ────────────────────────────────────────────────────────────
  *
  * `unsent` is not proof the server never got the row. A connection dropped after the request was
  * written — or after the row committed — surfaces as a thrown/rejected `fetch` here, exactly like
- * an offline device. Retrying only on `unsent` is therefore SAFER, not SAFE: it removes the
- * double-post the server itself told us about, and leaves the narrow window where the answer never
- * made it back onto the wire. Closing that window needs a CLIENT-MINTED IDEMPOTENCY KEY the server
- * upserts on, which is a server change (`CreateReviewRequest` + `create_review`) and is not
- * something the kit can fake. Until it exists, prefer losing a row over inventing one: a lost
- * detractor is a gap in the data, a duplicated one is a lie in the data.
+ * an offline device. That used to make the `unsent` re-post SAFER rather than SAFE, and it is what
+ * the client-minted idempotency key now covers: `ReviewSubmission.idempotency_key` reaches
+ * `CreateReviewRequest`, and the server upserts the derived row rather than inserting a second one.
+ *
+ * IT IS A CAPABILITY, NOT A GUARANTEE, and the condition is not ours to enforce from in here. The
+ * server honours the key only when the post also carries a unit it can scope it to —
+ * `meta.device_key`, else `session_id` — and ignores it outright otherwise. `ReviewGate` fills the
+ * device key in for exactly this reason, but this function posts whatever body it is handed, so a
+ * caller that assembles its own body without a unit is back in the old world where a lost detractor
+ * is a gap in the data and a duplicated one is a lie in the data.
  */
 declare const submitReview: (target: ReviewTarget | undefined, review: ReviewSubmission) => Promise<ReviewSubmitResult>;
 /**

package/dist/{transport-B_0SgCBe.d.ts → transport-xqqSFqxs.d.ts}

@@ -1,4 +1,4 @@
-import { k as ReviewTarget, S as SubmitResult, g as ReviewDecisionResponse, j as ReviewSubmission } from './types-h2BZvl1t.js';
+import { k as ReviewTarget, S as SubmitResult, g as ReviewDecisionResponse, j as ReviewSubmission } from './types-tdATL5z0.js';
 
 /**
  * What became of a review POST — the SHARED three-outcome verdict, re-exported under the name the
@@ -25,23 +25,28 @@ type ReviewSubmitResult = SubmitResult;
  *
  * It was, for exactly one unpublished release, and the boolean was the bug. `false` meant both
  * "nothing reached the server" and "the server answered non-2xx", and the one caller that reads
- * this (`ReviewGate.postOnce`) treats `false` as "still owed" and re-posts. But the server mints
- * its own row id (`create_review` / `_new_id()`) and `CreateReviewRequest` carries no id, so there
- * is NO idempotency key on the wire: a 502 returned AFTER the insert commits means the re-post
- * writes a SECOND row, double-counting `count` and corrupting `avg` — the precise corruption the
- * one-row latch exists to prevent. A response of any status proves the server was reached, and
- * that is a different question from whether it liked the row. So the two are different values.
+ * this (`ReviewGate.postOnce`) treats `false` as "still owed" and re-posts. At the time there was
+ * no idempotency key on the wire at all, so a 502 returned AFTER the insert commits meant the
+ * re-post wrote a SECOND row, double-counting `count` and corrupting `avg` — the precise corruption
+ * the one-row latch exists to prevent. A response of any status proves the server was reached, and
+ * that is a different question from whether it liked the row. So the two are different values, and
+ * they stay different: the split is what lets the caller decide, and the retry-on-`rejected`
+ * question is a recovery-budget decision the key does not answer on its own.
  *
  * ── THE RESIDUAL, STATED HONESTLY ────────────────────────────────────────────────────────────
  *
  * `unsent` is not proof the server never got the row. A connection dropped after the request was
  * written — or after the row committed — surfaces as a thrown/rejected `fetch` here, exactly like
- * an offline device. Retrying only on `unsent` is therefore SAFER, not SAFE: it removes the
- * double-post the server itself told us about, and leaves the narrow window where the answer never
- * made it back onto the wire. Closing that window needs a CLIENT-MINTED IDEMPOTENCY KEY the server
- * upserts on, which is a server change (`CreateReviewRequest` + `create_review`) and is not
- * something the kit can fake. Until it exists, prefer losing a row over inventing one: a lost
- * detractor is a gap in the data, a duplicated one is a lie in the data.
+ * an offline device. That used to make the `unsent` re-post SAFER rather than SAFE, and it is what
+ * the client-minted idempotency key now covers: `ReviewSubmission.idempotency_key` reaches
+ * `CreateReviewRequest`, and the server upserts the derived row rather than inserting a second one.
+ *
+ * IT IS A CAPABILITY, NOT A GUARANTEE, and the condition is not ours to enforce from in here. The
+ * server honours the key only when the post also carries a unit it can scope it to —
+ * `meta.device_key`, else `session_id` — and ignores it outright otherwise. `ReviewGate` fills the
+ * device key in for exactly this reason, but this function posts whatever body it is handed, so a
+ * caller that assembles its own body without a unit is back in the old world where a lost detractor
+ * is a gap in the data and a duplicated one is a lie in the data.
  */
 declare const submitReview: (target: ReviewTarget | undefined, review: ReviewSubmission) => Promise<ReviewSubmitResult>;
 /**

package/dist/{types-Cju-1_jT.d.mts → types-Byx306Kv.d.mts}

@@ -1,5 +1,5 @@
 import { O as OnboardingTheme } from './types-BKfpdZzX.mjs';
-import { C as CoachmarkStorage } from './types-BcmagF6K.mjs';
+import { C as CoachmarkStorage } from './types-D_0B0yay.mjs';
 import { a as WireFeatures, b as WireFeaturesConfig } from './types-BpwiRpA8.mjs';
 
 /**
@@ -25,20 +25,28 @@ import { a as WireFeatures, b as WireFeaturesConfig } from './types-BpwiRpA8.mjs
  *
  * `submitReview` was a boolean for exactly one unpublished release, and the boolean WAS the bug.
  * `false` meant both "nothing reached the server" and "the server answered non-2xx", and the caller
- * treats `false` as "still owed" and re-posts. But the server mints its own row id
- * (`create_review` / `_new_id()`), and neither `CreateReviewRequest` nor the questionnaire response
- * body carries a client id, so there is NO idempotency key on the wire: a 502 returned AFTER the
- * insert commits means the re-post writes a SECOND row. A response of any status proves the server
- * was reached, and that is a different question from whether it liked the payload.
+ * treats `false` as "still owed" and re-posts. At the time neither body carried a client id, so
+ * there was NO idempotency key on the wire on either surface: a 502 returned AFTER the insert
+ * commits meant the re-post wrote a SECOND row. A response of any status proves the server was
+ * reached, and that is a different question from whether it liked the payload — which is why the
+ * three values stay, on both surfaces, whatever the wire gains.
  *
  * ── THE RESIDUAL, STATED HONESTLY ─────────────────────────────────────────────────────────────
  *
  * `unsent` is not proof the server never got it. A connection dropped after the request was written
  * — or after the row committed — surfaces as a thrown/rejected `fetch`, exactly like an offline
- * device. Retrying only on `unsent` is therefore SAFER, not SAFE. Closing that window needs a
- * CLIENT-MINTED IDEMPOTENCY KEY the server upserts on, which is a server change and not something
- * the kit can fake. Until it exists, prefer losing a row over inventing one: a lost detractor is a
- * gap in the data, a duplicated one is a lie in the data.
+ * device. Closing that window needs a client-minted idempotency key the server upserts on, and AS
+ * OF 2026-08-19 THE TWO SURFACES DIFFER — do not read this paragraph as one fact about both:
+ *
+ *   • REVIEWS — closed. `CreateReviewRequest` takes an optional `idempotency_key` and the server
+ *     upserts a derived row on it, so a `ReviewGate` re-post merges instead of duplicating. It is a
+ *     capability, not a guarantee: the server honours the key only when the post also carries a
+ *     unit to scope it to (`meta.device_key`, else `session_id`), so a caller that strips both is
+ *     back to the old behaviour.
+ *   • QUESTIONNAIRES — still open, and still exactly as this paragraph used to read for both. The
+ *     response body carries no client id and the server has no idempotency path for it at all, so
+ *     retrying only on `unsent` there is SAFER, not SAFE. Prefer losing a row over inventing one: a
+ *     lost detractor is a gap in the data, a duplicated one is a lie in the data.
  */
 type SubmitResult = "accepted" | "rejected" | "unsent";
 
@@ -119,6 +127,13 @@ interface ReviewSubmission {
     contact?: string;
     session_id?: string;
     source?: string;
+    /**
+     * OPTIONAL client-minted key for the two-phase submit: two posts carrying the same key upsert ONE
+     * row instead of creating two. The server honours it ONLY when the post also carries a resolvable
+     * user — `meta.device_key`, else `session_id` — and silently ignores it otherwise, so it always
+     * travels with one of those. One key per gate impression, stable across that impression's posts.
+     */
+    idempotency_key?: string;
     meta?: Record<string, unknown>;
 }
 /**

package/dist/{types-BcmagF6K.d.mts → types-D_0B0yay.d.mts}

@@ -18,8 +18,13 @@ interface TargetRect {
 }
 /**
  * The host-injected gate storage. SYNCHRONOUS on purpose — a coachmark's
- * "seen?" gate must resolve during render with no async flash (otherwise a ring
- * momentarily paints before the read resolves and says "already seen"). MMKV's
+ * "seen?" gate must resolve during render. This is ENFORCED, fail closed: a
+ * probe on first read catches an adapter whose `getItem` returns a thenable
+ * (AsyncStorage handed straight in) and substitutes a closed adapter — every
+ * gate reads "seen", nothing shows, nothing fires, one dev warning names the
+ * fix (see `validateGateStorage` in ./runtime). A raw async adapter would
+ * otherwise report every gate unseen forever: tours replay each open, and a
+ * review gate with `minSessions` 0/1 re-fires each open. MMKV's
  * `getString`/`set` fit as-is; an in-memory `Map` wrapper works for tests. This
  * is deliberately separate from the async `WireOnboardingStorage` used for
  * session persistence.

package/dist/{types-BcmagF6K.d.ts → types-D_0B0yay.d.ts}

@@ -18,8 +18,13 @@ interface TargetRect {
 }
 /**
  * The host-injected gate storage. SYNCHRONOUS on purpose — a coachmark's
- * "seen?" gate must resolve during render with no async flash (otherwise a ring
- * momentarily paints before the read resolves and says "already seen"). MMKV's
+ * "seen?" gate must resolve during render. This is ENFORCED, fail closed: a
+ * probe on first read catches an adapter whose `getItem` returns a thenable
+ * (AsyncStorage handed straight in) and substitutes a closed adapter — every
+ * gate reads "seen", nothing shows, nothing fires, one dev warning names the
+ * fix (see `validateGateStorage` in ./runtime). A raw async adapter would
+ * otherwise report every gate unseen forever: tours replay each open, and a
+ * review gate with `minSessions` 0/1 re-fires each open. MMKV's
  * `getString`/`set` fit as-is; an in-memory `Map` wrapper works for tests. This
  * is deliberately separate from the async `WireOnboardingStorage` used for
  * session persistence.

package/dist/{types-h2BZvl1t.d.ts → types-tdATL5z0.d.ts}

@@ -1,5 +1,5 @@
 import { O as OnboardingTheme } from './types-BKfpdZzX.js';
-import { C as CoachmarkStorage } from './types-BcmagF6K.js';
+import { C as CoachmarkStorage } from './types-D_0B0yay.js';
 import { a as WireFeatures, b as WireFeaturesConfig } from './types-BpwiRpA8.js';
 
 /**
@@ -25,20 +25,28 @@ import { a as WireFeatures, b as WireFeaturesConfig } from './types-BpwiRpA8.js'
  *
  * `submitReview` was a boolean for exactly one unpublished release, and the boolean WAS the bug.
  * `false` meant both "nothing reached the server" and "the server answered non-2xx", and the caller
- * treats `false` as "still owed" and re-posts. But the server mints its own row id
- * (`create_review` / `_new_id()`), and neither `CreateReviewRequest` nor the questionnaire response
- * body carries a client id, so there is NO idempotency key on the wire: a 502 returned AFTER the
- * insert commits means the re-post writes a SECOND row. A response of any status proves the server
- * was reached, and that is a different question from whether it liked the payload.
+ * treats `false` as "still owed" and re-posts. At the time neither body carried a client id, so
+ * there was NO idempotency key on the wire on either surface: a 502 returned AFTER the insert
+ * commits meant the re-post wrote a SECOND row. A response of any status proves the server was
+ * reached, and that is a different question from whether it liked the payload — which is why the
+ * three values stay, on both surfaces, whatever the wire gains.
  *
  * ── THE RESIDUAL, STATED HONESTLY ─────────────────────────────────────────────────────────────
  *
  * `unsent` is not proof the server never got it. A connection dropped after the request was written
  * — or after the row committed — surfaces as a thrown/rejected `fetch`, exactly like an offline
- * device. Retrying only on `unsent` is therefore SAFER, not SAFE. Closing that window needs a
- * CLIENT-MINTED IDEMPOTENCY KEY the server upserts on, which is a server change and not something
- * the kit can fake. Until it exists, prefer losing a row over inventing one: a lost detractor is a
- * gap in the data, a duplicated one is a lie in the data.
+ * device. Closing that window needs a client-minted idempotency key the server upserts on, and AS
+ * OF 2026-08-19 THE TWO SURFACES DIFFER — do not read this paragraph as one fact about both:
+ *
+ *   • REVIEWS — closed. `CreateReviewRequest` takes an optional `idempotency_key` and the server
+ *     upserts a derived row on it, so a `ReviewGate` re-post merges instead of duplicating. It is a
+ *     capability, not a guarantee: the server honours the key only when the post also carries a
+ *     unit to scope it to (`meta.device_key`, else `session_id`), so a caller that strips both is
+ *     back to the old behaviour.
+ *   • QUESTIONNAIRES — still open, and still exactly as this paragraph used to read for both. The
+ *     response body carries no client id and the server has no idempotency path for it at all, so
+ *     retrying only on `unsent` there is SAFER, not SAFE. Prefer losing a row over inventing one: a
+ *     lost detractor is a gap in the data, a duplicated one is a lie in the data.
  */
 type SubmitResult = "accepted" | "rejected" | "unsent";
 
@@ -119,6 +127,13 @@ interface ReviewSubmission {
     contact?: string;
     session_id?: string;
     source?: string;
+    /**
+     * OPTIONAL client-minted key for the two-phase submit: two posts carrying the same key upsert ONE
+     * row instead of creating two. The server honours it ONLY when the post also carries a resolvable
+     * user — `meta.device_key`, else `session_id` — and silently ignores it otherwise, so it always
+     * travels with one of those. One key per gate impression, stable across that impression's posts.
+     */
+    idempotency_key?: string;
     meta?: Record<string, unknown>;
 }
 /**

package/llms.txt

@@ -8,19 +8,19 @@
 
 ## What an agent needs to know
 
-- **Install:** `npm install @wireai/activation wireai-rn` (react + react-native are peers).
+- **Install:** `npm install @wireai/activation wireai-rn zod react-native-safe-area-context` (react + react-native are peers).
 - **Metro (required):** `module.exports = withWireOnboarding(getDefaultConfig(__dirname))` from `@wireai/activation/metro`, which pins one copy of react/react-native/wireai-rn/zod (prevents the dual-React crash).
-- **Two secrets:** an app `apiKey` (a `wai_…` key that resolves the tenant server-side) and the backend `serverUrl`. Created in the getwireai console or via the backend's `register_<app>.py`. Nothing renders without both.
-- **Render:** drop `<WireOnboarding config={wireConfigFromEnv({ appId })} theme={...} onComplete={persist} fallbackFlow={<YourStaticOnboarding/>} />` into the signup flow.
+- **Two secrets:** an app `apiKey` (a `wai_…` key that resolves the tenant server-side) and the backend `serverUrl`. Both come from the console: sign up at https://getwireai.com/signup (app name + email; the confirmation link is where you choose a password, and that one step creates your first app and its key and lands you in the console already signed in), then read both off that app's Integrate tab at `https://getwireai.com/console/<app-id>/integrate`, where the key is a copy field and the server URL is the `serverUrl` line of the init snippet. The key stays readable there on every visit. Sign back in later at https://getwireai.com/login; register further apps at https://getwireai.com/console/register. Keys are per environment (dev / prod / staging). Nothing renders without both.
+- **Render:** build the config once and gate on it (`wireConfigFromEnv` returns `null` when the env is unset, and `config` is a required non-null prop), then drop `<WireOnboarding config={config} theme={...} onComplete={persist} fallbackFlow={<YourStaticOnboarding/>} ... />` into the signup flow.
 - **The join key.** Pass `userContext={activationJoinContext(deviceKey)}` on `<WireOnboarding>`, or, when the app owns no device id, pass a working `storage` and leave `userContext` alone so the kit injects its own (⛔ never hand-build it from the synchronous `resolveAutoDeviceKey`, which cannot report whether the id survives the launch). `user_context.device_key` is the ONLY thing that joins an onboarding session to the app's later events; omit it and the `activated` funnel reads zero with no error.
-- **Lifecycle (mount it once):** `useLifecycleEvents(config, { deviceKey?, sessionCount?, userId? })` at the app root, before anything else touches analytics. It is the only path that emits `app.first_open`, it registers the per-open session id `createAnalytics` / `wire.track` / the gates all correlate to, and with `config.storage` it stamps the persisted auto `device_key` on `app.session_started`, which is what the server counts `min_sessions` from. Storage that throws or rejects counts as no storage since 0.14.0: the events fire with no auto key rather than a per-launch one. `useSessionStart` / `reportSessionStart` are the alternatives for a host that already owns an open counter; neither emits `first_open`, and `useSessionStart` follows the same auto-key rule since 0.14.0.
+- **Lifecycle (mount it once):** `useLifecycleEvents({ serverUrl, apiKey, appId, storage }, { deviceKey, sessionCount, userId })` at the app root, before anything else touches analytics. The first argument is a `LifecycleConfig` built from explicit fields, NOT the `WireOnboardingConfig` (`wireConfigFromEnv` can return `null`, and `storage` is not a config field). It is the only path that emits `app.first_open`, it registers the per-open session id `createAnalytics` / `wire.track` / the gates all correlate to, and with a `storage` adapter in that first argument it stamps the persisted auto `device_key` on `app.session_started`, which is what the server counts `min_sessions` from. Storage that throws or rejects counts as no storage since 0.14.0: the events fire with no auto key rather than a per-launch one. `sessionCount` in the second argument is the HOST's obligation: a counter the app persists and increments once per open, starting at 1. A hardcoded `1` compiles and pins every user at `returning: false` forever with no error anywhere. `useSessionStart` / `reportSessionStart` are the alternatives for a host that already owns an open counter; neither emits `first_open`, and `useSessionStart` follows the same auto-key rule since 0.14.0.
 - **Capture is deterministic.** `onComplete` returns an `OnboardingResult`: `answers` and `raw` always, plus (since 0.13.6) `plan` when the backend sent an onboarding plan and `variant` when the tenant runs an experiment and the backend assigned an arm. No second LLM call. Persist all answers through the app's normal profile-update path. Those two extra keys are set ONLY when the backend actually sent them, so a run without them returns exactly the object earlier versions returned, and the kit interprets neither: validate `plan` before applying it.
 - **It can never break onboarding.** Pass `fallbackFlow` (your existing static onboarding) so a backend error/timeout degrades instead of dead-ending.
 
 ## Helpers (the reusable substrate)
 
 - `wireConfigFromEnv({ appId, metadata? })` → config or null (reads `EXPO_PUBLIC_WIREAI_API_KEY`/`_SERVER_URL`/`_APP_ID`).
-- `isOnboardingEnabled({ remote? })` → the standard gate (transport present: apiKey + serverUrl). No on/off env flag; `remote` is an optional kill-switch the app passes in.
+- `isOnboardingEnabled({ remote?, config? })` → the standard gate (transport present: apiKey + serverUrl). No on/off env flag; `remote` is an optional kill-switch the app passes in, and `config` forwards `WireConfigOverrides` (a programmatic apiKey/serverUrl) to the transport-present check.
 - `WIRE_ONBOARDING_EVENTS` + `toAnalyticsEvent(event)` → canonical `wire_onboarding_*` funnel names; log via the app's own analytics.
 - `attributionMetadata(a)` → shape install/ad attribution into `config.metadata` (forwarded to the agent).
 - `reportClientEvent(target, event)` / `reportClientEvents` / `makeSessionId` (ROOT-exported, not a subpath) → report device-only funnel events. Contract: `POST {serverUrl}/v1/events`, header `Authorization: Bearer {apiKey}`, body `{ "events": [ ... ] }`; `target = { serverUrl, apiKey }` from the config. `<WireOnboarding>` does this automatically: `dropped` on unmount-without-complete, `client_fallback` on degrade-to-static. Hosts must not double-report fallback.
@@ -30,10 +30,10 @@
 
 The package is more than `<WireOnboarding>`. Tree-shakeable subpath exports (each keeps the onboarding UI out of an analytics-only bundle):
 
-- `@wireai/activation/analytics`: `createAnalytics({ serverUrl, apiKey, storage })` (Segment/PostHog-shaped `track` / `screen` / `identify` / `setUserContext` / `reset` over an offline-first queue), `createScreenTracker` / `screenTrackingHandler` (auto screen views), `reportAppEvent`, `createEventQueue`, `clearUserContext` (logout). Rich `WireUserContext` supports an opt-in `userEmail` (raw by default, `hashEmail` to fold) and auto-mints a persisted per-install `device_key`. `identify` refuses email-shaped ids unless `allowEmailAsUserId`. See the README "Rich user context & PII" section. Also `wireDoctor({ target, storage })`, the DEV-ONLY self-check: four `{name, ok, detail}` checks (target shape, server reachability, storage writability, and a `dry_run` round trip whose verdict is `written === 1 && skipped === 0` read from the ack body, because `/v1/events` answers 200 for a batch it discards). It never throws, never prints any part of the apiKey, and does nothing at all when `__DEV__` is unset.
-- `@wireai/activation/reviews`: the in-app review gate. `useReviewGate`, `fetchReviewDecision` (server AI seam; a `{fire:false}` survives intact), `ReviewGate` UI. `minSessions` defaults to 2 (never prompts on the first session; a server decision still overrides).
+- `@wireai/activation/analytics`: `createAnalytics({ serverUrl, apiKey, storage })` (Segment/PostHog-shaped `track` / `screen` / `identify` / `setUserContext` / `reset` over an offline-first queue), `createScreenTracker` / `screenTrackingHandler` (auto screen views), `reportAppEvent`, `createEventQueue`, `clearUserContext` (logout). Rich `WireUserContext` supports an opt-in `userEmail` (raw by default, `hashEmail` to fold) and auto-mints a persisted per-install `device_key`. `identify` refuses email-shaped ids unless `allowEmailAsUserId`. See the README "Rich user context & PII" section. Also `wireDoctor({ target, storage, join })`, the DEV-ONLY self-check: five `{name, ok, detail}` checks (target shape, server reachability, storage writability, a `dry_run` round trip whose verdict is `written === 1 && skipped === 0` read from the ack body because `/v1/events` answers 200 for a batch it discards, and `join_key`). It never throws, never prints any part of the apiKey or the device key, and does nothing at all when `__DEV__` is unset. `join_key` answers whether the session will carry a `user_context.device_key` (host-supplied or the kit's auto-injected one), and it needs the `join: { appId, userContext, autoJoinKey }` argument; omitting `join` FAILS that check rather than skipping it. It is strictly read-only: no mint, no identity-registry write, nothing persisted. Read the scope of a green report: it now says events reach the server AND can be joined. `wireDoctor` still does not check that the lifecycle hook is mounted and does not check `min_sessions`, so an integration missing either reports all-green while its `activated` funnel stays permanently at zero.
+- `@wireai/activation/reviews`: the in-app review gate. `useReviewGate`, `fetchReviewDecision` (server AI seam; a `{fire:false}` survives intact), `ReviewGate` UI. `minSessions` defaults to 2 (never prompts on the first session; a server decision still overrides). THE GATE NEEDS SYNCHRONOUS STORAGE: pass `storage` to the hook, or mount `CoachmarkProvider` with one, as a `CoachmarkStorage` whose `getItem(key)` returns `string | null` and not a Promise. That is a DIFFERENT shape from `<WireOnboarding storage>`, which takes the AsyncStorage-style adapter. Without it the app-open counter is pinned at 1 forever, the fail-closed `minSessions` rule can never be met, and the gate silently never fires; an async adapter is detected and substituted with a fail-closed store, same outcome. The hook's `config` is the GATE's config (it needs an `id`), not the transport config, and `decision` takes `served ?? undefined` because the fetch resolves `ReviewDecisionResponse | null`. `<ReviewGate>` has no `gate` prop: render it on `gate.visible` and pass `onShown={gate.markShown}` + `onResolved={gate.markResolved}`, which are what persist the cooldown and the once-per-version seen gate. Omit them and it compiles, shows, and re-prompts forever. Full wiring: the "Wiring `<ReviewGate>`" block in AGENTS.md.
 - `@wireai/activation/questionnaire`: the pre-onboarding questionnaire gate. `useQuestionnaireGate`, `fetchQuestionnaireDecision` (same server seam; a body without a boolean `fire` resolves to null, never shows).
-- `createRevenueCatBridge({ analytics, entitlementId })` (ROOT-exported) → the RevenueCat purchase funnel: `paywallShown` / `checkoutStarted` / `purchaseCompleted` / `purchaseFailed` / `purchasesRestored` / `syncPlanTier`, emitting the canonical `wire_paywall_shown` / `wire_checkout_started` / `wire_purchase_completed` / `wire_purchase_failed` / `wire_purchase_restored` names. The kit does NOT depend on `react-native-purchases` (a native module); the RevenueCat objects are typed structurally, so a host passes the real ones. THE JOIN KEY between a purchase and an onboarding is `user_context.device_key`, never `session_id` (an onboarding session id is the A2A contextId, an app-event session id is the per-open id, and they are separate spaces): pass the same device key to `createAnalytics`/`createWireActivation` AND to `<WireOnboarding userContext={activationJoinContext(deviceKey)} />`.
+- `createRevenueCatBridge({ analytics, entitlementId })` (ROOT-exported) → the RevenueCat purchase funnel: `paywallShown` / `checkoutStarted` / `purchaseCompleted` / `purchaseFailed` / `purchasesRestored` / `syncPlanTier`, emitting the canonical `wire_paywall_shown` / `wire_checkout_started` / `wire_purchase_completed` / `wire_purchase_failed` / `wire_purchase_restored` names. The kit does NOT depend on `react-native-purchases` (a native module); the RevenueCat objects are typed structurally, so a host passes the real ones. THE JOIN KEY between a purchase and an onboarding is `user_context.device_key`, never `session_id` (an onboarding session id is the A2A contextId, an app-event session id is the per-open id, and they are separate spaces): pass the same device key to `createAnalytics`/`createWireActivation` AND to `<WireOnboarding userContext={activationJoinContext(deviceKey)} ... />`.
 - `useWireActivation({ serverUrl, apiKey, deviceKey? })` → `{ track, sessionId, revalidation }` (ROOT-exported; React-free factory `createWireActivation(config)`). `await track(name, meta?)` POSTs an `app_event` (`question_key=name`) under the current session, resolves `true` on 2xx, and bumps `revalidation`; list `revalidation` in a `fetchReviewDecision` / `fetchQuestionnaireDecision` effect's deps so a review/questionnaire gate re-fetches and fires off an in-app action instead of the host hand-rolling session-id + await-POST + revalidate.
 
 ## Files
@@ -45,4 +45,4 @@ The package is more than `<WireOnboarding>`. Tree-shakeable subpath exports (eac
 
 ## Fastest path
 
-Run the `wire-rn-integration` Claude skill. It detects the app's conventions, wires Metro, derives a theme, scaffolds the screen, wires a fallback, and type-checks. Otherwise use INTEGRATION_PROMPT.md.
+Paste [INTEGRATION_PROMPT.md](./INTEGRATION_PROMPT.md) into a coding agent. It ships in this package and drives the whole integration: detect the app's conventions, wire Metro, derive a theme, scaffold the screen, wire a fallback, and type-check.

package/package.json

@@ -1,17 +1,14 @@
 {
   "name": "@wireai/activation",
-  "version": "0.14.3",
+  "version": "0.16.0",
   "private": false,
   "description": "Premium, fully-themable drop-in AI onboarding kit for React Native / Expo, on top of the open-source wireai-rn SDK.",
   "author": "Malik Chohra <malik@getwireai.com>",
   "license": "MIT",
-  "homepage": "https://github.com/chohra-med/wireai-onboarding#readme",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/chohra-med/wireai-onboarding.git"
-  },
+  "homepage": "https://getwireai.com",
   "bugs": {
-    "url": "https://github.com/chohra-med/wireai-onboarding/issues"
+    "url": "https://getwireai.com/console/support",
+    "email": "malik@getwireai.com"
   },
   "keywords": [
     "react-native",
@@ -137,12 +134,12 @@
   "scripts": {
     "build": "tsup",
     "prepack": "npm run build",
-    "prepublishOnly": "npm run build && npm run test:canary",
+    "prepublishOnly": "npm run build && npm test",
     "typecheck": "tsc --noEmit",
     "pretest": "npm run build",
     "test": "node --test --experimental-strip-types --import ./test/register-ts-resolver.mjs \"src/**/*.test.ts\" \"test/canary/**/*.test.tsx\"",
     "test:canary": "node --test --experimental-strip-types --import ./test/register-ts-resolver.mjs \"test/canary/**/*.test.tsx\"",
-    "check:contract": "node --no-warnings --experimental-strip-types scripts/check-events-contract.mjs",
+    "check:contract": "node --no-warnings --experimental-strip-types --import ./test/register-ts-resolver.mjs scripts/check-events-contract.mjs",
     "pack:tarball": "npm pack"
   },
   "peerDependencies": {

package/src/WireOnboarding.tsx

@@ -135,7 +135,10 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
   // per-install `device_key` the analytics surfaces auto-mint and persist — so the default wiring
   // produces a joined funnel instead of a silent zero. Three conditions, all necessary:
   //
-  //   • `missingJoinKey` — a host-supplied key ALWAYS wins, verbatim, and is never touched.
+  //   • `missingJoinKey` — a host-supplied key ALWAYS wins, verbatim, and is never touched. What
+  //     COUNTS as supplied is `resolveIdentity`'s predicate above: a string with at least one
+  //     non-whitespace character. A non-string or an all-whitespace `device_key` yields no record,
+  //     so it reads as absent here and the auto key is merged over it.
   //   • `autoJoinKey !== false` — the documented opt-out for a host that genuinely wants an
   //     unlinked onboarding session; opting out restores the pre-0.12.2 behavior exactly.
   //   • `storage` that actually WORKS — without persistence the auto id is process-scoped, so every

package/src/analytics/currentSession.ts

@@ -77,13 +77,93 @@ type GlobalWithSlot = typeof globalThis & {
 
 const globalSlot = globalThis as GlobalWithSlot;
 
+/**
+ * Subscribers to be told when the id above CHANGES.
+ *
+ * ── WHY A REGISTRY THAT ONLY EMITS IS NOT ENOUGH ─────────────────────────────────────────────────
+ * The gates' app-open counter is bumped from a `useState` INITIALIZER, i.e. exactly once per
+ * component instance. `bumpSessionCount` itself follows real app-opens correctly, but nothing ever
+ * calls it a second time on a screen that stays mounted — and iOS suspends rather than kills, so a
+ * home screen holding `useReviewGate` outlives many opens. `useLifecycleEvents` registers each one
+ * here and the SERVER's `min_sessions` advances, while `wire_review_<id>_sessions` sits at its launch
+ * value and the LOCAL `minSessions` rule is unsatisfiable for the life of the process. Silent, and
+ * fails toward a prompt that never shows.
+ *
+ * The fix is not a second counter: it is that this module — the one place that knows an open was
+ * registered — says so. The gates subscribe (through `useSyncExternalStore`) and re-ask
+ * `bumpSessionCount`, which was already idempotent per open, so a notification that names the SAME
+ * open changes nothing.
+ *
+ * EVERY write to the id slot notifies, including `ensureCurrentSessionId`'s mint and the test-only
+ * reset: `getCurrentSessionId` is the `useSyncExternalStore` snapshot, and a snapshot that can change
+ * without a notification is a torn read, not an optimisation.
+ *
+ * @globalSlot LATCH — the listener SET is created once and its identity is then stable, for the same
+ * reason `activation/revalidation`'s store is: a second write replaces the set every existing
+ * subscriber registered in, so their unsubscribes free the wrong set and a registration reaches
+ * nobody — silently, which is the whole failure class this seam exists to close. Its CONTENTS are
+ * live and mutated in place, which is why every accessor goes through `listeners()`.
+ */
+const SESSION_ID_LISTENERS_SLOT: unique symbol = Symbol.for(
+  "@wireai/activation:currentSessionIdListeners",
+);
+
+type GlobalWithListeners = typeof globalThis & {
+  [SESSION_ID_LISTENERS_SLOT]?: Set<() => void>;
+};
+
+const listenerSlot = globalThis as GlobalWithListeners;
+
+/** The ONE shared listener set, lazily created on the runtime global (never a second copy per bundle). */
+const listeners = (): Set<() => void> => {
+  const existing = listenerSlot[SESSION_ID_LISTENERS_SLOT];
+  if (existing) return existing;
+  const created = new Set<() => void>();
+  listenerSlot[SESSION_ID_LISTENERS_SLOT] = created;
+  return created;
+};
+
+/**
+ * Write the slot and, only on a REAL change, tell every subscriber. The single writer for all three
+ * public entry points, so "the snapshot moved" and "the subscribers were told" can never drift.
+ */
+const writeCurrentSessionId = (id: string | undefined): void => {
+  if (globalSlot[CURRENT_SESSION_ID_SLOT] === id) return;
+  globalSlot[CURRENT_SESSION_ID_SLOT] = id;
+  // Iterate a snapshot so a listener that (un)subscribes during notify never corrupts the walk, and
+  // isolate each one: a throwing subscriber must not stop the others (fail-safe).
+  for (const listener of Array.from(listeners())) {
+    try {
+      listener();
+    } catch {
+      /* a subscriber's failure is not this registry's business */
+    }
+  }
+};
+
+/**
+ * Subscribe to app-open registrations. Returns an unsubscribe fn. Shaped for `useSyncExternalStore`
+ * over {@link getCurrentSessionId} — that pairing is what makes a mounted gate follow real opens
+ * instead of the one it sampled at mount.
+ *
+ * Internal seam — deliberately NOT on the public barrels (same as {@link isMintedSessionId}); the
+ * callers are `useReviewGate` / `useQuestionnaireGate`.
+ */
+export const subscribeCurrentSessionId = (listener: () => void): (() => void) => {
+  const set = listeners();
+  set.add(listener);
+  return () => {
+    set.delete(listener);
+  };
+};
+
 /**
  * Record the current per-open `session_id`. Called by `reportSessionStart` when it emits an
  * app-open. A blank / non-string id is ignored (the previous id stays current). Idempotent.
  */
 export const setCurrentSessionId = (id: string | undefined): void => {
   if (typeof id === "string" && id.length > 0) {
-    globalSlot[CURRENT_SESSION_ID_SLOT] = id;
+    writeCurrentSessionId(id);
   }
 };
 
@@ -91,9 +171,17 @@ export const setCurrentSessionId = (id: string | undefined): void => {
 export const getCurrentSessionId = (): string | undefined =>
   globalSlot[CURRENT_SESSION_ID_SLOT];
 
-/** Test-only: forget the current session id so a unit test starts from a clean registry. */
+/** Test-only: forget the current session id so a unit test starts from a clean registry. Does NOT
+ *  clear the MINTED-id record (see `isMintedSessionId`), for the same reason the warn latch below is
+ *  not cleared: `makeSessionId()` never repeats, so a remembered fallback id can never again equal a
+ *  live one, and the record is overwritten by the next mint anyway. */
 export const resetCurrentSessionId = (): void => {
-  globalSlot[CURRENT_SESSION_ID_SLOT] = undefined;
+  writeCurrentSessionId(undefined);
+};
+
+/** Test-only: drop every subscriber so one case's mounted gate cannot be notified by the next. */
+export const resetCurrentSessionIdListeners = (): void => {
+  listeners().clear();
 };
 
 /** The one-time message. Hoisted so a prod mint does not rebuild a string nobody will read. */
@@ -120,6 +208,52 @@ type GlobalWithWarnSlot = typeof globalThis & { [MINT_WARNED_SLOT]?: boolean };
 
 const warnSlot = globalThis as GlobalWithWarnSlot;
 
+/**
+ * The id THIS PROCESS minted, so a reader can tell a fallback id from a real app-open.
+ *
+ * WHY IT HAS TO EXIST. A mint means "no app-open was registered and something still needed a
+ * `session_id`". It is a fallback for the wire, NOT evidence that the app was opened. But the mint
+ * writes the shared slot above (it must — see the header: every later event has to correlate to the
+ * same id), so a reader of `getCurrentSessionId()` cannot tell the two apart. `reviews/runtime`'s
+ * `currentOpenId` could not, and that cost an app-open: it pinned the launch with
+ * `observed = <the minted id>`, so its cold-start adopt branch (which keys off `observed ===
+ * undefined`) never fired and the REAL `app.session_started` that followed read as a genuinely NEW
+ * open. One launch counted as TWO, making the fail-closed `minSessions: 2` default — the guard from
+ * the 2026-07-16 one-star incident — satisfiable inside a user's FIRST session. It failed in the
+ * UNSAFE direction.
+ *
+ * Its OWN `Symbol.for` slot, for the same cross-bundle reason as the id itself: a plain module
+ * `let` would be per inlined bundle copy, so a mint reached through `./analytics` would be invisible
+ * to the gate reading through `.`.
+ *
+ * @globalSlot LIVE — a real process mints at most once (the mint only fires when the id slot is
+ * EMPTY), but a process that clears the id and mints again — `resetCurrentSessionId` in the suite —
+ * MOVES this, and it must move: a record still naming the previous launch's fallback would make the
+ * new one unrecognisable, and a fallback id would be counted as an app-open again. So a reader that
+ * caches this answers
+ * for a launch that is over. Read it at the moment of use, through `isMintedSessionId()`.
+ */
+const MINTED_SESSION_ID_SLOT: unique symbol = Symbol.for(
+  "@wireai/activation:mintedSessionId",
+);
+
+type GlobalWithMintedSlot = typeof globalThis & {
+  [MINTED_SESSION_ID_SLOT]?: string | undefined;
+};
+
+const mintedSlot = globalThis as GlobalWithMintedSlot;
+
+/**
+ * Was `id` MINTED by this process rather than registered as a real app-open?
+ *
+ * `false` for `undefined`, for any id a host registered through `setCurrentSessionId`, and for
+ * every id once the launch has moved on. Internal seam — deliberately NOT on the public barrels;
+ * the only caller is `reviews/runtime`'s `currentOpenId`, which must not count a fallback id as an
+ * app-open.
+ */
+export const isMintedSessionId = (id: string | undefined): boolean =>
+  id !== undefined && id === mintedSlot[MINTED_SESSION_ID_SLOT];
+
 /**
  * The current per-open `session_id`, MINTING and registering one when no app-open has been
  * registered yet. Always returns a non-empty string. Idempotent (a second call returns the same id)
@@ -141,7 +275,10 @@ export const ensureCurrentSessionId = (): string => {
   const existing = globalSlot[CURRENT_SESSION_ID_SLOT];
   if (typeof existing === "string" && existing.length > 0) return existing;
   const minted = makeSessionId();
-  globalSlot[CURRENT_SESSION_ID_SLOT] = minted;
+  writeCurrentSessionId(minted);
+  // Remember that WE minted it. A fallback id is not an app-open, and `reviews/runtime` has to be
+  // able to tell the difference or the real registration that follows counts as a second open.
+  mintedSlot[MINTED_SESSION_ID_SLOT] = minted;
   if (!warnSlot[MINT_WARNED_SLOT] && warnInDev(MINT_WARNING)) {
     warnSlot[MINT_WARNED_SLOT] = true;
   }

package/src/analytics/index.ts

@@ -44,7 +44,12 @@ export type { ClientEvent, ClientEventType, ClientEventTarget } from "./reportCl
 // `readEventsAck` is deliberately NOT re-exported here: the doctor imports it from the transport
 // module directly, so reuse costs nothing and the package's public surface stays as it was.
 export { wireDoctor } from "./wireDoctor";
-export type { WireDoctorCheck, WireDoctorReport, WireDoctorOptions } from "./wireDoctor";
+export type {
+  WireDoctorCheck,
+  WireDoctorReport,
+  WireDoctorOptions,
+  WireDoctorJoinTarget,
+} from "./wireDoctor";
 
 // ─── Canonical onboarding funnel names + kit-event mapper ──────────────────────
 export { WIRE_ONBOARDING_EVENTS, toAnalyticsEvent } from "./analyticsEvent";