@wireai/activation 0.9.1 → 0.10.0

package/llms.txt

@@ -23,6 +23,7 @@
 - `attributionMetadata(a)` → shape install/ad attribution into `config.metadata` (forwarded to the agent).
 - `reportClientEvent(target, event)` / `reportClientEvents` / `makeSessionId` (ROOT-exported, not a subpath) → report device-only funnel events. Contract: `POST {serverUrl}/v1/events`, header `Authorization: Bearer {apiKey}`, body `{ "events": [ ... ] }`; `target = { serverUrl, apiKey }` from the config. `<WireOnboarding>` does this automatically: `dropped` on unmount-without-complete, `client_fallback` on degrade-to-static. Hosts must not double-report fallback.
 - `deriveAnswers(messages)`, `themeFromBrand({ primary })`, `defaultIllustrations`, `DemoOnboarding` (dev/QA, no account).
+- `useWireActivation({ serverUrl, apiKey, deviceKey? })` → `{ track, sessionId, revalidation }` (ROOT-exported; React-free factory `createWireActivation(config)`). `await track(name, meta?)` POSTs an `app_event` (`question_key=name`) under the current session, resolves `true` on 2xx, and bumps `revalidation`; list `revalidation` in a `fetchReviewDecision` / `fetchQuestionnaireDecision` effect's deps so a review/questionnaire gate re-fetches and fires off an in-app action instead of the host hand-rolling session-id + await-POST + revalidate.
 
 ## Files
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wireai/activation",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "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>",

package/src/WireOnboarding.tsx

@@ -27,6 +27,7 @@ import {
   clearPersistedSession,
   loadPersistedSession,
   sessionStorageKey,
+  shouldClearOnComplete,
   DEFAULT_SESSION_TTL_MS,
   type LoadedSession,
 } from "./session/persistedSession";
@@ -52,6 +53,7 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
   storage,
   sessionTtlMs = DEFAULT_SESSION_TTL_MS,
   persistKey,
+  retainSessionOnComplete,
   userContext,
   userId,
 }) => {
@@ -123,15 +125,24 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
     };
   }, [storage, storageKey, sessionTtlMs, session]);
 
-  // Clear the cached id the moment the flow completes, so the next onboarding on this
-  // device starts a fresh session. Dropped/degraded paths deliberately do NOT clear —
+  // By DEFAULT, clear the cached id the moment the flow completes, so the next onboarding on
+  // this device starts a fresh session. Dropped/degraded paths deliberately do NOT clear —
   // a dropped session must stay resumable within the TTL.
+  //
+  // OPT-IN (`retainSessionOnComplete`): a multi-stage / replay-after-complete signup re-enters
+  // (often via a `key=` remount) WITHIN one signup. If we cleared, that re-entry would find no
+  // seed and mint a fresh `metadata.sessionId` → a phantom second `session_started` on the same
+  // funnel. When the host opts in, we LEAVE the seed in place so the re-entry resumes the SAME
+  // session (one funnel start); freshness for a genuinely new run then rides the TTL (past
+  // `sessionTtlMs` → fresh mint) and an explicit new-run signal (a changed `persistKey`).
+  // `shouldClearOnComplete` is the pure, unit-tested seam; the `storage` guard is unchanged, so a
+  // host that does not opt in lands on the byte-for-byte legacy clear-on-complete path.
   const handleComplete = useCallback(
     (result: OnboardingResult) => {
-      if (storage) clearPersistedSession(storage, storageKey);
+      if (storage && shouldClearOnComplete(retainSessionOnComplete)) clearPersistedSession(storage, storageKey);
       onComplete(result);
     },
-    [storage, storageKey, onComplete],
+    [storage, storageKey, retainSessionOnComplete, onComplete],
   );
 
   const sessionId = session?.id ?? "";

package/src/activation/index.ts

