@wireai/activation 0.13.2 → 0.13.5

package/dist/{types-Buj9Lw9t.d.ts → types-h2BZvl1t.d.ts}

@@ -1,6 +1,46 @@
 import { O as OnboardingTheme } from './types-BKfpdZzX.js';
 import { C as CoachmarkStorage } from './types-BcmagF6K.js';
-import { W as WireFeatures, a as WireFeaturesConfig } from './types-CKFhyrMu.js';
+import { a as WireFeatures, b as WireFeaturesConfig } from './types-BpwiRpA8.js';
+
+/**
+ * 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.
+ */
+type SubmitResult = "accepted" | "rejected" | "unsent";
 
 /**
  * The firing verdict — the SAME contract on both sides of the seam. `decideReview`
@@ -161,4 +201,4 @@ interface ReviewGateController {
     markResolved: () => void;
 }
 
-export type { ReviewGateProps as R, UseReviewGateOptions as U, ReviewPresentation as a, ReviewGateController as b, ReviewDecision as c, ReviewStoreConfig as d, RatingRoute as e, ReviewConfig as f, ReviewDecisionResponse as g, ReviewGateEvent as h, ReviewGateEventName as i, ReviewSubmission as j, ReviewTarget as k };
+export type { ReviewGateProps as R, SubmitResult as S, UseReviewGateOptions as U, ReviewPresentation as a, ReviewGateController as b, ReviewDecision as c, ReviewStoreConfig as d, RatingRoute as e, ReviewConfig as f, ReviewDecisionResponse as g, ReviewGateEvent as h, ReviewGateEventName as i, ReviewSubmission as j, ReviewTarget as k };

package/llms.txt

@@ -30,7 +30,7 @@
 
 The package is more than `<WireOnboarding>`. Tree-shakeable subpath exports (each keeps the onboarding UI out of an analytics-only bundle):
 
-- `@wireai/activation/analytics`: `createAnalytics({ serverUrl, apiKey, storage })` (Segment/PostHog-shaped `track` / `screen` / `identify` / `setUserContext` / `reset` over an offline-first queue), `createScreenTracker` / `screenTrackingHandler` (auto screen views), `reportAppEvent`, `createEventQueue`, `clearUserContext` (logout). Rich `WireUserContext` supports an opt-in `userEmail` (raw by default, `hashEmail` to fold) and auto-mints a persisted per-install `device_key`. `identify` refuses email-shaped ids unless `allowEmailAsUserId`. See the README "Rich user context & PII" section.
+- `@wireai/activation/analytics`: `createAnalytics({ serverUrl, apiKey, storage })` (Segment/PostHog-shaped `track` / `screen` / `identify` / `setUserContext` / `reset` over an offline-first queue), `createScreenTracker` / `screenTrackingHandler` (auto screen views), `reportAppEvent`, `createEventQueue`, `clearUserContext` (logout). Rich `WireUserContext` supports an opt-in `userEmail` (raw by default, `hashEmail` to fold) and auto-mints a persisted per-install `device_key`. `identify` refuses email-shaped ids unless `allowEmailAsUserId`. See the README "Rich user context & PII" section. Also `wireDoctor({ target, storage })`, the DEV-ONLY self-check: four `{name, ok, detail}` checks (target shape, server reachability, storage writability, and a `dry_run` round trip whose verdict is `written === 1 && skipped === 0` read from the ack body, because `/v1/events` answers 200 for a batch it discards). It never throws, never prints any part of the apiKey, and does nothing at all when `__DEV__` is unset.
 - `@wireai/activation/reviews`: the in-app review gate. `useReviewGate`, `fetchReviewDecision` (server AI seam; a `{fire:false}` survives intact), `ReviewGate` UI. `minSessions` defaults to 2 (never prompts on the first session; a server decision still overrides).
 - `@wireai/activation/questionnaire`: the pre-onboarding questionnaire gate. `useQuestionnaireGate`, `fetchQuestionnaireDecision` (same server seam; a body without a boolean `fire` resolves to null, never shows).
 - `createRevenueCatBridge({ analytics, entitlementId })` (ROOT-exported) → the RevenueCat purchase funnel: `paywallShown` / `checkoutStarted` / `purchaseCompleted` / `purchaseFailed` / `purchasesRestored` / `syncPlanTier`, emitting the canonical `wire_paywall_shown` / `wire_checkout_started` / `wire_purchase_completed` / `wire_purchase_failed` / `wire_purchase_restored` names. The kit does NOT depend on `react-native-purchases` (a native module); the RevenueCat objects are typed structurally, so a host passes the real ones. THE JOIN KEY between a purchase and an onboarding is `user_context.device_key`, never `session_id` (an onboarding session id is the A2A contextId, an app-event session id is the per-open id, and they are separate spaces): pass the same device key to `createAnalytics`/`createWireActivation` AND to `<WireOnboarding userContext={activationJoinContext(deviceKey)} />`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wireai/activation",
-  "version": "0.13.2",
+  "version": "0.13.5",
   "private": false,
   "description": "Premium, fully-themable drop-in AI onboarding kit for React Native / Expo, on top of the open-source wireai-rn SDK.",
   "author": "Malik Chohra <malik@getwireai.com>",
@@ -137,8 +137,12 @@
   "scripts": {
     "build": "tsup",
     "prepack": "npm run build",
+    "prepublishOnly": "npm run build && npm run test:canary",
     "typecheck": "tsc --noEmit",
+    "pretest": "npm run build",
     "test": "node --test --experimental-strip-types --import ./test/register-ts-resolver.mjs \"src/**/*.test.ts\" \"test/canary/**/*.test.tsx\"",
