@wireai/activation 0.14.3 → 0.15.0

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.
@@ -169,8 +225,9 @@ const _ReviewGate: React.FC<ReviewGateProps> = ({
           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.
+        // `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;
       });
     },
@@ -202,12 +259,11 @@ const _ReviewGate: React.FC<ReviewGateProps> = ({
     }
     if (postedRef.current || stars < 1) return;
     postOnce(
-      buildReviewSubmission({
+      buildBody({
         stars,
         feedbackText: feedback,
         suggestion,
-        sessionId,
-        meta: { ...meta, abandoned: true },
+        extraMeta: { abandoned: true },
       }),
     );
   };
@@ -249,10 +305,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 +318,7 @@ const _ReviewGate: React.FC<ReviewGateProps> = ({
         setPhase("feedback");
       }
     },
-    [onEvent, id, store, postOnce, sessionId, meta, resolveWithDelay],
+    [onEvent, id, store, postOnce, buildBody, resolveWithDelay],
   );
 
   /**
@@ -284,19 +339,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;
 };

package/src/reviews/idempotency.ts

@@ -0,0 +1,71 @@
+/**
+ * idempotency.ts — the ONE idempotency key and the ONE identity a single gate impression posts under.
+ *
+ * ── WHAT THE SERVER DOES WITH THESE, AND WHY BOTH ARE REQUIRED ───────────────────────────────
+ *
+ * `POST /v1/reviews` accepts an optional `idempotency_key`: two posts carrying the same key upsert
+ * ONE row instead of creating two, which is what stops a re-post double-counting `count` and
+ * corrupting `avg`. The row id is derived, never the key verbatim —
+ * `rev_ + sha256(app_id : unit : key)[:24]` — where `app_id` comes from the resolved `wai_` Bearer
+ * key (never the body) and `unit` is the USER the key is scoped to.
+ *
+ * THE PART THAT MAKES A KEY-ONLY CHANGE INERT: `unit` is `meta.device_key`, else `session_id`, and
+ * when the post carries NEITHER the server drops the key on the floor and inserts a normal row —
+ * deliberately, because an unbounded key could merge two strangers' reviews. The gate lives on the
+ * home feed, where a user legitimately has no onboarding session, so `session_id` is frequently
+ * absent; and nothing in the kit ever put a `device_key` into a review `meta` — that was documented
+ * as a host responsibility. Sending a key without guaranteeing the identity would therefore have
+ * shipped a field the server discards.
+ *
+ * ── THE SCOPE IS THE WHOLE DESIGN ────────────────────────────────────────────────────────────
+ *
+ * One key per gate IMPRESSION, held across every post of that impression:
+ *   • minted per POST instead → the re-post carries a different key, writes the second row, and
+ *     defeats the feature on the exact path it exists to protect.
+ *   • minted once per INSTALL instead → a later, genuine second review merges into the first and
+ *     destroys a rating.
+ * The identity is pinned for the same reason and in the same object: the auto device key is adopted
+ * from persistence ASYNCHRONOUSLY, so a value re-read between two posts of one impression can move
+ * under us, and two posts under two different units hash to two different rows.
+ */
+import { ambientAutoDeviceKey } from "../context/deviceId";
+
+/** Prefix so a kit-minted review key is visibly ours in a stored `meta` dump. */
+export const REVIEW_IDEMPOTENCY_PREFIX = "rvw_";
+
+/**
+ * Mint a fresh idempotency key. Dependency-free timestamp + randomness, the same scheme
+ * `makeSessionId` and `mintDeviceId` already use — the key only has to be unique among the
+ * impressions of ONE install, because the server hashes it together with `app_id` and the unit
+ * before it ever becomes a row id.
+ */
+export const mintIdempotencyKey = (): string =>
+  `${REVIEW_IDEMPOTENCY_PREFIX}${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+
+/** Whether a `meta` bucket already carries a usable, host-supplied `device_key`. */
+export const hasDeviceKey = (meta: Record<string, unknown> | undefined): boolean => {
+  const value = meta?.device_key;
+  return typeof value === "string" && value.trim().length > 0;
+};
+
+/** The key + identity every post of ONE gate impression carries. Both resolved once, at creation. */
+export interface ReviewImpression {
+  /** The `idempotency_key` on the wire. Stable for the impression, distinct across impressions. */
+  readonly idempotencyKey: string;
+  /**
+   * The auto `device_key` to stamp when the host supplied none, or `undefined` when the kit cannot
+   * name one honestly (two tenants in one process). A host-supplied key that {@link hasDeviceKey}
+   * accepts — a string with at least one non-whitespace character — always wins over this and is
+   * never touched; the caller checks that first.
+   */
+  readonly deviceKey: string | undefined;
+}
+
+/**
+ * Open one impression. Both fields are resolved EAGERLY here rather than read per post, which is the
+ * entire point: a lazily re-read key or identity is a per-post value wearing an impression's name.
+ */
+export const createImpression = (): ReviewImpression => ({
+  idempotencyKey: mintIdempotencyKey(),
+  deviceKey: ambientAutoDeviceKey(),
+});

package/src/reviews/index.ts

@@ -55,8 +55,10 @@ export { requestStoreReview, openStoreListing, storeUrl } from "./storeReview";
 // 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.
+// not a boolean: only `unsent` is retried today. A body built by `ReviewGate` now carries an
+// `idempotency_key` plus the unit the server scopes it to, so that re-post upserts one row instead
+// of writing a second; whether a `rejected` verdict should ALSO retry is a separate recovery-budget
+// decision and is deliberately unchanged.
 export { submitReview, fetchReviewDecision, reportAppEvent } from "./transport";
 export type {
   FetchReviewDecisionOptions,

package/src/reviews/runtime.ts

@@ -5,7 +5,7 @@
  * mounted CoachmarkProvider gets review gating for free — no second storage to wire.
  */
 import type { CoachmarkStorage } from "../coachmarks/types";
-import { getCoachmarkStorage } from "../coachmarks/runtime";
+import { getCoachmarkStorage, validateGateStorage } from "../coachmarks/runtime";
 import { getCurrentSessionId } from "../analytics/currentSession";
 import { makeSessionId } from "../analytics/reportClientEvent";
 
@@ -22,10 +22,12 @@ export const reviewSessionsKey = (id: string): string => `wire_review_${id}_sess
 /** Companion key holding the open id the counter was LAST incremented for (see {@link bumpSessionCount}). */
 export const reviewSessionOpenKey = (id: string): string => `wire_review_${id}_open`;
 
-/** Resolve the storage to use: an explicit override, else the provider-injected singleton. */
+/** Resolve the storage to use: an explicit override, else the provider-injected singleton — both
+ *  routed through the thenable probe, so an ASYNC adapter resolves to the fail-closed substitute
+ *  (see `validateGateStorage` in coachmarks/runtime) instead of feeding Promises to `readInt`. */
 export const resolveStorage = (
   override?: CoachmarkStorage | null,
-): CoachmarkStorage | null => override ?? getCoachmarkStorage();
+): CoachmarkStorage | null => validateGateStorage(override ?? getCoachmarkStorage());
 
 /** RN sets this global; absent under node/SSR. Read defensively via {@link warnMissingGateStorage}. */
 declare const __DEV__: boolean | undefined;