@@ -0,0 +1,24 @@
+/**
+ * activation — the kit-owned `wire.track()` + `useWireActivation()` consolidation surface.
+ *
+ * The thin, reusable API that lets a consumer report a trigger action and re-fire the review /
+ * questionnaire gates WITHOUT hand-rolling an awaitable POST, its own session id, or an
+ * await-then-bump revalidation dance. Built on the existing events transport + the canonical
+ * `getCurrentSessionId()`. Re-exported from the main `@wireai/activation` barrel.
+ */
+
+// ─── The pure factory (React-free) ─────────────────────────────────────────────
+export { createWireActivation } from "./wireActivation";
+export type { WireActivation, WireActivationConfig } from "./wireActivation";
+
+// ─── The thin optional React hook (+ the standalone revalidation hook) ─────────
+export { useWireActivation, useActivationRevalidation } from "./useWireActivation";
+export type { UseWireActivation } from "./useWireActivation";
+
+// ─── The revalidation pub/sub (cross-bundle-safe; the gates subscribe to it) ───
+export {
+  bumpActivationRevalidation,
+  subscribeActivationRevalidation,
+  getActivationRevalidationVersion,
+  resetActivationRevalidation,
+} from "./revalidation";

package/src/activation/revalidation.ts

@@ -0,0 +1,88 @@
+/**
+ * activation revalidation — a tiny kit-owned pub/sub the review / questionnaire decision fetches
+ * subscribe to, so they RE-FETCH their server decision AFTER a trigger action, not only on mount.
+ *
+ * WHY THIS EXISTS (subsumes Morrow's hand-rolled `activation-revalidation.ts`): a host mounts the
+ * review / questionnaire gate on the home screen and fetches its `/decision` verdict once, in a
+ * mount-scoped effect. But the screen stays mounted while the user goes elsewhere to perform the
+ * triggering action (journal a win, complete a task); the server's firing rule is trigger-based AND
+ * session-scoped, so the mount fetch ran BEFORE the trigger event existed and never re-runs. Bumping
+ * this store after the action POSTs re-runs the gate's decision fetch (it lists the version in its
+ * deps) → the server now sees the trigger → `{fire:true}`.
+ *
+ * `wire.track()` bumps this automatically on a successful POST, so a consumer no longer hand-rolls
+ * an await-then-bump: it subscribes (via {@link useActivationRevalidation} in `useWireActivation`)
+ * and re-fetches when the version changes.
+ *
+ * ── WHY A globalThis SLOT, NOT MODULE-LOCAL STATE (same reasoning as currentSession) ─────────────
+ * This module can be reached from more than one package entry (the main `.` barrel exposes the
+ * revalidation surface; the gates live under the `./reviews` / `./questionnaire` subpaths). Under
+ * `dist` resolution tsup inlines a SEPARATE copy of a module into each bundle, so plain module-local
+ * `version` + `listeners` would give the BUMPER (main entry, via `wire.track`) and a SUBSCRIBER a
+ * different store — the bump would never reach the listener, exactly the defect-B failure mode. So
+ * the ONE store lives in a `globalThis` slot keyed by `Symbol.for(...)`: every inlined copy resolves
+ * 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. */
+const REVALIDATION_SLOT: unique symbol = Symbol.for(
+  "@wireai/activation:activationRevalidation",
+);
+
+/** The shared store: a monotonic version + the set of subscriber callbacks. */
+type RevalidationStore = { version: number; listeners: Set<() => void> };
+
+type GlobalWithSlot = typeof globalThis & {
+  [REVALIDATION_SLOT]?: RevalidationStore;
+};
+
+const globalSlot = globalThis as GlobalWithSlot;
+
+/** The one shared store, lazily created on the runtime global (never a second copy per bundle). */
+const store = (): RevalidationStore => {
+  const existing = globalSlot[REVALIDATION_SLOT];
+  if (existing) return existing;
+  const created: RevalidationStore = { version: 0, listeners: new Set() };
+  globalSlot[REVALIDATION_SLOT] = created;
+  return created;
+};
+
+/**
+ * Signal every activation subscriber to re-fetch its server decision. `wire.track()` calls this on a
+ * successful POST (await the post first so the re-fetch sees the event). A throwing subscriber never
+ * breaks the notify loop — each listener is isolated.
+ */
+export const bumpActivationRevalidation = (): void => {
+  const s = store();
+  s.version += 1;
+  // Iterate a snapshot so a listener that (un)subscribes during notify never corrupts the walk.
+  for (const listener of Array.from(s.listeners)) {
+    try {
+      listener();
+    } catch {
+      // A subscriber that throws must not stop the others (fail-safe).
+    }
+  }
+};
+
+/**
+ * Subscribe to revalidation. Returns an unsubscribe fn. Shaped for `useSyncExternalStore`
+ * (see {@link useActivationRevalidation} in `useWireActivation`).
+ */
+export const subscribeActivationRevalidation = (listener: () => void): (() => void) => {
+  const s = store();
+  s.listeners.add(listener);
+  return () => {
+    s.listeners.delete(listener);
+  };
+};
+
+/** The current revalidation version — include it in a decision-fetch effect's deps to re-fetch on bump. */
+export const getActivationRevalidationVersion = (): number => store().version;
+
+/** Test-only: reset the shared store between cases (clears version + listeners). */
+export const resetActivationRevalidation = (): void => {
+  const s = store();
+  s.version = 0;
+  s.listeners.clear();
+};

