@wireai/activation 0.13.0 → 0.13.3

package/src/permissions/types.ts

@@ -0,0 +1,131 @@
+/**
+ * Public types for the injectable mid-flow permission screens.
+ *
+ * THE ONE RULE THIS WHOLE MODULE EXISTS TO ENFORCE: the OS permission dialog is reached from the
+ * user's explicit primary tap and from nowhere else. iOS grants an app exactly ONE native
+ * notification prompt for its entire lifetime, so firing it on mount (the shape almost every app
+ * ships) spends the single ask on a user who has not been told why. A priming screen spends a
+ * cheap in-app screen first and only forwards the ones who said yes.
+ *
+ * DEPENDENCY-FREE, the RevenueCat-bridge idiom: the kit imports NO native permission module. The
+ * host passes `request` (and optionally `getStatus` / `openSettings`) in, exactly the way it hands
+ * the RevenueCat bridge real `CustomerInfo` objects. Wiring `expo-notifications` is five lines in
+ * the host and zero dependencies here.
+ *
+ * A PERMISSION SCREEN IS NOT A QUESTION. It mints no `key` and no `slot_id`, sends nothing to the
+ * backend, and never enters the thread, so `deriveAnswers` / `readProgress` and every completion
+ * semantic are byte-identical whether or not one is configured. Completion NEVER blocks on a grant.
+ */
+import type { PermissionScreenCopy } from "./permissionCopy";
+
+export type { PermissionScreenCopy } from "./permissionCopy";
+
+/**
+ * Which OS permission a screen primes. `notifications` is the one the kit ships copy for; any other
+ * string is accepted (the host supplies the copy) so a host can prime tracking, health or location
+ * without waiting on a kit release.
+ */
+export type WirePermissionKind = "notifications" | (string & {});
+
+/**
+ * What the host's `request` / `getStatus` answers.
+ *  - `granted`: the user allowed it.
+ *  - `denied`: not allowed right now, but the OS would still show a dialog if asked again
+ *    (Android, or an iOS provisional state).
+ *  - `blocked`: permanently refused. Asking again shows NOTHING, so the only route left is Settings.
+ */
+export type WirePermissionStatus = "granted" | "denied" | "blocked";
+
+/** How a permission screen ENDED. `skipped` is the secondary tap, which never burns the OS prompt. */
+export type WirePermissionOutcome = WirePermissionStatus | "skipped";
+
+/**
+ * The moments a permission screen reports. One stage, one canonical event name (see
+ * `permissionEventName`), so the funnel reads the same across every tenant.
+ *  - `shown`: the primer screen became visible. The denominator.
+ *  - `accepted`: the user tapped the primary, so the OS dialog is ABOUT to open. The gap between
+ *    `shown` and `accepted` is the only number that tells a host whether its rationale copy works.
+ *  - `granted` / `denied`: what the OS answered (a `blocked` answer reports as `denied` and carries
+ *    `status: "blocked"`, so the two are one funnel step and still distinguishable).
+ *  - `skipped`: the secondary tap. The prompt was NOT spent.
+ *  - `settings`: the user was redirected to the OS settings page (the `blocked` route).
+ */
+export type PermissionStage =
+  | "shown"
+  | "accepted"
+  | "granted"
+  | "denied"
+  | "skipped"
+  | "settings";
+
+/**
+ * WHERE a screen sits in the server-driven stream. The flow length is decided by the backend and
+ * varies per user, so every position is resolved against the card the flow is ABOUT to render:
+ *  - `"start"`: before the first card.
+ *  - `{ afterCard: n }`: after `n` cards have been shown (`{ afterCard: 2 }` sits between card 2
+ *    and card 3). An `n` past the end of a shorter-than-expected stream degrades to `"beforeEnd"`
+ *    rather than silently never showing.
+ *  - `"beforeEnd"`: immediately before the terminal recap. The default.
+ */
+export type PermissionPlacement = "start" | "beforeEnd" | { afterCard: number };
+
+/**
+ * One injectable permission screen.
+ *
+ * ```tsx
+ * import * as Notifications from "expo-notifications";
+ *
+ * <WireOnboarding
+ *   permissionScreens={[
+ *     {
+ *       permission: "notifications",
+ *       placement: "beforeEnd",
+ *       request: async () => {
+ *         const { status, canAskAgain } = await Notifications.requestPermissionsAsync();
+ *         return status === "granted" ? "granted" : canAskAgain ? "denied" : "blocked";
+ *       },
+ *     },
+ *   ]}
+ * />
+ * ```
+ */
+export type PermissionScreenConfig = {
+  /** Which permission this screen primes. Drives the default copy and every event's `permission`. */
+  permission: WirePermissionKind;
+  /**
+   * Stable id for the once-only / resume record. Defaults to `<permission>:<index in the array>`,
+   * which is right until you reorder the array; set it explicitly if you configure two screens for
+   * the same permission or intend to reorder them between releases.
+   */
+  id?: string;
+  /** Where the screen sits in the stream. Default `"beforeEnd"`. */
+  placement?: PermissionPlacement;
+  /**
+   * THE ONLY FUNCTION THE KIT CALLS THAT CAN OPEN AN OS DIALOG, and it is called from the primary
+   * press handler alone. Never from mount, never from an effect, never from a status probe.
+   */
+  request: () => Promise<WirePermissionStatus>;
+  /**
+   * Optional NON-PROMPTING status read (`Notifications.getPermissionsAsync()`), used only to pick
+   * which primary action the screen offers: a `blocked` user gets "Open settings" instead of an
+   * "Enable" button that would open nothing, and an already-granted user gets a plain Continue.
+   * Leave it out and the screen simply always offers the ask.
+   */
+  getStatus?: () => Promise<WirePermissionStatus>;
+  /** Open the OS settings page (`Linking.openSettings()`). Only reachable on the `blocked` route. */
+  openSettings?: () => void | Promise<void>;
+  /** Rationale copy overrides. Anything left out keeps the kit default for this permission. */
+  copy?: Partial<PermissionScreenCopy>;
+  /**
+   * Name of a host illustration (the existing `illustrations` registry). Defaults to the
+   * permission name, so registering `illustrations={{ notifications: <MyBell/> }}` is enough. The
+   * kit ships a dependency-free default so the screen is never a blank box.
+   */
+  illustration?: string;
+  /**
+   * Fired once, with the outcome this screen produced. This is the seam for scheduling a local
+   * notification the moment a grant lands; the kit deliberately schedules nothing itself. It can
+   * never break the flow: a throw here is caught and the flow continues.
+   */
+  onResult?: (permission: WirePermissionKind, outcome: WirePermissionOutcome) => void;
+};

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/persistedSession.ts