+    "test:canary": "node --test --experimental-strip-types --import ./test/register-ts-resolver.mjs \"test/canary/**/*.test.tsx\"",
+    "check:contract": "node --no-warnings --experimental-strip-types scripts/check-events-contract.mjs",
     "pack:tarball": "npm pack"
   },
   "peerDependencies": {
@@ -180,6 +184,7 @@
   "devDependencies": {
     "@blazejkustra/react-native-onboarding": "^1.0.1",
     "@types/react": "^19.0.0",
+    "ajv": "8.20.0",
     "expo-blur": "^15.0.0",
     "react": "^19.2.7",
     "react-native": "^0.86.0",

package/src/OnboardingFlow.tsx

@@ -179,7 +179,17 @@ export const OnboardingFlow: React.FC<OnboardingFlowProps> = ({
   // Trailing-edge debounce timer for prefetch-on-select (see previewOnSelect below).
   const previewTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
 
-  const started = useRef(false);
+  // The attempt generation. It lives in STATE, not in a ref, and both the auto-start effect and
+  // the startup watchdog list it in their deps — a retry has to genuinely RE-ARM both, and a ref
+  // cannot re-trigger an effect. Nothing else in those deps moves on a retry: `sendMessage` is
+  // memoized in wireai-rn on [registry, provider, model], and `lastCard` is still `undefined`
+  // because no card ever arrived. Without the generation the kickoff is never re-sent, `timedOut`
+  // can never become true a second time, and the retry budget can never be spent — which leaves a
+  // backend that never answers sitting on the loader forever.
+  const [runId, setRunId] = useState(0);
+  // The generation whose kickoff has already been sent. -1 = nothing sent yet (so the very first
+  // run can be told apart from a retry, which must NOT re-fire `started`/`resumed`).
+  const startedRunRef = useRef(-1);
   const finished = useRef(false);
   const errored = useRef(false);
   const attempts = useRef(0);
@@ -210,33 +220,50 @@ export const OnboardingFlow: React.FC<OnboardingFlowProps> = ({
   const progress = useMemo(() => readProgress(lastCard?.response), [lastCard]);
 
   // 1. Auto-start: the backend treats the first inbound message as "begin".
-  //    On a RESUMED session (persisted id restored after an app kill) the kickoff is
-  //    the skip sentinel instead: the server has this session mid-flow with a pending
-  //    question, and would record `startMessage`'s literal text as its ANSWER — the
-  //    sentinel advances one card recording nothing (a `screen_skipped`). On a session
-  //    the server no longer knows (restart/expiry), the sentinel degrades cleanly to a
-  //    normal kickoff under the same id. Retries re-send the same kickoff.
+  //    ONLY the very first attempt of a fresh session sends `startMessage`. Every other kickoff
+  //    — a RESUMED session (persisted id restored after an app kill) and every RETRY — sends the
+  //    skip sentinel, because both can reach a server that already has a question PENDING on this
+  //    session, and a non-empty message arriving against a pending question is recorded as that
+  //    question's ANSWER (server engine dispatch: `if user_message and pending and not
+  //    _stop_requested(...)` appends `{key, question, answer}` to `session["answers"]`). For a
+  //    retry that is not hypothetical: the watchdog fires at `startTimeoutMs` while a slow LLM is
+  //    still generating, so the server can genuinely hold card 1 pending when the retry lands, and
+  //    the user's first onboarding answer becomes the literal kickoff text — silently.
+  //    THE COST, stated plainly: when the server DID have card 1 pending, the sentinel SKIPS that
+  //    card — the user loses one question and the server logs a `screen_skipped`. Deliberate. A
+  //    skipped question is visible in the funnel and recorded as nothing; a kickoff string stored
+  //    as the user's first answer is invisible and poisons the data the product is built on.
+  //    When the server has no pending (restart/expiry, or a retry whose predecessor never landed)
+  //    the sentinel is zeroed and falls through — it degrades cleanly to a normal kickoff under
+  //    the same id, which is what makes it safe to send on an attempt that may be either.
   useEffect(() => {
-    if (started.current) return;
-    started.current = true;
-    sendMessage(resumed ? SKIP_ONE_SENTINEL : startMessage);
+    if (startedRunRef.current === runId) return;
+    const isFirstRun = startedRunRef.current < 0;
+    startedRunRef.current = runId;
+    sendMessage(isFirstRun && !resumed ? startMessage : SKIP_ONE_SENTINEL);
+    // Only the FIRST run is a session start. A retry re-kicks the flow (with the sentinel) but
+    // must not re-fire `started`/`resumed`, or every host funnel double-counts the session; the
+    // retry itself is already surfaced as a `retry` event by the error effect below.
+    if (!isFirstRun) return;
     // Surface the session id (the A2A contextId) on the start event so a host can capture it
     // and bind a user AFTER the flow via `identifyOnboarding({ contextId })` — completion clears
     // the persisted session, so the in-flight event is the reliable post-flow handle. sessionId
-    // is stable for the whole session (minted before this subtree mounts), so this stays mount-once.
+    // is stable for the whole session (minted before this subtree mounts), so this stays once
+    // per session.
     onEventRef.current?.(
       resumed
         ? { type: "resumed", contextId: sessionId }
         : { type: "started", contextId: sessionId },
     );
-  }, [sendMessage, startMessage, resumed, sessionId]);
+  }, [sendMessage, startMessage, resumed, sessionId, runId]);
 
-  // 2. Startup watchdog.
+  // 2. Startup watchdog. `runId` is load-bearing in these deps: after a retry there is still no
+  //    card, so `lastCard` does not change and nothing else would re-arm the timer.
   useEffect(() => {
     if (lastCard) return;
     const timer = setTimeout(() => setTimedOut(true), startTimeoutMs);
     return () => clearTimeout(timer);
-  }, [lastCard, startTimeoutMs]);
+  }, [lastCard, startTimeoutMs, runId]);
 
   // A new card arrived → clear any prior inline validation error + emit a turn event.
   useEffect(() => {
@@ -287,8 +314,10 @@ export const OnboardingFlow: React.FC<OnboardingFlowProps> = ({
   // Does NOT clear the attempt counter or the degraded flag — the caller decides that.
   const restartThread = useCallback(() => {
     setTimedOut(false);
-    started.current = false;
     errored.current = false;
+    // Bumping the generation IN STATE is what actually re-runs the kickoff effect and re-arms the
+    // watchdog. Flipping a ref here would re-trigger neither.
+    setRunId((n) => n + 1);
     reset();
   }, [reset]);
 

package/src/WireOnboarding.tsx

@@ -114,7 +114,8 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
   // `activated` funnel rather than an error. Two real consumers shipped without it.
   //
   // A host-supplied key is also RECORDED on the process-wide provenance registry, so a sibling
-  // surface can later ask "does this app own a device id?" — see the K9 warning below. The registry
+  // surface can later ask "does this app own a device id?" — see the third-id-space warning below.
+  // The registry
   // write is idempotent (same key, same value), so running it from a memo is safe under StrictMode's
   // double-invoke; it lives here rather than in an effect so the answer is already true for any
   // surface constructed later in the same tick.
@@ -143,7 +144,7 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
   //     counter rather than leaving it empty, and it inflates distinct-device counts on top. Same
   //     reason `useLifecycleEvents` gates its own fallback on storage.
   //
-  // ⚠️ 0.13.0 (K1): the third condition used to be `Boolean(storage)` — the PRESENCE of the prop,
+  // ⚠️ 0.13.0: the third condition used to be `Boolean(storage)` — the PRESENCE of the prop,
   // never the SUCCESS of the write. A REJECTING adapter (a locked / full / permission-denied
   // AsyncStorage, the most common real breakage) therefore walked the per-launch key in through the
   // front door: `hydrateAutoDeviceKey` resolves to the in-memory mint on every failure branch, and a
@@ -153,8 +154,8 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
   //
   // It resolves through `hydrateDeviceIdentity`, never the sync `resolveAutoDeviceKey`: the sync
   // contract returns the freshly minted id and adopts the persisted one milliseconds later, which
-  // is exactly the 0.12.1 H1 defect — the key stamped here must be the one the analytics side
-  // stamps, not a fresh mint per launch. The value is therefore awaited BEHIND THE LOADER GATE
+  // is exactly the split-identity defect 0.12.1 shipped — the key stamped here must be the one the
+  // analytics side stamps, not a fresh mint per launch. It is therefore awaited BEHIND THE LOADER GATE
   // below (the same gate the persisted-session read already holds, and it is only ever open when
   // `storage` is present anyway), because `userContext` feeds the `llm` memo: swapping it after the
   // provider mounted would recreate the A2A adapter and drop the server-learned `contextId`.
@@ -201,7 +202,7 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
     [userContextStable, injectedJoinKey],
   );
 
-  // THE JOIN DECISION IS FROZEN AT THE MOMENT THE GATE OPENS (K5), exactly as `startupUserIdRef`
+  // THE JOIN DECISION IS FROZEN AT THE MOMENT THE GATE OPENS, exactly as `startupUserIdRef`
   // below freezes the user id, and for the identical reason: `userContext` feeds the `llm` memo, and
   // wireai-rn recreates its A2A adapter whenever the `llm` identity changes — the adapter ctor resets
   // `contextId` (`this.contextId = void 0`), so the server-learned session id is dropped.
@@ -261,7 +262,7 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
     );
   }, [warnMissingJoinKey, autoJoinReason]);
 
-  // THE SECOND CASE AUTO-JOIN WOULD OTHERWISE SILENCE (K9). 0.12.2 suppressed the missing-join-key
+  // THE SECOND CASE AUTO-JOIN WOULD OTHERWISE SILENCE. 0.12.2 suppressed the missing-join-key
   // warning whenever injection succeeded, which is right when the host genuinely owns no device id —
   // and wrong when it owns one and simply forgot it HERE. That host used to get a loud warning and
   // now gets a silent third id space: its app events under its own key, this onboarding session under

package/src/activation/revalidation.ts

@@ -24,7 +24,15 @@
  * the same symbol and shares one store, on Hermes/RN, Node and SSR alike.
  */
 
-/** Well-known key into the runtime-global symbol registry — one shared store across every bundle. */
+/**
+ * Well-known key into the runtime-global symbol registry — one shared store across every bundle.
+ *
+ * @globalSlot LATCH — the STORE OBJECT is created once and its identity is then stable. A second
+ * write replaces the `listeners` set every existing subscriber is registered in, so their
+ * unsubscribes free the wrong set and a bump reaches nobody — silently, which is the whole failure
+ * class this slot exists to close. Its CONTENTS (`version`, `listeners`) are live and mutated in
+ * place, which is why every accessor here goes through `store()` instead of holding a reference.
+ */
 const REVALIDATION_SLOT: unique symbol = Symbol.for(
   "@wireai/activation:activationRevalidation",
 );

package/src/activation/wireActivation.ts

@@ -5,8 +5,8 @@
  * because the kit didn't own them — an awaitable action POST (`wireTrackActionAwait`), its OWN
  * per-open session id (`getWireSessionId`, minted because the kit's `getCurrentSessionId` desynced
  * cross-bundle — defect B), and an await-then-bump revalidation dance (`bumpActivationDecision`).
- * Defect B is fixed (PR #48: `getCurrentSessionId` is a `globalThis` singleton, reliable under
- * `dist`), so the kit can now own all three behind one thin surface:
+ * Defect B is fixed — `getCurrentSessionId` is now a `globalThis` singleton, reliable under
+ * `dist` — so the kit can own all three behind one thin surface:
  *
  *   const wire = createWireActivation({ serverUrl, apiKey });   // or useWireActivation(...)
  *   await wire.track("journal_done");                            // awaitable POST + auto-revalidate
@@ -108,7 +108,7 @@ export const createWireActivation = (config: WireActivationConfig): WireActivati
   const explicitDeviceKey = clean(config.deviceKey) ?? clean(config.userContext?.deviceKey);
   // Record a HOST-supplied key on the process provenance registry, so a `<WireOnboarding>` mount that
   // was NOT given one can tell "this app owns no device id" (fine, inject) from "this app owns one
-  // and forgot it here" (the silent third id space — K9). Recording only; nothing reads it on this path.
+  // and forgot it here" (the silent third id space). Recording only; nothing reads it on this path.
   resolveIdentity({
     value: explicitDeviceKey,
     space: "device",

package/src/analytics/analyticsFacade.ts

@@ -198,7 +198,7 @@ export const createAnalytics = (
       : undefined;
   // Record a HOST-supplied key on the process provenance registry, so a `<WireOnboarding>` mount that
   // was NOT given one can tell "this app owns no device id" (fine, inject) from "this app owns one
-  // and forgot it here" (the silent third id space — K9). Recording only; nothing reads it here.
+  // and forgot it here" (the silent third id space). Recording only; nothing reads it here.
   resolveIdentity({
     value: hostDeviceKeyAtInit,
     space: "device",
@@ -333,7 +333,7 @@ export const createAnalytics = (
 
   const screen = (name: string, props?: AnalyticsProps): void => {
     if (!name) return;
-    // Reuse the K6 screen event shape (question_key='screen'); route through the queue for offline-first.
+    // Reuse the existing screen event shape (question_key='screen'); route through the queue for offline-first.
     const meta = { screen: name, ...(props ?? {}) };
     const clientEvent: ClientEvent = {
       event_type: "app_event",

package/src/analytics/currentSession.ts

@@ -59,6 +59,12 @@ import { warnInDev } from "../utils/warnInDev";
  * 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 LIVE — every app-open overwrites this with that open's id, so a reader that captures
+ * it into a module-local (or a `const` taken once at mount) posts the PREVIOUS open's session to a
+ * server that has already moved on. Read it at the moment of use, through `getCurrentSessionId()` /
+ * `ensureCurrentSessionId()`. `reviews/runtime`'s `currentOpenId()` deliberately pins one sample of
+ * it for the launch; that is a documented latch DERIVED from this slot, not a cache of it.
  */
 const CURRENT_SESSION_ID_SLOT: unique symbol = Symbol.for(
   "@wireai/activation:currentSessionId",
@@ -100,6 +106,10 @@ const MINT_WARNING =
  * cross-bundle reason as the id itself: a plain module `let` would warn once per inlined copy, i.e.
  * once per bundle, not once per process. NOT cleared by `resetCurrentSessionId`: "warn once" is a
  * process-lifetime promise, and a test that resets the id between mints is still one process.
+ *
+ * @globalSlot LATCH — written `true` on the first mint that actually warned, and never again. A
+ * second differing write would re-arm a warning the process has already spent, turning "once" into
+ * "once per whoever cleared it".
  */
 const MINT_WARNED_SLOT: unique symbol = Symbol.for(
   "@wireai/activation:currentSessionIdMintWarned",

package/src/analytics/eventQueue.ts

@@ -86,7 +86,7 @@ const DEFAULTS = {
 /** Ceiling on the persisted-backlog read — a hung adapter degrades to an empty start, never a stall. */
 const READ_TIMEOUT_MS = 1500;
 
-// ── One storage slot per QUEUE, not per appId (K4) ───────────────────────────────────────────────
+// ── One storage slot per QUEUE, not per appId ────────────────────────────────────────────────────
 //
 // The default key was derived from `appId` alone, so two `createAnalytics` instances for one tenant —
 // the documented double-wiring, a façade for `track`/`screen` plus an activation instance — shared ONE
@@ -99,6 +99,11 @@ const READ_TIMEOUT_MS = 1500;
 // A `Symbol.for` slot for the same reason as every other registry here: tsup inlines a copy of this
 // module into each bundle, and a plain module `let` would let the `.` and `./analytics` copies each
 // think they were the first claimant of the same key.
+//
+// @globalSlot LATCH — the claimed-key Set is created once and its identity is then stable. A second
+// write hands the next queue an EMPTY claim list, so it re-claims a key a live queue already owns
+// and the two silently share one persisted backlog again. Its MEMBERS are live, which is why
+// `claimedQueueKeys()` re-reads the slot on every call rather than caching the Set.
 const QUEUE_KEY_SLOT: unique symbol = Symbol.for("@wireai/activation:eventQueueKeys");
 
 type GlobalWithQueueKeys = typeof globalThis & { [QUEUE_KEY_SLOT]?: Set<string> };
@@ -153,10 +158,19 @@ type QueuedItem = { id: number; event: ClientEvent; sig: string };
 /** Persisted shape — the local id + the (already envelope-stamped) event. `sig` is recomputed on load. */
 type PersistedItem = { id: number; event: ClientEvent };
 
-const withTimeout = <T>(p: Promise<T>, ms: number): Promise<T | undefined> => {
+/**
+ * The verdict of a read that ran out of time. A DISTINCT value, and never `undefined` — an
+ * `undefined` here is byte-identical to "the adapter answered, there is no backlog", and that
+ * conflation destroys data silently: `parsePersisted(undefined)` gives `[]`, hydration takes its
+ * `length === 0` early return without throwing, and the next `persist()` writes the in-memory
+ * pending list over a blob nobody has read — or, with nothing pending, `removeItem`s it outright.
+ */
+const READ_TIMED_OUT: unique symbol = Symbol("wireai:storage-read-timeout");
+
+const withTimeout = <T>(p: Promise<T>, ms: number): Promise<T | typeof READ_TIMED_OUT> => {
   let timer: ReturnType<typeof setTimeout>;
-  const timeout = new Promise<undefined>((resolve) => {
-    timer = setTimeout(() => resolve(undefined), ms);
+  const timeout = new Promise<typeof READ_TIMED_OUT>((resolve) => {
+    timer = setTimeout(() => resolve(READ_TIMED_OUT), ms);
   });
   return Promise.race([p, timeout]).finally(() => clearTimeout(timer));
 };
@@ -198,7 +212,7 @@ const parsePersisted = (raw: string | null | undefined): PersistedItem[] => {
 export const createEventQueue = (options: EventQueueOptions): EventQueue => {
   const target = options.target;
   const storage = options.storage;
-  // One slot per QUEUE (K4): an explicit key is taken verbatim; the appId-derived default is rotated
+  // One slot per QUEUE: an explicit key is taken verbatim; the appId-derived default is rotated
   // to `…#2` when a live queue already holds it, so two instances can never share one backlog.
   //
   // Only claimed when there IS storage. The defect is entirely about the persisted slot, and a
@@ -217,6 +231,13 @@ export const createEventQueue = (options: EventQueueOptions): EventQueue => {
   let flushing = false;
   let attempt = 0;
   let retryTimer: ReturnType<typeof setTimeout> | undefined;
+  // The persisted blob exists but has NOT been read yet (the cold-start read blew its deadline and
+  // is still in flight). While this is true every write is suppressed: the only thing the queue
+  // could write is a view of `pending` that does not include the backlog it has not seen, and
+  // `setItem`/`removeItem` would destroy it. Cleared as soon as the slow read settles, whichever
+  // way it settles, so a read that ultimately fails resumes normal persistence rather than
+  // suppressing it for the life of the process.
+  let backlogUnread = false;
 
   const resolveEnvelope = (): ContextEnvelope | undefined => {
     try {
@@ -254,6 +275,8 @@ export const createEventQueue = (options: EventQueueOptions): EventQueue => {
 
   const persist = (): void => {
     if (!storage) return;
+    // NEVER write over a blob that has not been read yet. See `backlogUnread`.
+    if (backlogUnread) return;
     try {
       if (pending.length === 0) {
         void storage.removeItem(key).catch(() => {});
@@ -280,25 +303,70 @@ export const createEventQueue = (options: EventQueueOptions): EventQueue => {
     }
   };
 
-  // Load any persisted backlog. Anything enqueued before this settles stays in memory; we merge
-  // persisted (older) ahead of it and reassign monotonic ids so dequeue-after-ack is deterministic.
+  /**
+   * Merge a loaded backlog into the in-memory buffer: persisted (older) events go AHEAD of
+   * whatever was enqueued while the read was in flight, duplicates collapse, and the size cap
+   * applies as usual.
+   *
+   * Ids are minted FRESH from the running `nextId` rather than reset to 0. A drain may already be
+   * in flight holding a batch of ids it will filter out on ack, and re-numbering from 0 would make
+   * those ids point at different events — the ack would then dequeue (silently drop) whichever
+   * events happened to inherit them. Monotonic ids are never reused, so an in-flight ack stays
+   * correct whatever lands in between.
+   */
+  const mergePersisted = (persistedItems: PersistedItem[]): void => {
+    if (persistedItems.length === 0) return;
+    const seen = new Set(pending.map((item) => item.sig));
+    const restored: QueuedItem[] = [];
+    for (const persisted of persistedItems) {
+      const sig = safeSig(persisted.event);
+      if (seen.has(sig)) continue; // already in memory — collapse the duplicate
+      seen.add(sig);
+      restored.push({ id: nextId++, event: persisted.event, sig });
+    }
+    if (restored.length === 0) return;
+    pending = [...restored, ...pending];
+    enforceSizeCap();
+    persist();
+  };
+
+  // Load any persisted backlog. Anything enqueued before this settles stays in memory; the merge
+  // above puts persisted (older) events ahead of it.
+  //
+  // A read that blows READ_TIMEOUT_MS is NOT treated as "no backlog". The race only unblocks the
+  // DRAIN — the original read is kept and merged whenever it lands, and until then every write is
+  // suppressed so the unread blob survives intact.
   const loadPromise: Promise<void> = (async () => {
     if (!storage) return;
     try {
-      const persistedItems = parsePersisted(await withTimeout(storage.getItem(key), READ_TIMEOUT_MS));
-      if (persistedItems.length === 0) return;
-      const events = [...persistedItems.map((p) => p.event), ...pending.map((p) => p.event)];
-      pending = [];
-      nextId = 0;
-      const seen = new Set<string>();
-      for (const event of events) {
-        const sig = safeSig(event);
-        if (seen.has(sig)) continue; // collapse duplicates carried across the merge
-        seen.add(sig);
-        pending.push({ id: nextId++, event, sig });
+      const read = Promise.resolve(storage.getItem(key));
+      // A rejecting read must not surface as an unhandled rejection when the race is won by the
+      // timeout; the recovery path below re-attaches its own handlers.
+      read.catch(() => {});
+      const raced = await withTimeout(read, READ_TIMEOUT_MS);
+      if (raced === READ_TIMED_OUT) {
+        backlogUnread = true;
+        warnInDev(
+          `[wireai] the persisted analytics backlog at "${key}" took longer than ${READ_TIMEOUT_MS}ms ` +
+            "to read, so the queue started without it. The stored events are NOT discarded: writes " +
+            "are held back until the read lands, and the backlog is merged in then. If you see this " +
+            "on every cold start, your storage adapter is too slow to be on the launch path.",
+        );
+        void read
+          .then((late) => {
+            backlogUnread = false;
+            mergePersisted(parsePersisted(late));
+            // Send whatever was just recovered; without this it would wait for the next enqueue.
+            flush();
+          })
+          .catch(() => {
+            // The slow read ultimately failed → nothing to preserve, resume normal persistence.
+            backlogUnread = false;
+            persist();
+          });
+        return;
       }
-      enforceSizeCap();
-      persist();
+      mergePersisted(parsePersisted(raced));
     } catch {
       // Unreadable backlog → start empty; nothing enqueued in-memory is lost.
     }

package/src/analytics/index.ts

@@ -40,6 +40,12 @@ export {
 } from "./reportClientEvent";
 export type { ClientEvent, ClientEventType, ClientEventTarget } from "./reportClientEvent";
 
+// ─── Dev-only integration self-check (opt-in; a host that never calls it pays nothing) ─────────
+// `readEventsAck` is deliberately NOT re-exported here: the doctor imports it from the transport
+// module directly, so reuse costs nothing and the package's public surface stays as it was.
+export { wireDoctor } from "./wireDoctor";
+export type { WireDoctorCheck, WireDoctorReport, WireDoctorOptions } from "./wireDoctor";
+
 // ─── Canonical onboarding funnel names + kit-event mapper ──────────────────────
 export { WIRE_ONBOARDING_EVENTS, toAnalyticsEvent } from "./analyticsEvent";
 export type { WireOnboardingEventName, AnalyticsEvent } from "./analyticsEvent";

package/src/analytics/reportClientEvent.ts

@@ -122,10 +122,15 @@ export const makeSessionId = (): string =>
  * `{written: 0, skipped: N, errors: [{index, reason: "validation_error", field: "ts"}]}` — every
  * `app_event` from `track()`/`screen()` silently discarded behind a green response.
  *
- * WHY HERE and not at the queue's `stamp()`: this is the single choke point all FOUR send paths go
- * through (offline queue, fire-and-forget, awaitable, session-start). Converting here leaves the
- * queue's numeric `ts` — and therefore its identical-JSON de-dup signature — exactly as it was, and
- * it also converts the persisted 0.13.0 backlogs (which hold a numeric `ts`) on their way out.
+ * WHY HERE and not at the queue's `stamp()`: this is the single choke point all FIVE send paths go
+ * through (offline queue, fire-and-forget, awaitable, review transport, session-start). Converting
+ * here leaves the queue's numeric `ts` — and therefore its identical-JSON de-dup signature — exactly
+ * as it was, and it also converts the persisted 0.13.0 backlogs (which hold a numeric `ts`) on their
+ * way out.
+ *
+ * ⚠️ NOT the same list as the ack-consumer list in {@link warnOnSkippedEvents}, which is FOUR. The
+ * review transport builds its request here but fires and forgets without reading the response, so
+ * it rides this conversion and is absent from that one. Count the call sites before editing either.
  *
  * NEVER mutates the caller's event: an event that needs a change is copied. A string `ts` (a
  * caller-set ISO stamp) and an absent `ts` pass through untouched. A non-finite (`NaN`/`Infinity`)
@@ -154,17 +159,30 @@ const toWireEvents = (events: ClientEvent[]): ClientEvent[] =>
  *
  * It is also where the internal epoch-ms `ts` becomes the wire's ISO8601 string — see
  * {@link toWireEvents} for why the conversion belongs at this choke point.
+ *
+ * `options.dryRun` asks the server to VALIDATE the batch and write nothing, which is what the wire
+ * doctor's round-trip check needs: a real POST, through this one builder, that cannot pollute a
+ * tenant's funnel. The `dry_run` key is added ONLY on an explicit `true`, so every production
+ * caller (which passes no options at all) still serializes the exact same bytes it did before the
+ * parameter existed. That byte-identity is asserted in `buildEventsRequest.test.ts`; every shipped
+ * send path rides this envelope, so a diagnostic is not allowed to change it for them.
  */
 export const buildEventsRequest = (
   target: { serverUrl: string; apiKey?: string } | undefined,
   events: ClientEvent[],
+  options?: { dryRun?: boolean },
 ): { url: string; init: RequestInit } | null => {
   if (!target?.serverUrl || events.length === 0) return null;
   try {
     const url = `${target.serverUrl.replace(/\/$/, "")}/v1/events`;
     const headers: Record<string, string> = { "Content-Type": "application/json" };
     if (target.apiKey) headers.Authorization = `Bearer ${target.apiKey}`;
-    const body = JSON.stringify({ events: toWireEvents(events) });
+    // The key is CONDITIONALLY assigned rather than set to a falsy default: an absent property and
+    // a `dry_run: false` property do not serialize the same, and only absence keeps the body byte
+    // identical for the production call sites.
+    const envelope: { events: ClientEvent[]; dry_run?: true } = { events: toWireEvents(events) };
+    if (options?.dryRun === true) envelope.dry_run = true;
+    const body = JSON.stringify(envelope);
     return { url, init: { method: "POST", headers, body } };
   } catch {
     // URL construction or JSON serialization failed — nothing to send.
@@ -176,7 +194,7 @@ export const buildEventsRequest = (
  *  each entry carrying `{index, reason, field}` — `field` names the property that failed validation
  *  (it is what identified the `ts` rejection), so it is folded into the reason string here. Still
  *  read defensively: an older server sends no `errors` at all. */
-type EventsAck = { written?: number; skipped: number; reasons: string[] };
+export type EventsAck = { written?: number; skipped: number; reasons: string[] };
 
 /**
  * Read the `/v1/events` ACK body. Resolves `undefined` when there is nothing readable — no `.json`
@@ -186,8 +204,12 @@ type EventsAck = { written?: number; skipped: number; reasons: string[] };
  *
  * ⚠️ The body can be read exactly once, so a caller that both decides on `skipped` AND warns must do
  * both from ONE call to this.
+ *
+ * Exported from this MODULE (not from the `./analytics` barrel) so the wire doctor can read an ack
+ * with the same reader the send paths use. A second ack reader would be a second thing to drift,
+ * and the drift it exists to catch is exactly the kind that hides behind a 200.
  */
-const readEventsAck = async (res: unknown): Promise<EventsAck | undefined> => {
+export const readEventsAck = async (res: unknown): Promise<EventsAck | undefined> => {
   try {
     const json = (res as { json?: () => Promise<unknown> } | null | undefined)?.json;
     if (typeof json !== "function") return undefined;