@wireai/activation 0.14.3 → 0.16.0

package/src/features/useWireFeatures.ts

@@ -5,13 +5,21 @@
  * network resolves. When no `serverUrl`+`apiKey` is supplied it never fetches and just returns
  * defaults, so a host that never adopts flags sees ZERO behavior change and ZERO network calls.
  *
+ * ⚠️ THE OPTIMISTIC DEFAULT IS A GUESS, AND SOME CONSUMERS CANNOT ACT ON A GUESS. Fail-open is the
+ * right resting state, but "all on because we have not asked yet" and "all on because the tenant
+ * says so" are different answers and the returned flags cannot tell them apart. A surface whose
+ * first render is IRREVERSIBLE — the review gate posts a `review_prompt_shown` and can take a row
+ * the moment it appears — needs the difference, or a tenant with `review.enabled: false` still gets
+ * one impression on every launch before the answer lands. {@link useWireFeaturesState} exposes it as
+ * `settled`; `useWireFeatures` is the flags-only wrapper and is unchanged.
+ *
  * frequent_rules #11 (unstable inline props): the config is idiomatically passed inline
  * (`config={{ serverUrl, apiKey }}`), a fresh identity every render. We stabilize the fetch key
  * by VALUE so the effect fires once per real credential change, and we only swap the returned
  * flags object when its VALUES change — so a host that lists the returned flags in an effect dep
  * array settles in a bounded number of commits instead of looping (enforced by the canary suite).
  */
-import { useEffect, useRef, useState } from "react";
+import { useEffect, useMemo, useRef, useState } from "react";
 
 import { defaultWireFeatures, featuresEqual } from "./defaults";
 import { fetchWireFeatures } from "./fetchWireFeatures";