package/src/activation/useWireActivation.ts

@@ -0,0 +1,70 @@
+/**
+ * useWireActivation — a THIN optional React hook over {@link createWireActivation}.
+ *
+ * One import gives a consumer everything the activation consolidation owns: `track` (awaitable POST
+ * that auto-revalidates), the CURRENT `sessionId`, and a `revalidation` counter that ticks whenever
+ * a `track()` (from anywhere) succeeds — subscribe to re-render, then re-fetch your gate decision.
+ *
+ *   const { track, sessionId, revalidation } = useWireActivation({ serverUrl, apiKey });
+ *   // fetch the gate decision on mount AND whenever revalidation ticks:
+ *   useEffect(() => { fetchReviewDecision(target, { sessionId, deviceKey }).then(setDecision); },
+ *             [revalidation]);
+ *   // on the trigger action:
+ *   await track("journal_done");
+ *
+ * Mirrors the existing `createAnalytics` / `useAnalytics` (and `createScreenTracker` /
+ * `useScreenTracking`) split: the factory stays React-free; this is the glue. The instance is built
+ * once per mount and held in a ref, so re-renders never rebuild it or re-resolve the device key.
+ */
+import { useRef, useSyncExternalStore } from "react";
+
+import {
+  getActivationRevalidationVersion,
+  subscribeActivationRevalidation,
+} from "./revalidation";
+import {
+  createWireActivation,
+  type WireActivation,
+  type WireActivationConfig,
+} from "./wireActivation";
+
+/**
+ * Subscribe a component to decision revalidation. Returns the current version; list it in a
+ * decision-fetch effect's deps so a `bumpActivationRevalidation()` (which a successful `track` does)
+ * re-runs the fetch. The kit-owned replacement for a host's hand-rolled `useActivationRevalidation`.
+ */
+export const useActivationRevalidation = (): number =>
+  useSyncExternalStore(
+    subscribeActivationRevalidation,
+    getActivationRevalidationVersion,
+    getActivationRevalidationVersion,
+  );
+
+/** What {@link useWireActivation} returns: the awaitable `track`, the live `sessionId`, and the tick. */
+export type UseWireActivation = {
+  /** Awaitable action report that auto-revalidates on success (see {@link WireActivation.track}). */
+  track: WireActivation["track"];
+  /** The CURRENT per-open session id (read fresh each render), or `undefined`. */
+  sessionId: string | undefined;
+  /** Monotonic counter that increments on every successful `track()` — a re-fetch trigger. */
+  revalidation: number;
+};
+
+/**
+ * Build a per-mount activation instance. `config` is read once at first render (the instance is
+ * stable for the component's lifetime, keyed on the transport creds + device key); the returned
+ * `revalidation` re-renders the component whenever any `track()` succeeds.
+ */
+export const useWireActivation = (config: WireActivationConfig): UseWireActivation => {
+  const ref = useRef<WireActivation | undefined>(undefined);
+  const prevKeys = useRef<string>("");
+
+  const currentKeys = `${config.serverUrl}|${config.apiKey}|${config.appId}|${config.deviceKey}`;
+  if (!ref.current || prevKeys.current !== currentKeys) {
+    prevKeys.current = currentKeys;
+    ref.current = createWireActivation(config);
+  }
+
+  const revalidation = useActivationRevalidation();
+  return { track: ref.current.track, sessionId: ref.current.sessionId, revalidation };
+};

