@wireai/activation 0.10.0 → 0.12.0

package/src/revenuecat/purchaseEvents.ts

@@ -0,0 +1,167 @@
+/**
+ * purchaseEvents - the canonical Wire names for a subscription funnel, plus the PURE mappers that
+ * turn a RevenueCat snapshot into small, non-PII event props.
+ *
+ * Same job `analyticsEvent.ts` does for the onboarding funnel: every app was naming these events
+ * itself (`PURCHASE`, `purchase_success`, `AI_PAYWALL_VIEW`), so the same funnel read differently
+ * per tenant and no cross-app report was possible. These are the ONE set of names; the mappers are
+ * the ONE definition of which RevenueCat fields are safe to send.
+ *
+ * PURE + dependency-free: no React, no React Native, no `react-native-purchases`, no transport.
+ * Every function tolerates a malformed or absent snapshot and returns a defined value instead of
+ * throwing, because a paywall must never break on an analytics mapping.
+ */
+import type {
+  RevenueCatCustomerInfoLike,
+  RevenueCatEntitlementLike,
+  RevenueCatPackageLike,
+} from "./types";
+
+/**
+ * The canonical purchase-funnel event names. These are `app_event` `question_key` values on the
+ * wire, so they are ALSO the exact strings a review / questionnaire firing trigger matches on.
+ * Never rename one: a rename silently unfires every trigger configured against the old string.
+ */
+export const WIRE_PURCHASE_EVENTS = {
+  /** The paywall became visible (offerings loaded). */
+  paywallShown: "wire_paywall_shown",
+  /** The user tapped buy; the store sheet is about to open. */
+  checkoutStarted: "wire_checkout_started",
+  /** The store confirmed the purchase AND the entitlement is now active. */
+  purchased: "wire_purchase_completed",
+  /** The purchase did not land: a user cancel or a real store/network error (see `reason`). */
+  purchaseFailed: "wire_purchase_failed",
+  /** A restore ran (whether or not it produced an entitlement; see `plan_tier`). */
+  restored: "wire_purchase_restored",
+} as const;
+
+export type WirePurchaseEventName =
+  (typeof WIRE_PURCHASE_EVENTS)[keyof typeof WIRE_PURCHASE_EVENTS];
+
+/**
+ * The user-context key the bridge writes the tier to. It lands NAMESPACED as
+ * `user_context["custom.plan_tier"]` (host extras are always prefixed), which is the flattened
+ * dimension the server report can break the funnel down by.
+ */
+export const PLAN_TIER_CONTEXT_KEY = "plan_tier";
+
+/** The three tiers the kit models. Anything richer belongs in the host's own analytics. */
+export type PlanTier = "paid" | "trial" | "free";
+
+/** Read a plain record field defensively (the snapshot comes from a native bridge). */
+const asRecord = (value: unknown): Record<string, unknown> | undefined =>
+  typeof value === "object" && value !== null ? (value as Record<string, unknown>) : undefined;
+
+/**
+ * The ACTIVE entitlement matching `entitlementId`, or `undefined`. Returns `undefined` for a
+ * missing key, an explicitly inactive entry, and any malformed snapshot.
+ */
+export const activeEntitlement = (
+  info: RevenueCatCustomerInfoLike | undefined,
+  entitlementId: string,
+): RevenueCatEntitlementLike | undefined => {
+  const active = asRecord(asRecord(asRecord(info)?.entitlements)?.active);
+  const found = active?.[entitlementId];
+  const entitlement = asRecord(found) as RevenueCatEntitlementLike | undefined;
+  if (!entitlement) return undefined;
+  // `isActive` is always present on the real type; treat an explicit `false` as not entitled and a
+  // missing value as entitled, because the key only appears in `entitlements.active` at all when
+  // RevenueCat considers it granted.
+  return entitlement.isActive === false ? undefined : entitlement;
+};
+
+/** True when RevenueCat says this entitlement is a free trial rather than a paid period. */
+const isTrial = (entitlement: RevenueCatEntitlementLike): boolean =>
+  typeof entitlement.periodType === "string" && entitlement.periodType.toUpperCase() === "TRIAL";
+
+/** `paid` / `trial` / `free` for the configured entitlement. Never throws. */
+export const resolvePlanTier = (
+  info: RevenueCatCustomerInfoLike | undefined,
+  entitlementId: string,
+): PlanTier => {
+  const entitlement = activeEntitlement(info, entitlementId);
+  if (!entitlement) return "free";
+  return isTrial(entitlement) ? "trial" : "paid";
+};
+
+/**
+ * Non-PII props for an offering package: which package, which product, what it costs. Every field
+ * is optional on the wire, so a missing one is OMITTED rather than sent empty or invented.
+ */
+export const describePackage = (
+  pkg: RevenueCatPackageLike | undefined,
+): Record<string, string | number> => {
+  const props: Record<string, string | number> = {};
+  if (!pkg) return props;
+  if (typeof pkg.identifier === "string") props.package_id = pkg.identifier;
+  if (typeof pkg.packageType === "string") props.package_type = pkg.packageType;
+  if (typeof pkg.offeringIdentifier === "string") props.offering_id = pkg.offeringIdentifier;
+  const product = asRecord(pkg.product) as RevenueCatProductFields | undefined;
+  if (product) {
+    if (typeof product.identifier === "string") props.product_id = product.identifier;
+    if (typeof product.price === "number" && Number.isFinite(product.price)) {
+      props.price = product.price;
+    }
+    if (typeof product.currencyCode === "string") props.currency = product.currencyCode;
+  }
+  return props;
+};
+
+/** The product fields `describePackage` reads, narrowed after the defensive record check. */
+type RevenueCatProductFields = {
+  identifier?: unknown;
+  price?: unknown;
+  currencyCode?: unknown;
+};
+
+/**
+ * Non-PII props for the entitlement state after a purchase or a restore. Always carries
+ * `entitlement` + `plan_tier` so a "restore that granted nothing" is still a queryable row; the
+ * rest of the fields only appear when the entitlement is actually active.
+ */
+export const describeEntitlement = (
+  info: RevenueCatCustomerInfoLike | undefined,
+  entitlementId: string,
+): Record<string, string | number | boolean> => {
+  const entitlement = activeEntitlement(info, entitlementId);
+  const props: Record<string, string | number | boolean> = {
+    entitlement: entitlementId,
+    plan_tier: entitlement ? (isTrial(entitlement) ? "trial" : "paid") : "free",
+  };
+  if (!entitlement) return props;
+  if (typeof entitlement.periodType === "string") props.period_type = entitlement.periodType;
+  props.is_trial = isTrial(entitlement);
+  if (typeof entitlement.willRenew === "boolean") props.will_renew = entitlement.willRenew;
+  if (typeof entitlement.store === "string") props.store = entitlement.store;
+  if (typeof entitlement.productIdentifier === "string") {
+    props.product_id = entitlement.productIdentifier;
+  }
+  if (typeof entitlement.isSandbox === "boolean") props.is_sandbox = entitlement.isSandbox;
+  return props;
+};
+
+/** RevenueCat's `PURCHASES_ERROR_CODE.PURCHASE_CANCELLED_ERROR`. A STRING enum, value `"1"`. */
+const PURCHASE_CANCELLED_CODE = "1";
+
+/**
+ * True when the rejection is the user backing out of the store sheet rather than a real failure.
+ * Reads BOTH signals the SDK exposes: the current `code` and the deprecated-but-still-populated
+ * `userCancelled` flag. Anything else (including a plain `Error`) is a genuine failure.
+ */
+export const isUserCancelled = (error: unknown): boolean => {
+  const record = asRecord(error);
+  if (!record) return false;
+  if (record.userCancelled === true) return true;
+  return record.code === PURCHASE_CANCELLED_CODE;
+};
+
+/**
+ * A short, stable, non-PII failure descriptor. The store's `message` is DELIBERATELY dropped: it is
+ * localized, unbounded, and occasionally echoes the account it failed for, so it is not something
+ * the kit forwards to a shared analytics backend. The RevenueCat `code` is the stable handle.
+ */
+export const describeFailure = (error: unknown): { reason: string; code: string } => {
+  const record = asRecord(error);
+  const code = typeof record?.code === "string" ? record.code : "unknown";
+  return { reason: isUserCancelled(error) ? "cancelled" : "error", code };
+};