@@ -28,16 +36,35 @@ const useStableValue = <T,>(value: T, isEqual: (a: T, b: T) => boolean): T => {
 const sameFetchKey = (a: WireFeaturesConfig | undefined, b: WireFeaturesConfig | undefined): boolean =>
   a?.serverUrl === b?.serverUrl && a?.apiKey === b?.apiKey && a?.appId === b?.appId;
 
-export const useWireFeatures = (config?: WireFeaturesConfig): WireFeatures => {
+/**
+ * The flags PLUS whether they are an answer yet — the shape `useWireFeatures` returns half of.
+ *
+ * `settled: false` means "nobody has answered; these are the optimistic defaults". It becomes
+ * `true` the moment the fetch resolves (fail-open included: an unreachable control plane resolves
+ * to the defaults and that IS a settled answer, because it is the answer we are keeping), and it
+ * starts `true` whenever there is nothing to wait for — no creds, so no flag can ever arrive.
+ */
+export interface WireFeaturesState {
+  flags: WireFeatures;
+  /** `false` only while a fetch that could still change the answer is in flight. */
+  settled: boolean;
+}
+
+export const useWireFeaturesState = (config?: WireFeaturesConfig): WireFeaturesState => {
   const stableConfig = useStableValue(config, sameFetchKey);
   const [flags, setFlags] = useState<WireFeatures>(defaultWireFeatures);
 
   const canFetch = !!stableConfig?.serverUrl && !!stableConfig?.apiKey;
+  // Nothing to fetch → the defaults are already the final answer, so a consumer that waits for an
+  // answer must not wait forever. Only ever moves to `true`: a later credential change refreshes a
+  // KNOWN answer, and un-answering it would re-hide a surface the user is already looking at.
+  const [settled, setSettled] = useState<boolean>(!canFetch);
 
   useEffect(() => {
     if (!canFetch) {
       // No creds → stay on the all-on defaults (and reset if creds were removed).
       setFlags((prev) => (featuresEqual(prev, defaultWireFeatures) ? prev : defaultWireFeatures));
+      setSettled(true);
       return;
     }
     let alive = true;
@@ -47,11 +74,20 @@ export const useWireFeatures = (config?: WireFeaturesConfig): WireFeatures => {
       // Only adopt a NEW reference on a real value change, so a host effect keyed on the
       // returned flags doesn't loop (frequent_rules #11).
       setFlags((prev) => (featuresEqual(prev, next) ? prev : next));
+      // Settled on EVERY resolution, including the fail-open one: `fetchWireFeatures` swallows a
+      // timeout / 401 / 5xx into the defaults, and that fallback is the final answer, not a
+      // pending one. This is what keeps fail-open intact — a broken control plane resolves fast
+      // and permissive, it does not leave a gated surface waiting.
+      setSettled(true);
     });
     return () => {
       alive = false;
     };
   }, [canFetch, stableConfig]);
 
-  return flags;
+  return useMemo(() => ({ flags, settled }), [flags, settled]);
 };
+
+/** The flags alone — the original hook, unchanged for every consumer that cannot act on `settled`. */
+export const useWireFeatures = (config?: WireFeaturesConfig): WireFeatures =>
+  useWireFeaturesState(config).flags;

package/src/identity/identityRecord.ts

@@ -96,6 +96,20 @@ const provenanceRegistry = (): ProvenanceRegistry => {
 const provenanceKey = (space: IdentitySpace, scope?: string): string =>
   `${space}:${scope ?? "default"}`;
 
+/**
+ * Is this candidate a usable identity value? A string with at least one non-whitespace character.
+ *
+ * ⛔ PURE, and that is the whole point of it existing separately from {@link resolveIdentity}: it is
+ * the predicate a READ-ONLY caller needs. `resolveIdentity` cannot serve that caller, because for a
+ * `host`-sourced input it WRITES to the process provenance registry — so merely asking it "is this a
+ * usable key?" would enrol the asker in the census it was only trying to read. That is the exact
+ * defect 0.15.1 fixed (a propless reader minting into `registry.keys` made the census read two, and
+ * the reader answered `undefined` forever), so the predicate is shared rather than re-typed:
+ * `resolveIdentity` below is its only other caller, so the two can never drift.
+ */
+export const isUsableIdentityValue = (value: unknown): value is string =>
+  typeof value === "string" && value.trim().length > 0;
+
 /**
  * Build an {@link IdentityRecord} from a candidate value, or `undefined` when there is nothing usable
  * (a non-string, or blank after trimming) — so a caller can `if (record)`-gate instead of guessing
@@ -107,9 +121,8 @@ const provenanceKey = (space: IdentitySpace, scope?: string): string =>
  * key" from a silent third id space into a warnable condition. Never throws.
  */
 export const resolveIdentity = (input: ResolveIdentityInput): IdentityRecord | undefined => {
-  if (typeof input.value !== "string") return undefined;
+  if (!isUsableIdentityValue(input.value)) return undefined;
   const value = input.value.trim();
-  if (!value) return undefined;
   const durable = input.durable ?? input.source === "host";
   if (input.source === "host") {
     provenanceRegistry().host.set(provenanceKey(input.space, input.scope), value);

package/src/questionnaire/QuestionnaireGate.tsx

@@ -236,6 +236,31 @@ const _QuestionnaireGate: React.FC<QuestionnaireGateProps> = ({
   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);
+  /**
+   * THE NET WAS INERT WHILE THE POST WAS IN FLIGHT, which is precisely when it is needed.
+   *
+   * This is the review-gate defect on its second copy: 0.15.1 closed it in `reviews/ReviewGate.tsx`
+   * and left the twin here open. The latch is taken OPTIMISTICALLY and only released in the `.then`
+   * below, while `finish` auto-closes the modal 1500ms after the post. So on any network slower than
+   * that — the offline answerer, a stalled radio, a captive portal — the unmount ran with the latch
+   * still CLOSED: `recoverRef`'s only branch requires `!postedRef.current`, so it no-opped, and the
+   * post later resolved `"unsent"` with nothing mounted to notice. The host's `onResolved` →
+   * `markResolved` has ALREADY written the permanent `wire_questionnaire_<id>_<ver>_seen` key, so
+   * that user is never asked again and their answers are gone. Silent. The existing canary missed it
+   * because every case awaits the submit BEFORE unmounting — the fast path, where the latch has
+   * already reopened.
+   *
+   * So the unmount hands the recovery to the promise: when it finds a post STILL IN FLIGHT — the one
+   * state its branch cannot serve — it arms `recoverOnSettleRef`, and the `.then` below does the
+   * re-post if nothing reached the server. It is armed ONLY in that state, so the fast path is
+   * untouched and still recovers exactly once, in the net. `recoveredRef` bounds this to exactly ONE
+   * extra post — the same in-process ceiling the net always had, never a retry loop.
+   */
+  const recoverOnSettleRef = useRef(false);
+  const recoveredRef = useRef(false);
+  /** Latest `postOnce`, so the recovery above can call it from inside its own promise chain
+   *  (the same ref convention `recoverRef` below uses) without a self-referencing callback. */
+  const postOnceRef = useRef<(body: QuestionnaireSubmission) => void>(() => {});
   const postOnce = useCallback(
     (body: QuestionnaireSubmission) => {
       if (postedRef.current) return;
@@ -245,6 +270,12 @@ const _QuestionnaireGate: React.FC<QuestionnaireGateProps> = ({
         if (result === "unsent") {
           // Nothing reached the server → un-latch, so these answers can still go out.
           postedRef.current = false;
+          // The gate is already gone: the unmount net ran while this post was still in flight and
+          // found the latch closed, so nothing else will ever recover this row. Do it here, once.
+          if (recoverOnSettleRef.current && !recoveredRef.current) {
+            recoveredRef.current = true;
+            postOnceRef.current(body);
+          }
           return;
         }
         // `accepted` OR `rejected`: the server answered, so it owns this row. Never re-post it.
@@ -253,6 +284,7 @@ const _QuestionnaireGate: React.FC<QuestionnaireGateProps> = ({
     },
     [target, id],
   );
+  postOnceRef.current = postOnce;
 
   /**
    * The recovery point for a submission the server never ANSWERED — never for one it answered
@@ -268,7 +300,14 @@ const _QuestionnaireGate: React.FC<QuestionnaireGateProps> = ({
   const recoverRef = useRef<() => void>(() => {});
   recoverRef.current = () => {
     const undelivered = unackedRef.current;
-    if (undelivered && !postedRef.current) postOnce(undelivered);
+    if (undelivered && !postedRef.current) {
+      postOnce(undelivered);
+      return;
+    }
+    // STILL IN FLIGHT (latch closed, row unanswered) — the state that made this net inert. The
+    // branch above cannot act from here, so the pending post is asked to recover itself when it
+    // settles unsent. Nothing else is scheduled to look at this row again.
+    if (postedRef.current && undelivered) recoverOnSettleRef.current = true;
   };
   React.useEffect(() => () => recoverRef.current(), []);
 

package/src/questionnaire/transport.ts

@@ -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 { DEADLINE_EXPIRED, withDeadline } from "../utils/withDeadline";
 import type { SubmitResult } from "../utils/submitResult";
 import type {
   QuestionnaireDecisionResponse,
@@ -63,11 +64,19 @@ export const submitQuestionnaireResponse = async (
     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}`;
-    const res = await fetch(url, {
-      method: "POST",
-      headers,
-      body: JSON.stringify(submission),
-    });
+    // Under a deadline (see `utils/withDeadline`): a hung POST used to hold `QuestionnaireGate`'s
+    // `postOnce` latch closed for the ~60s platform default, which is exactly the window the
+    // unmount recovery net cannot re-post inside.
+    const res = await withDeadline((signal) =>
+      fetch(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(submission),
+        signal,
+      }),
+    );
+    // A deadline that expired is not a rejection: nothing reached the server, so it stays re-postable.
+    if (res === DEADLINE_EXPIRED) return "unsent";
     // 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";
@@ -107,9 +116,14 @@ export const fetchQuestionnaireDecision = async (
     const url = `${base}/v1/questionnaires/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 QuestionnaireDecisionResponse | null;
+    // The BODY read is inside the deadline too: a ceiling cleared when the headers land is not a
+    // ceiling (the `fetchWireFeatures` lesson — see `utils/withDeadline`).
+    const json = await withDeadline(async (signal): Promise<QuestionnaireDecisionResponse | null> => {
+      const res = await fetch(url, { headers, signal });
+      if (!res || !res.ok) return null;
+      return (await res.json()) as QuestionnaireDecisionResponse | null;
+    });
+    if (json === DEADLINE_EXPIRED) return null;
     // A body without a boolean `fire` is not a decision. Guard it explicitly (mirrors
     // `fetchReviewDecision`) rather than letting `{}` through as a truthy object a gate would treat
     // as a verdict (`{}.fire === undefined` is falsy, so it would silently read as "never fire").

package/src/questionnaire/useQuestionnaireGate.ts

@@ -13,10 +13,11 @@
  * the popup. The global `isTestingCoachmark` flag force-shows the gate for QA replay, and the
  * `questionnaire` master switch (a disabled tenant) wins over everything.
  */
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 
+import { getCurrentSessionId, subscribeCurrentSessionId } from "../analytics/currentSession";
 import { hasSeenGate, isCoachmarkTesting, markSeenGate } from "../coachmarks/runtime";
-import { useResolvedFeatures } from "../features/WireFeaturesProvider";
+import { useResolvedFeaturesState } from "../features/WireFeaturesProvider";
 import { sameDecision, shallowEqual } from "../reviews/equality";
 import { decideQuestionnaire, evaluateGate, resolveRules } from "./decision";
 import {
@@ -64,8 +65,20 @@ export const useQuestionnaireGate = ({
 
   // The questionnaire MASTER switch. Disabled → the gate never fires, composing as an extra
   // AND over the local rules + the server decision seam below (fail-open: defaults to enabled).
-  const featureEnabled = useResolvedFeatures({ flags: features, config: featuresConfig })
-    .questionnaire.enabled;
+  //
+  // `settled` is read too, and it is the half that makes the switch real — the same asymmetry
+  // `useReviewGate` closed, on the same seam. The flags start on the all-on defaults and swap only
+  // when the fetch resolves, so `featureEnabled` is `true` on the FIRST render of every mount,
+  // including a tenant with `questionnaire.enabled: false`. With no `timeoutFallbackMs` the local
+  // wait is skipped as well (`elapsed` starts `true`), so the gate could become visible, fire
+  // `questionnaire_prompt_shown`, and POST a response from a user the tenant had switched off. The
+  // comment below ("must never see it") was falsified by its own async default. Holding the FIRST
+  // impression until an answer exists is what honours the switch.
+  const { flags: resolvedFeatures, settled: featuresSettled } = useResolvedFeaturesState({
+    flags: features,
+    config: featuresConfig,
+  });
+  const featureEnabled = resolvedFeatures.questionnaire.enabled;
 
   const testing = isTesting ?? isCoachmarkTesting();
   const seenKey = questionnaireSeenKey(
@@ -76,16 +89,48 @@ export const useQuestionnaireGate = ({
   const sessionsKey = questionnaireSessionsKey(config.id);
   const sessionOpenKey = questionnaireSessionOpenKey(config.id);
 
+  // ── FOLLOW real app-opens, do not sample one ────────────────────────────────────────────────
+  //
+  // `bumpSessionCount` is IDEMPOTENT per app-open and moves once per open — but it used to be reached
+  // ONLY from the `useState` initializer below, which runs once per component INSTANCE. On a screen
+  // that never unmounts (a home feed, a tab that stays alive) that meant once per PROCESS, and iOS
+  // suspends rather than kills: `useLifecycleEvents` fires a fresh `app.session_started` on every
+  // foreground past its threshold and the SERVER's `min_sessions` advances, while `wire_questionnaire_<id>_sessions`
+  // stayed at its launch value and the LOCAL `minSessions` rule was unsatisfiable for the life of the
+  // app. Silent, and in the safe direction (a prompt that never shows), which is why it survived —
+  // `sessionCountAcrossOpens.test.ts` proved the FUNCTION advances and could not see that the HOOK
+  // never asked it again.
+  //
+  // So subscribe to the registry that knows. A notification naming the same open is a no-op by
+  // construction (`bumpSessionCount` reads its stored count back), so the cold-start ordering this
+  // pin exists for is untouched.
+  const openSessionId = useSyncExternalStore(
+    subscribeCurrentSessionId,
+    getCurrentSessionId,
+    getCurrentSessionId,
+  );
+  // Read through a ref: a host that passes `storage={{ … }}` inline (idiomatic React, and what
+  // `frequent_rules` #11 requires this hook to tolerate) mints a fresh identity every render, and
+  // listing it in the deps below would re-run the effect on every one of them.
+  const storageRef = useRef(storage);
+  storageRef.current = storage;
+
   // Read (and bump) the app-open counter. IDEMPOTENT per app-open, NOT per mount — see the same note
   // in `useReviewGate`; `bumpSessionCount` keys off the live per-open session id, so a remount or a
   // StrictMode double-invoke of this initializer reads the same number back instead of inflating it.
-  const sessions = useState(() => {
+  const [sessions, setSessions] = useState(() => {
     const store = resolveStorage(storage);
     // Same as `useReviewGate`: no storage means the counter never leaves 1, so the fail-closed
     // minSessions rule is unsatisfiable and the gate silently never fires. Dev-only, once per process.
     warnMissingGateStorage(store, "questionnaire");
     return bumpSessionCount(store, sessionsKey, sessionOpenKey);
-  })[0];
+  });
+  useEffect(() => {
+    const next = bumpSessionCount(resolveStorage(storageRef.current), sessionsKey, sessionOpenKey);
+    // A bail-out when the count is unchanged, so a notification for an open already counted costs
+    // nothing: React skips the re-render when the state is identical.
+    setSessions((prev) => (prev === next ? prev : next));
+  }, [openSessionId, sessionsKey, sessionOpenKey]);
 
   // Gate the local rules behind an optional client-side timeout, so a reachable server gets a
   // window to answer first. A present `decision` bypasses the wait entirely.
@@ -129,11 +174,17 @@ export const useQuestionnaireGate = ({
     const resolved = decideQuestionnaire(local, decision);
     // (3) the once-gate always wins locally, even over a server "fire".
     const alreadySeen = hasSeenGate(seenKey, storage, isTesting);
-    const ready = hasServerDecision || elapsed;
+    // FAIL-OPEN IS NOT WEAKENED BY THIS. `featuresSettled` is `false` only while a fetch that could
+    // still change the answer is in flight; it is `true` with no `featuresConfig` (nothing to ask),
+    // with explicit `features`, and — the case that matters — the moment a FAILED fetch resolves,
+    // because `fetchWireFeatures` swallows a timeout / 401 / 5xx into the all-on defaults. So an
+    // unreachable control plane still allows the gate; only an unanswered one holds it.
+    const ready = (hasServerDecision || elapsed) && featuresSettled;
     return { visible: ready && resolved.fire && !alreadySeen, verdict: resolved };
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [
     featureEnabled,
+    featuresSettled,
     testing,
     config,
     decision,

package/src/reviews/ReviewGate.tsx

@@ -17,7 +17,11 @@
  *
  * 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.
+ * the POST body carries alongside the rating and the free text. Since 2026-08-19 the gate also
+ * fills in `meta.device_key` from the kit's own per-install id when the host passed none — not for
+ * identification, but because it is the unit the server scopes the idempotency key to, and without
+ * it the key is discarded. Any non-blank string the host passes still wins verbatim. See
+ * `idempotency.ts`.
  *
  * 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
@@ -45,6 +49,7 @@ import { useOnboardingTheme } from "../theme/ThemeContext";
 import { bodyStyle, captionStyle, headingStyle } from "../theme/typography";
 import { buildReviewSubmission, routeRating } from "./decision";
 import { feedbackInputHeights } from "./feedbackForm";
+import { createImpression, hasDeviceKey, type ReviewImpression } from "./idempotency";
 import { resolvePresentation } from "./presentation";
 import { ReviewModal, type ReviewModalHandle } from "./ReviewModal";
 import { requestStoreReview } from "./storeReview";
@@ -107,18 +112,63 @@ const _ReviewGate: React.FC<ReviewGateProps> = ({
     onResolved?.();
   }, [onResolved]);
 
+  /**
+   * ONE identity + ONE idempotency key for this whole gate impression, opened lazily at the first
+   * post so a prompt the user never acts on mints nothing.
+   *
+   * Both values live for the IMPRESSION, not the render and not the post: the server derives the
+   * row id from `(app_id, unit, key)`, so a key that moves between two posts writes two rows and a
+   * unit that moves does the same. `idempotency.ts` carries the full reasoning.
+   */
+  const impressionRef = React.useRef<ReviewImpression | null>(null);
+
+  /**
+   * Build a submission for THIS impression: the host's `meta` plus whatever the call site adds,
+   * stamped with the impression's key and — only when the host supplied none — its device key.
+   *
+   * A host-supplied `meta.device_key` ALWAYS wins and is never overwritten — "supplied" meaning a
+   * string with at least one non-whitespace character, the bar {@link hasDeviceKey} sets; a blank
+   * or non-string value is not a usable unit and is replaced. This mirrors the `userContext` /
+   * `autoJoinKey` rule one directory over, which sets the same bar through `resolveIdentity`. The
+   * injection exists because without a resolvable unit the server discards the key outright, and a
+   * home-feed gate has no `session_id` to fall back to.
+   */
+  const buildBody = useCallback(
+    (input: {
+      stars: number;
+      feedbackText?: string;
+      suggestion?: string;
+      extraMeta?: Record<string, unknown>;
+    }): ReviewSubmission => {
+      let impression = impressionRef.current;
+      if (!impression) {
+        impression = createImpression();
+        impressionRef.current = impression;
+      }
+      const merged: Record<string, unknown> = { ...meta, ...input.extraMeta };
+      if (!hasDeviceKey(merged) && impression.deviceKey) merged.device_key = impression.deviceKey;
+      return buildReviewSubmission({
+        stars: input.stars,
+        feedbackText: input.feedbackText,
+        suggestion: input.suggestion,
+        sessionId,
+        meta: merged,
+        idempotencyKey: impression.idempotencyKey,
+      });
+    },
+    [meta, sessionId],
+  );
+
   /**
    * 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`. 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.
+   * 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. The server now supports exactly that — a post
+   * carrying `idempotency_key` upserts on a derived row id instead of inserting — but the latch
+   * stays, because two posts buy nothing the one-at-the-last-responsible-moment post does not
+   * already have, and every additional post is another chance to hand the server a unit it cannot
+   * resolve. What the key genuinely buys is the RECOVERY paths below: the `unsent` re-post and the
+   * abandonment net now merge into the row they may have already written instead of duplicating it.
    *
    * ── THE LATCH IS A CLAIM, NOT A RECEIPT ────────────────────────────────────────────────────
    *
@@ -134,17 +184,23 @@ const _ReviewGate: React.FC<ReviewGateProps> = ({
    *
    * "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.
+   * A non-2xx means the server was REACHED, and we still cannot know whether it stored the row
+   * before failing to say so — a gateway 502 after the insert commits looks identical to a refusal.
+   * That verdict is left alone DELIBERATELY (2026-08-19): re-posting on it is now safe wherever the
+   * key is honoured, but it would also turn a genuine 4xx refusal into a retry needing its own
+   * budget, so changing it is its own decision and not this one. 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.
+   * WHAT THE KEY CHANGED, STATED AS A CAPABILITY: `unsent` was never proof the server got nothing —
+   * a connection dropped after the row committed throws here exactly like an offline device, so the
+   * one re-post below could duplicate. It now carries this impression's `idempotency_key` and the
+   * unit the server scopes it to, so the server upserts that row rather than adding a second one.
+   * That holds while the unit is resolvable, and a host CANNOT make it unresolvable by editing
+   * `meta`: `buildBody` tests the MERGED bucket, so stripping `device_key` there only gets the auto
+   * id re-injected. The one post that carries no unit is the one where the kit cannot name an id
+   * honestly — two tenants registered in one process leave `impression.deviceKey` undefined, and
+   * nothing is stamped. On a gate with no `session_id` that post reaches the server with no unit to
+   * scope the key to, so the server ignores the key and it is back in the old, duplicating world.
    *
    * 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.
@@ -158,6 +214,31 @@ const _ReviewGate: React.FC<ReviewGateProps> = ({
   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);
+  /**
+   * THE NET WAS INERT WHILE THE POST WAS IN FLIGHT, which is precisely when it is needed.
+   *
+   * The latch is taken OPTIMISTICALLY and only released in `submitReview`'s `.then`, while the gate
+   * auto-closes 1500ms after the post (`resolveWithDelay`). So on any network slower than that —
+   * the offline detractor, a stalled radio, a captive portal — the unmount ran with the latch still
+   * CLOSED: the recovery branch below requires `!postedRef.current`, and the abandonment branch
+   * returns on `postedRef.current`, so BOTH no-opped and a 1-4 rating plus its mandatory text was
+   * dropped in silence. The once-gate means that user is never asked again. The existing canary
+   * missed it because it awaits the submit BEFORE unmounting — the fast path, where the latch has
+   * already reopened.
+   *
+   * So the unmount hands the recovery to the promise: when it finds a post STILL IN FLIGHT — the
+   * one state neither of its branches can serve — it arms `recoverOnSettleRef`, and the `.then`
+   * below does the re-post if nothing reached the server. It is armed ONLY in that state, so the
+   * fast path (settled before unmount) is untouched and still recovers exactly once, in the net.
+   * `recoveredRef` bounds this to exactly ONE extra post — the same in-process ceiling the net
+   * always had, never a retry loop — and the re-post carries this impression's `idempotency_key`
+   * plus its unit, so a row that did land is upserted rather than duplicated.
+   */
+  const recoverOnSettleRef = React.useRef(false);
+  const recoveredRef = React.useRef(false);
+  /** Latest `postOnce`, so the recovery above can call it from inside its own promise chain
+   *  (the same ref convention `abandonRef` below uses) without a self-referencing callback. */
+  const postOnceRef = React.useRef<(body: ReviewSubmission) => void>(() => {});
   const postOnce = useCallback(
     (body: ReviewSubmission) => {
       if (postedRef.current) return;
@@ -167,15 +248,23 @@ const _ReviewGate: React.FC<ReviewGateProps> = ({
         if (result === "unsent") {
           // Nothing reached the server → un-latch, so this row can still go out.
           postedRef.current = false;
+          // The gate is already gone: the unmount net ran while this post was still in flight and
+          // found the latch closed, so nothing else will ever recover this row. Do it here, once.
+          if (recoverOnSettleRef.current && !recoveredRef.current) {
+            recoveredRef.current = true;
+            postOnceRef.current(body);
+          }
           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.
+        // `accepted` OR `rejected`: the server answered, so it owns this row. Not re-posted here —
+        // a non-2xx can follow a committed insert, and re-posting a refusal is a retry decision
+        // with its own budget, deliberately left out of the change that added the key.
         unackedRef.current = null;
       });
     },
     [target],
   );
+  postOnceRef.current = postOnce;
 
   /**
    * The abandonment safety net, and the reason forcing feedback does not COST us detractor data.
@@ -200,14 +289,20 @@ const _ReviewGate: React.FC<ReviewGateProps> = ({
       postOnce(undelivered);
       return;
     }
+    // STILL IN FLIGHT (latch closed, row unanswered) — the state that made this net inert. Neither
+    // branch can act from here, so the pending post is asked to recover itself when it settles
+    // unsent. Nothing else is scheduled to look at this row again.
+    if (postedRef.current && undelivered) {
+      recoverOnSettleRef.current = true;
+      return;
+    }
     if (postedRef.current || stars < 1) return;
     postOnce(
-      buildReviewSubmission({
+      buildBody({
         stars,
         feedbackText: feedback,
         suggestion,
-        sessionId,
-        meta: { ...meta, abandoned: true },
+        extraMeta: { abandoned: true },
       }),
     );
   };
@@ -249,10 +344,9 @@ const _ReviewGate: React.FC<ReviewGateProps> = ({
         // 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({
+          buildBody({
             stars: value,
-            sessionId,
-            meta: { ...meta, store_route: route },
+            extraMeta: { store_route: route },
           }),
         );
         setPhase("thanks");
@@ -263,7 +357,7 @@ const _ReviewGate: React.FC<ReviewGateProps> = ({
         setPhase("feedback");
       }
     },
-    [onEvent, id, store, postOnce, sessionId, meta, resolveWithDelay],
+    [onEvent, id, store, postOnce, buildBody, resolveWithDelay],
   );
 
   /**
@@ -284,19 +378,13 @@ const _ReviewGate: React.FC<ReviewGateProps> = ({
     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({
-      stars,
-      feedbackText: feedback,
-      suggestion,
-      sessionId,
-      meta,
-    });
+    const body = buildBody({ stars, feedbackText: feedback, suggestion });
     postOnce(body);
     onEvent?.({ name: "review_feedback_submitted", id, stars });
     playHaptic("success");
     setPhase("thanks");
     resolveWithDelay();
-  }, [feedbackReady, stars, feedback, suggestion, sessionId, meta, postOnce, onEvent, id, resolveWithDelay]);
+  }, [feedbackReady, stars, feedback, suggestion, buildBody, postOnce, onEvent, id, resolveWithDelay]);
 
   const dismiss = useCallback(() => {
     setPhase("thanks");

package/src/reviews/decision.ts

@@ -103,7 +103,14 @@ export const evaluateGate = (rules: GateRules, s: GateSignals): ReviewDecision =
 export const routeRating = (stars: number): RatingRoute =>
   stars >= 5 ? "store" : "feedback";
 
-/** Build the `POST /v1/reviews` body. Feedback text/contact belong ONLY here, never in events. */
+/**
+ * Build the `POST /v1/reviews` body. Feedback text/contact belong ONLY here, never in events.
+ *
+ * STILL PURE, deliberately: `idempotencyKey` and the `meta.device_key` the server scopes it to are
+ * both passed IN rather than resolved here. Reaching into the device-key registry from this function
+ * would make the gate logic untestable in isolation, and both values are scoped to an impression
+ * this function cannot see — see `reviews/idempotency.ts`.
+ */
 export const buildReviewSubmission = (input: {
   stars: number;
   feedbackText?: string;
@@ -111,6 +118,8 @@ export const buildReviewSubmission = (input: {
   contact?: string;
   sessionId?: string;
   source?: string;
+  /** The impression's idempotency key. Omitted → the server mints a row id and inserts, as before. */
+  idempotencyKey?: string;
   meta?: Record<string, unknown>;
 }): ReviewSubmission => {
   const body: ReviewSubmission = { stars: input.stars };
@@ -122,6 +131,7 @@ export const buildReviewSubmission = (input: {
   if (contact) body.contact = contact;
   if (input.sessionId) body.session_id = input.sessionId;
   if (input.source) body.source = input.source;
+  if (input.idempotencyKey) body.idempotency_key = input.idempotencyKey;
   if (input.meta && Object.keys(input.meta).length > 0) body.meta = input.meta;
   return body;
 };