package/src/activation/wireActivation.ts

@@ -0,0 +1,156 @@
+/**
+ * wireActivation — the kit-owned `wire.track()` + session accessor + revalidation surface.
+ *
+ * WHAT IT CONSOLIDATES (subsumes Morrow's workarounds): a consumer used to hand-roll three things
+ * 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:
+ *
+ *   const wire = createWireActivation({ serverUrl, apiKey });   // or useWireActivation(...)
+ *   await wire.track("journal_done");                            // awaitable POST + auto-revalidate
+ *
+ * `track` POSTs `event_type='app_event'`, `question_key=<name>` (the EXACT string a review /
+ * questionnaire firing TRIGGER matches on) under the CURRENT `getCurrentSessionId()` — the same id
+ * the gates pass to their `/decision` fetch, so the server's session-scoped trigger rule agrees —
+ * with `user_context.device_key` for the min-sessions / arm-assignment lookups. On a successful POST
+ * it bumps decision revalidation so a subscribed gate re-fetches and can fire.
+ *
+ * ADDITIVE + built on existing primitives: it reuses the events transport
+ * (`reportClientEventAwait`, the awaitable sibling of `reportClientEvents` — ONE `/v1/events` path)
+ * and `getCurrentSessionId` — it introduces NO second session concept and duplicates no POST path.
+ * React-free (the optional React glue is the thin `useWireActivation` hook).
+ */
+import { getCurrentSessionId } from "../analytics/currentSession";
+import {
+  reportClientEventAwait,
+  type ClientEvent,
+  type ClientEventTarget,
+} from "../analytics/reportClientEvent";
+import { deviceIdStorageKey, mintDeviceId } from "../context/deviceId";
+import { resolveUserContext, type WireUserContext } from "../context/userContext";
+import type { WireOnboardingStorage } from "../session/persistedSession";
+import {
+  bumpActivationRevalidation,
+  getActivationRevalidationVersion,
+  subscribeActivationRevalidation,
+} from "./revalidation";
+
+/** Trim a candidate string; return `undefined` for a non-string / blank so callers can `if`-gate. */
+const clean = (value: unknown): string | undefined => {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+};
+
+/**
+ * Tenant transport + context inputs for {@link createWireActivation}. `serverUrl`/`apiKey` are the
+ * SAME creds as onboarding (never a second key); everything else is optional.
+ */
+export type WireActivationConfig = {
+  /** Base server URL (same as `WireOnboardingConfig.serverUrl`); `/v1/events` is appended. */
+  serverUrl: string;
+  /** Tenant API key; sent as `Authorization: Bearer`. */
+  apiKey: string;
+  /**
+   * A stable, non-PII device id → `user_context.device_key` (the server's review/questionnaire
+   * gating + A/B stickiness key on it). When omitted, the kit auto-mints ONE per-install id, persists
+   * it via `storage` when given, and reuses it — so `device_key` is ALWAYS present. Host-supplied wins.
+   */
+  deviceKey?: string;
+  /**
+   * Optional rich context stamped onto every tracked event's `user_context` (opaque `userId` →
+   * top-level `user_id`, opt-in `userEmail`, namespaced `extra`). `deviceKey` here is equivalent to
+   * the top-level one (top-level wins). Same shape the analytics façade accepts.
+   */
+  userContext?: WireUserContext;
+  /** Tenant/app id — namespaces the auto-minted device-key storage slot. */
+  appId?: string;
+  /** Host app version → `user_context.app_version` when no explicit `userContext.appVersion` is set. */
+  appVersion?: string;
+  /** Host persistence (AsyncStorage-compatible subset) so the auto-minted device key survives launches. */
+  storage?: WireOnboardingStorage;
+};
+
+/** The kit-owned activation surface. `sessionId` is a live getter (reads `getCurrentSessionId()`). */
+export type WireActivation = {
+  /**
+   * Awaitable action report: POST `event_type='app_event'`, `question_key=<name>`, optional `meta`,
+   * under the CURRENT session id + `user_context.device_key`. Resolves `true` once the server has
+   * stored it (2xx) and THEN bumps decision revalidation; resolves `false` (no bump) when there is no
+   * current session, a blank name, or the POST fails. Never throws.
+   */
+  track(name: string, meta?: Record<string, unknown>): Promise<boolean>;
+  /** The CURRENT per-open session id (the kit's canonical `getCurrentSessionId()`), or `undefined`. */
+  readonly sessionId: string | undefined;
+  /** Subscribe to decision revalidation (bumped by a successful `track`). Returns an unsubscribe fn. */
+  subscribeRevalidation(listener: () => void): () => void;
+  /** The current revalidation version — include in a decision-fetch effect's deps to re-fetch on bump. */
+  getRevalidationVersion(): number;
+};
+
+/**
+ * Create a bound activation instance for a tenant transport. Resolves the device key once (explicit >
+ * `userContext.deviceKey` > auto-minted + persisted). Pure + React-free.
+ */
+export const createWireActivation = (config: WireActivationConfig): WireActivation => {
+  const target: ClientEventTarget = { serverUrl: config.serverUrl, apiKey: config.apiKey };
+
+  // Device key: an explicit id (top-level or in userContext) wins and is never overwritten; otherwise
+  // auto-mint ONE and persist via storage (reused every open) so `device_key` is always present.
+  const explicitDeviceKey = clean(config.deviceKey) ?? clean(config.userContext?.deviceKey);
+  let autoDeviceKey = explicitDeviceKey ?? mintDeviceId();
+  if (config.storage && !explicitDeviceKey) {
+    const storage = config.storage;
+    const key = deviceIdStorageKey(config.appId);
+    void storage
+      .getItem(key)
+      .then((saved) => {
+        const persisted = clean(saved ?? undefined);
+        if (persisted) autoDeviceKey = persisted;
+        else void storage.setItem(key, autoDeviceKey).catch(() => {});
+      })
+      .catch(() => {});
+  }
+
+  // Stamp the resolved rich context onto the event: `user_context` bucket (device_key always, plus any
+  // app_version / opt-in user_email / namespaced extra) and the top-level opaque `user_id`.
+  const applyContext = (event: ClientEvent): void => {
+    const resolved = resolveUserContext(
+      { ...(config.userContext ?? {}), deviceKey: explicitDeviceKey ?? autoDeviceKey },
+      { autoAppVersion: config.appVersion },
+    );
+    if (resolved.userContext) {
+      event.user_context = { ...resolved.userContext, ...(event.user_context ?? {}) };
+    }
+    if (resolved.userId && !event.user_id) event.user_id = resolved.userId;
+  };
+
+  const track = async (name: string, meta?: Record<string, unknown>): Promise<boolean> => {
+    const sessionId = getCurrentSessionId();
+    // No current session (no app-open registered yet) or a blank name → nothing to correlate; bail
+    // WITHOUT bumping (a bump with no posted event would only make the gate re-fetch for nothing).
+    if (!clean(name) || !sessionId) return false;
+    const event: ClientEvent = {
+      event_type: "app_event",
+      session_id: sessionId,
+      question_key: name,
+    };
+    if (meta && Object.keys(meta).length > 0) event.meta = JSON.stringify(meta);
+    applyContext(event);
+    const ok = await reportClientEventAwait(target, event);
+    // Only revalidate once the event is actually in the stream — a failed POST leaves the gate as-is.
+    if (ok) bumpActivationRevalidation();
+    return ok;
+  };
+
+  return {
+    track,
+    get sessionId() {
+      return getCurrentSessionId();
+    },
+    subscribeRevalidation: subscribeActivationRevalidation,
+    getRevalidationVersion: getActivationRevalidationVersion,
+  };
+};

