@wireai/activation 0.13.3 → 0.13.5

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;

package/src/analytics/wireDoctor.ts

@@ -0,0 +1,330 @@
+/**
+ * wireDoctor: a DEV-ONLY, opt-in self-check that proves a fresh integration end to end before the
+ * first real user ever runs it.
+ *
+ * WHY IT EXISTS: the `/v1/events` endpoint answers HTTP **200** for a batch it throws away. It
+ * reports the refusal in the response body (`{written, skipped, errors:[{reason, field}]}`), so a
+ * mis-wired integration looks perfectly healthy from the outside while every event evaporates. A
+ * numeric `ts` did exactly that through 0.13.0. This turns that class of loss from something you
+ * discover in a funnel report weeks later into something the first run tells you.
+ *
+ * SHAPE: four independent checks, each a `{name, ok, detail}` unit that can be read (and tested)
+ * without the others. The report is data, never a thrown error and never a side effect on the host:
+ *
+ *   1. `target`      : is there a server URL and a key, and do they look like a key and a URL?
+ *   2. `reachability`: is the server actually there? (`GET /v1/events/contract`, public and cheap)
+ *   3. `storage`      : can the offline queue persist? (a write / read / delete probe)
+ *   4. `round_trip`   : does a REAL event survive REAL server validation? (a `dry_run` POST)
+ *
+ * NEVER THROWS, under any input, any network condition, or any hostile response object. A doctor
+ * that can crash the screen it is diagnosing is worse than no doctor.
+ *
+ * ⛔ NEVER PRINTS A SECRET. The `target` check reports the key's SHAPE (present / absent, length,
+ * whether the prefix is the expected one) and never any character of the key itself, in any
+ * `detail`, any log line, or any error. `wireDoctor.test.ts` asserts that with a sentinel key.
+ *
+ * COSTS A NON-CALLER NOTHING: it is a plain function behind the `./analytics` subpath, the package
+ * is `sideEffects: false`, and this module has no top-level side effects, so a host that never
+ * imports it never bundles it. It also mints no `globalThis` slot and retains no timer or listener.
+ *
+ * USAGE (dev builds only):
+ *
+ *   import { wireDoctor } from "@wireai/activation/analytics";
+ *
+ *   const report = await wireDoctor({
+ *     target: { serverUrl: "https://api.example.com", apiKey: DRIVELINE_KEY },
+ *     storage: AsyncStorage,
+ *   });
+ *   console.log(report.ok, report.checks);
+ */
+// Imported DIRECTLY from the transport module, never through `./index`: the barrel would pull the
+// whole analytics surface into anything that touches the doctor. `readEventsAck` is module-exported
+// for exactly this, so the doctor reads an ack with the SAME reader the send paths use rather than
+// growing a second one to drift.
+import {
+  buildEventsRequest,
+  makeSessionId,
+  readEventsAck,
+  type ClientEvent,
+  type ClientEventTarget,
+} from "./reportClientEvent";
+import type { WireOnboardingStorage } from "../session/persistedSession";
+
+/** RN sets this global; absent under node/SSR. Read defensively, exactly as `warnOnSkippedEvents` does. */
+declare const __DEV__: boolean | undefined;
+
+/** One diagnosis. `name` is stable and machine-readable; `detail` is for a human reading a console. */
+export type WireDoctorCheck = {
+  /**
+   * Stable id: `target` | `reachability` | `storage` | `round_trip` | `dev_only` | `internal_error`.
+   *
+   * `dev_only` means ONE thing and only that thing: `__DEV__` is unset or false, so nothing ran.
+   * `internal_error` is the separate catch-all for a failure that got past every check's own
+   * swallow. They are distinct names because a consumer branching on `dev_only` would otherwise
+   * read an internal fault as "this is a release build" and report a healthy skip.
+   */
+  name: string;
+  ok: boolean;
+  /** Human-readable result. ⛔ Never contains any part of an API key. */
+  detail: string;
+};
+
+/** What {@link wireDoctor} resolves to. `ok` is true only when EVERY check passed. */
+export type WireDoctorReport = {
+  ok: boolean;
+  checks: WireDoctorCheck[];
+};
+
+/** Input for {@link wireDoctor}. `storage` is optional: without it the queue runs in-memory only. */
+export type WireDoctorOptions = {
+  /** The same `{serverUrl, apiKey}` the kit is configured with. */
+  target: ClientEventTarget | undefined;
+  /**
+   * The host storage the offline queue would use (AsyncStorage-compatible). Omit it and the storage
+   * check reports the DEGRADED in-memory mode rather than failing.
+   */
+  storage?: WireOnboardingStorage;
+};
+
+/**
+ * The probe's own storage key. Deliberately NOT under the queue's `wireai:evtq:` namespace, so a
+ * doctor run can never read, overwrite or delete a pending backlog. A diagnostic that eats a user's
+ * unsent events is a worse bug than the one it was written to find.
+ */
+const PROBE_STORAGE_KEY = "wireai:doctor:probe";
+
+/** The `question_key` the synthetic round-trip event carries. `dry_run` means it is never written. */
+const PROBE_QUESTION_KEY = "wire_doctor_probe";
+
+/** Tenant keys start with this. Used ONLY for a boolean comparison; ⛔ never interpolated into a detail. */
+const EXPECTED_KEY_PREFIX = "wai_";
+
+/** Ceiling on each network check, so a hung server degrades to a failed check, never a hung caller. */
+const NETWORK_TIMEOUT_MS = 10_000;
+
+const check = (name: string, ok: boolean, detail: string): WireDoctorCheck => ({ name, ok, detail });
+
+/**
+ * `fetch` with a timeout that is ALWAYS cleared, including on rejection. Resolves `undefined`
+ * instead of throwing, so every caller stays on the happy path. Returns no timer to the caller and
+ * leaves none pending: a diagnostic must not keep the JS thread alive after it has answered.
+ */
+const fetchWithTimeout = async (url: string, init?: RequestInit): Promise<Response | undefined> => {
+  if (typeof fetch === "undefined") return undefined;
+  const controller = typeof AbortController !== "undefined" ? new AbortController() : undefined;
+  const timer = setTimeout(() => controller?.abort(), NETWORK_TIMEOUT_MS);
+  try {
+    return await fetch(url, controller ? { ...init, signal: controller.signal } : init);
+  } catch {
+    // Unreachable host, DNS failure, abort, or a missing fetch implementation.
+    return undefined;
+  } finally {
+    clearTimeout(timer);
+  }
+};
+
+/**
+ * CHECK 1: is the target usable at all?
+ *
+ * Reports the key's shape and NEVER its content: present/absent, character length, and whether the
+ * prefix matches what a tenant key starts with. Length and a yes/no are enough to tell "you pasted
+ * the wrong string" from "you pasted nothing", which is the entire diagnostic value here.
+ */
+const checkTarget = (target: ClientEventTarget | undefined): WireDoctorCheck => {
+  const serverUrl = target?.serverUrl;
+  if (typeof serverUrl !== "string" || serverUrl.trim().length === 0) {
+    return check("target", false, "no serverUrl configured: set `serverUrl` on the kit config.");
+  }
+  let parsedHost = false;
+  try {
+    const parsed = new URL(serverUrl);
+    parsedHost = parsed.protocol === "http:" || parsed.protocol === "https:";
+  } catch {
+    parsedHost = false;
+  }
+  if (!parsedHost) {
+    return check("target", false, "serverUrl is not a valid http(s) URL.");
+  }
+  const apiKey = target?.apiKey;
+  if (typeof apiKey !== "string" || apiKey.length === 0) {
+    return check("target", false, "serverUrl looks valid, but no apiKey is configured.");
+  }
+  // ⛔ `EXPECTED_KEY_PREFIX` is compared, never printed: it is itself a substring of a real key.
+  const prefixOk = apiKey.startsWith(EXPECTED_KEY_PREFIX);
+  return check(
+    "target",
+    true,
+    `serverUrl is a valid http(s) URL; apiKey present (${apiKey.length} chars, expected prefix: ${
+      prefixOk ? "yes" : "no"
+    }).`,
+  );
+};
+
+/**
+ * CHECK 2: is the server there, and is it a Wire server?
+ *
+ * `GET /v1/events/contract` is public, cheap, and it answers the question the round-trip check
+ * cannot answer on its own: a failure here means "wrong URL / server down", not "bad payload".
+ */
+const checkReachability = async (serverUrl: string): Promise<WireDoctorCheck> => {
+  const url = `${serverUrl.replace(/\/$/, "")}/v1/events/contract`;
+  const res = await fetchWithTimeout(url, { method: "GET" });
+  if (!res) {
+    return check("reachability", false, "could not reach the server (network error or timeout).");
+  }
+  const status = (res as { status?: unknown }).status;
+  const ok = !!(res as { ok?: boolean }).ok;
+  if (!ok) {
+    return check(
+      "reachability",
+      false,
+      `the server answered ${typeof status === "number" ? status : "an error"} for the events contract; ` +
+        "check the serverUrl points at a Wire server.",
+    );
+  }
+  return check("reachability", true, "the server answered the events contract.");
+};
+
+/**
+ * CHECK 3: can the offline queue actually persist?
+ *
+ * Write, read back, compare. Without working storage the queue silently degrades to in-memory only,
+ * so a backgrounded app loses whatever it had not flushed, and nothing anywhere says so.
+ *
+ * The probe key is REMOVED in a `finally`, so a failing read or a throwing adapter still cleans up.
+ */
+const checkStorage = async (storage: WireOnboardingStorage | undefined): Promise<WireDoctorCheck> => {
+  if (!storage) {
+    return check(
+      "storage",
+      true,
+      "no storage injected: the queue runs in DEGRADED in-memory mode and loses pending events on an app kill. " +
+        "Pass AsyncStorage (or an MMKV wrapper) to make it durable.",
+    );
+  }
+  const token = `probe_${Date.now().toString(36)}`;
+  try {
+    await storage.setItem(PROBE_STORAGE_KEY, token);
+    const read = await storage.getItem(PROBE_STORAGE_KEY);
+    if (read !== token) {
+      return check(
+        "storage",
+        false,
+        "the storage adapter accepted a write but did not read the same value back, so the queue cannot persist.",
+      );
+    }
+    // ⚠️ "write / read" only: this returns BEFORE the `finally` runs its delete, and a throwing
+    // `removeItem` is deliberately swallowed there, so the delete is attempted, never asserted.
+    return check("storage", true, "storage write / read round trip succeeded.");
+  } catch {
+    return check("storage", false, "the storage adapter threw, so the queue cannot persist events.");
+  } finally {
+    // Always, including after a failed write or read: never leave the probe key behind.
+    try {
+      await storage.removeItem(PROBE_STORAGE_KEY);
+    } catch {
+      // A remove that throws is not worth failing the run over; nothing else depends on it.
+    }
+  }
+};
+
+/**
+ * CHECK 4: does a real event survive real server validation?
+ *
+ * POSTs ONE synthetic event through the REAL {@link buildEventsRequest} with `dry_run: true`, so it
+ * travels the exact bytes a production event travels and the server validates it exactly the same
+ * way, but writes nothing. The probe is inert: it pollutes no funnel and no metric.
+ *
+ * ⚠️ The verdict is `written === 1 && skipped === 0`, read from the ACK BODY. A 200 is not a
+ * receipt here: the endpoint returns 200 for a batch it discarded. A `ts`-shaped drift shows up as
+ * `skipped: 1` with the server's own `field: "ts"`, which is the whole point of this check.
+ */
+const checkRoundTrip = async (target: ClientEventTarget): Promise<WireDoctorCheck> => {
+  const event: ClientEvent = {
+    event_type: "app_event",
+    session_id: makeSessionId(),
+    question_key: PROBE_QUESTION_KEY,
+  };
+  const req = buildEventsRequest(target, [event], { dryRun: true });
+  if (!req) {
+    return check("round_trip", false, "could not build the events request from this target.");
+  }
+  const res = await fetchWithTimeout(req.url, req.init);
+  if (!res) {
+    return check("round_trip", false, "the events POST failed (network error or timeout).");
+  }
+  if (!(res as { ok?: boolean }).ok) {
+    const status = (res as { status?: unknown }).status;
+    return check(
+      "round_trip",
+      false,
+      `the events endpoint answered ${typeof status === "number" ? status : "an error"}; ` +
+        "a 401 here means the apiKey is not accepted.",
+    );
+  }
+  const ack = await readEventsAck(res);
+  if (!ack) {
+    return check(
+      "round_trip",
+      false,
+      "the server answered 2xx but sent no readable ack body, so it is unknown whether the event validated.",
+    );
+  }
+  if (ack.written === 1 && ack.skipped === 0) {
+    return check("round_trip", true, "the server validated the probe event: written=1, skipped=0.");
+  }
+  // The server's own reasons, verbatim, each already carrying the field it refused.
+  return check(
+    "round_trip",
+    false,
+    `the server DISCARDED the probe event: written=${ack.written ?? "unknown"}, skipped=${ack.skipped}` +
+      (ack.reasons.length > 0
+        ? `, reasons: ${ack.reasons.join(", ")}.`
+        : ". It gave no reason; check the server's ingest log for this request."),
+  );
+};
+
+/**
+ * Run the full diagnosis. Resolves a report; NEVER throws and NEVER rejects.
+ *
+ * DEV-ONLY BY CONTRACT: the `__DEV__` guard is the FIRST statement, so a release build performs no
+ * network call, no storage write, and no work at all. The report says it was skipped rather than
+ * pretending everything passed, because a green report that never ran is the exact failure mode
+ * this whole feature exists to remove.
+ */
+export const wireDoctor = async (options: WireDoctorOptions): Promise<WireDoctorReport> => {
+  if (typeof __DEV__ === "undefined" || !__DEV__) {
+    return {
+      ok: false,
+      checks: [
+        check(
+          "dev_only",
+          false,
+          "wireDoctor is dev-only and did NOT run: __DEV__ is unset or false. Nothing was checked.",
+        ),
+      ],
+    };
+  }
+  try {
+    const target = options?.target;
+    const checks: WireDoctorCheck[] = [checkTarget(target)];
+    // Reachability and the round trip both need a usable target; running them against a broken one
+    // would report a network failure and bury the real cause, which check 1 already named.
+    if (checks[0]!.ok && target) {
+      checks.push(await checkReachability(target.serverUrl));
+      checks.push(await checkStorage(options?.storage));
+      checks.push(await checkRoundTrip(target));
+    } else {
+      checks.push(await checkStorage(options?.storage));
+    }
+    return { ok: checks.every((c) => c.ok), checks };
+  } catch {
+    // Belt and braces: every check above already swallows its own failures, so reaching here means
+    // something hostile got past them. Still a report, still not a throw. The name is
+    // `internal_error`, NOT `dev_only`: this ran and broke, which is the opposite of "never ran".
+    return {
+      ok: false,
+      checks: [check("internal_error", false, "wireDoctor could not complete: an unexpected error was swallowed.")],
+    };
+  }
+};

