@wireai/activation 0.14.0 → 0.14.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wireai/activation",
-  "version": "0.14.0",
+  "version": "0.14.1",
   "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

@@ -36,7 +36,7 @@ import {
 } from "./session/persistedSession";
 import {
   clearSettledPermissions,
-  loadSettledPermissions,
+  loadSettledPermissionsOutcome,
   permissionStorageKey,
   saveSettledPermissions,
 } from "./permissions/permissionMemory";
@@ -384,18 +384,57 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
   // a late arrival cannot recreate the A2A adapter. The flow simply suppresses permission screens
   // while `permissionsPending` is true, and that window closes long before the first card arrives
   // (one timeout-capped storage read against a backend round trip).
+  //
+  // ── AN UNREADABLE RECORD IS NOT AN EMPTY ONE (ruled 2026-08-18: skip, never re-ask) ──────────
+  //
+  // A read that timed out or threw used to arrive here as `[]`, i.e. "this session has settled
+  // nothing", and that guess is wrong in the expensive direction TWICE. The flow re-asks a
+  // permission the OS grants exactly once, AND the first answer then persists a set grown from
+  // that `[]`, overwriting a stored record that may have held several ids with a single one. A
+  // slow adapter could therefore permanently shrink the memory it exists to keep.
+  //
+  // So `unknown` is now its own outcome and it means: leave the memory UNRESOLVED. Because
+  // `permissionsPending` below is exactly `settledPermissions === undefined`, an unresolved memory
+  // suppresses every permission screen for this mount — which is the ruling, and it also closes
+  // the write path for free (no screen renders → nothing settles → `saveSettledPermissions` is
+  // never called → the stored record is left exactly as it was).
+  //
+  // The cost is stated rather than hidden: on a host whose adapter never answers, configured
+  // permission screens silently never show. That is the failure `placement.ts` calls out as the
+  // one a host cannot see, so it warns in dev naming the adapter.
   const wantsPermissionMemory = Boolean(storage) && (permissionScreens?.length ?? 0) > 0;
   const [settledPermissions, setSettledPermissions] = useState<string[] | undefined>(undefined);
+  // LATCHED: without it, a hung or throwing adapter is re-read on every single render — an
+  // unbounded read loop against the storage that is already failing.
+  const [permissionMemoryUnreadable, setPermissionMemoryUnreadable] = useState(false);
   useEffect(() => {
-    if (!wantsPermissionMemory || !storage || !sessionId || settledPermissions !== undefined) return;
+    if (!wantsPermissionMemory || !storage || !sessionId) return;
+    if (settledPermissions !== undefined || permissionMemoryUnreadable) return;
     let cancelled = false;
-    void loadSettledPermissions(storage, permissionsKey, sessionId).then((ids) => {
-      if (!cancelled) setSettledPermissions(ids);
+    void loadSettledPermissionsOutcome(storage, permissionsKey, sessionId).then((outcome) => {
+      if (cancelled) return;
+      if (outcome.status === "read") {
+        setSettledPermissions(outcome.ids);
+        return;
+      }
+      setPermissionMemoryUnreadable(true);
+      warnInDev(
+        "[wireai] the permission-screen memory could not be read (the storage adapter timed out " +
+          "or threw), so permission screens are suppressed for this session rather than re-asking " +
+          "a permission the OS grants once. Check the `storage` adapter passed to WireOnboarding.",
+      );
     });
     return () => {
       cancelled = true;
     };
-  }, [wantsPermissionMemory, storage, permissionsKey, sessionId, settledPermissions]);
+  }, [
+    wantsPermissionMemory,
+    storage,
+    permissionsKey,
+    sessionId,
+    settledPermissions,
+    permissionMemoryUnreadable,
+  ]);
 
   // Persist the settled set as it grows. Fire-and-forget: a failed write only costs a re-ask on a
   // resume, never a broken flow. Without `storage` there is nothing to write to and the

package/src/analytics/currentSession.ts