package/src/analytics/currentSession.ts

@@ -1,5 +1,5 @@
 /**
- * currentSession — a tiny module-level registry of the CURRENT per-open `session_id`.
+ * currentSession — a tiny registry of the CURRENT per-open `session_id`.
  *
  * WHY it exists (kills the phantom-session): the per-open emitters (`reportSessionStart` and the
  * `useSessionStart` / `useLifecycleEvents` hooks) mint a fresh `session_id` for each app-open and
@@ -12,24 +12,58 @@
  * server already ingested. `reportSessionStart` writes the current id here on every open; the façade
  * reads it so `identify`/app-events correlate to the real session instead of minting a phantom.
  *
- * DEPENDENCY-FREE + PROCESS-LOCAL: a plain module variable. It is intentionally NOT persisted — it
- * tracks the CURRENT process's open, and a fresh open always overwrites it. No cross-launch state.
+ * ── WHY A globalThis SLOT, NOT A PLAIN MODULE VARIABLE ────────────────────────────────────────
+ * This module is exported from TWO package entry points — the main `.` bundle (`src/index.ts`) and
+ * the `./analytics` subpath (`src/analytics/index.ts`). Under `dist` resolution (node `import`/
+ * `require`, which is how tests, SSR and some tooling load the kit) tsup inlines a SEPARATE copy of
+ * this module into each bundle, so a plain `let` would give the SETTER (reached via `.` →
+ * `reportSessionStart`) and the READER (reached via `./analytics` → façade / `userIdentity`) TWO
+ * different variables: the reader would see `undefined` even after an open set the id, and gating
+ * would fire under a null session id. On-device this was masked only because Metro's `react-native`
+ * export condition resolves both subpaths back to this one `src/` file (a single instance) — a
+ * bundler accident, not a guarantee.
+ *
+ * The bundler-agnostic fix: keep the ONE live value in a well-known `globalThis` slot keyed by a
+ * `Symbol.for(...)`. `Symbol.for` uses the runtime-global symbol registry, so every inlined copy of
+ * this module resolves the SAME symbol and reads/writes the SAME slot — one identity no matter how
+ * many times the module is duplicated across bundles. `globalThis` is present and identical in
+ * Hermes/React Native, Node and SSR (we never touch `window`), so this is safe on every host.
+ *
+ * PROCESS-LOCAL, NOT PERSISTED: the slot lives on the runtime global, so it tracks the CURRENT
+ * process's open and a fresh open overwrites it. There is no cross-launch state.
+ * `resetCurrentSessionId` clears the slot so a unit test starts from a clean registry.
  */
 
