@wireai/activation 0.13.2 → 0.13.5

package/src/identity/identityRecord.ts

@@ -65,7 +65,15 @@ export type ResolveIdentityInput = {
   scope?: string;
 };
 
-/** Well-known key into the runtime-global symbol registry — one provenance registry per process. */
+/**
+ * Well-known key into the runtime-global symbol registry — one provenance registry per process.
+ *
+ * @globalSlot LATCH — the REGISTRY OBJECT is created once and its identity is then stable. A second
+ * write drops every host id recorded so far, so `hostIdentity()` answers "no host key in this
+ * process" for a process that demonstrably has one, and the kit injects its own `wdev_*` beside it
+ * without warning. Its CONTENTS are live (`host` gains an entry on every host-sourced
+ * `resolveIdentity`), so both accessors go through `provenanceRegistry()` on every call.
+ */
 const IDENTITY_PROVENANCE_SLOT: unique symbol = Symbol.for("@wireai/activation:identityProvenance");
 
 /** `"<space>:<scope>"` → the HOST-supplied value seen for it. Auto values are never recorded. */

package/src/identity/userIdentity.ts

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

package/src/questionnaire/QuestionnaireGate.tsx

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

package/src/questionnaire/index.ts

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

package/src/questionnaire/transport.ts

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

package/src/reviews/ReviewGate.tsx

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

package/src/reviews/index.ts

@@ -54,8 +54,17 @@ export { requestStoreReview, openStoreListing, storeUrl } from "./storeReview";
 // `fetchReviewDecision` is the mirror of `fetchQuestionnaireDecision`. Use it instead of
 // hand-rolling a decision fetch: a host-rolled one that collapses `{fire:false}` into undefined
 // makes the server able to turn prompts ON but never OFF (the 2026-07-16 first-session incident).
+// `submitReview` resolves with a THREE-state `ReviewSubmitResult` (accepted / rejected / unsent),
+// not a boolean: only `unsent` may be retried, because the wire has no idempotency key and a
+// re-post after a non-2xx that already committed writes a second row.
 export { submitReview, fetchReviewDecision, reportAppEvent } from "./transport";
