@wireai/activation 0.13.2 → 0.13.3

package/src/coachmarks/useCoachmarkTour.ts

@@ -1,8 +1,14 @@
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useRef, useState, useSyncExternalStore } from "react";
 
 import { coachmarkAnchors } from "./coachmarkAnchorRegistry";
 import { coachmarkOverlay } from "./coachmarkOverlayStore";
-import { areCoachmarksEnabled, coachmarkGateKey, hasSeenGate, markSeenGate } from "./runtime";
+import {
+  areCoachmarksEnabled,
+  coachmarkGateKey,
+  hasSeenGate,
+  markSeenGate,
+  subscribeCoachmarksEnabled,
+} from "./runtime";
 import type { CoachmarkStep } from "./types";
 
 export interface UseCoachmarkTourOptions {
@@ -61,6 +67,15 @@ const DEFAULT_START_DELAY_MS = 3000;
  * target is picked up. `onStepShown` is suppressed on that resume (last-shown
  * step id is tracked in a ref) so a pause/resume never double-counts a step.
  *
+ * KILL SWITCH vs PAUSE — two different gates, two different endings. `enabled` is the host's
+ * domain gate and PAUSES (position kept, gate unwritten, resumes on the same step). The tenant's
+ * coachmarks feature flag (`setCoachmarksEnabled`, from GET /v1/features) is TERMINAL: flipped off
+ * mid-tour it ends the tour and fires `onComplete`, but does NOT write the once-gate, so the tour
+ * replays on the next mount once the flag is back on. It is read through a subscription rather
+ * than sampled, because the flip has to reach a tour that is already in flight: the overlay's
+ * `show()` is a no-op while the flag is off, so a tour that carried on would paint nothing, could
+ * not be tapped to advance, and would never reach a terminal state.
+ *
  * IMPORTANT: `steps` MUST be a stable (memoized) array. If a new array identity
  * is passed on every render the drive effect re-runs and re-shows the current
  * step (wasteful anchor re-resolves / overlay churn), and analytics can
@@ -97,34 +112,67 @@ export const useCoachmarkTour = (
   const callbacksRef = useRef({ onStepShown, onStepEngaged, onStepDismissed });
   callbacksRef.current = { onStepShown, onStepEngaged, onStepDismissed };
 
-  const finish = useCallback(() => {
-    if (finishedRef.current) return;
-    finishedRef.current = true;
-    if (showOnce) markSeenGate(coachmarkGateKey(tourId));
-    coachmarkOverlay.hide();
-    setActiveIndex(null);
-    onComplete?.();
-  }, [onComplete, showOnce, tourId]);
+  // The tenant's coachmarks kill switch, SUBSCRIBED rather than sampled so a mid-tour flip reaches
+  // a tour already in flight. See the KILL SWITCH vs PAUSE note above.
+  const coachmarksOn = useSyncExternalStore(
+    subscribeCoachmarksEnabled,
+    areCoachmarksEnabled,
+    areCoachmarksEnabled,
+  );
+
+  /**
+   * The single terminal exit. `writeGate` is what separates the two ways a tour can end:
+   *   • the user reached the end (or dismissed the last step) → the once-gate IS written, so a
+   *     finished tour never nags again;
+   *   • the kill switch went off mid-tour → the gate is NOT written. That gate belongs to a tour
+   *     the user actually saw, and the module's whole kill-switch contract is that disabling
+   *     never consumes it, so re-enabling replays the tour.
+   * Either way `onComplete` fires: a host that gates its own UI on the tour finishing must not be
+   * left waiting on a callback that can no longer arrive.
+   */
+  const exit = useCallback(
+    (writeGate: boolean) => {
+      if (finishedRef.current) return;
+      finishedRef.current = true;
+      if (writeGate && showOnce) markSeenGate(coachmarkGateKey(tourId));
+      coachmarkOverlay.hide();
+      setActiveIndex(null);
+      onComplete?.();
+    },
+    [onComplete, showOnce, tourId],
+  );
+
+  const finish = useCallback(() => exit(true), [exit]);
 
   // Arm once, after the delay, when enabled and the gate is unseen.
   useEffect(() => {
     if (!enabled || startedRef.current) return undefined;
     // Feature kill switch: never arm while coachmarks are disabled, so no timer starts, no
-    // overlay shows, and the once-gate is NOT consumed — re-enabling replays the tour.
-    if (!areCoachmarksEnabled()) return undefined;
+    // overlay shows, and the once-gate is NOT consumed — re-enabling replays the tour. Reading
+    // the SUBSCRIBED value (and listing it in the deps) is what makes that last clause true
+    // without a remount: flipping it off clears a pending arm timer, flipping it back on re-arms.
+    if (!coachmarksOn) return undefined;
     if (showOnce && hasSeenGate(coachmarkGateKey(tourId))) return undefined;
     const timer = setTimeout(() => {
       startedRef.current = true;
       setActiveIndex(0);
     }, startDelayMs);
     return () => clearTimeout(timer);
-  }, [enabled, startDelayMs, showOnce, tourId]);
+  }, [enabled, coachmarksOn, startDelayMs, showOnce, tourId]);
 
   // Drive the active step. Keyed on `enabled` too, so a mid-tour focus loss
   // pauses (hide, keep position) and a return to focus resumes the same step.
   useEffect(() => {
     if (activeIndex === null) return undefined;
 
+    // KILL SWITCH, mid-tour: exit terminally, WITHOUT writing the once-gate, so the tour replays
+    // when it is switched back on. Checked BEFORE the pause branch below — a disable is terminal,
+    // a focus loss is not.
+    if (!coachmarksOn) {
+      exit(false);
+      return undefined;
+    }
+
     // PAUSE: armed but the screen lost focus (enabled flipped false while in
     // flight). Hide the overlay so a stale rect can't float over the wrong
     // screen, but KEEP activeIndex and DON'T write the gate. When enabled
@@ -188,7 +236,7 @@ export const useCoachmarkTour = (
     return () => {
       cancelled = true;
     };
-  }, [activeIndex, steps, finish, enabled]);
+  }, [activeIndex, steps, finish, exit, enabled, coachmarksOn]);
 
   // Safety: clear the overlay if the screen unmounts mid-tour.
   useEffect(

package/src/context/deviceId.ts

@@ -74,7 +74,7 @@ const AUTO_DEVICE_KEY_SLOT: unique symbol = Symbol.for("@wireai/activation:autoD
 /** 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
+ *  or there was no adapter at all. That distinction is the whole point here: 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}. */
@@ -131,7 +131,7 @@ export interface ResolveAutoDeviceKeyOptions {
  *                                   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
+ * A DEGRADED outcome also drops the registry latches so the NEXT caller starts a fresh read. 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.
  */
@@ -170,7 +170,7 @@ const startHydration = (
     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
+  // Retry-on-failure: 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) => {
@@ -238,7 +238,7 @@ export const hydrateAutoDeviceKey = async (
  * 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
+ * WHY IT EXISTS. `<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`,

package/src/features/WireFeaturesProvider.tsx

@@ -19,7 +19,10 @@ import { useWireFeatures } from "./useWireFeatures";
 import type { WireFeatures, WireFeaturesConfig } from "./types";
 
 const CONTEXT_SYMBOL = Symbol.for("wireai.features.context");
-const globalObj = global as any;
+// `globalThis`, not `global`: the other nine `Symbol.for` slots in this kit all use it, and `global`
+// simply does not exist in a plain browser (RN-web / SSR-in-the-browser), where this line would
+// throw a ReferenceError before the provider could render anything.
+const globalObj = globalThis as any;
 
 if (!globalObj[CONTEXT_SYMBOL]) {
   globalObj[CONTEXT_SYMBOL] = createContext<WireFeatures | null>(null);

package/src/identity/userIdentity.ts

@@ -131,7 +131,7 @@ export const identifyOnboarding = async (
     }
   }
   let space: Exclude<IdentifyOnboardingBinding, false> = "onboarding";
-  // The OPT-IN last resort (K3). Until 0.13.0 this ran unconditionally: with no captured contextId
+  // The OPT-IN last resort. Until 0.13.0 this ran unconditionally: with no captured contextId
   // it posted the LIVE PER-OPEN session id in the `session_id` field — which on this endpoint means
   // the ONBOARDING session — and then returned `true`. Two disjoint id spaces share that field, so
   // the row it wrote could never join the onboarding funnel, and the host got a success signal for a

package/src/questionnaire/QuestionnaireGate.tsx

@@ -27,8 +27,10 @@
  * step is simply an empty answer, which is what the builder already handled.
  *
  * ⚠️ This gate now REQUIRES the server to accept an empty `answers.opinion` - step 1 is
- * skippable and the live endpoint still 422s a blank opinion, silently (the transport is
- * fire-and-forget). See the REQUIRED_STEPS note in steps.ts. Server fix, not a client one.
+ * skippable and the live endpoint still 422s a blank opinion. The 422 is read (the transport
+ * resolves `"rejected"`) but deliberately not retried — the server ANSWERED, so re-posting could
+ * duplicate the row. The user still sees the thank-you either way. See the REQUIRED_STEPS note in
+ * steps.ts. Server fix, not a client one.
  *
  * Motion: `ModalPaneHost` slides step→step (and mirrors the slide on Back) and resizes the
  * card; `StepDots` fills; `DoneCheck` plays the submit payoff. All shared, all reduce-motion
@@ -69,7 +71,7 @@ import {
   type StepDrafts,
 } from "./steps";
 import { submitQuestionnaireResponse } from "./transport";
-import type { QuestionnaireGateProps } from "./types";
+import type { QuestionnaireGateProps, QuestionnaireSubmission } from "./types";
 
 type Phase = "form" | "thanks";
 
@@ -193,16 +195,94 @@ const _QuestionnaireGate: React.FC<QuestionnaireGateProps> = ({
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [id, onResolved]);
 
+  /**
+   * EXACTLY ONE response row per run, ever — the twin of `postOnce` in `reviews/ReviewGate.tsx`,
+   * and the reason an answer given offline is no longer silently thrown away.
+   *
+   * ── THE DEFECT THIS CLOSES ─────────────────────────────────────────────────────────────────
+   *
+   * `finish` used to call a `void`-returning `submitQuestionnaireResponse` and move on. The
+   * response was never read, so a submission that died in the socket was indistinguishable from
+   * one the server stored — and `onResolved` → `markResolved` writes the PERMANENT
+   * `wire_questionnaire_<id>_<ver>_seen` key regardless. A user who answered offline lost their
+   * answers AND was never asked again. This is the same hole 0.13.3 closed for reviews, on the one
+   * surface that both burns a permanent once-gate and had zero evidence of delivery.
+   *
+   * ── THE LATCH IS A CLAIM, NOT A RECEIPT ────────────────────────────────────────────────────
+   *
+   * `postedRef` is taken OPTIMISTICALLY, before the row has landed, so two callers in the same tick
+   * cannot post twice. It is RELEASED only when the transport reports that NOTHING REACHED THE
+   * SERVER, and the undelivered body is kept in `unackedRef` so the unmount net below can re-post
+   * it when the gate goes away.
+   *
+   * ── A NON-2xx IS NOT A RETRY TICKET ────────────────────────────────────────────────────────
+   *
+   * Only `"unsent"` un-latches. A non-2xx means the server was REACHED, and the response id is
+   * server-minted with no idempotency key on the wire, so a 502 arriving after the insert commits
+   * looks identical to a refusal. Re-posting on that verdict writes a SECOND response row — the
+   * duplicate-row defect reviews already fixed, one module over. On any answer the latch stays
+   * closed and `unackedRef` is cleared.
+   *
+   * NOTHING HERE IS AWAITED. `postOnce` returns synchronously and `finish` advances to the
+   * thank-you on the next line, so the user never waits on the network.
+   *
+   * HONEST CEILING — identical to reviews, deliberately: recovery is IN-PROCESS, one re-post when
+   * the gate unmounts. A run answered offline and never recovered before the app is killed is still
+   * lost, and the once-gate is still written by the host on `onResolved`. Durable cross-launch
+   * retry needs a storage prop on this component (new public API) or a generalized queue (the
+   * analytics one is hardwired to POST /v1/events, and a questionnaire response is not an event);
+   * both are deliberately out of scope here.
+   */
+  const postedRef = useRef(false);
+  /** The last submission fired with no answer yet. Non-null after an UNSENT post = still owed. */
+  const unackedRef = useRef<QuestionnaireSubmission | null>(null);
+  const postOnce = useCallback(
+    (body: QuestionnaireSubmission) => {
+      if (postedRef.current) return;
+      postedRef.current = true;
+      unackedRef.current = body;
+      void submitQuestionnaireResponse(target, id, body).then((result) => {
+        if (result === "unsent") {
+          // Nothing reached the server → un-latch, so these answers can still go out.
+          postedRef.current = false;
+          return;
+        }
+        // `accepted` OR `rejected`: the server answered, so it owns this row. Never re-post it.
+        unackedRef.current = null;
+      });
+    },
+    [target, id],
+  );
+
+  /**
+   * The recovery point for a submission the server never ANSWERED — never for one it answered
+   * non-2xx, which `postOnce` clears rather than re-queues. 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 the fire-once effect above uses).
+   *
+   * Unlike `ReviewGate` there is no abandonment branch here: a questionnaire that was never
+   * submitted has no payload to rescue (a half-typed draft is not an answer, and the last step is
+   * required precisely so a completed run always carries one). This net exists for exactly one
+   * case — the run FINISHED and the answers never made it onto the wire.
+   */
+  const recoverRef = useRef<() => void>(() => {});
+  recoverRef.current = () => {
+    const undelivered = unackedRef.current;
+    if (undelivered && !postedRef.current) postOnce(undelivered);
+  };
+  React.useEffect(() => () => recoverRef.current(), []);
+
   // The run is over: POST the answers and play the payoff. Identity is NEVER collected here -
   // the host already sends user_id / device_key / session via `sessionId` + `meta`.
   const finish = useCallback(
     (drafts: StepDrafts) => {
-      const submission = buildQuestionnaireSubmission({
-        answers: toAnswers(drafts),
-        sessionId,
-        meta,
-      });
-      submitQuestionnaireResponse(target, id, submission);
+      postOnce(
+        buildQuestionnaireSubmission({
+          answers: toAnswers(drafts),
+          sessionId,
+          meta,
+        }),
+      );
       submittedRef.current = true;
       onEvent?.({ name: "questionnaire_submitted", id });
       playHaptic("success");
@@ -212,7 +292,7 @@ const _QuestionnaireGate: React.FC<QuestionnaireGateProps> = ({
         modalRef.current?.close();
       }, 1500);
     },
-    [sessionId, meta, target, id, onEvent],
+    [sessionId, meta, postOnce, id, onEvent],
   );
 
   // Apply a machine transition: either submit (last step) or seed the next step's draft.

package/src/questionnaire/index.ts

@@ -28,8 +28,16 @@ export {
 export type { GateSignals, GateRules } from "./decision";
 
 // ─── Server transport: submit a response + best-effort fetch the decision ───────
+// `submitQuestionnaireResponse` resolves a THREE-state `QuestionnaireSubmitResult`
+// (accepted / rejected / unsent), not `void`: only `unsent` may be retried, because the wire has no
+// idempotency key and a re-post after a non-2xx that already committed writes a second row. It is
+// still non-throwing and still fired synchronously — the caller never awaits.
 export { submitQuestionnaireResponse, fetchQuestionnaireDecision } from "./transport";
-export type { FetchQuestionnaireDecisionOptions } from "./transport";
+export type {
+  FetchQuestionnaireDecisionOptions,
+  QuestionnaireSubmitResult,
+} from "./transport";
+export type { SubmitResult } from "../utils/submitResult";
 
 // ─── Gate-key helpers (shared coachmark storage singleton) ──────────────────────
 export {

package/src/questionnaire/transport.ts

@@ -1,7 +1,7 @@
 /**
- * transport.ts - kit → Wire server requests for the questionnaire module, all fire-and-forget
+ * transport.ts - kit → Wire server requests for the questionnaire module, never throwing
  * (a pre-onboarding questionnaire must NEVER break the app). Mirrors `submitReview`: a thin
- * fetch wrapper, Bearer tenant key, swallow every error.
+ * fetch wrapper, Bearer tenant key, and — since 0.13.3 — the SAME three-outcome delivery ack.
  *
  *   • submitQuestionnaireResponse → POST {serverUrl}/v1/questionnaires/{id}/responses
  *   • fetchQuestionnaireDecision  → GET  {serverUrl}/v1/questionnaires/decision  (best-effort)
@@ -10,6 +10,7 @@
  * non-2xx (incl. 404), a missing `fetch`, or bad JSON all resolve to null, so a host wiring
  * pure server-directed firing simply shows nothing - exactly the reviews decision seam.
  */
+import type { SubmitResult } from "../utils/submitResult";
 import type {
   QuestionnaireDecisionResponse,
   QuestionnaireSubmission,
@@ -17,29 +18,63 @@ import type {
 } from "./types";
 
 /**
- * POST a questionnaire response. Fire-and-forget: a missing target, a missing id, a build
- * error, a missing `fetch`, or a network failure is swallowed and the call returns immediately.
+ * What became of a questionnaire POST. The SHARED verdict — identical values, identical meaning,
+ * identical retry rule as `ReviewSubmitResult`. The reasoning lives once, in `utils/submitResult.ts`.
  */
-export const submitQuestionnaireResponse = (
+export type QuestionnaireSubmitResult = SubmitResult;
+
+/**
+ * POST a questionnaire response.
+ *
+ * NON-BLOCKING, and ACKED. It never throws and never makes a caller wait — the request is fired
+ * synchronously and the UI is free to advance on the next line — but it RESOLVES with what became
+ * of the response.
+ *
+ * ── WHY THE RETURN VALUE EXISTS (this used to be `void`) ─────────────────────────────────────
+ *
+ * The body was `void fetch(...).catch(() => {})`: the response was never read, so the caller could
+ * not tell a delivered submission from one that died in the socket. `QuestionnaireGate.finish`
+ * therefore latched the run as submitted unconditionally and resolved the gate, and `onResolved` →
+ * `markResolved` writes the PERMANENT `wire_questionnaire_<id>_<ver>_seen` key. A user who answered
+ * offline was never asked again and their answers were gone — the exact failure 0.13.3's
+ * `submitReview` fix was written for ("a detractor who rated offline was dropped AND never asked
+ * again"), on the one surface that both burns a permanent once-gate and had zero evidence of
+ * delivery. This is the twin of that fix.
+ *
+ * ── ONLY `unsent` MAY BE RETRIED ─────────────────────────────────────────────────────────────
+ *
+ * The same rule as reviews, for the same reason: the server mints the response id and the body
+ * carries no client id, so there is no idempotency key on the wire. A non-2xx proves the server was
+ * REACHED — a gateway 502 after the insert commits is indistinguishable from a refusal — so
+ * re-posting on it writes a SECOND response row. See `utils/submitResult.ts` for the full split and
+ * the honest residual.
+ *
+ * A missing target or a missing id resolves `"unsent"` with no request at all: nothing reached a
+ * server, which is exactly what a caller must be told before it decides the answers are delivered.
+ */
+export const submitQuestionnaireResponse = async (
   target: QuestionnaireTarget | undefined,
   id: string,
   submission: QuestionnaireSubmission,
-): void => {
-  if (!target?.serverUrl || !id) return;
+): Promise<QuestionnaireSubmitResult> => {
+  if (!target?.serverUrl || !id) return "unsent";
   try {
     const base = target.serverUrl.replace(/\/$/, "");
     const url = `${base}/v1/questionnaires/${encodeURIComponent(id)}/responses`;
     const headers: Record<string, string> = { "Content-Type": "application/json" };
     if (target.apiKey) headers.Authorization = `Bearer ${target.apiKey}`;
-    void fetch(url, {
+    const res = await fetch(url, {
       method: "POST",
       headers,
       body: JSON.stringify(submission),
-    }).catch(() => {
-      /* best-effort, swallow */
     });
+    // No response object at all is not an answer — treat it as nothing having reached the server
+    // rather than as a rejection, or a stubbed-out `fetch` would silently latch the answers away.
+    if (!res) return "unsent";
+    return (res as { ok?: boolean }).ok ? "accepted" : "rejected";
   } catch {
-    /* URL/JSON/missing-fetch - swallow */
+    /* URL/JSON/missing-fetch/network - nothing came back, and never surfaced to the UI */
+    return "unsent";
   }
 };
 

package/src/reviews/ReviewGate.tsx

@@ -115,18 +115,64 @@ const _ReviewGate: React.FC<ReviewGateProps> = ({
    * 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.
+   * double-counts `count` and corrupts `avg`. Reading the ack does not rescue that guess either:
+   * a second post against a server with no upsert comes back 2xx HAVING created the second row, so
+   * the failure is invisible to the caller and permanent. Post once, at the last responsible
+   * moment, and never depend on an unmerged/undeployed server capability.
+   *
+   * ── THE LATCH IS A CLAIM, NOT A RECEIPT ────────────────────────────────────────────────────
+   *
+   * The latch is taken OPTIMISTICALLY, before the row has landed, because its first job is to stop
+   * two callers in the same tick from posting twice (the double-row corruption above). It is
+   * RELEASED again when `submitReview` reports that NOTHING REACHED THE SERVER, and the undelivered
+   * body is kept in `unackedRef` so the abandonment net below can re-post it when the gate goes
+   * away. Without that release, a rating that died in the socket — the offline detractor, whose 1-4
+   * stars plus mandatory text is the most valuable payload this kit carries — is latched as posted
+   * and silently dropped, and the once-gate means they are never asked again.
+   *
+   * ── A NON-2xx IS NOT A RETRY TICKET ────────────────────────────────────────────────────────
+   *
+   * "Did it land" and "did the server answer" are DIFFERENT questions, which is why `submitReview`
+   * resolves `accepted` / `rejected` / `unsent` instead of a boolean. Only `unsent` un-latches.
+   * A non-2xx means the server was REACHED, and with no idempotency key on the wire (see above:
+   * the id is server-minted) we cannot know whether it stored the row before failing to say so — a
+   * gateway 502 after the insert commits looks identical to a refusal. Re-posting on that verdict
+   * writes the second row this whole latch exists to prevent, and does it on the exact code path
+   * meant to protect the data. So on any answer the latch stays closed and `unackedRef` is
+   * cleared: the row is the server's problem now.
+   *
+   * HONEST RESIDUAL: `unsent` is not proof the server never got it either. A connection dropped
+   * after the row committed throws here exactly like an offline device, so the one re-post below
+   * can still duplicate. This is SAFER, not safe. The real fix is a client-minted idempotency key
+   * the server upserts on — a server change, out of scope for the kit.
+   *
+   * NOTHING HERE IS AWAITED. `postOnce` returns synchronously and every caller advances the phase
+   * on the next line, so the user is never waiting on the network to dismiss the prompt.
+   *
+   * HONEST CEILING: recovery is IN-PROCESS — one re-post when the gate unmounts. A rating taken
+   * offline and never recovered before the app is killed is still lost. Durable cross-launch retry
+   * needs either a storage prop on this component (new public API) or a generalized
+   * `createEventQueue` (that queue is hardwired to POST /v1/events, and a review row is not an
+   * event); both are deliberately out of scope here.
    */
   const postedRef = React.useRef(false);
+  /** The last submission fired with no answer yet. Non-null after an UNSENT post = still owed. */
+  const unackedRef = React.useRef<ReviewSubmission | null>(null);
   const postOnce = useCallback(
     (body: ReviewSubmission) => {
       if (postedRef.current) return;
       postedRef.current = true;
-      submitReview(target, body);
+      unackedRef.current = body;
+      void submitReview(target, body).then((result) => {
+        if (result === "unsent") {
+          // Nothing reached the server → un-latch, so this row can still go out.
+          postedRef.current = false;
+          return;
+        }
+        // `accepted` OR `rejected`: the server answered, so it owns this row. Never re-post it —
+        // a non-2xx can follow a committed insert, and the wire has no idempotency key.
+        unackedRef.current = null;
+      });
     },
     [target],
   );
@@ -142,9 +188,18 @@ const _ReviewGate: React.FC<ReviewGateProps> = ({
    *
    * 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).
+   *
+   * It is ALSO the recovery point for a submission the server never ANSWERED — never for one it
+   * answered non-2xx, which `postOnce` clears rather than re-queues. That body already carries the
+   * user's real text, so it is re-posted verbatim rather than re-flagged `abandoned`.
    */
   const abandonRef = React.useRef<() => void>(() => {});
   abandonRef.current = () => {
+    const undelivered = unackedRef.current;
+    if (undelivered && !postedRef.current) {
+      postOnce(undelivered);
+      return;
+    }
     if (postedRef.current || stars < 1) return;
     postOnce(
       buildReviewSubmission({

package/src/reviews/index.ts

@@ -54,8 +54,17 @@ export { requestStoreReview, openStoreListing, storeUrl } from "./storeReview";
 // `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).
+// `submitReview` resolves with a THREE-state `ReviewSubmitResult` (accepted / rejected / unsent),
+// not a boolean: only `unsent` may be retried, because the wire has no idempotency key and a
+// re-post after a non-2xx that already committed writes a second row.
 export { submitReview, fetchReviewDecision, reportAppEvent } from "./transport";
-export type { FetchReviewDecisionOptions, ReportAppEventOptions } from "./transport";
+export type {
+  FetchReviewDecisionOptions,
+  ReportAppEventOptions,
+  ReviewSubmitResult,
+} from "./transport";
+// The same verdict under its shared name — `submitQuestionnaireResponse` resolves it too.
+export type { SubmitResult } from "../utils/submitResult";
 
 // ─── Gate-key + storage helpers (shared coachmark storage singleton) ──────────
 export {

package/src/reviews/transport.ts

@@ -1,7 +1,9 @@
 /**
- * transport.ts — kit → Wire server requests for the review module, all fire-and-forget
- * (analytics/reviews must never break the app). Mirrors analytics/reportClientEvent: a
- * thin fetch wrapper, Bearer tenant key, swallow every error.
+ * transport.ts — kit → Wire server requests for the review module. Non-blocking and never
+ * throwing (analytics/reviews must never break the app). Mirrors analytics/reportClientEvent: a
+ * thin fetch wrapper with a Bearer tenant key. `submitReview` additionally REPORTS the fate of the
+ * row to its caller — accepted / rejected / unsent, three outcomes on purpose; the rest swallow
+ * every error.
  *
  *   • submitReview         → POST {serverUrl}/v1/reviews          (the review row)
  *   • fetchReviewDecision  → GET  {serverUrl}/v1/reviews/decision (best-effort, the AI seam)
@@ -14,30 +16,74 @@
  */
 import { ensureCurrentSessionId } from "../analytics/currentSession";
 import { buildEventsRequest, type ClientEvent } from "../analytics/reportClientEvent";
+import type { SubmitResult } from "../utils/submitResult";
 import type { ReviewDecisionResponse, ReviewSubmission, ReviewTarget } from "./types";
 
 /**
- * POST a review (the 1-4 feedback path). Fire-and-forget: a missing target, a build error,
- * a missing `fetch`, or a network failure is swallowed and the call returns immediately.
+ * What became of a review POST — the SHARED three-outcome verdict, re-exported under the name the
+ * reviews surface has always published. The split is load-bearing and the reasoning lives once, in
+ * `utils/submitResult.ts`, because `submitQuestionnaireResponse` answers the identical question.
+ * See `submitReview` below for what reads it.
  */
-export const submitReview = (
+export type ReviewSubmitResult = SubmitResult;
+
+/**
+ * POST a review (the 1-4 feedback path, and the text-less 5-star row).
+ *
+ * NON-BLOCKING, and ACKED. It never throws and never makes a caller wait — the request is fired
+ * synchronously and the UI is free to advance on the next line — but it RESOLVES with what became
+ * of the row.
+ *
+ * WHY THE RETURN VALUE EXISTS: a 1-4 star rating with mandatory free text is the kit's most
+ * valuable payload and it has no persisted queue behind it (unlike `analytics/eventQueue`). If the
+ * response is dropped on the floor, a caller cannot tell a delivered submission from one that died
+ * in the socket, so it must latch the rating as posted and a detractor who rated offline is lost
+ * AND never asked again. Reading the ack is what lets `ReviewGate` keep an undelivered row
+ * recoverable.
+ *
+ * ── WHY IT IS NOT A BOOLEAN ──────────────────────────────────────────────────────────────────
+ *
+ * It was, for exactly one unpublished release, and the boolean was the bug. `false` meant both
+ * "nothing reached the server" and "the server answered non-2xx", and the one caller that reads
+ * this (`ReviewGate.postOnce`) treats `false` as "still owed" and re-posts. But the server mints
+ * its own row id (`create_review` / `_new_id()`) and `CreateReviewRequest` carries no id, so there
+ * is NO idempotency key on the wire: a 502 returned AFTER the insert commits means the re-post
+ * writes a SECOND row, double-counting `count` and corrupting `avg` — the precise corruption the
+ * one-row latch exists to prevent. A response of any status proves the server was reached, and
+ * that is a different question from whether it liked the row. So the two are different values.
+ *
+ * ── THE RESIDUAL, STATED HONESTLY ────────────────────────────────────────────────────────────
+ *
+ * `unsent` is not proof the server never got the row. A connection dropped after the request was
+ * written — or after the row committed — surfaces as a thrown/rejected `fetch` here, exactly like
+ * an offline device. Retrying only on `unsent` is therefore SAFER, not SAFE: it removes the
+ * double-post the server itself told us about, and leaves the narrow window where the answer never
+ * made it back onto the wire. Closing that window needs a CLIENT-MINTED IDEMPOTENCY KEY the server
+ * upserts on, which is a server change (`CreateReviewRequest` + `create_review`) and is not
+ * something the kit can fake. Until it exists, prefer losing a row over inventing one: a lost
+ * detractor is a gap in the data, a duplicated one is a lie in the data.
+ */
+export const submitReview = async (
   target: ReviewTarget | undefined,
   review: ReviewSubmission,
-): void => {
-  if (!target?.serverUrl) return;
+): Promise<ReviewSubmitResult> => {
+  if (!target?.serverUrl) return "unsent";
   try {
     const url = `${target.serverUrl.replace(/\/$/, "")}/v1/reviews`;
     const headers: Record<string, string> = { "Content-Type": "application/json" };
     if (target.apiKey) headers.Authorization = `Bearer ${target.apiKey}`;
-    void fetch(url, {
+    const res = await fetch(url, {
       method: "POST",
       headers,
       body: JSON.stringify(review),
-    }).catch(() => {
-      /* best-effort, swallow */
     });
+    // No response object at all is not an answer — treat it as nothing having reached the server
+    // rather than as a rejection, or a stubbed-out `fetch` would silently latch the row away.
+    if (!res) return "unsent";
+    return (res as { ok?: boolean }).ok ? "accepted" : "rejected";
   } catch {
-    /* URL/JSON/missing-fetch — swallow */
+    /* URL/JSON/missing-fetch/network — nothing came back, and never surfaced to the UI */
+    return "unsent";
   }
 };
 

package/src/session-analytics/useLifecycleEvents.ts

@@ -140,7 +140,7 @@ export const useLifecycleEvents = (
     ): string | undefined => {
       // A HOST-supplied key is recorded on the process provenance registry, so a `<WireOnboarding>`
       // mount that was not given one can tell "this app owns no device id" from "this app owns one
-      // and forgot it there" — the silent third id space (K9). Recording only; nothing reads it here.
+      // and forgot it there" — the silent third id space. Recording only; nothing reads it here.
       const host = resolveIdentity({
         value: opts.deviceKey,
         space: "device",