package/src/revenuecat/revenueCatBridge.ts

@@ -0,0 +1,221 @@
+/**
+ * revenueCatBridge - the short, first-class path from RevenueCat to Wire activation.
+ *
+ *   const revenuecat = createRevenueCatBridge({ analytics, entitlementId: "pro" });
+ *   revenuecat.paywallShown(offering, { source: variant });
+ *   revenuecat.checkoutStarted(pkg, { source: variant });
+ *   const entitled = revenuecat.purchaseCompleted(customerInfo, pkg, { source: variant });
+ *
+ * WHAT IT REPLACES: every consumer was hand-rolling the same four things around its paywall,
+ * differently: its own event names, its own idea of which RevenueCat fields are safe to send, its
+ * own entitlement check duplicated at the purchase and the restore site, and its own plan-tier
+ * user property. This owns all four, so adopting the purchase funnel is a constructor plus five
+ * call sites.
+ *
+ * ── THE JOIN KEY (read this before you wire it) ───────────────────────────────────────────────
+ * A purchase event is only worth anything if it can be joined to the SAME user's onboarding. The
+ * key that does that is `user_context.device_key`, NOT `session_id`:
+ *
+ *   • Purchase side: this bridge reports through a kit sink (`createAnalytics` or
+ *     `createWireActivation`). Both auto-mint a stable, persisted, per-install `device_key` and
+ *     stamp it on every event (see `context/deviceId.ts`).
+ *   • Onboarding side: `<WireOnboarding userContext={activationJoinContext(deviceKey)} />`. The kit
+ *     forwards `userContext` verbatim into the A2A session-start metadata, and the server records
+ *     it on the session's `session_started` event, where the SAME `device_key` lookup reads it.
+ *
+ * Pass the SAME `deviceKey` to both. `session_id` is NOT a join key across these two families: the
+ * onboarding session id is the A2A `contextId`, the app-event session id is the per-open id, and
+ * they live in disjoint spaces on purpose. Intersecting them yields zero rows, every time.
+ *
+ * PURE + dependency-free: no React, no React Native, no `react-native-purchases`. Fire-and-forget
+ * throughout, so an analytics failure can never take the paywall down with it.
+ */
+import type { Analytics } from "../analytics/analyticsFacade";
+import type { WireActivation } from "../activation/wireActivation";
+import {
+  PLAN_TIER_CONTEXT_KEY,
+  WIRE_PURCHASE_EVENTS,
+  describeEntitlement,
+  describeFailure,
+  describePackage,
+  resolvePlanTier,
+  type PlanTier,
+} from "./purchaseEvents";
+import type {
+  RevenueCatCustomerInfoLike,
+  RevenueCatOfferingLike,
+  RevenueCatPackageLike,
+  RevenueCatSink,
+} from "./types";
+
+/**
+ * COMPILE-TIME PROOF that both kit sinks satisfy {@link RevenueCatSink}, so a host can pass the
+ * analytics instance it already holds with no adapter of its own. Type-only (erased at build), and
+ * `tsc --noEmit` fails here the day either surface drifts. This lives in source, not the test file,
+ * because `tsconfig.json` excludes tests from the typecheck.
+ */
+type AssertIsSink<T extends RevenueCatSink> = T;
+type _AnalyticsIsASink = AssertIsSink<Analytics>;
+type _WireActivationIsASink = AssertIsSink<WireActivation>;
+
+/** Small, non-PII extras a host merges onto a purchase event (paywall variant, entry point, ...). */
+export type PurchaseProps = Record<string, string | number | boolean>;
+
+/** Inputs for {@link createRevenueCatBridge}. */
+export interface RevenueCatBridgeConfig {
+  /**
+   * Where events go: the `createAnalytics(...)` instance (offline-first queue) or the
+   * `createWireActivation(...)` instance (awaitable POST). Both already carry the `device_key` this
+   * funnel joins on, so pass the one the app already holds rather than creating a second.
+   */
+  analytics: RevenueCatSink;
+  /**
+   * The entitlement identifier that means "paid" in THIS app, exactly as configured in the
+   * RevenueCat dashboard (e.g. `"pro"`). The bridge reads `customerInfo.entitlements.active[id]`.
+   */
+  entitlementId: string;
+  /** Non-PII props merged into EVERY event from this bridge. A per-call prop of the same name wins. */
+  commonProps?: PurchaseProps;
+  /**
+   * Whether entitlement changes also update the bound user context with `plan_tier`
+   * (`user_context["custom.plan_tier"]`), so the whole funnel can be sliced paid vs trial vs free.
+   * Default `true`. Requires a sink with `setUserContext` (`createAnalytics`); a no-op otherwise.
+   */
+  writePlanTier?: boolean;
+}
+
+/** The bridge surface. Every method is fire-and-forget and never throws. */
+export interface RevenueCatBridge {
+  /**
+   * The paywall became visible. Pass the RevenueCat offering you just loaded and the bridge derives
+   * `offering_id` + `packages_count`. Fires even with no offering, because a paywall that reached
+   * the user with nothing to sell is exactly the failure you want in the funnel.
+   */
+  paywallShown(offering?: RevenueCatOfferingLike, props?: PurchaseProps): void;
+  /** The user tapped buy and the store sheet is opening. */
+  checkoutStarted(pkg: RevenueCatPackageLike, props?: PurchaseProps): void;
+  /**
+   * The store returned from a purchase. Fires `wire_purchase_completed` when the configured
+   * entitlement is now active, and `wire_purchase_failed` with `reason: "not_entitled"` when the
+   * store confirmed but nothing was granted (the case hosts usually drop on the floor). Syncs
+   * `plan_tier` either way. Returns whether the user is entitled now, so the caller can navigate.
+   */
+  purchaseCompleted(
+    customerInfo: RevenueCatCustomerInfoLike | undefined,
+    pkg?: RevenueCatPackageLike,
+    props?: PurchaseProps,
+  ): boolean;
+  /** The purchase call rejected. Separates a user cancel from a real store error via `reason`. */
+  purchaseFailed(error: unknown, pkg?: RevenueCatPackageLike, props?: PurchaseProps): void;
+  /** A restore finished. Reports the resulting tier and returns whether the user is entitled now. */
+  purchasesRestored(
+    customerInfo: RevenueCatCustomerInfoLike | undefined,
+    props?: PurchaseProps,
+  ): boolean;
+  /**
+   * Write the current tier to the bound user context WITHOUT emitting an event. Call it once at
+   * launch with a `getCustomerInfo()` snapshot so returning subscribers are segmented correctly
+   * from their first event of the session. Returns the tier it resolved.
+   */
+  syncPlanTier(customerInfo: RevenueCatCustomerInfoLike | undefined): PlanTier;
+}
+
+/**
+ * Create a bridge bound to one sink and one entitlement. Pure, React-free, and safe to create at
+ * module scope next to the paywall.
+ */
+export const createRevenueCatBridge = (config: RevenueCatBridgeConfig): RevenueCatBridge => {
+  const { analytics, entitlementId } = config;
+  const writeTier = config.writePlanTier !== false;
+
+  /**
+   * Send one event. Swallows a throwing sink AND a rejected promise from an awaitable one, so an
+   * analytics failure is never visible at the paywall and never becomes an unhandled rejection.
+   */
+  const emit = (event: string, props: Record<string, unknown>): void => {
+    try {
+      const result = analytics.track(event, { ...config.commonProps, ...props });
+      if (result && typeof (result as Promise<boolean>).catch === "function") {
+        void (result as Promise<boolean>).catch(() => {});
+      }
+    } catch {
+      /* analytics must never break a purchase */
+    }
+  };
+
+  const syncPlanTier = (customerInfo: RevenueCatCustomerInfoLike | undefined): PlanTier => {
+    const tier = resolvePlanTier(customerInfo, entitlementId);
+    if (!writeTier) return tier;
+    try {
+      analytics.setUserContext?.({ extra: { [PLAN_TIER_CONTEXT_KEY]: tier } });
+    } catch {
+      /* a sink without a usable context writer is not a purchase failure */
+    }
+    return tier;
+  };
+
+  const paywallShown = (offering?: RevenueCatOfferingLike, props?: PurchaseProps): void => {
+    const shown: Record<string, unknown> = {
+      packages_count: offering?.availablePackages?.length ?? 0,
+    };
+    if (typeof offering?.identifier === "string") shown.offering_id = offering.identifier;
+    emit(WIRE_PURCHASE_EVENTS.paywallShown, { ...shown, ...props });
+  };
+
+  const checkoutStarted = (pkg: RevenueCatPackageLike, props?: PurchaseProps): void => {
+    emit(WIRE_PURCHASE_EVENTS.checkoutStarted, { ...describePackage(pkg), ...props });
+  };
+
+  const purchaseCompleted = (
+    customerInfo: RevenueCatCustomerInfoLike | undefined,
+    pkg?: RevenueCatPackageLike,
+    props?: PurchaseProps,
+  ): boolean => {
+    const tier = syncPlanTier(customerInfo);
+    const entitled = tier !== "free";
+    if (entitled) {
+      emit(WIRE_PURCHASE_EVENTS.purchased, {
+        ...describePackage(pkg),
+        ...describeEntitlement(customerInfo, entitlementId),
+        ...props,
+      });
+      return true;
+    }
+    // The store said yes but the entitlement is not active: a product/entitlement mapping problem,
+    // the single most common silent paywall defect. Report it rather than returning quietly.
+    emit(WIRE_PURCHASE_EVENTS.purchaseFailed, {
+      ...describePackage(pkg),
+      reason: "not_entitled",
+      code: "unknown",
+      entitlement: entitlementId,
+      ...props,
+    });
+    return false;
+  };
+
+  const purchaseFailed = (
+    error: unknown,
+    pkg?: RevenueCatPackageLike,
+    props?: PurchaseProps,
+  ): void => {
+    emit(WIRE_PURCHASE_EVENTS.purchaseFailed, {
+      ...describePackage(pkg),
+      ...describeFailure(error),
+      ...props,
+    });
+  };
+
+  const purchasesRestored = (
+    customerInfo: RevenueCatCustomerInfoLike | undefined,
+    props?: PurchaseProps,
+  ): boolean => {
+    const tier = syncPlanTier(customerInfo);
+    emit(WIRE_PURCHASE_EVENTS.restored, {
+      ...describeEntitlement(customerInfo, entitlementId),
+      ...props,
+    });
+    return tier !== "free";
+  };
+
+  return { paywallShown, checkoutStarted, purchaseCompleted, purchaseFailed, purchasesRestored, syncPlanTier };
+};