-export type { FetchReviewDecisionOptions, ReportAppEventOptions } from "./transport";
+export type {
+  FetchReviewDecisionOptions,
+  ReportAppEventOptions,
+  ReviewSubmitResult,
+} from "./transport";
+// The same verdict under its shared name — `submitQuestionnaireResponse` resolves it too.
+export type { SubmitResult } from "../utils/submitResult";
 
 // ─── Gate-key + storage helpers (shared coachmark storage singleton) ──────────
 export {

package/src/reviews/runtime.ts

@@ -31,7 +31,11 @@ export const resolveStorage = (
 declare const __DEV__: boolean | undefined;
 
 /** Once-per-process latch on its own `Symbol.for` slot: a plain `let` would warn once per inlined
- *  bundle copy, and the gates live in three of them. */
+ *  bundle copy, and the gates live in three of them.
+ *
+ *  @globalSlot LATCH — written `true` by the first gate that found no sync storage, and never again.
+ *  A second differing write re-arms a warning the process already spent, so a host that mounts three
+ *  gates gets the same paragraph three times and stops reading it. */
 const NO_STORAGE_WARNED_SLOT: unique symbol = Symbol.for(
   "@wireai/activation:gateStorageWarned",
 );
@@ -138,6 +142,12 @@ const readStr = (storage: CoachmarkStorage | null, key: string): string | undefi
 // regardless of what the session registry does afterwards. The client counter only has to be
 // monotone and per-launch; the server's own `min_sessions` still counts real `app.session_started`
 // events, so nothing downstream needs the two ids to be identical.
+//
+// @globalSlot LATCH — pinned by the FIRST read and stable for the whole launch. This is the one
+// slot whose latch is the fix: it samples the LIVE `currentSessionId` once, on purpose, so that
+// registry changing underneath it (render before effect, on every cold start) cannot change the
+// unit mid-launch and hand `minSessions: 2` a second "session" inside one app open. A second
+// differing write is therefore not a stale-cache bug, it IS the defect — see the block above.
 const PROCESS_OPEN_ID_SLOT: unique symbol = Symbol.for("@wireai/activation:processOpenId");
 
 type GlobalWithOpenId = typeof globalThis & { [PROCESS_OPEN_ID_SLOT]?: string };

package/src/reviews/transport.ts

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

package/src/session-analytics/useLifecycleEvents.ts

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

package/src/theme/ThemeContext.tsx

@@ -3,12 +3,60 @@
  * themed card via `useOnboardingTheme()`. WHY a context rather than prop-drilling:
  * the cards are mounted by the SDK's ComponentRenderer (not by us), so we can't
  * pass them props directly — they must read the theme from context.
+ *
+ * ── WHY THE CONTEXT LIVES ON A `Symbol.for` SLOT ───────────────────────────────────────────────
+ *
+ * It was a plain `createContext(...)`, and tsup inlines this module into FIVE dist bundles
+ * (`.`, `./reviews`, `./questionnaire`, `./coachmarks`, `./showcase`) — so each one carried its own
+ * context instance. `OnboardingThemeProvider` is exported ONLY from the root barrel, so on any
+ * `dist` resolution path (plain RN CLI, `unstable_enablePackageExports: false`, node, jest, SSR) a
+ * host that wrapped its tree in `<OnboardingThemeProvider>` and rendered `<ReviewGate>` from
+ * `@wireai/activation/reviews` was writing one context and reading another. Nothing crashed and
+ * nothing warned: `useOnboardingTheme`'s `ctx ?? mergeTheme()` fallback quietly served the NEUTRAL
+ * default theme, so the tenant's brand simply did not apply to the gate. On-device this was masked
+ * only because Metro's `react-native` export condition collapses every subpath back to this one
+ * `src/` file — the same "bundler accident, not a guarantee" the `currentSession` header names, and
+ * the same root cause as the optional-peers bug 0.13.3 fixed.
+ *
+ * The bundler-agnostic fix, exactly as `coachmarks/runtime`, `analytics/currentSession`,
+ * `context/deviceId` and `features/WireFeaturesProvider` already do it: park the ONE context on a
+ * well-known `globalThis` slot keyed by `Symbol.for(...)`. `Symbol.for` uses the runtime-global
+ * symbol registry, so every inlined copy of this module resolves the SAME symbol, finds the slot
+ * already filled, and reuses that instance — one context identity however many copies exist.
+ * `globalThis` is present and identical in Hermes/React Native, Node and SSR (we never touch
+ * `window`), so this is safe on every host. `test/canary/themeContextIdentity.test.tsx` measures it
+ * in the BUILT artifact, because the defect is invisible in source.
  */
 import React, { createContext, useContext, useMemo } from "react";
 import { mergeTheme } from "./defaultTheme";
 import type { OnboardingTheme } from "./types";
 
-const OnboardingThemeContext = createContext<OnboardingTheme | null>(null);
+/**
+ * Well-known key into the runtime-global symbol registry. `Symbol.for` (NOT a plain `Symbol()`) is
+ * what makes this cross-bundle: it returns the SAME symbol for the same string across every copy of
+ * this module, so duplicated inlined copies all address one slot.
+ *
+ * @globalSlot LATCH — the React context object is minted by the first copy of this module to load
+ * and every later copy ADOPTS it (the `if (!…)` guard below says so in one line). A second write
+ * re-splits the identity: `<OnboardingThemeProvider>` (root barrel only) publishes into one context
+ * while `<ReviewGate>` from a subpath reads another, and `useOnboardingTheme`'s `ctx ?? mergeTheme()`
+ * fallback quietly serves the NEUTRAL theme. Because it is a latch, and only because of that, the
+ * module-local `const OnboardingThemeContext` below may cache it.
+ */
+const THEME_CONTEXT_SLOT: unique symbol = Symbol.for("@wireai/activation:themeContext");
+
+type GlobalWithThemeContext = typeof globalThis & {
+  [THEME_CONTEXT_SLOT]?: React.Context<OnboardingTheme | null>;
+};
+
+const themeGlobal = globalThis as GlobalWithThemeContext;
+
+// First copy to load creates the context; every later copy adopts it. Never overwrite an existing
+// slot — a second `createContext` here would re-split the identity this guard exists to keep whole.
+if (!themeGlobal[THEME_CONTEXT_SLOT]) {
+  themeGlobal[THEME_CONTEXT_SLOT] = createContext<OnboardingTheme | null>(null);
+}
+const OnboardingThemeContext = themeGlobal[THEME_CONTEXT_SLOT] as React.Context<OnboardingTheme | null>;
 
 export type OnboardingThemeProviderProps = {
   /** Partial overrides merged over the neutral default theme. */

package/src/types.ts

@@ -340,7 +340,7 @@ export type OnboardingProgress = {
    * `answers.interests` silently becomes `answers.what_are_you_into_v2`, with no error anywhere. A
    * slot is the question's identity independent of its wording.
    *
-   * FULLY ADDITIVE, AND LIVE SINCE 2026-07-28 (server `47dae92`). The deployed server sends it on
+   * FULLY ADDITIVE, AND LIVE SINCE 2026-07-28. The deployed server sends it on
    * `progress` for every AI-GENERATED question, as `adaptive_<n>` 1-based over adaptive answers, and
    * for a CONFIGURED question only when the tenant set one. Where the tenant set none the field is
    * simply absent. Every fallback is PER-CARD, so a thread that mixes slotted and unslotted cards

package/src/utils/submitResult.ts

@@ -0,0 +1,39 @@
+/**
+ * submitResult — the ONE delivery verdict every user-payload POST in this kit reports back.
+ *
+ * WHY IT IS SHARED, AND WHY IT IS NOT A BOOLEAN. Two surfaces post a payload the user typed —
+ * `submitReview` (`reviews/transport.ts`) and `submitQuestionnaireResponse`
+ * (`questionnaire/transport.ts`) — and NEITHER has a persisted queue behind it (unlike
+ * `analytics/eventQueue`, with its `maxSize`/`maxRetries`/backoff). Both sit behind a permanent
+ * once-gate: the host writes `wire_review_<id>_seen` / `wire_questionnaire_<id>_<ver>_seen` when the
+ * gate resolves, so a payload that dies in the socket is lost AND the user is never asked again.
+ * Reading the fate of the request is the only thing that lets a caller keep an undelivered payload
+ * recoverable, so the two surfaces must answer the same question in the same words.
+ *
+ *   • `accepted` — the server answered 2xx. Stored.
+ *   • `rejected` — the server ANSWERED, non-2xx. It was reached; it either stored the payload and
+ *                  lost the ack (a gateway 502 after the write commits) or deliberately refused it.
+ *                  Either way the server owns the outcome and a re-post risks a SECOND row.
+ *   • `unsent`   — nothing came back at all: no target, a missing/throwing `fetch`, a rejected
+ *                  request. **This is the ONLY outcome a caller may retry on.**
+ *
+ * ── WHY THREE VALUES AND NOT TWO (pinned here so the defect cannot move surface) ───────────────
+ *
+ * `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.
+ *
+ * ── 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.
+ */
+export type SubmitResult = "accepted" | "rejected" | "unsent";