-let _currentSessionId: string | undefined;
+/**
+ * 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.
+ */
+const CURRENT_SESSION_ID_SLOT: unique symbol = Symbol.for(
+  "@wireai/activation:currentSessionId",
+);
+
+type GlobalWithSlot = typeof globalThis & {
+  [CURRENT_SESSION_ID_SLOT]?: string | undefined;
+};
+
+const globalSlot = globalThis as GlobalWithSlot;
 
 /**
  * Record the current per-open `session_id`. Called by `reportSessionStart` when it emits an
  * app-open. A blank / non-string id is ignored (the previous id stays current). Idempotent.
  */
 export const setCurrentSessionId = (id: string | undefined): void => {
-  if (typeof id === "string" && id.length > 0) _currentSessionId = id;
+  if (typeof id === "string" && id.length > 0) {
+    globalSlot[CURRENT_SESSION_ID_SLOT] = id;
+  }
 };
 
 /** The current per-open `session_id`, or `undefined` when no app-open has been registered yet. */
-export const getCurrentSessionId = (): string | undefined => _currentSessionId;
+export const getCurrentSessionId = (): string | undefined =>
+  globalSlot[CURRENT_SESSION_ID_SLOT];
 
 /** Test-only: forget the current session id so a unit test starts from a clean registry. */
 export const resetCurrentSessionId = (): void => {
-  _currentSessionId = undefined;
+  globalSlot[CURRENT_SESSION_ID_SLOT] = undefined;
 };