@@ -37,7 +37,7 @@ export type WireOnboardingStorage = {
 export const DEFAULT_SESSION_TTL_MS = 3_600_000;
 
 /** Ceiling on the storage read — a hung adapter degrades to a fresh mint, never a stuck gate. */
-const READ_TIMEOUT_MS = 1_500;
+export const READ_TIMEOUT_MS = 1_500;
 
 /** Storage key for an app's cached session, e.g. `wireai:session:acme`. */
 export const sessionStorageKey = (appId: string): string => `wireai:session:${appId}`;
@@ -51,7 +51,14 @@ export type LoadedSession = {
   resumed: boolean;
 };
 
-const withTimeout = <T>(p: Promise<T>, ms: number): Promise<T | undefined> => {
+/**
+ * Race a storage read against a ceiling, resolving `undefined` when the adapter did not answer.
+ * Exported so the permission memory reads through the same ceiling as the session seed rather than
+ * carrying a second copy of it. NOT the kit's only such helper: `features/cache.ts`,
+ * `session-analytics/lifecycle.ts` and `analytics/eventQueue.ts` each keep their own local timeout
+ * for their own transports. Consolidating those is a separate change, not this one.
+ */
+export const withTimeout = <T>(p: Promise<T>, ms: number): Promise<T | undefined> => {
   let timer: ReturnType<typeof setTimeout>;
   const timeout = new Promise<undefined>((resolve) => {
     timer = setTimeout(() => resolve(undefined), ms);
@@ -150,7 +157,7 @@ export const clearPersistedSession = (storage: WireOnboardingStorage, key: strin
  * not opt in.)
  *
  *  - undefined / false (the default) → `true`: clear on completion, so the NEXT onboarding on this
- *    device mints a fresh session. This is the legacy single-stage behavior (e.g. Myelino).
+ *    device mints a fresh session. This is the legacy single-stage behavior.
  *  - true → `false`: LEAVE the seed in place so a same-signup re-entry/remount within the TTL
  *    resumes the SAME session (one funnel start) instead of minting a phantom second `started`.
  *    Freshness for a genuinely new run is then governed by the TTL (past `sessionTtlMs` → fresh

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",