@wireai/activation 0.14.3 → 0.15.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wireai/activation",
-  "version": "0.14.3",
+  "version": "0.15.0",
   "private": false,
   "description": "Premium, fully-themable drop-in AI onboarding kit for React Native / Expo, on top of the open-source wireai-rn SDK.",
   "author": "Malik Chohra <malik@getwireai.com>",

package/src/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/coachmarks/runtime.ts

@@ -27,6 +27,9 @@
  */
 import type { CoachmarkStorage } from "./types";
 
+/** RN sets this global; absent under node/SSR. Read defensively via the async-adapter warn below. */
+declare const __DEV__: boolean | undefined;
+
 /**
  * Well-known key into the runtime-global symbol registry — one coachmark runtime across bundles.
  *
@@ -166,6 +169,104 @@ export const showcaseGateKey = (showcaseId: string): string =>
 /** Marker value written for a seen gate. */
 const SEEN_VALUE = "1";
 
+/** Key used only by the one-off synchronicity probe below. Never carries a meaningful value. */
+const GATE_PROBE_KEY = "wire_gate_probe";
+
+/** Once-per-process latch on its own `Symbol.for` slot, mirroring `gateStorageWarned` next door
+ *  in reviews/runtime: a plain `let` would warn once per inlined bundle copy, and the gates live
+ *  in three of them.
+ *
+ *  @globalSlot LATCH — written `true` by the first probe that caught an ASYNC gate adapter, and
+ *  never again. A second differing write re-arms a warning the process already spent, so a host
+ *  whose broken adapter reaches three gates gets the same paragraph three times and stops reading. */
+const ASYNC_GATE_STORAGE_WARNED_SLOT: unique symbol = Symbol.for(
+  "@wireai/activation:asyncGateStorageWarned",
+);
+
+type GlobalWithAsyncGateWarn = typeof globalThis & {
+  [ASYNC_GATE_STORAGE_WARNED_SLOT]?: boolean;
+};
+
+const asyncGateWarnGlobal = globalThis as GlobalWithAsyncGateWarn;
+
+/**
+ * The substitute for an adapter whose `getItem` returned a thenable (an ASYNC adapter, e.g.
+ * AsyncStorage handed straight in). Every seen-gate reads SEEN and every write is dropped, so
+ * nothing shows and nothing fires — FAIL CLOSED, deliberately in both directions the async bug
+ * could err: a Promise is never `=== "1"`, so a raw async adapter reports every gate UNSEEN
+ * forever — tours and showcases replay on every open, and a review gate with `minSessions` 0/1
+ * RE-FIRES its prompt each open (the 2026-07-16 one-star incident class). Never-fire is the only
+ * direction a once-per-user gate may err in.
+ */
+const closedGateStorage: CoachmarkStorage = Object.freeze({
+  getItem: (): string => SEEN_VALUE,
+  setItem: (): void => {},
+});
+
+/** Adapters probed sync (or throwing, which every reader already tolerates): pass through. */
+const syncGateAdapters = new WeakSet<CoachmarkStorage>();
+/** Adapters caught returning a thenable: substituted, and never probed again. */
+const asyncGateAdapters = new WeakSet<CoachmarkStorage>();
+
+/** Warn once, in dev builds only, when a gate adapter turned out to be async. */
+const warnAsyncGateStorage = (): void => {
+  if (asyncGateWarnGlobal[ASYNC_GATE_STORAGE_WARNED_SLOT]) return;
+  if (typeof __DEV__ === "undefined" || !__DEV__) return;
+  if (typeof console === "undefined" || !console.warn) return;
+  asyncGateWarnGlobal[ASYNC_GATE_STORAGE_WARNED_SLOT] = true;
+  console.warn(
+    "[wireai] the gate storage's getItem returned a Promise — an async adapter (e.g. AsyncStorage) " +
+      "cannot drive the once-per-user gates, so coachmark tours, showcases and the review/questionnaire " +
+      "gates are all DISABLED (fail closed: nothing shows, nothing fires) until a synchronous adapter " +
+      "is provided. Pass a sync adapter (e.g. MMKV: `{ getItem: (k) => mmkv.getString(k) ?? null, " +
+      "setItem: (k, v) => mmkv.set(k, v) }`) to CoachmarkProvider or the gate's `storage` prop.",
+  );
+};
+
+/** Test-only: forget the once-per-process async-adapter warn latch. */
+export const resetAsyncGateStorageWarning = (): void => {
+  asyncGateWarnGlobal[ASYNC_GATE_STORAGE_WARNED_SLOT] = undefined;
+};
+
+/**
+ * The thenable probe (fail closed): resolve an adapter to itself when its `getItem` is
+ * synchronous, and to `closedGateStorage` when it returns a thenable. Called on every gate READ
+ * rather than at injection, so (a) a host handing storage straight to a gate's `storage` prop is
+ * probed too, and (b) `CoachmarkProvider`'s unmount cleanup — which compares the singleton to its
+ * own prop by IDENTITY — keeps seeing the object the host passed. Verdicts are WeakSet-cached, so
+ * each adapter pays for exactly one probe read.
+ */
+export const validateGateStorage = (
+  storage: CoachmarkStorage | null,
+): CoachmarkStorage | null => {
+  if (!storage) return null;
+  if (syncGateAdapters.has(storage)) return storage;
+  if (asyncGateAdapters.has(storage)) return closedGateStorage;
+  let probed: unknown;
+  try {
+    probed = storage.getItem(GATE_PROBE_KEY);
+  } catch {
+    // A throwing adapter is synchronous, which is all the probe rules on; every reader already
+    // tolerates the throw itself.
+    syncGateAdapters.add(storage);
+    return storage;
+  }
+  if (probed != null && typeof (probed as { then?: unknown }).then === "function") {
+    asyncGateAdapters.add(storage);
+    try {
+      // Detach the probe's promise so an adapter that REJECTS (e.g. a broken native store) cannot
+      // surface as an unhandled rejection the host never scheduled.
+      (probed as PromiseLike<unknown>).then(undefined, () => {});
+    } catch {
+      // A hostile thenable whose `then` throws is still async; the verdict stands.
+    }
+    warnAsyncGateStorage();
+    return closedGateStorage;
+  }
+  syncGateAdapters.add(storage);
+  return storage;
+};
+
 /**
  * Read a seen gate. Testing mode ALWAYS reports unseen (so everything replays).
  * A missing storage (no provider) also reports unseen — the safe default is to
@@ -179,7 +280,7 @@ export const hasSeenGate = (
   testingOverride?: boolean,
 ): boolean => {
   if (testingOverride ?? isCoachmarkTesting()) return false;
-  const storage = storageOverride ?? getCoachmarkStorage();
+  const storage = validateGateStorage(storageOverride ?? getCoachmarkStorage());
   if (!storage) return false;
   try {
     return storage.getItem(key) === SEEN_VALUE;
@@ -198,7 +299,7 @@ export const markSeenGate = (
   testingOverride?: boolean,
 ): void => {
   if (testingOverride ?? isCoachmarkTesting()) return;
-  const storage = storageOverride ?? getCoachmarkStorage();
+  const storage = validateGateStorage(storageOverride ?? getCoachmarkStorage());
   if (!storage) return;
   try {
     storage.setItem(key, SEEN_VALUE);

package/src/coachmarks/types.ts

@@ -31,8 +31,13 @@ export 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/src/context/deviceId.ts

@@ -291,3 +291,35 @@ export const resetAutoDeviceKeys = (): void => {
   registry.hydrating.clear();
   registry.pending?.clear();
 };
+
+/**
+ * The auto `device_key` a surface with NO `appId` and NO `storage` of its own may stamp onto a
+ * payload — the review gate being the one that exists (`ReviewGate` takes neither prop).
+ *
+ * WHY IT IS NOT JUST `resolveAutoDeviceKey()`. That function is keyed by `appId`, and `appId` is a
+ * REQUIRED field on `WireOnboardingConfig` that real hosts set to a real value. A propless caller
+ * can only pass `undefined`, which addresses the `"default"` slot — so on any host that names its
+ * app, a bare call would MINT a second id beside the one every other surface already shares. That is
+ * the halved-counter defect this registry exists to close (see the registry note above), arrived at
+ * from the other direction.
+ *
+ * So this READS and does not address:
+ *   • exactly one id space in the process → that id, whoever registered it. This is every
+ *     single-tenant app, i.e. every real app, and it is how the gate joins the analytics surfaces.
+ *   • none at all → mint one through {@link resolveAutoDeviceKey}. Nothing exists to collide with,
+ *     so `"default"` is not a second space, it is the first. PROCESS-scoped (there is no storage to
+ *     persist through), which is honest and still resolvable: a review row is written once per user,
+ *     so a per-launch value here cannot corrupt a counter the way it corrupts `min_sessions`.
+ *   • two or more → `undefined`. Two tenants in one process must never share an id, and a caller
+ *     with no `appId` cannot say which one it belongs to. Refusing is the only safe answer;
+ *     guessing would stamp one tenant's device onto the other's row.
+ *
+ * Never throws, never mints a SECOND id, and never overrides anything a host supplied — the caller
+ * checks for a host value first.
+ */
+export const ambientAutoDeviceKey = (): string | undefined => {
+  const registry = autoDeviceKeyRegistry();
+  if (registry.keys.size === 0) return resolveAutoDeviceKey();
+  if (registry.keys.size > 1) return undefined;
+  return [...registry.keys.values()][0];
+};