@wireai/activation 0.12.2 → 0.13.2

package/src/cards/PermissionCard.tsx

@@ -0,0 +1,438 @@
+/**
+ * PermissionCard - the priming screen that stands in front of an OS permission dialog.
+ *
+ * THE PRIMING PATTERN, which is the entire point: the OS dialog opens from the primary press
+ * handler and from nowhere else. There is no mount effect, no auto-fire, no timer, and no code path
+ * from render to `request()`. iOS grants an app exactly ONE native notification prompt for its
+ * whole lifetime, so this cheap in-app screen spends first and only forwards the users who said
+ * yes. The secondary ("Maybe later") advances the flow with the prompt still unspent.
+ *
+ * THREE PRIMARY ACTIONS, picked from the non-prompting `getStatus` probe (never from `request`):
+ *   • ask (the default, and the only branch that can reach `request`)
+ *   • settings (status `blocked`: the OS would show nothing, so the only route left is Settings)
+ *   • continue (already granted, or a host that supplied no `request` at all - the kit declines to
+ *     fabricate a prompt it has no way to open)
+ *
+ * IT IS NOT A QUESTION. It sends nothing to the backend, appends nothing to the thread, and mints
+ * no `key` / `slot_id`, so `deriveAnswers` and every completion semantic are untouched. Every
+ * outcome, including a denial, continues the flow.
+ *
+ * Motion: the same register as the other value beats. The illustration springs in
+ * (STATUS_POP_SPRING, the StatusCard glyph pop) and the copy rises behind it on the interstitial
+ * head stagger. Reduce motion: final frame at once, like every other card.
+ *
+ * Registered as a `WireAIComponent` so a later server-emitted placement (AI-chosen timing) renders
+ * through the same component with no rewrite. It is deliberately NOT in `onboardingComponents`:
+ * that array is what the device ADVERTISES as renderable, and a backend told it may emit this card
+ * could emit one for a host that wired no `request`.
+ */
+import React, { useCallback, useEffect, useRef, useState } from "react";
+import { Animated, Easing, StyleSheet, Text, View } from "react-native";
+import { z } from "zod";
+import type { InjectedProps, WireAIComponent } from "wireai-rn";
+import { useOnboardingTheme } from "../theme/ThemeContext";
+import { bodyStyle, headingStyle } from "../theme/typography";
+import { useIllustration } from "../components/Illustration";
+import { Button } from "../components/Button";
+import { CardLayout } from "../components/CardLayout";
+import {
+  INTERSTITIAL_HEAD_MS,
+  INTERSTITIAL_HEAD_STAGGER_MS,
+  STATUS_POP_SCALE_FROM,
+  STATUS_POP_SPRING,
+  WIRE_BEZIER,
+  scaledMs,
+} from "../motion/motionSpec";
+import { useReducedMotion } from "../motion/useReducedMotion";
+import { normalizePermissionStatus } from "../permissions/permissionEvents";
+import type {
+  PermissionStage,
+  WirePermissionOutcome,
+  WirePermissionStatus,
+} from "../permissions/types";
+import { playHaptic } from "../haptics/haptics";
+import { warnInDev } from "../utils/warnInDev";
+
+const easeWire = Easing.bezier(...WIRE_BEZIER);
+const RISE_PX = 10;
+
+/** The name the card is registered under, and the `component` stamped on its events. */
+export const PERMISSION_CARD_NAME = "PermissionCard";
+
+/**
+ * How long a host's `request` may stay outstanding before the kit hands the controls back.
+ *
+ * DELIBERATELY GENEROUS. This is not a race against the user: someone reading an OS permission
+ * dialog, switching apps mid-prompt, or hitting a slow native bridge is doing nothing wrong, and a
+ * short ceiling would advance the flow underneath a dialog that is still open. It exists for one
+ * failure only, a `request` that never settles at all (a swallowed native callback, a promise
+ * nobody resolves), which would otherwise leave the user on a screen whose buttons are all
+ * disabled. On expiry the kit records NO outcome, because a pending request is not a denial.
+ */
+export const REQUEST_WATCHDOG_MS = 90_000;
+
+/**
+ * The COPY half of the card, i.e. everything a server could legitimately author. The capability
+ * half (`request` / `getStatus` / `openSettings`) is host-injected and deliberately absent here:
+ * a schema field can only ever carry data, never a function, and the kit imports no native module.
+ */
+const schema = z.object({
+  permission: z
+    .string()
+    .describe("Which OS permission this screen primes, e.g. 'notifications'"),
+  title: z.string().describe("Headline for the ask"),
+  message: z.string().describe("Why the app needs it, in the user's terms"),
+  primaryLabel: z.string().describe("Primary button, the only control that can open the OS dialog"),
+  secondaryLabel: z.string().describe("Secondary button, advances without spending the OS prompt"),
+  blockedTitle: z.string().optional().describe("Headline once the permission is permanently refused"),
+  blockedMessage: z.string().optional().describe("Rationale for the settings route"),
+  settingsLabel: z.string().optional().describe("Primary button label on the blocked route"),
+  continueLabel: z.string().optional().describe("Primary button label when there is nothing to ask"),
+  illustration: z
+    .string()
+    .optional()
+    .describe("Name of an app-provided illustration (defaults to the permission name)"),
+});
+
+export type PermissionCardProps = z.infer<typeof schema> &
+  Partial<InjectedProps> & {
+    /** THE ONLY function that can open an OS dialog. Called from the primary handler alone. */
+    request?: () => Promise<WirePermissionStatus>;
+    /** NON-PROMPTING status read. Decides which primary action is offered, nothing else. */
+    getStatus?: () => Promise<WirePermissionStatus>;
+    /** Open the OS settings page. Only reachable on the `blocked` route. */
+    openSettings?: () => void | Promise<void>;
+    /** Reports each moment for analytics. Never control flow. */
+    onStage?: (stage: PermissionStage, status?: WirePermissionStatus) => void;
+    /** Fires exactly once, with the outcome this screen produced. The flow advances on it. */
+    onSettled?: (outcome: WirePermissionOutcome) => void;
+  };
+
+/** Which action the primary button performs. `ask` is the only one that can reach `request`. */
+type PrimaryAction = "ask" | "settings" | "continue";
+
+const _PermissionCard: React.FC<PermissionCardProps> = ({
+  permission,
+  title,
+  message,
+  primaryLabel,
+  secondaryLabel,
+  blockedTitle,
+  blockedMessage,
+  settingsLabel,
+  continueLabel,
+  illustration,
+  request,
+  getStatus,
+  openSettings,
+  onStage,
+  onSettled,
+}) => {
+  const t = useOnboardingTheme();
+  const reduced = useReducedMotion();
+  const art = useIllustration(illustration ?? permission);
+  // The probed status. `undefined` means "not known", which is the ASK state: the kit never
+  // assumes a grant it has not been told about.
+  const [status, setStatus] = useState<WirePermissionStatus | undefined>(undefined);
+  const [busy, setBusy] = useState(false);
+  // One settle per mount. The card is keyed by screen id, so this is one settle per screen. It is
+  // also what makes a late `request` settlement a no-op, since `finish` reaches `settle`
+  // synchronously (see `handlePrimary`).
+  const settledRef = useRef(false);
+  // `accepted` is a per-screen boolean, so `accepted / shown` stays a readable rate.
+  const acceptedRef = useRef(false);
+  const watchdogRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const clearWatchdog = useCallback(() => {
+    if (watchdogRef.current) {
+      clearTimeout(watchdogRef.current);
+      watchdogRef.current = null;
+    }
+  }, []);
+  // A pending watchdog must never outlive the screen (it would setState on an unmounted card).
+  useEffect(() => clearWatchdog, [clearWatchdog]);
+
+  // Host callbacks held in refs so the mount-once effects below stay mount-once no matter how a
+  // host passes them (the documented usage is an INLINE `permissionScreens={[...]}`, which mints a
+  // fresh closure for every one of them on every render).
+  const onStageRef = useRef(onStage);
+  onStageRef.current = onStage;
+  const onSettledRef = useRef(onSettled);
+  onSettledRef.current = onSettled;
+  const getStatusRef = useRef(getStatus);
+  getStatusRef.current = getStatus;
+
+  // `shown` fires once per mount, ref-guarded so StrictMode's dev double-invoke cannot
+  // double-count the denominator every rate in this funnel is measured against.
+  const shownRef = useRef(false);
+  useEffect(() => {
+    if (shownRef.current) return;
+    shownRef.current = true;
+    onStageRef.current?.("shown");
+  }, []);
+
+  // The status probe, MOUNT-ONCE. `getPermissionsAsync()` and its equivalents READ, they never
+  // prompt - which is exactly why `request` is not called here and why this effect may exist at
+  // all. All it decides is which primary action the screen offers.
+  useEffect(() => {
+    const probe = getStatusRef.current;
+    if (!probe) return;
+    let cancelled = false;
+    try {
+      void Promise.resolve(probe())
+        .then((value) => {
+          if (!cancelled) setStatus(normalizePermissionStatus(value));
+        })
+        .catch(() => {
+          // A host probe that throws just leaves the screen in its ask state.
+        });
+    } catch {
+      // A synchronously-throwing probe, same treatment.
+    }
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  // A host that configured a screen with no `request` gets a screen that cannot ask. The kit says
+  // so instead of rendering a button that silently does nothing (dev only, never a throw).
+  const requestRef = useRef(request);
+  requestRef.current = request;
+  useEffect(() => {
+    if (requestRef.current) return;
+    warnInDev(
+      `[wireai] <WireOnboarding> got a permission screen for "${permission}" with no \`request\` ` +
+        "function, so it cannot open the OS dialog and renders as a plain continue. Pass " +
+        "request: () => Promise<'granted' | 'denied' | 'blocked'> (5 lines around " +
+        "expo-notifications, see the README).",
+    );
+  }, [permission]);
+
+  const settle = useCallback((outcome: WirePermissionOutcome) => {
+    if (settledRef.current) return;
+    settledRef.current = true;
+    clearWatchdog();
+    onSettledRef.current?.(outcome);
+  }, [clearWatchdog]);
+
+  const primaryAction: PrimaryAction =
+    status === "blocked" ? "settings" : status === "granted" || !request ? "continue" : "ask";
+
+  const handlePrimary = useCallback(() => {
+    if (settledRef.current || busy) return;
+
+    if (primaryAction === "settings") {
+      onStageRef.current?.("settings", "blocked");
+      try {
+        void Promise.resolve(openSettings?.()).catch(() => {});
+      } catch {
+        // A settings redirect that fails is not a reason to trap the user on this screen.
+      }
+      settle("blocked");
+      return;
+    }
+
+    if (primaryAction === "continue") {
+      // Already granted (nothing to ask), or no `request` was supplied. Report the state as it is;
+      // never report a grant this screen did not produce as anything other than what it is.
+      if (status === "granted") {
+        onStageRef.current?.("granted", "granted");
+        settle("granted");
+      } else {
+        onStageRef.current?.("skipped");
+        settle("skipped");
+      }
+      return;
+    }
+
+    // THE ONE PATH TO THE OS DIALOG, reachable from this press handler only.
+    //
+    // `accepted` is a per-screen boolean, not a per-tap counter: the screen is shown once, and
+    // `accepted / shown` is the rate that says whether the rationale copy works. A second tap after
+    // the watchdog re-armed the UI would push that rate past 100%, so it is emitted once.
+    if (!acceptedRef.current) {
+      acceptedRef.current = true;
+      onStageRef.current?.("accepted");
+    }
+    setBusy(true);
+    // FIRST SETTLEMENT WINS, and `settledRef` is the whole mechanism. The watchdog below can hand
+    // the UI back while a `request` is still outstanding, so a second tap can put a SECOND one in
+    // flight, and the original can answer late. What decides between them is that this function
+    // runs STRAIGHT THROUGH to `settle` with no await in between: the first settlement to arrive
+    // has already flipped that ref by the time any later one is invoked, so the later one returns
+    // on the line below. The flow advances once and each stage event is emitted once. The same ref
+    // is why a settlement landing after the user skipped changes nothing.
+    const finish = (value: unknown) => {
+      if (settledRef.current) return;
+      clearWatchdog();
+      const resolved = normalizePermissionStatus(value);
+      setBusy(false);
+      setStatus(resolved);
+      if (resolved === "granted") {
+        // A light success tap on the grant, through the kit's optional-peer haptics: a host
+        // without `expo-haptics` simply feels nothing and nothing throws.
+        playHaptic("success");
+        onStageRef.current?.("granted", "granted");
+      } else {
+        onStageRef.current?.("denied", resolved);
+      }
+      settle(resolved);
+    };
+
+    // THE WATCHDOG, and what it deliberately does NOT do.
+    //
+    // A host `request` that never settles (a native module that swallows its callback, a promise
+    // that is never resolved) would otherwise BRICK the screen: `busy` disables both buttons, the
+    // secondary re-guards on it, and nothing upstream rescues a rendered card. Dead end, and
+    // `onComplete` never fires.
+    //
+    // So the ceiling exists to un-brick a HOST BUG, never to race the user. A person can sit on an
+    // OS permission dialog for a long time, so a short ceiling that recorded `denied` on expiry
+    // would advance the flow underneath a dialog that is still open and log an outcome the user
+    // never gave. On expiry this therefore fabricates NOTHING: no outcome, no event, no settle. It
+    // only hands the controls back so the user can tap again or skip, and says so in dev.
+    clearWatchdog();
+    watchdogRef.current = setTimeout(() => {
+      watchdogRef.current = null;
+      if (settledRef.current) return;
+      setBusy(false);
+      warnInDev(
+        `[wireai] the \`request\` for the "${permission}" permission screen has not settled after ` +
+          `${Math.round(REQUEST_WATCHDOG_MS / 1000)}s, so the kit handed the controls back rather ` +
+          "than leaving the user on a dead-end screen. It recorded NO outcome, because a pending " +
+          "request is not a denial. Make sure your request resolves to 'granted' | 'denied' | " +
+          "'blocked' on every branch, including the one where the user dismisses the OS dialog.",
+      );
+    }, REQUEST_WATCHDOG_MS);
+
+    try {
+      void Promise.resolve(request?.()).then(finish, () => finish("denied"));
+    } catch {
+      // A synchronously-throwing request is a denial, never a stuck screen.
+      finish("denied");
+    }
+  }, [busy, primaryAction, status, request, openSettings, settle, clearWatchdog, permission]);
+
+  const handleSecondary = useCallback(() => {
+    if (settledRef.current || busy) return;
+    onStageRef.current?.("skipped");
+    settle("skipped");
+  }, [busy, settle]);
+
+  // Art springs in, copy rises behind it (final frame at once under reduce motion).
+  const popT = useRef(new Animated.Value(reduced ? 1 : 0)).current;
+  const titleT = useRef(new Animated.Value(reduced ? 1 : 0)).current;
+  const bodyT = useRef(new Animated.Value(reduced ? 1 : 0)).current;
+  useEffect(() => {
+    if (reduced) {
+      popT.setValue(1);
+      titleT.setValue(1);
+      bodyT.setValue(1);
+      return;
+    }
+    const rise = (value: Animated.Value, delay: number) =>
+      Animated.timing(value, {
+        toValue: 1,
+        duration: scaledMs(INTERSTITIAL_HEAD_MS),
+        delay,
+        easing: easeWire,
+        useNativeDriver: true,
+      });
+    const anims = [
+      Animated.spring(popT, {
+        toValue: 1,
+        friction: STATUS_POP_SPRING.friction,
+        tension: STATUS_POP_SPRING.tension,
+        useNativeDriver: true,
+      }),
+      rise(titleT, scaledMs(INTERSTITIAL_HEAD_STAGGER_MS)),
+      rise(bodyT, scaledMs(INTERSTITIAL_HEAD_STAGGER_MS * 2)),
+    ];
+    anims.forEach((a) => a.start());
+    return () => anims.forEach((a) => a.stop());
+  }, [reduced, popT, titleT, bodyT]);
+
+  const popScale = popT.interpolate({
+    inputRange: [0, 1],
+    outputRange: [STATUS_POP_SCALE_FROM, 1],
+  });
+  const riseStyle = (value: Animated.Value) => ({
+    opacity: value,
+    transform: [
+      { translateY: value.interpolate({ inputRange: [0, 1], outputRange: [RISE_PX, 0] }) },
+    ],
+  });
+
+  const blocked = status === "blocked";
+  const shownTitle = blocked ? (blockedTitle ?? title) : title;
+  const shownMessage = blocked ? (blockedMessage ?? message) : message;
+  const primaryTitle =
+    primaryAction === "settings"
+      ? (settingsLabel ?? primaryLabel)
+      : primaryAction === "continue"
+        ? (continueLabel ?? primaryLabel)
+        : primaryLabel;
+  // Nothing left to decline once the permission is already granted.
+  const showSecondary = status !== "granted";
+
+  return (
+    <CardLayout
+      align="center"
+      footer={
+        <View style={[styles.footer, { gap: t.spacing.sm }]}>
+          <Button title={primaryTitle} onPress={handlePrimary} variant="primary" disabled={busy} />
+          {showSecondary ? (
+            <Button
+              title={secondaryLabel}
+              onPress={handleSecondary}
+              variant="outline"
+              disabled={busy}
+            />
+          ) : null}
+        </View>
+      }
+    >
+      <View style={[styles.center, { gap: t.spacing.md }]}>
+        {art ? (
+          <Animated.View
+            style={[styles.art, { opacity: popT, transform: [{ scale: popScale }] }]}
+          >
+            {art}
+          </Animated.View>
+        ) : null}
+
+        <Animated.View style={riseStyle(titleT)}>
+          <Text style={[headingStyle(t.fonts), { color: t.colors.text, textAlign: "center" }]}>
+            {shownTitle}
+          </Text>
+        </Animated.View>
+
+        <Animated.View style={riseStyle(bodyT)}>
+          <Text style={[bodyStyle(t.fonts), { color: t.colors.textMuted, textAlign: "center" }]}>
+            {shownMessage}
+          </Text>
+        </Animated.View>
+      </View>
+    </CardLayout>
+  );
+};
+
+/** The typed component the flow renders directly (host-injected placement). */
+export const PermissionCardView = React.memo(_PermissionCard);
+
+/**
+ * The SDK registration object, so a server-emitted placement can adopt this exact screen later.
+ * Not part of `onboardingComponents` on purpose - see the file header.
+ */
+export const PermissionCard: WireAIComponent = {
+  name: PERMISSION_CARD_NAME,
+  description:
+    "A priming screen shown BEFORE an OS permission dialog: it explains why the app wants the permission and asks only on the primary tap. Never first, never last. The user is never blocked by it: the secondary advances the flow with the OS prompt unspent.",
+  component: PermissionCardView as WireAIComponent["component"],
+  propsSchema: schema,
+};
+
+const styles = StyleSheet.create({
+  center: { width: "100%", alignItems: "center", justifyContent: "center" },
+  art: { alignItems: "center", justifyContent: "center" },
+  footer: { width: "100%", alignItems: "center" },
+});

package/src/cards/index.ts

@@ -21,9 +21,16 @@ export {
   NumberStepperCard,
   InterstitialCard,
 };
+export { PermissionCard, PermissionCardView, PERMISSION_CARD_NAME } from "./PermissionCard";
+export type { PermissionCardProps } from "./PermissionCard";
 export { normalizeOptions, optionsField, optionObjectSchema } from "./optionSchema";
 export type { CardOption } from "./optionSchema";
 
+// ⚠️ `PermissionCard` is deliberately NOT in this array. The list is what the device ADVERTISES to
+// the backend as renderable (`metadata.supportedComponents`), and a backend told it may emit a
+// permission screen could emit one into a host that injected no `request` function, which the kit
+// has no way to honour. Permission screens are host-declared for now (`permissionScreens`); the
+// card is registered and ready for the day a server-emitted placement lands.
 export const onboardingComponents: WireAIComponent[] = [
   ChipSelectCard,
   TextInputCard,

package/src/config/wireConfigFromEnv.ts

@@ -17,6 +17,7 @@
  */
 import { detectAppVersion } from "../device/appVersion";
 import type { WireOnboardingConfig } from "../types";
+import { warnInDev } from "../utils/warnInDev";
 
 export type WireConfigOverrides = Partial<WireOnboardingConfig>;
 
@@ -27,16 +28,6 @@ export const WIRE_ENV_VARS = [
   "EXPO_PUBLIC_WIREAI_APP_ID",
 ] as const;
 
-/** RN sets this global; absent under node/SSR. Read defensively via {@link warnInDev}. */
-declare const __DEV__: boolean | undefined;
-
-/** Emit a one-line developer warning, but ONLY in a dev build (RN `__DEV__`). No-op in prod/tests. */
-const warnInDev = (message: string): void => {
-  if (typeof __DEV__ !== "undefined" && __DEV__ && typeof console !== "undefined" && console.warn) {
-    console.warn(message);
-  }
-};
-
 /**
  * Minimal `process.env` declaration so the kit stays RN-pure (no `@types/node`).
  * In RN/Expo, `process.env.EXPO_PUBLIC_*` is provided/inlined by Metro at build

package/src/context/deviceId.ts

@@ -18,6 +18,8 @@
  * that verbatim and never mints/persists an auto id.
  */
 
+import { resolveIdentity, type IdentityRecord } from "../identity/identityRecord";
+
 /** Prefix so an auto-minted id is visibly the kit's (distinguishable from a host-supplied `deviceKey`). */
 export const AUTO_DEVICE_ID_PREFIX = "wdev_";
 
@@ -69,12 +71,21 @@ export const mintDeviceId = (): string => {
 /** Well-known key into the runtime-global symbol registry — one auto-id registry across every bundle. */
 const AUTO_DEVICE_KEY_SLOT: unique symbol = Symbol.for("@wireai/activation:autoDeviceKeys");
 
+/** What a hydration settled on: the id, and whether persistence actually CONFIRMED it.
+ *
+ *  `durable: false` means the id lives only in this process's memory — the adapter rejected, threw,
+ *  or there was no adapter at all. That distinction is the whole of K1: a string is a string, so
+ *  before 0.13.0 a caller could not tell a persisted id from a per-launch mint, and the auto-join
+ *  gate (`Boolean(storage)`) was reading the PRESENCE of the prop rather than the SUCCESS of the
+ *  write. See {@link hydrateDeviceIdentity}. */
+type HydrationOutcome = { value: string; durable: boolean };
+
 /** The shared registry: the live id per `appId`, the set of appIds whose hydration already started,
  *  and the in-flight (or settled) hydration promise per `appId` so a waiter can join it. */
 type AutoDeviceKeyRegistry = {
   keys: Map<string, string>;
   hydrating: Set<string>;
-  pending?: Map<string, Promise<string>>;
+  pending?: Map<string, Promise<HydrationOutcome>>;
 };
 
 type GlobalWithDeviceKeys = typeof globalThis & {
@@ -108,40 +119,65 @@ export interface ResolveAutoDeviceKeyOptions {
 }
 
 /**
- * Start (or join) the SINGLE-FLIGHT storage read for `appId` and resolve to the id it settles on.
- * The promise is parked on the registry so a later `hydrateAutoDeviceKey` awaits the SAME read
- * instead of starting a second one. Never rejects: any storage failure resolves to the live id.
+ * Start (or join) the SINGLE-FLIGHT storage read for `appId` and resolve to the {@link HydrationOutcome}
+ * it settles on. The promise is parked on the registry so a later `hydrateAutoDeviceKey` awaits the
+ * SAME read instead of starting a second one. Never rejects: any storage failure resolves to the live
+ * id with `durable: false`.
+ *
+ * TWO OUTCOMES, NOT ONE STRING:
+ *   • ADOPTED (`durable: true`)   — a persisted id was read back, or the freshly minted one was
+ *                                   written successfully. The next launch will see the same id.
+ *   • DEGRADED (`durable: false`) — the adapter rejected, threw, or returned nothing and then failed
+ *                                   the write. The id is real but PROCESS-scoped, so anything that
+ *                                   counts a device across launches must refuse it.
+ *
+ * A DEGRADED outcome also drops the registry latches so the NEXT caller starts a fresh read (K8). A
+ * cold-boot storage lock is transient; caching it as a verdict for the process lifetime turned a
+ * one-second problem into a whole-launch one, and nothing ever retried.
  */
 const startHydration = (
   registry: AutoDeviceKeyRegistry,
   appId: string,
   storage: DeviceKeyStorage,
   minted: string,
-): Promise<string> => {
+): Promise<HydrationOutcome> => {
   if (!registry.pending) registry.pending = new Map();
   const existing = registry.pending.get(appId);
   if (existing) return existing;
 
   const slot = deviceIdStorageKey(appId);
-  const settled = (): string => registry.keys.get(appId) ?? minted;
-  let run: Promise<string>;
+  const degraded = (): HydrationOutcome => ({ value: registry.keys.get(appId) ?? minted, durable: false });
+  const adopted = (value: string): HydrationOutcome => ({ value, durable: true });
+  let run: Promise<HydrationOutcome>;
   try {
     run = Promise.resolve(storage.getItem(slot))
       .then((saved) => {
         const persisted = typeof saved === "string" && saved.trim() ? saved.trim() : undefined;
         if (persisted) {
           registry.keys.set(appId, persisted);
-          return persisted;
+          return adopted(persisted);
         }
         // First run on this install: persist the id we just minted so the next launch adopts it.
-        return Promise.resolve(storage.setItem(slot, minted)).then(settled, settled);
+        // ONLY a resolved write earns `durable` — a rejected one leaves the id in memory alone.
+        return Promise.resolve(storage.setItem(slot, minted)).then(
+          () => adopted(registry.keys.get(appId) ?? minted),
+          degraded,
+        );
       })
-      .catch(settled);
+      .catch(degraded);
   } catch {
     // A storage adapter that throws synchronously — degrade to the in-memory id.
-    run = Promise.resolve(settled());
+    run = Promise.resolve(degraded());
   }
   registry.pending.set(appId, run);
+  // Retry-on-failure (K8): release the latches once a degraded outcome settles, so a later caller
+  // is not permanently bound to one bad read. Registered AFTER the `set` above, so the clean-up can
+  // never race ahead of the entry it is clearing.
+  void run.then((outcome) => {
+    if (outcome.durable) return;
+    registry.pending?.delete(appId);
+    registry.hydrating.delete(appId);
+  });
   return run;
 };
 
@@ -196,15 +232,40 @@ export const resolveAutoDeviceKey = (opts: ResolveAutoDeviceKeyOptions = {}): st
  */
 export const hydrateAutoDeviceKey = async (
   opts: ResolveAutoDeviceKeyOptions = {},
-): Promise<string> => {
+): Promise<string> => (await hydrateDeviceIdentity(opts))?.value ?? resolveAutoDeviceKey(opts);
+
+/**
+ * The PROVENANCE-CARRYING sibling of {@link hydrateAutoDeviceKey}: the same awaited read, but it
+ * answers "is this id one this install will KEEP?" instead of only "what is the id?".
+ *
+ * WHY IT EXISTS (K1). `<WireOnboarding>` gated auto-injection on `Boolean(storage)` — the presence of
+ * the prop — because a string carries no provenance and there was nothing better to gate on. A
+ * REJECTING adapter therefore injected a fresh `wdev_*` on every launch: strictly worse than
+ * injecting nothing, since the server counts `min_sessions` by distinct opens grouped on `device_key`,
+ * so a per-launch key corrupts that counter AND inflates distinct-device counts. Callers that write a
+ * key onto the wire as a cross-launch join must read `durable` and refuse a `false`.
+ *
+ * Resolves `undefined` only when there is no usable id at all. With no `storage` it resolves
+ * immediately with `durable: false` — a process-scoped id is exactly what "no persistence" means.
+ * Never throws or rejects.
+ */
+export const hydrateDeviceIdentity = async (
+  opts: ResolveAutoDeviceKeyOptions = {},
+): Promise<IdentityRecord | undefined> => {
   // Mint + register synchronously first, so a waiter and a concurrent sync caller share ONE id.
   const id = resolveAutoDeviceKey(opts);
-  if (!opts.storage) return id;
-  const registry = autoDeviceKeyRegistry();
   const appId = opts.appId ?? "default";
+  const record = (value: string, durable: boolean): IdentityRecord | undefined =>
+    resolveIdentity({ value, space: "device", source: "auto", durable, scope: appId });
+
+  if (!opts.storage) return record(id, false);
+  const registry = autoDeviceKeyRegistry();
   const pending = registry.pending?.get(appId);
-  if (pending) await pending;
-  return registry.keys.get(appId) ?? id;
+  // No pending entry means a previous hydration already settled DEGRADED and released its latches
+  // (see `startHydration`), so the live id is the in-memory one — real, but not durable.
+  if (!pending) return record(registry.keys.get(appId) ?? id, false);
+  const outcome = await pending;
+  return record(outcome.value, outcome.durable);
 };
 
 /** Test-only: forget every auto id + hydration flag so a unit test starts from a clean registry. */

package/src/context/userContext.ts

@@ -88,19 +88,6 @@ export interface ResolvedUserContext {
   userContext?: Record<string, string | number | boolean>;
 }
 
-/** Reserved `user_context` keys the kit itself writes; host `extra` is namespaced away from these. */
-export const RESERVED_USER_CONTEXT_KEYS = [
-  "device_key",
-  "app_version",
-  "app_build",
-  "network_type",
-  "session_count",
-  "returning",
-  "platform",
-  "user_email",
-  "user_email_hashed",
-] as const;
-
 /** The prefix applied to every host `extra` key so it can never collide with a reserved key. */
 export const EXTRA_KEY_PREFIX = "custom." as const;
 
@@ -127,8 +114,10 @@ export const hashEmailFnv1a = (email: string): string => {
   return (hash >>> 0).toString(16).padStart(8, "0");
 };
 
-/** Trim a candidate string; return `undefined` for a non-string / blank so callers can `if`-gate. */
-const cleanString = (value: unknown): string | undefined => {
+/** Trim a candidate string; return `undefined` for a non-string / blank so callers can `if`-gate.
+ *  Shared with `activation/wireActivation`, which carried a byte-identical private copy named `clean`.
+ *  Not re-exported from the package barrel — this is an internal helper, not public surface. */
+export const cleanString = (value: unknown): string | undefined => {
   if (typeof value !== "string") return undefined;
   const trimmed = value.trim();
   return trimmed.length > 0 ? trimmed : undefined;