package/src/revenuecat/types.ts

@@ -0,0 +1,95 @@
+/**
+ * types - STRUCTURAL mirrors of the `react-native-purchases` shapes this adapter READS.
+ *
+ * WHY structural and not an import: `react-native-purchases` is a NATIVE module. Importing it
+ * (even as an optional peer) would put a native rebuild in the kit's dependency story, which the
+ * kit's hard rule forbids. Every field below is a subset of the real 9.6.x typings
+ * (`@revenuecat/purchases-typescript-internal`: `CustomerInfo`, `PurchasesEntitlementInfo`,
+ * `PurchasesPackage`, `PurchasesStoreProduct`, `PurchasesError`), declared as plain `string` /
+ * `number` / `boolean` so a host can pass its REAL RevenueCat objects straight in: RevenueCat's
+ * `Store`, `PACKAGE_TYPE`, `PERIOD_TYPE` and `PURCHASES_ERROR_CODE` are all STRING enums, and a
+ * string enum member is assignable to `string`.
+ *
+ * The adapter only ever reads. It never constructs a RevenueCat object and never calls the SDK.
+ */
+
+/** One entitlement as RevenueCat reports it (subset of `PurchasesEntitlementInfo`). */
+export interface RevenueCatEntitlementLike {
+  /** The entitlement identifier configured in the RevenueCat dashboard, e.g. `"pro"`. */
+  readonly identifier: string;
+  /** True while the customer has access. */
+  readonly isActive: boolean;
+  /** `"NORMAL" | "INTRO" | "TRIAL" | "PREPAID"` on the real type; compared case-insensitively. */
+  readonly periodType?: string;
+  /** True when the underlying subscription renews at the end of the period. */
+  readonly willRenew?: boolean;
+  /** The store the entitlement was unlocked from, e.g. `"APP_STORE"`. */
+  readonly store?: string;
+  /** The product id that unlocked the entitlement. */
+  readonly productIdentifier?: string;
+  /** False when the purchase is a production one. */
+  readonly isSandbox?: boolean;
+}
+
+/** The customer snapshot RevenueCat returns from a purchase, a restore, or `getCustomerInfo`. */
+export interface RevenueCatCustomerInfoLike {
+  readonly entitlements: {
+    /** Active entitlements keyed by identifier. Missing key means "not entitled". */
+    readonly active: { readonly [key: string]: RevenueCatEntitlementLike | undefined };
+  };
+  /** Product ids of the customer's active subscriptions. */
+  readonly activeSubscriptions?: readonly string[];
+}
+
+/** The purchasable product on a package (subset of `PurchasesStoreProduct`). */
+export interface RevenueCatProductLike {
+  readonly identifier: string;
+  /** Price in the local currency, as a number. */
+  readonly price?: number;
+  /** ISO currency code of `price`, e.g. `"EUR"`. */
+  readonly currencyCode?: string;
+}
+
+/** One offering package (subset of `PurchasesPackage`). */
+export interface RevenueCatPackageLike {
+  readonly identifier: string;
+  /** `"ANNUAL" | "MONTHLY" | ...` on the real type. */
+  readonly packageType?: string;
+  readonly product: RevenueCatProductLike;
+  /** The offering this package belongs to. */
+  readonly offeringIdentifier?: string;
+}
+
+/** The current offering a paywall renders (subset of `PurchasesOffering`). */
+export interface RevenueCatOfferingLike {
+  readonly identifier?: string;
+  readonly availablePackages?: readonly RevenueCatPackageLike[];
+}
+
+/** The rejected value of a RevenueCat purchase call (subset of `PurchasesError`). */
+export interface RevenueCatErrorLike {
+  /** `PURCHASES_ERROR_CODE`, a STRING enum; `"1"` is `PURCHASE_CANCELLED_ERROR`. */
+  readonly code?: string;
+  readonly message?: string;
+  /** Deprecated on the real type but still populated by 9.6.x. */
+  readonly userCancelled?: boolean | null;
+}
+
+/**
+ * The Wire sink the bridge reports through. Deliberately STRUCTURAL so BOTH kit surfaces satisfy
+ * it with no adapter of their own:
+ *   - `createAnalytics(...)` (offline-first queue) matches `track` + `setUserContext`;
+ *   - `createWireActivation(...)` (awaitable `wire.track`) matches `track`.
+ *
+ * Both auto-mint and stamp `user_context.device_key` on every event, which is the join key this
+ * adapter's whole design rests on (see `joinKey.md` in the module docs / the README section).
+ */
+export interface RevenueCatSink {
+  /** Report an in-app event. Returns `void` (queued) or `Promise<boolean>` (awaited POST). */
+  track(event: string, props?: Record<string, unknown>): void | Promise<boolean>;
+  /**
+   * Optional: update the bound user context. Present on `createAnalytics`, absent on
+   * `createWireActivation` (its config is captured immutably), so entitlement sync is a no-op there.
+   */
+  setUserContext?(partial: { extra?: Record<string, string | number | boolean> }): void;
+}