package/src/analytics/index.ts

@@ -31,7 +31,13 @@ export { reportAppEvent } from "../reviews/transport";
 export type { ReportAppEventOptions } from "../reviews/transport";
 
 // ─── Device-only onboarding event reporters + session id seed ─────────────────
-export { reportClientEvent, reportClientEvents, makeSessionId } from "./reportClientEvent";
+export {
+  reportClientEvent,
+  reportClientEvents,
+  reportClientEventAwait,
+  reportClientEventsAwait,
+  makeSessionId,
+} from "./reportClientEvent";
 export type { ClientEvent, ClientEventType, ClientEventTarget } from "./reportClientEvent";
 
 // ─── Canonical onboarding funnel names + kit-event mapper ──────────────────────

package/src/analytics/reportClientEvent.ts

@@ -95,6 +95,29 @@ export type ClientEventTarget = {
 export const makeSessionId = (): string =>
   `wire_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
 
+/**
+ * The ONE place the `/v1/events` POST is described (url + method + headers + body). Both the
+ * fire-and-forget {@link reportClientEvents} and the awaitable {@link reportClientEventsAwait}
+ * build their request here so there is a SINGLE definition of the events transport — no second
+ * copy of the endpoint path, headers, or envelope shape to drift. Returns `null` when there is
+ * nothing to send (no target / no events) or serialization throws, so callers just bail.
+ */
+const buildEventsRequest = (
+  target: ClientEventTarget | undefined,
+  events: ClientEvent[],
+): { 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}`;
+    return { url, init: { method: "POST", headers, body: JSON.stringify({ events }) } };
+  } catch {
+    // URL construction or JSON serialization failed — nothing to send.
+    return null;
+  }
+};
+
 /**
  * POST one or more client events, fire-and-forget. A missing/invalid target, a build error,
  * a missing `fetch`, or a network failure is swallowed — the call returns immediately and the
@@ -104,20 +127,14 @@ export const reportClientEvents = (
   target: ClientEventTarget | undefined,
   events: ClientEvent[],
 ): void => {
-  if (!target?.serverUrl || events.length === 0) return;
   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}`;
-    void fetch(url, {
-      method: "POST",
-      headers,
-      body: JSON.stringify({ events }),
-    }).catch(() => {
+    const req = buildEventsRequest(target, events);
+    if (!req) return;
+    void fetch(req.url, req.init).catch(() => {
       // Network/transport error — analytics is best-effort, swallow.
     });
   } catch {
-    // URL construction, JSON serialization, or a missing fetch — swallow.
+    // A missing `fetch` — swallow.
   }
 };
 
@@ -126,3 +143,32 @@ export const reportClientEvent = (
   target: ClientEventTarget | undefined,
   event: ClientEvent,
 ): void => reportClientEvents(target, [event]);
+
+/**
+ * AWAITABLE sibling of {@link reportClientEvents}: POST one or more client events through the SAME
+ * `/v1/events` path, but resolve only once the server has RESPONDED — so a decision re-fetch fired
+ * immediately after is guaranteed to see the event in the session stream (this is the guarantee
+ * `wire.track` needs before it triggers decision revalidation). Never throws: a missing/invalid
+ * target, a missing `fetch`, a network error, or a non-2xx status all resolve to `false`. Resolves
+ * `true` only on a 2xx response.
+ */
+export const reportClientEventsAwait = async (
+  target: ClientEventTarget | undefined,
+  events: ClientEvent[],
+): Promise<boolean> => {
+  try {
+    const req = buildEventsRequest(target, events);
+    if (!req) return false;
+    const res = await fetch(req.url, req.init);
+    return Boolean(res && res.ok);
+  } catch {
+    // Unreachable / missing-fetch / network — best-effort, report failure.
+    return false;
+  }
+};
+
+/** Convenience single-event wrapper around {@link reportClientEventsAwait}. */
+export const reportClientEventAwait = (
+  target: ClientEventTarget | undefined,
+  event: ClientEvent,
+): Promise<boolean> => reportClientEventsAwait(target, [event]);