package/src/reviews/transport.ts

@@ -45,23 +45,28 @@ export type ReviewSubmitResult = SubmitResult;
  *
  * 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.
+ * this (`ReviewGate.postOnce`) treats `false` as "still owed" and re-posts. At the time there was
+ * no idempotency key on the wire at all, so a 502 returned AFTER the insert commits meant the
+ * re-post wrote 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, and
+ * they stay different: the split is what lets the caller decide, and the retry-on-`rejected`
+ * question is a recovery-budget decision the key does not answer on its own.
  *
  * ── 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.
+ * an offline device. That used to make the `unsent` re-post SAFER rather than SAFE, and it is what
+ * the client-minted idempotency key now covers: `ReviewSubmission.idempotency_key` reaches
+ * `CreateReviewRequest`, and the server upserts the derived row rather than inserting a second one.
+ *
+ * IT IS A CAPABILITY, NOT A GUARANTEE, and the condition is not ours to enforce from in here. The
+ * server honours the key only when the post also carries a unit it can scope it to —
+ * `meta.device_key`, else `session_id` — and ignores it outright otherwise. `ReviewGate` fills the
+ * device key in for exactly this reason, but this function posts whatever body it is handed, so a
+ * caller that assembles its own body without a unit is back in the old world where a lost detractor
+ * is a gap in the data and a duplicated one is a lie in the data.
  */
 export const submitReview = async (
   target: ReviewTarget | undefined,

package/src/reviews/types.ts

@@ -97,6 +97,13 @@ export interface ReviewSubmission {
   contact?: string;
   session_id?: string;
   source?: string;
+  /**
+   * OPTIONAL client-minted key for the two-phase submit: two posts carrying the same key upsert ONE
+   * row instead of creating two. The server honours it ONLY when the post also carries a resolvable
+   * user — `meta.device_key`, else `session_id` — and silently ignores it otherwise, so it always
+   * travels with one of those. One key per gate impression, stable across that impression's posts.
+   */
+  idempotency_key?: string;
   meta?: Record<string, unknown>;
 }
 

package/src/types.ts

@@ -256,8 +256,11 @@ export type WireOnboardingProps = {
    *
    * SINCE 0.12.2, leaving it out no longer silently empties the funnel: when you pass `storage` and
    * this prop carries no `device_key`, the kit injects its OWN per-install key — the same one the
-   * analytics surfaces mint and persist — so the default wiring joins. Anything you DO pass wins
-   * verbatim and is never touched. See `autoJoinKey` for the opt-out and the two cases where the kit
+   * analytics surfaces mint and persist — so the default wiring joins. A `device_key` you DO pass
+   * wins verbatim and is never touched, provided it is a string with at least one non-whitespace
+   * character (`resolveIdentity`) — this map also accepts numbers and booleans, and a non-string or
+   * all-whitespace value is not a usable join key, so it is read as absent and the auto key is
+   * merged over it. See `autoJoinKey` for the opt-out and the two cases where the kit
    * still cannot fill the gap (no `storage`, or you opted out), which keep warning in dev.
    *
    * Never hand-write `userContext={{ deviceKey }}`: the server's device lookup reads `device_key`,
@@ -284,8 +287,11 @@ export type WireOnboardingProps = {
    * `autoJoinKey={false}` if you genuinely want an UNLINKED onboarding session; that restores the
    * pre-0.12.2 behavior exactly (nothing injected) and the dev warning fires again.
    *
-   * Two things this flag does NOT do. It never overrides a `device_key` you passed — a host-supplied
-   * key always wins, whatever this is set to. And it cannot conjure a key without `storage`: with no
+   * Two things this flag does NOT do. It never overrides a `device_key` you actually supplied — a
+   * host-supplied key always wins, whatever this is set to, where "supplied" means a string with at
+   * least one non-whitespace character (`resolveIdentity`); a non-string or an all-whitespace value
+   * is read as absent and the auto key is merged over it. And it cannot conjure a key without
+   * `storage`: with no
    * persistence the kit's id is minted fresh every launch, and a per-launch key corrupts
    * `min_sessions` instead of merely leaving the join empty, so the kit declines to inject and warns
    * in dev instead.

package/src/utils/submitResult.ts

@@ -21,19 +21,27 @@
  *
  * `submitReview` was a boolean 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 caller
- * treats `false` as "still owed" and re-posts. But the server mints its own row id
- * (`create_review` / `_new_id()`), and neither `CreateReviewRequest` nor the questionnaire response
- * body carries a client 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. A response of any status proves the server
- * was reached, and that is a different question from whether it liked the payload.
+ * treats `false` as "still owed" and re-posts. At the time neither body carried a client id, so
+ * there was NO idempotency key on the wire on either surface: a 502 returned AFTER the insert
+ * commits meant the re-post wrote a SECOND row. A response of any status proves the server was
+ * reached, and that is a different question from whether it liked the payload — which is why the
+ * three values stay, on both surfaces, whatever the wire gains.
  *
  * ── THE RESIDUAL, STATED HONESTLY ─────────────────────────────────────────────────────────────
  *
  * `unsent` is not proof the server never got it. A connection dropped after the request was written
  * — or after the row committed — surfaces as a thrown/rejected `fetch`, exactly like an offline
- * device. Retrying only on `unsent` is therefore SAFER, not SAFE. Closing that window needs a
- * CLIENT-MINTED IDEMPOTENCY KEY the server upserts on, which is a server change and 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.
+ * device. Closing that window needs a client-minted idempotency key the server upserts on, and AS
+ * OF 2026-08-19 THE TWO SURFACES DIFFER — do not read this paragraph as one fact about both:
+ *
+ *   • REVIEWS — closed. `CreateReviewRequest` takes an optional `idempotency_key` and the server
+ *     upserts a derived row on it, so a `ReviewGate` re-post merges instead of duplicating. It is a
+ *     capability, not a guarantee: the server honours the key only when the post also carries a
+ *     unit to scope it to (`meta.device_key`, else `session_id`), so a caller that strips both is
+ *     back to the old behaviour.
+ *   • QUESTIONNAIRES — still open, and still exactly as this paragraph used to read for both. The
+ *     response body carries no client id and the server has no idempotency path for it at all, so
+ *     retrying only on `unsent` there is SAFER, not SAFE. 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 type SubmitResult = "accepted" | "rejected" | "unsent";