@@ -63,8 +63,9 @@ import { warnInDev } from "../utils/warnInDev";
  * @globalSlot LIVE — every app-open overwrites this with that open's id, so a reader that captures
  * it into a module-local (or a `const` taken once at mount) posts the PREVIOUS open's session to a
  * server that has already moved on. Read it at the moment of use, through `getCurrentSessionId()` /
- * `ensureCurrentSessionId()`. `reviews/runtime`'s `currentOpenId()` deliberately pins one sample of
- * it for the launch; that is a documented latch DERIVED from this slot, not a cache of it.
+ * `ensureCurrentSessionId()`. `reviews/runtime`'s `currentOpenId()` derives its own pinned value
+ * from this slot: it holds one sample for the duration of an app-open and re-pins when a genuinely
+ * NEW open is registered here, so it follows this slot deliberately and late, never eagerly.
  */
 const CURRENT_SESSION_ID_SLOT: unique symbol = Symbol.for(
   "@wireai/activation:currentSessionId",

package/src/permissions/permissionMemory.ts

@@ -48,29 +48,54 @@ export const readSettledPermissions = (
   }
 };
 
-/** Read the settled ids for `sessionId`. Never throws, never hangs past the shared read ceiling. */
-export const loadSettledPermissions = async (
+/**
+ * Did the store ANSWER, or did it not? A read that timed out or threw is `unknown` — which is NOT
+ * the same fact as "this session has settled nothing", even though both used to arrive as `[]`.
+ *
+ * The distinction is load-bearing in two directions. A caller that treats `unknown` as empty
+ * (a) re-asks a permission the OS grants exactly once, and (b) persists a set it grew from that
+ * `[]`, SHRINKING the stored record to a single id. A successful read of a corrupt, absent, or
+ * other-session entry is a genuine `[]`: the store answered, and there is nothing here for us.
+ */
+export type SettledPermissionsOutcome =
+  | { status: "read"; ids: string[] }
+  | { status: "unknown" };
+
+/**
+ * Read the settled ids for `sessionId`, reporting WHETHER the store answered. Never throws, never
+ * hangs past the shared read ceiling.
+ */
+export const loadSettledPermissionsOutcome = async (
   storage: WireOnboardingStorage,
   key: string,
   sessionId: string,
-): Promise<string[]> => {
+): Promise<SettledPermissionsOutcome> => {
   try {
     const raw = await withTimeout(storage.getItem(key), READ_TIMEOUT_MS);
-    // A timed-out read degrades to "nothing settled yet", the same answer as before this sentinel
-    // existed (the symbol used to fall through `readSettledPermissions`'s JSON.parse and be caught).
-    // Stated explicitly rather than left to an accident.
-    //
-    // ⚠️ KNOWN, NOT FIXED HERE: the CALLER (`WireOnboarding`) then persists the set it grows from
-    // this `[]`, so a timed-out read can shrink the stored set to one id. It is the same class as
-    // the two sites above, but the fix is a UX ruling, not a mechanical one — on an unknown set,
-    // does a resumed flow re-ask a permission or skip it? Reported, deliberately not guessed at.
-    if (raw === READ_TIMED_OUT) return [];
-    return readSettledPermissions(raw, sessionId);
+    if (raw === READ_TIMED_OUT) return { status: "unknown" };
+    return { status: "read", ids: readSettledPermissions(raw, sessionId) };
   } catch {
-    return [];
+    // The adapter threw or rejected: the store did not answer, so we know nothing either way.
+    return { status: "unknown" };
   }
 };
 
+/**
+ * Read the settled ids for `sessionId`, collapsing "the store did not answer" to `[]`.
+ *
+ * Kept as the module's simple reader for callers that have no way to act on the difference. The
+ * one caller that CAN — `WireOnboarding`, which would otherwise re-ask and then overwrite the
+ * stored record — uses {@link loadSettledPermissionsOutcome} instead.
+ */
+export const loadSettledPermissions = async (
+  storage: WireOnboardingStorage,
+  key: string,
+  sessionId: string,
+): Promise<string[]> => {
+  const outcome = await loadSettledPermissionsOutcome(storage, key, sessionId);
+  return outcome.status === "read" ? outcome.ids : [];
+};
+
 /** Persist the settled ids for `sessionId` - fire-and-forget, all errors swallowed. */
 export const saveSettledPermissions = (
   storage: WireOnboardingStorage,

package/src/reviews/runtime.ts

@@ -125,7 +125,7 @@ const readStr = (storage: CoachmarkStorage | null, key: string): string | undefi
 // 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".
 //
-// ── WHY THE UNIT IS PINNED FOR THE WHOLE LAUNCH ──────────────────────────────────────────────
+// ── WHY THE UNIT IS PINNED, AND WHEN IT IS ALLOWED TO MOVE ───────────────────────────────────
 // The first shape of this function read the two tiers LIVE on every call: the registered session id
 // when there was one, else the process id. That let the UNIT change mid-launch, and React's own
 // ordering guarantees it does. The gates call `bumpSessionCount` from a `useState` INITIALIZER,
@@ -137,39 +137,91 @@ const readStr = (storage: CoachmarkStorage | null, key: string): string | undefi
 //   remount: gate initializer → SESSION id ≠ the stored open           → count = 2
 //
 // Two "sessions" inside one app open, which makes the fail-closed `minSessions: 2` default (added
-// after the 2026-07-16 one-star incident) satisfiable in the very launch it exists to guard. So the
-// FIRST read pins whatever it resolved into the process slot and every later read returns that,
-// regardless of what the session registry does afterwards. The client counter only has to be
-// monotone and per-launch; the server's own `min_sessions` still counts real `app.session_started`
-// events, so nothing downstream needs the two ids to be identical.
+// after the 2026-07-16 one-star incident) satisfiable in the very launch it exists to guard.
 //
-// @globalSlot LATCH — pinned by the FIRST read and stable for the whole launch. This is the one
-// slot whose latch is the fix: it samples the LIVE `currentSessionId` once, on purpose, so that
-// registry changing underneath it (render before effect, on every cold start) cannot change the
-// unit mid-launch and hand `minSessions: 2` a second "session" inside one app open. A second
-// differing write is therefore not a stale-cache bug, it IS the defect — see the block above.
+// THE FIRST FIX PINNED THE WHOLE LAUNCH — one sample, never revisited. That closed the cold start
+// and opened the opposite defect. `useLifecycleEvents` defines an app-open as a foreground after 30
+// minutes
+// in the background and fires a fresh `app.session_started` for it, but on iOS an app is SUSPENDED,
+// not killed, so ONE JS process outlives many opens. A user who opens the app daily for a week
+// produces seven server-side opens while `wire_review_<id>_sessions` stays at 1, and the local
+// `minSessions: 2` rule is unsatisfiable on a phone that is never force-quit — which is most
+// phones. It failed in the SAFE direction (a prompt that never shows, not one that shows too
+// early), but the counter's own docstring promised "once per APP-OPEN" and did not deliver it.
+//
+// THE DISTINCTION THAT RESOLVES BOTH. The two ids in the cold-start trace name the SAME open; a
+// LATER registration names a DIFFERENT one. Nothing else has to change: remember the registered id
+// that was live when the pin was taken, and read it lazily.
+//
+//   • pin unset              → pin = the registered id ?? a freshly minted one, and remember which
+//                              registered id that was (`undefined` when we had to mint).
+//   • remembered `undefined` → the FIRST registration merely NAMES the open the gate already
+//                              counted under a minted id. Adopt it, leave the PIN alone. This is
+//                              the cold-start case, and it stays shut.
+//   • live id ≠ remembered   → a genuinely new app-open. Re-pin to it; the counter bumps once.
+//
+// ⚠️ ONE ACCEPTED MISS, deliberately in the safe direction: if the mount open never registers (a
+// refused non-durable device key over a broken store) and a LATER foreground is the first
+// registration the launch ever sees, that registration is ADOPTED rather than counted, costing one
+// open on an already storage-degraded device. Under-counting is the only direction a fail-closed
+// gate may err in, so this is accepted rather than chased.
+//
+// The client counter only has to be monotone and to move once per real open; the server's own
+// `min_sessions` still counts real `app.session_started` events, so nothing downstream needs the
+// two ids to be identical.
+//
+// @globalSlot LIVE — it re-pins on a genuinely new app-open, so a reader that caches the returned
+// string across opens re-freezes the counter at 1, and the local minSessions rule stops advancing
+// forever on a suspended-not-killed app. The slot holds a PAIR rather than a bare id, because "is this a new
+// open?" is only answerable against the registered id that was live when the pin was taken.
 const PROCESS_OPEN_ID_SLOT: unique symbol = Symbol.for("@wireai/activation:processOpenId");
 
-type GlobalWithOpenId = typeof globalThis & { [PROCESS_OPEN_ID_SLOT]?: string };
+/** The pinned open id plus the registered session id that was live at the moment it was pinned. */
+type OpenPin = {
+  /** The id gate counting treats as THIS app-open. Never empty. */
+  openId: string;
+  /** The registered session id observed at pin time; `undefined` when `openId` was minted. */
+  observed: string | undefined;
+};
+
+type GlobalWithOpenId = typeof globalThis & { [PROCESS_OPEN_ID_SLOT]?: OpenPin };
 
 const openIdGlobal = globalThis as GlobalWithOpenId;
 
 /**
- * The id identifying THIS app-open for gate counting, PINNED on first read for the whole launch:
- * the live per-open `session_id` if one was already registered when the first gate asked, else a
- * minted per-process id. Stable from the first render to the last. Never empty.
+ * The id identifying THIS app-open for gate counting: the live per-open `session_id` once one has
+ * been registered, else a minted per-process id. Stable for the whole of an app-open and across
+ * every remount inside it, and it moves exactly once when a genuinely new open is registered.
+ * Never empty.
  */
 export const currentOpenId = (): string => {
-  const existing = openIdGlobal[PROCESS_OPEN_ID_SLOT];
-  if (existing) return existing;
-  // Adopt the registered session id when the host wired lifecycle BEFORE any gate rendered; that is
-  // the same unit the server counts. Otherwise mint one. Either way it is pinned from here on.
-  const resolved = getCurrentSessionId() ?? makeSessionId();
-  openIdGlobal[PROCESS_OPEN_ID_SLOT] = resolved;
-  return resolved;
+  const live = getCurrentSessionId();
+  const pin = openIdGlobal[PROCESS_OPEN_ID_SLOT];
+
+  // First read of the launch. Adopt the registered id when the host wired lifecycle BEFORE any gate
+  // rendered — that is the same unit the server counts — otherwise mint one and record that we did.
+  if (!pin) {
+    const openId = live ?? makeSessionId();
+    openIdGlobal[PROCESS_OPEN_ID_SLOT] = { openId, observed: live };
+    return openId;
+  }
+
+  // Nothing registered yet, or still the same registered open: the pin stands.
+  if (!live || live === pin.observed) return pin.openId;
+
+  // The first registration of the launch NAMES the open we already pinned under a minted id, so it
+  // is adopted, not counted. Re-pinning here is exactly the cold-start double-count described above.
+  if (pin.observed === undefined) {
+    openIdGlobal[PROCESS_OPEN_ID_SLOT] = { openId: pin.openId, observed: live };
+    return pin.openId;
+  }
+
+  // A second, DIFFERENT registration is a genuinely new app-open.
+  openIdGlobal[PROCESS_OPEN_ID_SLOT] = { openId: live, observed: live };
+  return live;
 };
 
-/** Test-only: forget the process open id so a unit test starts from a clean launch. */
+/** Test-only: forget the pinned open so a unit test starts from a clean launch. */
 export const resetProcessOpenId = (): void => {
   openIdGlobal[PROCESS_OPEN_ID_SLOT] = undefined;
 };