package/src/index.ts

@@ -167,6 +167,24 @@ export {
   resetCurrentSessionId,
 } from "./analytics/currentSession";
 
+// ─── Awaitable client-event report (the transport `wire.track` posts through) ─
+export { reportClientEventAwait, reportClientEventsAwait } from "./analytics/reportClientEvent";
+
+// ─── Activation consolidation: wire.track() + useWireActivation() + revalidation ──
+export { createWireActivation, useWireActivation } from "./activation";
+export type {
+  WireActivation,
+  WireActivationConfig,
+  UseWireActivation,
+} from "./activation";
+export {
+  useActivationRevalidation,
+  bumpActivationRevalidation,
+  subscribeActivationRevalidation,
+  getActivationRevalidationVersion,
+  resetActivationRevalidation,
+} from "./activation";
+
 // ─── Session mapping (one `app.session_started` per app-open → /v1/events) ─────
 export {
   reportSessionStart,

package/src/session/persistedSession.ts

@@ -141,3 +141,20 @@ export const clearPersistedSession = (storage: WireOnboardingStorage, key: strin
     // Best-effort.
   }
 };
+
+/**
+ * The opt-in decision for `WireOnboarding.handleComplete`: given the host's
+ * `retainSessionOnComplete` opt-in, whether a completion should CLEAR the persisted seed.
+ * (The caller still gates on `storage` being present — this only encodes the opt-in axis, so the
+ * legacy `if (storage) clearPersistedSession(...)` guard stays byte-for-byte for a host that does
+ * 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).
+ *  - 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
+ *    mint) and an explicit new-run signal (a changed `persistKey`).
+ */
+export const shouldClearOnComplete = (retainSessionOnComplete: boolean | undefined): boolean =>
+  !retainSessionOnComplete;

package/src/types.ts

@@ -211,6 +211,22 @@ export type WireOnboardingProps = {
    * accounts mid-flow. Only meaningful with `storage`.
    */
   persistKey?: string;
+  /**
+   * OPT-IN: keep the persisted session seed alive ACROSS completion, so a multi-stage or
+   * replay-after-complete re-entry WITHIN one signup (typically a `key=` remount) resumes the
+   * SAME session instead of minting a fresh `metadata.sessionId` — which the backend would adopt
+   * as a second `contextId`, double-counting a `session_started` on the funnel.
+   *
+   * Default (omitted / `false`): a completion CLEARS the seed, so the next onboarding on this
+   * device starts fresh — the legacy single-stage behavior. Leave it unset and NOTHING changes.
+   *
+   * When `true`: the seed survives completion, and freshness for a genuinely new run is governed
+   * by the TTL (past `sessionTtlMs` → a fresh seed is minted) and an explicit new-run signal
+   * (scope a new `persistKey`, e.g. a per-signup id, to force a fresh seed within the TTL).
+   *
+   * Only meaningful with `storage`. Dropped/degraded sessions are unaffected (they never clear).
+   */
+  retainSessionOnComplete?: boolean;
 };
 
 /** Backend-supplied progress, read off `response.props.progress` when present. */