package/src/reviews/decision.ts

@@ -64,7 +64,14 @@ export const resolveRules = (config: {
   oncePerVersion?: boolean;
 }): GateRules => ({
   enabled: config.enabled ?? true,
-  minSessions: config.minSessions ?? 0,
+  // FAIL-CLOSED on the first session (behavior change, 0.11.0). An unconfigured host with no
+  // server decision must NOT prompt on the very first mount: `minSessions` defaults to 2 so the
+  // gate needs at least a second session before the LOCAL rules can fire. This is the client-side
+  // floor only — a server `decision` (from `fetchReviewDecision`) still OVERRIDES everything, and a
+  // host that genuinely wants first-session prompting can set `minSessions: 1` (or `0`) explicitly.
+  // Mirrors the 2026-07-16 incident: a first-session user, no server decision, got the prompt and
+  // left 1 star. See `evaluateGate` (`min_sessions` reason) and the CHANGELOG.
+  minSessions: config.minSessions ?? 2,
   minEvents: config.minEvents ?? 0,
   cooldownDays: config.cooldownDays ?? 0,
   oncePerVersion: config.oncePerVersion ?? true,

package/src/reviews/runtime.ts

@@ -6,6 +6,8 @@
  */
 import type { CoachmarkStorage } from "../coachmarks/types";
 import { getCoachmarkStorage } from "../coachmarks/runtime";
+import { getCurrentSessionId } from "../analytics/currentSession";
+import { makeSessionId } from "../analytics/reportClientEvent";
 
 /** Once-gate key. Keyed by app version when `oncePerVersion` is on, so a new release re-enables. */
 export const reviewSeenKey = (id: string, version?: string): string =>
@@ -14,9 +16,12 @@ export const reviewSeenKey = (id: string, version?: string): string =>
 /** Last-shown timestamp key (epoch ms), for the cooldown rule. */
 export const reviewLastShownKey = (id: string): string => `wire_review_${id}_last`;
 
-/** Session-count key, incremented once per gate mount, for the min-sessions rule. */
+/** Session-count key, incremented once per APP-OPEN (not per mount), for the min-sessions rule. */
 export const reviewSessionsKey = (id: string): string => `wire_review_${id}_sessions`;
 
+/** Companion key holding the open id the counter was LAST incremented for (see {@link bumpSessionCount}). */
+export const reviewSessionOpenKey = (id: string): string => `wire_review_${id}_open`;
+
 /** Resolve the storage to use: an explicit override, else the provider-injected singleton. */
 export const resolveStorage = (
   override?: CoachmarkStorage | null,
@@ -43,3 +48,89 @@ export const writeInt = (storage: CoachmarkStorage | null, key: string, value: n
     // Best-effort.
   }
 };
+
+/** Read a string from sync storage (undefined on a missing/blank/throwing read). */
+const readStr = (storage: CoachmarkStorage | null, key: string): string | undefined => {
+  if (!storage) return undefined;
+  try {
+    const raw = storage.getItem(key);
+    return typeof raw === "string" && raw.length > 0 ? raw : undefined;
+  } catch {
+    return undefined;
+  }
+};
+
+// ── The "which app-open is this" id ──────────────────────────────────────────────────────────
+//
+// The gates' `minSessions` rule needs a SESSION, and the counter behind it used to increment once
+// per gate MOUNT. A mount is not a session: navigating away from the home feed and back, a tab that
+// unmounts its screen, or React StrictMode's dev double-invoke of the `useState` initializer all
+// bumped it. So `minSessions: 2` — the fail-closed default added after the 2026-07-16 one-star
+// incident — was satisfiable inside the user's FIRST app open, which is the exact thing it exists
+// to prevent. `sessions` was a count of mounts wearing the name of a session.
+//
+// The correct unit already exists: `getCurrentSessionId()`, the per-open id the server sees on
+// `app.session_started`. When a host wires the lifecycle events, the counter keys off THAT and is
+// exactly "distinct app-opens", the same unit the server's own `min_sessions` uses.
+//
+// When no host wired lifecycle events there is no registered open, so we fall back to a PROCESS-
+// scoped id: one JS process is one app launch, which is still a genuine app-open and is strictly
+// closer to a session than a mount is. It lives in a `globalThis` slot keyed by `Symbol.for(...)`
+// for the same reason `currentSession` does: tsup inlines this module into several bundles and a
+// plain module-local `let` would give each bundle its own "process".
+const PROCESS_OPEN_ID_SLOT: unique symbol = Symbol.for("@wireai/activation:processOpenId");
+
+type GlobalWithOpenId = typeof globalThis & { [PROCESS_OPEN_ID_SLOT]?: string };
+
+const openIdGlobal = globalThis as GlobalWithOpenId;
+
+/**
+ * The id identifying THIS app-open for gate counting: the live per-open `session_id` when a host
+ * wired the lifecycle events, else a stable per-process id. Never empty.
+ */
+export const currentOpenId = (): string => {
+  const live = getCurrentSessionId();
+  if (live) return live;
+  const existing = openIdGlobal[PROCESS_OPEN_ID_SLOT];
+  if (existing) return existing;
+  const created = makeSessionId();
+  openIdGlobal[PROCESS_OPEN_ID_SLOT] = created;
+  return created;
+};
+
+/** Test-only: forget the process open id so a unit test starts from a clean launch. */
+export const resetProcessOpenId = (): void => {
+  openIdGlobal[PROCESS_OPEN_ID_SLOT] = undefined;
+};
+
+/**
+ * Return the app-open count for the gate, incrementing it AT MOST ONCE per app-open.
+ *
+ * IDEMPOTENT by construction: the open id that last incremented the counter is stored alongside it,
+ * so a second call within the same open (a remount, a StrictMode double-invoke, a second gate render)
+ * reads the stored count back instead of bumping it. A new open id bumps exactly once.
+ *
+ * Storage-less hosts get `1` for the first call and `1` for every later call within the open —
+ * degraded but never inflating, which is the safe direction for a fail-closed gate.
+ */
+export const bumpSessionCount = (
+  storage: CoachmarkStorage | null,
+  sessionsKey: string,
+  openKey: string,
+  openId: string = currentOpenId(),
+): number => {
+  const lastOpen = readStr(storage, openKey);
+  const stored = readInt(storage, sessionsKey);
+  // Already counted this open → return what we counted, do not bump again.
+  if (lastOpen === openId) return stored > 0 ? stored : 1;
+  const next = stored + 1;
+  writeInt(storage, sessionsKey, next);
+  if (storage) {
+    try {
+      storage.setItem(openKey, openId);
+    } catch {
+      // Best-effort: a failed write only means this open may be counted twice.
+    }
+  }
+  return next;
+};