package/src/coachmarks/runtime.ts

@@ -27,7 +27,16 @@
  */
 import type { CoachmarkStorage } from "./types";
 
-/** Well-known key into the runtime-global symbol registry — one coachmark runtime across bundles. */
+/**
+ * Well-known key into the runtime-global symbol registry — one coachmark runtime across bundles.
+ *
+ * @globalSlot LATCH — the RUNTIME RECORD is created once and its identity is then stable. A second
+ * write replaces the record `subscribeCoachmarksEnabled` registered its listeners on, so a
+ * kill-switch flip notifies an orphaned set while a tour that believes it is running paints nothing
+ * — the exact limbo `coachmarkKillSwitch` canaries. Its FIELDS (`storage`, `testing`,
+ * `coachmarksEnabled`, `listeners`) are live, which is why every accessor calls `coachmarkRuntime()`
+ * instead of holding the record, and why `coachmarksEnabled` is subscribable rather than sampled.
+ */
 const COACHMARK_RUNTIME_SLOT: unique symbol = Symbol.for("@wireai/activation:coachmarkRuntime");
 
 /** The shared runtime: the provider-injected storage, the QA replay flag, and the kill switch. */

package/src/context/deviceId.ts

@@ -68,7 +68,16 @@ export const mintDeviceId = (): string => {
 // events are the ONLY ones the server counts `min_sessions` from, so a per-launch id there is not a
 // millisecond of noise, it is a counter that can never exceed 1.
 
-/** Well-known key into the runtime-global symbol registry — one auto-id registry across every bundle. */
+/**
+ * Well-known key into the runtime-global symbol registry — one auto-id registry across every bundle.
+ *
+ * @globalSlot LATCH — the REGISTRY OBJECT is created once and its identity is then stable. A second
+ * write empties `keys`/`hydrating`/`pending`, so the next surface mints a SECOND auto id for one
+ * install and the `device_key` the server joins sessions on splits in two — the halved-counter
+ * defect this registry exists to close. Its CONTENTS are live (the id per `appId` is replaced when
+ * an async hydration adopts a persisted value), so callers must re-read through
+ * `resolveAutoDeviceKey()` rather than hold the string a mount happened to see first.
+ */
 const AUTO_DEVICE_KEY_SLOT: unique symbol = Symbol.for("@wireai/activation:autoDeviceKeys");
 
 /** What a hydration settled on: the id, and whether persistence actually CONFIRMED it.

package/src/features/WireFeaturesProvider.tsx

@@ -18,6 +18,14 @@ import { defaultWireFeatures } from "./defaults";
 import { useWireFeatures } from "./useWireFeatures";
 import type { WireFeatures, WireFeaturesConfig } from "./types";
 
+/**
+ * @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). A second write would re-split the
+ * identity the guard exists to keep whole: the provider would publish into one context while a
+ * subpath bundle's `useContext` read another, and `useResolvedFeatures`' null fallback would serve
+ * the all-on defaults with no crash and no warning. Because it is a latch, and only because of
+ * that, the module-local `const WireFeaturesContext` below may cache it.
+ */
 const CONTEXT_SYMBOL = Symbol.for("wireai.features.context");
 // `globalThis`, not `global`: the other nine `Symbol.for` slots in this kit all use it, and `global`
 // simply does not exist in a plain browser (RN-web / SSR-in-the-browser), where this line would

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/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/theme/ThemeContext.tsx

@@ -35,6 +35,13 @@ import type { OnboardingTheme } from "./types";
  * 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");