@wireai/activation 0.7.0 → 0.9.0

package/src/reviews/ReviewGate.tsx

@@ -3,17 +3,29 @@
  *
  * A NEUTRAL prompt ("Enjoying <app>?") over five tappable stars. The honest split:
  *   • 5 stars → the native store review (expo-store-review when available, else the
- *     configured store URL). Fires `store_review_requested`.
- *   • 1-4 stars → a feather-light feedback form: TWO optional inputs, the "why this
- *     rating" opinion box (~4 lines) and a smaller "what can you suggest" box, POSTed
- *     to the Wire server (`feedback_text` + `suggestion`). The rating is the only
- *     mandatory action, so Send works with either box, both, or neither. Warm
- *     thank-you state, never a dead end.
+ *     configured store URL). Fires `store_review_requested`, and POSTs a text-less
+ *     `stars=5` row carrying `meta.store_route` so promoters reach the server too
+ *     (before 2026-07-16 this route posted nothing — see `pickRating`).
+ *   • 1-4 stars → a feedback form: the "why this rating" opinion box (~4 lines, MANDATORY
+ *     as of Malik's 2026-07-16 ruling) and a smaller optional "what can you suggest" box,
+ *     POSTed to the Wire server (`feedback_text` + `suggestion`). Warm thank-you state,
+ *     never a dead end.
+ *
+ * EXACTLY ONE row is POSTed per gate, at the last responsible moment — see `postOnce`. A
+ * detractor who abandons instead of typing still has their rating posted (`meta.abandoned`),
+ * so forcing the text can never cost us the detractor data it exists to collect.
  *
  * The form NEVER asks for identity (no name / email / contact field): the host already
  * identifies the user via `sessionId` + `meta` (e.g. user_id, device_key), which is all
  * the POST body carries alongside the rating and the free text.
  *
+ * Motion (2026-07-16): the three phases used to swap IN PLACE with no transition. They now
+ * ride `ModalPaneHost`, the same pane-slide primitive the questionnaire steps use, and the
+ * thank-you plays the shared `DoneCheck` payoff before the existing 1500ms auto-close.
+ * Picking a star fires a haptic through the lazy, optional `expo-haptics` peer — silently
+ * absent when the host has not installed it. The popup's own entrance is unchanged: it is
+ * the CenteredModal shell's spring, which already animates.
+ *
  * Every visual value comes from the OnboardingTheme (useOnboardingTheme). Analytics are
  * callback-based (mirroring the coachmark convention): the host wires `onEvent` to its own
  * analytics. No PII in events — feedback text goes ONLY in the POST body.
@@ -25,8 +37,11 @@ import React, { useCallback, useMemo, useState } from "react";
 import { Pressable, StyleSheet, Text, TextInput, View } from "react-native";
 
 import { Button } from "../components/Button";
+import { DoneCheck } from "../components/DoneCheck";
+import { ModalPaneHost } from "../components/ModalPaneHost";
+import { playHaptic } from "../haptics/haptics";
+import { mergeThemeOver } from "../theme/mergeThemeOver";
 import { useOnboardingTheme } from "../theme/ThemeContext";
-import type { OnboardingTheme } from "../theme/types";
 import { bodyStyle, captionStyle, headingStyle } from "../theme/typography";
 import { buildReviewSubmission, routeRating } from "./decision";
 import { feedbackInputHeights } from "./feedbackForm";
@@ -34,21 +49,7 @@ import { resolvePresentation } from "./presentation";
 import { ReviewModal, type ReviewModalHandle } from "./ReviewModal";
 import { requestStoreReview } from "./storeReview";
 import { submitReview } from "./transport";
-import type { ReviewGateProps } from "./types";
-
-const mergeThemeOver = (
-  base: OnboardingTheme,
-  override?: Partial<OnboardingTheme>,
-): OnboardingTheme => {
-  if (!override) return base;
-  return {
-    colors: { ...base.colors, ...override.colors },
-    fonts: { ...base.fonts, ...override.fonts },
-    radius: { ...base.radius, ...override.radius },
-    spacing: { ...base.spacing, ...override.spacing },
-    button: { ...base.button, ...override.button },
-  };
-};
+import type { ReviewGateProps, ReviewSubmission } from "./types";
 
 type Phase = "rating" | "feedback" | "thanks";
 
@@ -106,6 +107,57 @@ const _ReviewGate: React.FC<ReviewGateProps> = ({
     onResolved?.();
   }, [onResolved]);
 
+  /**
+   * EXACTLY ONE review row per gate, ever — the latch that makes "force feedback" safe.
+   *
+   * WHY ONE POST AND NOT TWO: the tempting design is to post the rating at star-tap and then
+   * post again with the text, enriching the first row. That needs the server to accept a
+   * client-supplied id so the second write UPSERTS. It does not, as deployed today:
+   * `create_review` mints its own id unconditionally (`app/reviews.py` `_new_id()`) and
+   * `CreateReviewRequest` (`app/schemas.py`) has no id field — so two posts = two rows, which
+   * double-counts `count` and corrupts `avg`. That is the SAME class of data corruption this
+   * whole change exists to fix. And `submitReview` is fire-and-forget (transport.ts: the
+   * response is never read), so the kit CANNOT detect a rejection and repair it: a wrong guess
+   * fails silently and permanently. So we post once, at the last responsible moment, and never
+   * depend on an unmerged/undeployed server capability.
+   */
+  const postedRef = React.useRef(false);
+  const postOnce = useCallback(
+    (body: ReviewSubmission) => {
+      if (postedRef.current) return;
+      postedRef.current = true;
+      submitReview(target, body);
+    },
+    [target],
+  );
+
+  /**
+   * The abandonment safety net, and the reason forcing feedback does not COST us detractor data.
+   *
+   * Malik's ruling: a 1-4 rater must leave text. Implemented naively (block Send, remove Skip),
+   * that would LOSE the ratings of everyone who bails rather than types — the detractors we most
+   * need — because today the 1-4 branch posts only from `sendFeedback`. So: if the gate goes away
+   * while a rating is pending and unposted, we post the rating anyway, with whatever text was
+   * typed, flagged `meta.abandoned`. The user is pushed to explain; the rating is never the price.
+   *
+   * Read through a ref and fired from an unmount-only effect, so it always sees the latest
+   * state without re-subscribing (the same ref convention `review_prompt_shown` above uses).
+   */
+  const abandonRef = React.useRef<() => void>(() => {});
+  abandonRef.current = () => {
+    if (postedRef.current || stars < 1) return;
+    postOnce(
+      buildReviewSubmission({
+        stars,
+        feedbackText: feedback,
+        suggestion,
+        sessionId,
+        meta: { ...meta, abandoned: true },
+      }),
+    );
+  };
+  React.useEffect(() => () => abandonRef.current(), []);
+
   const resolveWithDelay = useCallback(() => {
     if (resolveTimer.current) clearTimeout(resolveTimer.current);
     resolveTimer.current = setTimeout(() => {
@@ -120,20 +172,61 @@ const _ReviewGate: React.FC<ReviewGateProps> = ({
   const pickRating = useCallback(
     async (value: number) => {
       setStars(value);
+      // The tap you feel. Fire-and-forget: an absent peer must never delay the route below.
+      playHaptic("selection");
       onEvent?.({ name: "review_rating_selected", id, stars: value });
       if (routeRating(value) === "store") {
         onEvent?.({ name: "store_review_requested", id, stars: value });
-        await requestStoreReview(store);
+        const route = await requestStoreReview(store);
+        // The 5-star row. Until 2026-07-16 this branch POSTed NOTHING: submitReview was
+        // reachable only from the feedback phase, which only the 1-4 route enters. Every
+        // promoter was silently dropped, so server-side `by_stars["5"]` and `store_routed`
+        // were permanently 0 and `avg` averaged detractors only. The four onEvent moments
+        // above go to the HOST's analytics, never to Wire, so nothing else covered this.
+        //
+        // The body is `stars` + `meta` with NO feedback text — exactly the shape the server
+        // already documents as the store route ("A 5-star tap posts stars=5 with no text")
+        // and the shape its `store_routed` aggregate counts (stars == 5 and not
+        // feedback_text). So this is valid against prod as deployed, with no server change.
+        //
+        // `store_route` records WHICH route we took (native dialog / store URL / neither).
+        // Honest ceiling: requestStoreReview is OS-quota'd and reports nothing about whether
+        // the user actually left a review — this only ever means we ASKED. Never read it as
+        // a review count. We await first so the row carries the route it actually took.
+        postOnce(
+          buildReviewSubmission({
+            stars: value,
+            sessionId,
+            meta: { ...meta, store_route: route },
+          }),
+        );
         setPhase("thanks");
         resolveWithDelay();
       } else {
+        // 1-4: no post yet. The row lands either from `sendFeedback` (with the forced text) or
+        // from the abandonment net above — one row, whichever happens first.
         setPhase("feedback");
       }
     },
-    [onEvent, id, store, resolveWithDelay],
+    [onEvent, id, store, postOnce, sessionId, meta, resolveWithDelay],
   );
 
+  /**
+   * Malik's ruling (2026-07-16): a 1-4 rater is FORCED to leave feedback. Enforced HERE, on the
+   * client, and deliberately NOT on the wire: `feedback_text` stays optional in
+   * `CreateReviewRequest`, because the transport is fire-and-forget and every already-shipped
+   * client still posts text-less rows — tightening the server would silently 422 them into
+   * oblivion. Permissive wire, strict client.
+   *
+   * Mirrors the questionnaire contract exactly: the opinion box is the mandatory one, the
+   * suggestion box stays optional. Trimmed — whitespace is not feedback.
+   */
+  const feedbackReady = feedback.trim().length > 0;
+
   const sendFeedback = useCallback(() => {
+    // The forced-text gate. Also guarded here, not just on the button's `disabled`, so the
+    // rule holds no matter who calls this.
+    if (!feedbackReady) return;
     // Identity is NEVER collected here — the host already sends user_id / device /
     // session via `sessionId` + `meta`. We POST only the rating + the free text.
     const body = buildReviewSubmission({
@@ -143,11 +236,12 @@ const _ReviewGate: React.FC<ReviewGateProps> = ({
       sessionId,
       meta,
     });
-    submitReview(target, body);
+    postOnce(body);
     onEvent?.({ name: "review_feedback_submitted", id, stars });
+    playHaptic("success");
     setPhase("thanks");
     resolveWithDelay();
-  }, [stars, feedback, suggestion, sessionId, meta, target, onEvent, id, resolveWithDelay]);
+  }, [feedbackReady, stars, feedback, suggestion, sessionId, meta, postOnce, onEvent, id, resolveWithDelay]);
 
   const dismiss = useCallback(() => {
     setPhase("thanks");
@@ -162,15 +256,6 @@ const _ReviewGate: React.FC<ReviewGateProps> = ({
     else dismiss();
   }, [mode, dismiss]);
 
-  const title =
-    phase === "feedback"
-      ? "What should we improve?"
-      : phase === "thanks"
-        ? "Thank you"
-        : appName
-          ? `Enjoying ${appName}?`
-          : "How's your experience?";
-
   const surface = {
     backgroundColor: t.colors.surface,
     borderRadius: t.radius.lg,
@@ -183,129 +268,141 @@ const _ReviewGate: React.FC<ReviewGateProps> = ({
   // padding is folded in so the requested lines are visible inside the padding.
   const feedbackBox = feedbackInputHeights(t.fonts, t.spacing.md);
 
-  // The phase content, shared by both presentations. In "modal" mode ReviewModal supplies
-  // the centered, dimmed, animated card surface; in "inline" mode the bare card below does.
-  const content = (
-    <>
-      <Text style={[headingStyle(t.fonts), { color: t.colors.text }]}>{title}</Text>
+  const linkStyle = [captionStyle(t.fonts), styles.link, { color: t.colors.textMuted }];
 
-      {phase === "rating" && (
-        <>
-          <Text style={[captionStyle(t.fonts), { color: t.colors.textMuted }]}>
-            Tap a star to let us know.
-          </Text>
-          <View style={styles.stars}>
-            {[1, 2, 3, 4, 5].map((n) => {
-              const filled = n <= (hovered || stars);
-              return (
-                <Pressable
-                  key={n}
-                  onPressIn={() => setHovered(n)}
-                  onPressOut={() => setHovered(0)}
-                  onPress={() => void pickRating(n)}
-                  accessibilityRole="button"
-                  accessibilityLabel={`${n} star${n > 1 ? "s" : ""}`}
-                  hitSlop={8}
-                >
-                  <Text
-                    style={[
-                      styles.star,
-                      { color: filled ? t.colors.primary : t.colors.border },
-                    ]}
-                  >
-                    {filled ? "★" : "☆"}
-                  </Text>
-                </Pressable>
-              );
-            })}
-          </View>
-          {dismissible && (
-            <Pressable onPress={handleDismissTap} hitSlop={8}>
-              <Text style={[captionStyle(t.fonts), styles.link, { color: t.colors.textMuted }]}>
-                Not now
+  // Each phase is a self-contained PANE, title included, so the heading travels with its
+  // content instead of swapping under a static header — one moving surface, not two.
+  const ratingPane = (
+    <View style={{ gap: t.spacing.md }}>
+      <Text style={[headingStyle(t.fonts), { color: t.colors.text }]}>
+        {appName ? `Enjoying ${appName}?` : "How's your experience?"}
+      </Text>
+      <Text style={[captionStyle(t.fonts), { color: t.colors.textMuted }]}>
+        Tap a star to let us know.
+      </Text>
+      <View style={styles.stars}>
+        {[1, 2, 3, 4, 5].map((n) => {
+          const filled = n <= (hovered || stars);
+          return (
+            <Pressable
+              key={n}
+              onPressIn={() => setHovered(n)}
+              onPressOut={() => setHovered(0)}
+              onPress={() => void pickRating(n)}
+              accessibilityRole="button"
+              accessibilityLabel={`${n} star${n > 1 ? "s" : ""}`}
+              hitSlop={8}
+            >
+              <Text style={[styles.star, { color: filled ? t.colors.primary : t.colors.border }]}>
+                {filled ? "★" : "☆"}
               </Text>
             </Pressable>
-          )}
-        </>
+          );
+        })}
+      </View>
+      {dismissible && (
+        <Pressable
+          onPress={handleDismissTap}
+          hitSlop={8}
+          accessibilityRole="button"
+          accessibilityLabel="Dismiss the review prompt"
+        >
+          <Text style={linkStyle}>Not now</Text>
+        </Pressable>
       )}
+    </View>
+  );
 
-      {phase === "feedback" && (
-        <>
-          <Text style={[captionStyle(t.fonts), { color: t.colors.textMuted }]}>
-            A few words is plenty. Both boxes are optional, so send whatever you like.
-          </Text>
-          {/* Two OPTIONAL inputs. No name / email / contact field: the host already
-              identifies the user via sessionId + meta, so we never ask for identity
-              here. Send stays enabled whether the user fills one box, both, or neither
-              (the rating is the only mandatory action). */}
-          <Text style={[captionStyle(t.fonts), { color: t.colors.textMuted }]}>
-            Why this rating? (optional)
-          </Text>
-          <TextInput
-            value={feedback}
-            onChangeText={setFeedback}
-            placeholder="e.g. too many steps"
-            placeholderTextColor={t.colors.textMuted}
-            multiline
-            textAlignVertical="top"
-            style={[
-              bodyStyle(t.fonts),
-              styles.input,
-              {
-                color: t.colors.text,
-                backgroundColor: t.colors.background,
-                borderRadius: t.radius.md,
-                borderColor: t.colors.border,
-                padding: t.spacing.md,
-                minHeight: feedbackBox.minHeight,
-                maxHeight: feedbackBox.maxHeight,
-              },
-            ]}
-          />
-          <Text style={[captionStyle(t.fonts), { color: t.colors.textMuted }]}>
-            What can we do better? (optional)
-          </Text>
-          <TextInput
-            value={suggestion}
-            onChangeText={setSuggestion}
-            placeholder="e.g. save my place between steps"
-            placeholderTextColor={t.colors.textMuted}
-            style={[
-              bodyStyle(t.fonts),
-              styles.input,
-              {
-                color: t.colors.text,
-                backgroundColor: t.colors.background,
-                borderRadius: t.radius.md,
-                borderColor: t.colors.border,
-                paddingHorizontal: t.spacing.md,
-                paddingVertical: t.spacing.sm,
-                minHeight: t.button.height,
-              },
-            ]}
-          />
-          <Button
-            title="Send feedback"
-            onPress={sendFeedback}
-            variant="primary"
-            fullWidth
-          />
-          {dismissible && (
-            <Pressable onPress={handleDismissTap} hitSlop={8}>
-              <Text style={[captionStyle(t.fonts), styles.link, { color: t.colors.textMuted }]}>
-                Skip
-              </Text>
-            </Pressable>
-          )}
-        </>
-      )}
+  const feedbackPane = (
+    <View style={{ gap: t.spacing.md }}>
+      <Text style={[headingStyle(t.fonts), { color: t.colors.text }]}>What should we improve?</Text>
+      <Text style={[captionStyle(t.fonts), { color: t.colors.textMuted }]}>
+        A few words is plenty — tell us what went wrong and we'll fix it.
+      </Text>
+      {/* No name / email / contact field: the host already identifies the user via
+          sessionId + meta, so we never ask for identity here. As of Malik's 2026-07-16
+          ruling the FIRST box is mandatory (mirroring the questionnaire's `opinion`);
+          the suggestion box stays optional. */}
+      <Text style={[captionStyle(t.fonts), { color: t.colors.textMuted }]}>
+        Why this rating?
+      </Text>
+      <TextInput
+        value={feedback}
+        onChangeText={setFeedback}
+        placeholder="e.g. too many steps"
+        placeholderTextColor={t.colors.textMuted}
+        accessibilityLabel="Why this rating?"
+        multiline
+        textAlignVertical="top"
+        style={[
+          bodyStyle(t.fonts),
+          styles.input,
+          {
+            color: t.colors.text,
+            backgroundColor: t.colors.background,
+            borderRadius: t.radius.md,
+            borderColor: t.colors.border,
+            padding: t.spacing.md,
+            minHeight: feedbackBox.minHeight,
+            maxHeight: feedbackBox.maxHeight,
+          },
+        ]}
+      />
+      <Text style={[captionStyle(t.fonts), { color: t.colors.textMuted }]}>
+        What can we do better? (optional)
+      </Text>
+      <TextInput
+        value={suggestion}
+        onChangeText={setSuggestion}
+        placeholder="e.g. save my place between steps"
+        placeholderTextColor={t.colors.textMuted}
+        accessibilityLabel="What can we do better? (optional)"
+        style={[
+          bodyStyle(t.fonts),
+          styles.input,
+          {
+            color: t.colors.text,
+            backgroundColor: t.colors.background,
+            borderRadius: t.radius.md,
+            borderColor: t.colors.border,
+            paddingHorizontal: t.spacing.md,
+            paddingVertical: t.spacing.sm,
+            minHeight: t.button.height,
+          },
+        ]}
+      />
+      <Button
+        title="Send feedback"
+        onPress={sendFeedback}
+        variant="primary"
+        fullWidth
+        disabled={!feedbackReady}
+      />
+      {/* No Skip here — this step is mandatory (Malik, 2026-07-16). The rating itself is
+          still never held hostage: bailing out of the gate entirely (backdrop / Android
+          back / navigation) posts it through the abandonment net above. We do NOT trap the
+          user in the modal; forcing the TEXT is the rule, imprisoning them is not. */}
+    </View>
+  );
 
-      {phase === "thanks" && (
-        <Text style={[bodyStyle(t.fonts), { color: t.colors.textMuted }]}>
-          We appreciate you. This helps us make it better.
-        </Text>
-      )}
-    </>
+  const thanksPane = (
+    <View style={{ gap: t.spacing.md }}>
+      <DoneCheck theme={t} />
+      <Text style={[headingStyle(t.fonts), styles.centerText, { color: t.colors.text }]}>
+        Thank you
+      </Text>
+      <Text style={[bodyStyle(t.fonts), styles.centerText, { color: t.colors.textMuted }]}>
+        We appreciate you. This helps us make it better.
+      </Text>
+    </View>
+  );
+
+  // The phase content, shared by both presentations. In "modal" mode ReviewModal supplies
+  // the centered, dimmed, animated card surface; in "inline" mode the bare card below does.
+  const content = (
+    <ModalPaneHost paneKey={phase}>
+      {phase === "rating" ? ratingPane : phase === "feedback" ? feedbackPane : thanksPane}
+    </ModalPaneHost>
   );
 
   // Default: a centered popup over a dimmed backdrop with a spring/fade entrance. A backdrop
@@ -331,6 +428,7 @@ const styles = StyleSheet.create({
   star: { fontSize: 40, lineHeight: 46 },
   input: { borderWidth: 1 },
   link: { textAlign: "center", textDecorationLine: "underline" },
+  centerText: { textAlign: "center" },
 });
 
 export default ReviewGate;

package/src/reviews/index.ts

@@ -50,9 +50,12 @@ export type { FeedbackInputHeights } from "./feedbackForm";
 // ─── The 5-star store path (optional peer + URL fallback) ─────────────────────
 export { requestStoreReview, openStoreListing, storeUrl } from "./storeReview";
 
-// ─── Server transport: submit a review + report generic app.* events ──────────
-export { submitReview, reportAppEvent } from "./transport";
-export type { ReportAppEventOptions } from "./transport";
+// ─── Server transport: submit a review, FETCH THE FIRING DECISION, report app.* events ──
+// `fetchReviewDecision` is the mirror of `fetchQuestionnaireDecision`. Use it instead of
+// hand-rolling a decision fetch: a host-rolled one that collapses `{fire:false}` into undefined
+// makes the server able to turn prompts ON but never OFF (the 2026-07-16 first-session incident).
+export { submitReview, fetchReviewDecision, reportAppEvent } from "./transport";
+export type { FetchReviewDecisionOptions, ReportAppEventOptions } from "./transport";
 
 // ─── Gate-key + storage helpers (shared coachmark storage singleton) ──────────
 export {
@@ -64,6 +67,7 @@ export {
 // ─── Types ────────────────────────────────────────────────────────────────────
 export type {
   ReviewDecision,
+  ReviewDecisionResponse,
   RatingRoute,
   ReviewConfig,
   ReviewStoreConfig,

package/src/reviews/transport.ts

@@ -3,15 +3,16 @@
  * (analytics/reviews must never break the app). Mirrors analytics/reportClientEvent: a
  * thin fetch wrapper, Bearer tenant key, swallow every error.
  *
- *   • submitReview        → POST {serverUrl}/v1/reviews   (the 1-4 feedback body)
- *   • reportAppEvent      → POST {serverUrl}/v1/events    (generic app.* namespace)
+ *   • submitReview         → POST {serverUrl}/v1/reviews          (the review row)
+ *   • fetchReviewDecision  → GET  {serverUrl}/v1/reviews/decision (best-effort, the AI seam)
+ *   • reportAppEvent       → POST {serverUrl}/v1/events           (generic app.* namespace)
  *
  * `reportAppEvent` is the strategic extension: it lets a host report arbitrary in-app
  * events through the SAME transport (stored server-side as event_type='app_event',
  * question_key=<name>), which is what the backend review-firing rules evaluate on — and
  * it seeds the broader app-analytics stream. Keep payloads minimal + non-PII.
  */
-import type { ReviewSubmission, ReviewTarget } from "./types";
+import type { ReviewDecisionResponse, ReviewSubmission, ReviewTarget } from "./types";
 
 /**
  * POST a review (the 1-4 feedback path). Fire-and-forget: a missing target, a build error,
@@ -38,6 +39,79 @@ export const submitReview = (
   }
 };
 
+/** Options for the best-effort review decision fetch. */
+export interface FetchReviewDecisionOptions {
+  /**
+   * The onboarding session id, when there IS one. OPTIONAL on purpose: the review gate lives on
+   * the home feed, where a user legitimately has no onboarding session. `deviceKey` is the real
+   * identity for this call. (Today's prod still requires `session_id` and answers 422 without it;
+   * the server relaxation is unmerged. A 422 is a non-2xx, so it returns null like any other
+   * failure, and the local rules stand. Permissive wire: do NOT make this required here.)
+   */
+  sessionId?: string;
+  /** A stable, non-PII device id. The decision endpoint reads it for cooldown + min-sessions. */
+  deviceKey?: string;
+}
+
+/**
+ * Best-effort fetch of the SERVER's review firing decision. The mirror of
+ * `fetchQuestionnaireDecision`, and the primitive whose absence caused a live incident.
+ *
+ * ── WHY THIS LIVES IN THE KIT (Malik, 2026-07-16) ────────────────────────────────────────
+ *
+ * The questionnaire module has always had its decision fetch; reviews never did. So a host
+ * hand-rolled one, and got it subtly wrong: its helper collapsed an explicit `{fire:false}`
+ * into `undefined`. `decideReview` is `(local, decision) => decision ?? local`, so `undefined`
+ * means "the server has no opinion, use the local rules" — and the local timer fired. The
+ * server could therefore only ever turn review prompts ON, never OFF. A real user was asked to
+ * rate the app ~3 minutes into their FIRST session, having seen nothing yet, and left 1 star.
+ *
+ * The bug was not that the host was careless. It was that the kit made every host invent this.
+ * So the primitive moves here and hosts keep a thin call site.
+ *
+ * ── THE CONTRACT THAT MATTERS ────────────────────────────────────────────────────────────
+ *
+ *   • 2xx  → the FULL `{fire, reason, arm}`, INCLUDING `fire:false`. Never collapse a false
+ *            into null. That collapse IS the bug: a false must reach `decideReview` intact so
+ *            it can override the local rules and keep the gate shut.
+ *   • else → null, and ONLY then. Null means "the server genuinely has no opinion", which is
+ *            the one case where falling back to local rules is correct.
+ *
+ * Never throws: unreachable, non-2xx (incl. today's 422), bad JSON, or a missing `fetch` all
+ * resolve to null. The kit does not call this internally; a host awaits it and passes the
+ * result straight to `useReviewGate({ decision })`.
+ *
+ *   const decision = await fetchReviewDecision(target, { deviceKey });
+ *   const gate = useReviewGate({ config, decision: decision ?? undefined, storage });
+ */
+export const fetchReviewDecision = async (
+  target: ReviewTarget | undefined,
+  options: FetchReviewDecisionOptions = {},
+): Promise<ReviewDecisionResponse | null> => {
+  if (!target?.serverUrl) return null;
+  try {
+    const base = target.serverUrl.replace(/\/$/, "");
+    const params = new URLSearchParams();
+    if (options.sessionId) params.set("session_id", options.sessionId);
+    if (options.deviceKey) params.set("device_key", options.deviceKey);
+    const qs = params.toString();
+    const url = `${base}/v1/reviews/decision${qs ? `?${qs}` : ""}`;
+    const headers: Record<string, string> = {};
+    if (target.apiKey) headers.Authorization = `Bearer ${target.apiKey}`;
+    const res = await fetch(url, { headers });
+    if (!res || !res.ok) return null;
+    const json = (await res.json()) as ReviewDecisionResponse | null;
+    // A body without a boolean `fire` is not a decision. Guard it explicitly rather than
+    // letting `{}` through as a truthy object that `decideReview` would treat as a verdict
+    // (`{}.fire === undefined` is falsy, so it would silently read as "never fire").
+    if (!json || typeof json.fire !== "boolean") return null;
+    return json;
+  } catch {
+    /* unreachable / non-2xx / bad JSON / missing-fetch → the server has no opinion */
+    return null;
+  }
+};
+
 /** Options for a reported app event. `deviceKey` groups a device's sessions server-side. */
 export interface ReportAppEventOptions {
   /** The onboarding/session id to correlate with, when known. */

package/src/reviews/types.ts

@@ -19,6 +19,19 @@ export interface ReviewDecision {
   reason?: string;
 }
 
+/**
+ * The `GET /v1/reviews/decision` response: `ReviewDecision` plus the additive `arm`.
+ *
+ * `arm` is the firing experiment's sticky assignment for this device/session. Echo it back in
+ * the submission's `meta.firing_arm` and the server keeps it verbatim (`_stamp_firing_arm`:
+ * "an arm the kit already echoed is left as-is"); omit it and the server recomputes from the
+ * sticky hash. Echoing is what makes per-arm attribution survive a later reweighting of the
+ * experiment, so a host running one should pass it through.
+ */
+export interface ReviewDecisionResponse extends ReviewDecision {
+  arm?: string | null;
+}
+
 /** Where to route a rating: 5 stars → the store, 1-4 → the feedback form. */
 export type RatingRoute = "store" | "feedback";
 

package/src/session/persistedSession.ts

@@ -39,7 +39,7 @@ export const DEFAULT_SESSION_TTL_MS = 3_600_000;
 /** Ceiling on the storage read — a hung adapter degrades to a fresh mint, never a stuck gate. */
 const READ_TIMEOUT_MS = 1_500;
 
-/** Storage key for an app's cached session, e.g. `wireai:session:myelino`. */
+/** Storage key for an app's cached session, e.g. `wireai:session:acme`. */
 export const sessionStorageKey = (appId: string): string => `wireai:session:${appId}`;
 
 type PersistedSession = { id: string; ts: number };