@wireai/activation 0.12.2 → 0.13.0

package/src/analytics/reportClientEvent.ts

@@ -128,16 +128,71 @@ export const buildEventsRequest = (
   }
 };
 
+/** What the `/v1/events` endpoint says in its 200 body. `errors` is the server's planned per-event
+ *  reason list; it is read defensively because no deployed server sends it yet. */
+type EventsAck = { written?: number; skipped: number; reasons: string[] };
+
+/**
+ * Read the `/v1/events` ACK body. Resolves `undefined` when there is nothing readable — no `.json`
+ * (an old server, a bare test mock), an already-consumed body, or a hostile response object. NEVER
+ * throws, and NEVER dev-gated: the `skipped` count is a RETURN VALUE for the awaitable path, not only
+ * a warning, so it has to be read in production too.
+ *
+ * ⚠️ 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.
+ */
+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;
+    const body = (await Promise.resolve(json.call(res))) as
+      | { written?: unknown; skipped?: unknown; errors?: unknown }
+      | null
+      | undefined;
+    const skipped = body?.skipped;
+    if (typeof skipped !== "number" || !Number.isFinite(skipped)) return undefined;
+    const reasons = Array.isArray(body?.errors)
+      ? body.errors
+          .map((e) => (e as { reason?: unknown } | null)?.reason)
+          .filter((r): r is string => typeof r === "string")
+      : [];
+    return { written: typeof body?.written === "number" ? body.written : undefined, skipped, reasons };
+  } catch {
+    // Unreadable / already-consumed body / hostile object — best-effort, treat as "no ack".
+    return undefined;
+  }
+};
+
+/**
+ * The DISCARDED warning text, built from what the server ACTUALLY said.
+ *
+ * It used to staple a cause onto a bare integer — "the usual cause is a missing or empty session_id".
+ * Since `ensureCurrentSessionId` shipped, no kit path can emit an event without a `session_id`, so
+ * that is now the LEAST likely explanation, and naming it sent every reader looking in the one place
+ * the problem is not. The endpoint folds four real failures and two idempotent no-ops into one
+ * integer, so unless the server volunteers reasons, the honest thing to report is the count and where
+ * the reason lives.
+ */
+const describeDiscarded = (ack: EventsAck): string =>
+  `[wireai] the server ACCEPTED the /v1/events POST but DISCARDED ${ack.skipped} event(s) ` +
+  "(skipped in the response body) — they are gone, not retried. The server reported: " +
+  `skipped=${ack.skipped}${ack.written !== undefined ? `, written=${ack.written}` : ""}` +
+  (ack.reasons.length > 0
+    ? `, reasons: ${ack.reasons.join(", ")}.`
+    : ". It gave no reason (the endpoint folds every rejection into one count), so check the " +
+      "server's ingest log for this request rather than guessing.");
+
 /** RN sets this global; absent under node/SSR. Read defensively inside {@link warnOnSkippedEvents}. */
 declare const __DEV__: boolean | undefined;
 
 /**
  * Read the `/v1/events` ACK body and warn (dev builds only) when the server DISCARDED events.
  *
- * The endpoint answers HTTP **200** with `{ ok, written, skipped }` — an event it refuses (a missing
- * `session_id`, a malformed payload) is counted in `skipped`, never surfaced in the status code. Every
- * send path here reads `res.ok` alone, so a whole batch can evaporate behind a green response. This
- * consumes the body of the PERSISTENT paths (the offline queue + session-start) and names the count.
+ * The endpoint answers HTTP **200** with `{ ok, written, skipped }` — an event it refuses is counted
+ * in `skipped`, never surfaced in the status code. Every send path here reads `res.ok` alone, so a
+ * whole batch can evaporate behind a green response. As of 0.13.0 ALL FOUR send paths consume the ack:
+ * the offline queue, session-start, the fire-and-forget POST, and the awaitable one (which also acts
+ * on it — see {@link reportClientEventsAwait}).
  *
  * LOG ONLY: returns immediately, never throws, and never influences retry / dequeue / return values.
  * A response with no usable `.json` (an old server, a test mock) is silently ignored.
@@ -149,25 +204,10 @@ declare const __DEV__: boolean | undefined;
 export const warnOnSkippedEvents = (res: unknown): void => {
   if (typeof __DEV__ === "undefined" || !__DEV__) return;
   if (typeof console === "undefined" || !console.warn) return;
-  try {
-    const json = (res as { json?: () => Promise<unknown> } | null | undefined)?.json;
-    if (typeof json !== "function") return;
-    void Promise.resolve(json.call(res))
-      .then((body) => {
-        const skipped = (body as { skipped?: unknown } | null | undefined)?.skipped;
-        if (typeof skipped !== "number" || skipped <= 0) return;
-        console.warn(
-          `[wireai] the server ACCEPTED the /v1/events POST but DISCARDED ${skipped} event(s) ` +
-            "(skipped in the response body) — they are gone, not retried. The usual cause is an " +
-            "event with a missing or empty session_id.",
-        );
-      })
-      .catch(() => {
-        // Unreadable / already-consumed body — best-effort logging, swallow.
-      });
-  } catch {
-    // A hostile response object — swallow.
-  }
+  void readEventsAck(res).then((ack) => {
+    if (!ack || ack.skipped <= 0) return;
+    console.warn(describeDiscarded(ack));
+  });
 };
 
 /**
@@ -182,9 +222,16 @@ export const reportClientEvents = (
   try {
     const req = buildEventsRequest(target, events);
     if (!req) return;
-    void fetch(req.url, req.init).catch(() => {
-      // Network/transport error — analytics is best-effort, swallow.
-    });
+    void fetch(req.url, req.init)
+      .then((res) => {
+        // Still fire-and-forget — nothing is retried, nothing is returned. But a batch that
+        // evaporated behind a 200 is exactly what this path used to make invisible, so in dev it
+        // now says so, like the queue and session-start paths already did.
+        warnOnSkippedEvents(res);
+      })
+      .catch(() => {
+        // Network/transport error — analytics is best-effort, swallow.
+      });
   } catch {
     // A missing `fetch` — swallow.
   }
@@ -201,8 +248,17 @@ export const reportClientEvent = (
  * `/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.
+ * target, a missing `fetch`, a network error, or a non-2xx status all resolve to `false`.
+ *
+ * ⚠️ 0.13.0: a 2xx is NO LONGER SUFFICIENT. The endpoint answers HTTP 200 with `{ ok, written,
+ * skipped }` and counts an event it refuses in `skipped`, so this used to resolve `true` for an event
+ * the server had thrown away — and `wire.track` then bumped decision revalidation, making every
+ * subscribed gate re-fetch against a stream the action never entered. It now reads the ack and
+ * resolves `false` when the server reports a positive `skipped`.
+ *
+ * BACKWARD COMPATIBLE BY CONSTRUCTION: only an explicit positive `skipped` demotes a 200. An old
+ * server that sends no such field, a body that cannot be parsed, or a response with no `.json` at all
+ * resolves `true` exactly as before — the change can produce no false negatives.
  */
 export const reportClientEventsAwait = async (
   target: ClientEventTarget | undefined,
@@ -212,7 +268,14 @@ export const reportClientEventsAwait = async (
     const req = buildEventsRequest(target, events);
     if (!req) return false;
     const res = await fetch(req.url, req.init);
-    return Boolean(res && res.ok);
+    if (!res || !res.ok) return false;
+    // ONE body read, used for both the verdict and the dev warning — it can only be read once.
+    const ack = await readEventsAck(res);
+    if (!ack || ack.skipped <= 0) return true;
+    if (typeof __DEV__ !== "undefined" && __DEV__ && typeof console !== "undefined" && console.warn) {
+      console.warn(describeDiscarded(ack));
+    }
+    return false;
   } catch {
     // Unreachable / missing-fetch / network — best-effort, report failure.
     return false;

package/src/config/wireConfigFromEnv.ts

@@ -17,6 +17,7 @@
  */
 import { detectAppVersion } from "../device/appVersion";
 import type { WireOnboardingConfig } from "../types";
+import { warnInDev } from "../utils/warnInDev";
 
 export type WireConfigOverrides = Partial<WireOnboardingConfig>;
 
@@ -27,16 +28,6 @@ export const WIRE_ENV_VARS = [
   "EXPO_PUBLIC_WIREAI_APP_ID",
 ] as const;
 
-/** RN sets this global; absent under node/SSR. Read defensively via {@link warnInDev}. */
-declare const __DEV__: boolean | undefined;
-
-/** Emit a one-line developer warning, but ONLY in a dev build (RN `__DEV__`). No-op in prod/tests. */
-const warnInDev = (message: string): void => {
-  if (typeof __DEV__ !== "undefined" && __DEV__ && typeof console !== "undefined" && console.warn) {
-    console.warn(message);
-  }
-};
-
 /**
  * Minimal `process.env` declaration so the kit stays RN-pure (no `@types/node`).
  * In RN/Expo, `process.env.EXPO_PUBLIC_*` is provided/inlined by Metro at build

package/src/context/deviceId.ts

@@ -18,6 +18,8 @@
  * that verbatim and never mints/persists an auto id.
  */
 
+import { resolveIdentity, type IdentityRecord } from "../identity/identityRecord";
+
 /** Prefix so an auto-minted id is visibly the kit's (distinguishable from a host-supplied `deviceKey`). */
 export const AUTO_DEVICE_ID_PREFIX = "wdev_";
 
@@ -69,12 +71,21 @@ export const mintDeviceId = (): string => {
 /** Well-known key into the runtime-global symbol registry — one auto-id registry across every bundle. */
 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.
+ *
+ *  `durable: false` means the id lives only in this process's memory — the adapter rejected, threw,
+ *  or there was no adapter at all. That distinction is the whole of K1: a string is a string, so
+ *  before 0.13.0 a caller could not tell a persisted id from a per-launch mint, and the auto-join
+ *  gate (`Boolean(storage)`) was reading the PRESENCE of the prop rather than the SUCCESS of the
+ *  write. See {@link hydrateDeviceIdentity}. */
+type HydrationOutcome = { value: string; durable: boolean };
+
 /** The shared registry: the live id per `appId`, the set of appIds whose hydration already started,
  *  and the in-flight (or settled) hydration promise per `appId` so a waiter can join it. */
 type AutoDeviceKeyRegistry = {
   keys: Map<string, string>;
   hydrating: Set<string>;
-  pending?: Map<string, Promise<string>>;
+  pending?: Map<string, Promise<HydrationOutcome>>;
 };
 
 type GlobalWithDeviceKeys = typeof globalThis & {
@@ -108,40 +119,65 @@ export interface ResolveAutoDeviceKeyOptions {
 }
 
 /**
- * Start (or join) the SINGLE-FLIGHT storage read for `appId` and resolve to the id it settles on.
- * The promise is parked on the registry so a later `hydrateAutoDeviceKey` awaits the SAME read
- * instead of starting a second one. Never rejects: any storage failure resolves to the live id.
+ * Start (or join) the SINGLE-FLIGHT storage read for `appId` and resolve to the {@link HydrationOutcome}
+ * it settles on. The promise is parked on the registry so a later `hydrateAutoDeviceKey` awaits the
+ * SAME read instead of starting a second one. Never rejects: any storage failure resolves to the live
+ * id with `durable: false`.
+ *
+ * TWO OUTCOMES, NOT ONE STRING:
+ *   • ADOPTED (`durable: true`)   — a persisted id was read back, or the freshly minted one was
+ *                                   written successfully. The next launch will see the same id.
+ *   • DEGRADED (`durable: false`) — the adapter rejected, threw, or returned nothing and then failed
+ *                                   the write. The id is real but PROCESS-scoped, so anything that
+ *                                   counts a device across launches must refuse it.
+ *
+ * A DEGRADED outcome also drops the registry latches so the NEXT caller starts a fresh read (K8). A
+ * cold-boot storage lock is transient; caching it as a verdict for the process lifetime turned a
+ * one-second problem into a whole-launch one, and nothing ever retried.
  */
 const startHydration = (
   registry: AutoDeviceKeyRegistry,
   appId: string,
   storage: DeviceKeyStorage,
   minted: string,
-): Promise<string> => {
+): Promise<HydrationOutcome> => {
   if (!registry.pending) registry.pending = new Map();
   const existing = registry.pending.get(appId);
   if (existing) return existing;
 
   const slot = deviceIdStorageKey(appId);
-  const settled = (): string => registry.keys.get(appId) ?? minted;
-  let run: Promise<string>;
+  const degraded = (): HydrationOutcome => ({ value: registry.keys.get(appId) ?? minted, durable: false });
+  const adopted = (value: string): HydrationOutcome => ({ value, durable: true });
+  let run: Promise<HydrationOutcome>;
   try {
     run = Promise.resolve(storage.getItem(slot))
       .then((saved) => {
         const persisted = typeof saved === "string" && saved.trim() ? saved.trim() : undefined;
         if (persisted) {
           registry.keys.set(appId, persisted);
-          return persisted;
+          return adopted(persisted);
         }
         // First run on this install: persist the id we just minted so the next launch adopts it.
-        return Promise.resolve(storage.setItem(slot, minted)).then(settled, settled);
+        // ONLY a resolved write earns `durable` — a rejected one leaves the id in memory alone.
+        return Promise.resolve(storage.setItem(slot, minted)).then(
+          () => adopted(registry.keys.get(appId) ?? minted),
+          degraded,
+        );
       })
-      .catch(settled);
+      .catch(degraded);
   } catch {
     // A storage adapter that throws synchronously — degrade to the in-memory id.
-    run = Promise.resolve(settled());
+    run = Promise.resolve(degraded());
   }
   registry.pending.set(appId, run);
+  // Retry-on-failure (K8): release the latches once a degraded outcome settles, so a later caller
+  // is not permanently bound to one bad read. Registered AFTER the `set` above, so the clean-up can
+  // never race ahead of the entry it is clearing.
+  void run.then((outcome) => {
+    if (outcome.durable) return;
+    registry.pending?.delete(appId);
+    registry.hydrating.delete(appId);
+  });
   return run;
 };
 
@@ -196,15 +232,40 @@ export const resolveAutoDeviceKey = (opts: ResolveAutoDeviceKeyOptions = {}): st
  */
 export const hydrateAutoDeviceKey = async (
   opts: ResolveAutoDeviceKeyOptions = {},
-): Promise<string> => {
+): Promise<string> => (await hydrateDeviceIdentity(opts))?.value ?? resolveAutoDeviceKey(opts);
+
+/**
+ * The PROVENANCE-CARRYING sibling of {@link hydrateAutoDeviceKey}: the same awaited read, but it
+ * answers "is this id one this install will KEEP?" instead of only "what is the id?".
+ *
+ * WHY IT EXISTS (K1). `<WireOnboarding>` gated auto-injection on `Boolean(storage)` — the presence of
+ * the prop — because a string carries no provenance and there was nothing better to gate on. A
+ * REJECTING adapter therefore injected a fresh `wdev_*` on every launch: strictly worse than
+ * injecting nothing, since the server counts `min_sessions` by distinct opens grouped on `device_key`,
+ * so a per-launch key corrupts that counter AND inflates distinct-device counts. Callers that write a
+ * key onto the wire as a cross-launch join must read `durable` and refuse a `false`.
+ *
+ * Resolves `undefined` only when there is no usable id at all. With no `storage` it resolves
+ * immediately with `durable: false` — a process-scoped id is exactly what "no persistence" means.
+ * Never throws or rejects.
+ */
+export const hydrateDeviceIdentity = async (
+  opts: ResolveAutoDeviceKeyOptions = {},
+): Promise<IdentityRecord | undefined> => {
   // Mint + register synchronously first, so a waiter and a concurrent sync caller share ONE id.
   const id = resolveAutoDeviceKey(opts);
-  if (!opts.storage) return id;
-  const registry = autoDeviceKeyRegistry();
   const appId = opts.appId ?? "default";
+  const record = (value: string, durable: boolean): IdentityRecord | undefined =>
+    resolveIdentity({ value, space: "device", source: "auto", durable, scope: appId });
+
+  if (!opts.storage) return record(id, false);
+  const registry = autoDeviceKeyRegistry();
   const pending = registry.pending?.get(appId);
-  if (pending) await pending;
-  return registry.keys.get(appId) ?? id;
+  // No pending entry means a previous hydration already settled DEGRADED and released its latches
+  // (see `startHydration`), so the live id is the in-memory one — real, but not durable.
+  if (!pending) return record(registry.keys.get(appId) ?? id, false);
+  const outcome = await pending;
+  return record(outcome.value, outcome.durable);
 };
 
 /** Test-only: forget every auto id + hydration flag so a unit test starts from a clean registry. */

package/src/context/userContext.ts

@@ -88,19 +88,6 @@ export interface ResolvedUserContext {
   userContext?: Record<string, string | number | boolean>;
 }
 
-/** Reserved `user_context` keys the kit itself writes; host `extra` is namespaced away from these. */
-export const RESERVED_USER_CONTEXT_KEYS = [
-  "device_key",
-  "app_version",
-  "app_build",
-  "network_type",
-  "session_count",
-  "returning",
-  "platform",
-  "user_email",
-  "user_email_hashed",
-] as const;
-
 /** The prefix applied to every host `extra` key so it can never collide with a reserved key. */
 export const EXTRA_KEY_PREFIX = "custom." as const;
 
@@ -127,8 +114,10 @@ export const hashEmailFnv1a = (email: string): string => {
   return (hash >>> 0).toString(16).padStart(8, "0");
 };
 
-/** Trim a candidate string; return `undefined` for a non-string / blank so callers can `if`-gate. */
-const cleanString = (value: unknown): string | undefined => {
+/** Trim a candidate string; return `undefined` for a non-string / blank so callers can `if`-gate.
+ *  Shared with `activation/wireActivation`, which carried a byte-identical private copy named `clean`.
+ *  Not re-exported from the package barrel — this is an internal helper, not public surface. */
+export const cleanString = (value: unknown): string | undefined => {
   if (typeof value !== "string") return undefined;
   const trimmed = value.trim();
   return trimmed.length > 0 ? trimmed : undefined;

package/src/identity/identityRecord.ts

@@ -0,0 +1,123 @@
+/**
+ * identityRecord — the ONE provenance-carrying shape for an id the kit puts on the wire.
+ *
+ * WHY IT EXISTS. `session_id` and `device_key` are bare `string`s minted independently by four
+ * subsystems, and nothing anywhere recorded WHERE a given id came from. Every id-layer defect this
+ * release fixes is a direct consequence of that one omission:
+ *
+ *   • a rejecting storage adapter's in-memory id was indistinguishable from a persisted one, so the
+ *     kit injected a fresh per-launch join key on every launch — nothing carried `durable`.
+ *   • an app-OPEN session id could be posted into a field that means the ONBOARDING session, and the
+ *     caller was told `true` — nothing carried `space`.
+ *   • an auto-minted `wdev_*` could be injected beside a device id the host demonstrably owns on
+ *     another surface, silently — nothing carried `source`.
+ *
+ * WHAT THIS IS, AND WHAT IT DELIBERATELY IS NOT. It is a small record plus a process-wide registry of
+ * the ids a HOST supplied. It is NOT a branded-type refactor (`OnboardingSessionId` / `AppSessionId` /
+ * `DeviceKey` across every signature) — that is real value and it is deferred, because it touches
+ * every file and is not what makes a number correct this week. Nothing here changes the wire.
+ *
+ * WHY A `Symbol.for` REGISTRY. Same reason as `analytics/currentSession` and `context/deviceId`: tsup
+ * inlines a separate copy of a module into each bundle (`.` and `./analytics`), so a plain module
+ * `let` would give every bundle its own registry and the cross-surface question this exists to answer
+ * ("did ANY surface in this process get a host-supplied device key?") would read `no` from the wrong
+ * copy. `Symbol.for` resolves to one slot on `globalThis` no matter how many copies exist.
+ */
+
+/**
+ * Which id space a value belongs to. These are NOT interchangeable, and the whole point of naming
+ * them is that a value from one space must never be posted into a field that means another:
+ *   • `onboarding-session` — the A2A `contextId` for ONE onboarding run.
+ *   • `app-session`        — the per-app-open session id (`app.session_started`).
+ *   • `device`             — the per-install `device_key`; the only cross-family join key.
+ */
+export type IdentitySpace = "onboarding-session" | "app-session" | "device";
+
+/** Where the value came from: the host handed it over, or the kit minted it. */
+export type IdentitySource = "host" | "auto";
+
+/** An id plus everything a consumer needs to decide whether it may use it. */
+export type IdentityRecord = {
+  /** The id itself, trimmed. Never empty (a blank input yields no record at all). */
+  value: string;
+  /** Which id space {@link value} belongs to. */
+  space: IdentitySpace;
+  /** `host` = the integrator supplied it; `auto` = the kit minted it. */
+  source: IdentitySource;
+  /**
+   * Whether the value was actually PERSISTED (or adopted from persistence), as opposed to living
+   * only in this process's memory. A non-durable auto id is a DIFFERENT id on the next launch, which
+   * for a `device` value is worse than no value at all: the server counts `min_sessions` by distinct
+   * opens grouped on `device_key`, so a per-launch key corrupts the counter rather than leaving it
+   * empty. A host-supplied value is durable by definition — the host owns its lifetime.
+   */
+  durable: boolean;
+};
+
+/** Input to {@link resolveIdentity}. `value` is `unknown` so callers can pass a raw prop through. */
+export type ResolveIdentityInput = {
+  value: unknown;
+  space: IdentitySpace;
+  source: IdentitySource;
+  /** Defaults to `true` for a host value (the host owns its lifetime) and `false` otherwise. */
+  durable?: boolean;
+  /** Tenant/app id — two tenants in one process never share a provenance entry. */
+  scope?: string;
+};
+
+/** Well-known key into the runtime-global symbol registry — one provenance registry per process. */
+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. */
+type ProvenanceRegistry = { host: Map<string, string> };
+
+type GlobalWithProvenance = typeof globalThis & {
+  [IDENTITY_PROVENANCE_SLOT]?: ProvenanceRegistry;
+};
+
+const provenanceGlobal = globalThis as GlobalWithProvenance;
+
+const provenanceRegistry = (): ProvenanceRegistry => {
+  const existing = provenanceGlobal[IDENTITY_PROVENANCE_SLOT];
+  if (existing) return existing;
+  const created: ProvenanceRegistry = { host: new Map() };
+  provenanceGlobal[IDENTITY_PROVENANCE_SLOT] = created;
+  return created;
+};
+
+const provenanceKey = (space: IdentitySpace, scope?: string): string =>
+  `${space}:${scope ?? "default"}`;
+
+/**
+ * Build an {@link IdentityRecord} from a candidate value, or `undefined` when there is nothing usable
+ * (a non-string, or blank after trimming) — so a caller can `if (record)`-gate instead of guessing
+ * whether an empty string means "none" or "not yet".
+ *
+ * SIDE EFFECT, deliberate and the reason this is a function and not an object literal: a `host`-sourced
+ * record is RECORDED on the process registry, so a later surface can ask {@link hostIdentity} whether
+ * this process demonstrably owns a host id in that space. That is what turns "the kit injected its own
+ * key" from a silent third id space into a warnable condition. Never throws.
+ */
+export const resolveIdentity = (input: ResolveIdentityInput): IdentityRecord | undefined => {
+  if (typeof input.value !== "string") return undefined;
+  const value = input.value.trim();
+  if (!value) return undefined;
+  const durable = input.durable ?? input.source === "host";
+  if (input.source === "host") {
+    provenanceRegistry().host.set(provenanceKey(input.space, input.scope), value);
+  }
+  return { value, space: input.space, source: input.source, durable };
+};
+
+/**
+ * The HOST-supplied id this process has seen for a space, or `undefined` when every surface so far
+ * let the kit mint its own. Answers the cross-surface question no single mount can answer alone:
+ * "does this app own a device id that this particular mount was not given?"
+ */
+export const hostIdentity = (space: IdentitySpace, scope?: string): string | undefined =>
+  provenanceRegistry().host.get(provenanceKey(space, scope));
+
+/** Test-only: forget every recorded host identity so a unit test starts from a clean registry. */
+export const resetIdentityProvenance = (): void => {
+  provenanceRegistry().host.clear();
+};

package/src/identity/userIdentity.ts

@@ -76,20 +76,49 @@ export type IdentifyOnboardingOptions = {
   appId?: string;
   /** Storage key override — pass the same `persistKey` you gave `<WireOnboarding>`, if any. */
   persistKey?: string;
+  /**
+   * OPT-IN LAST RESORT, default `false`. When no ONBOARDING session can be resolved (no `contextId`,
+   * nothing in `storage`), bind the user to the LIVE PER-OPEN app session instead and return
+   * `"app_session"`.
+   *
+   * ⚠️ These are two different id spaces sharing one wire field. An onboarding session id is the A2A
+   * `contextId`; a per-open id is what `app.session_started` registers. The server's onboarding funnel
+   * groups by `session_id`, so a per-open id posted here does not attach the user to their onboarding
+   * — it writes a row nothing in that funnel can join. Until 0.13.0 this happened SILENTLY and
+   * returned `true`, in exactly the documented post-completion case (completion clears the persisted
+   * session), so the funnel stayed unattributed while the host was told it had worked.
+   *
+   * Turn it on only if binding the id to *some* session the server saw is genuinely worth more to you
+   * than knowing the onboarding bind failed — and read the return value, which now says which it was.
+   */
+  allowAppSessionFallback?: boolean;
 };
 
+/**
+ * What {@link identifyOnboarding} bound, and to WHICH id space — because `true` could not say.
+ *
+ *   • `"onboarding"`  — bound to the A2A `contextId`. This is the one that attributes the funnel.
+ *   • `"app_session"` — bound to the live per-open app session, via `allowAppSessionFallback`. The
+ *                       server saw that session, but it is not this user's onboarding.
+ *   • `false`         — nothing was dispatched (no user id, no server url, no resolvable session).
+ *
+ * ⚠️ 0.13.0 widened this from `boolean`. `"onboarding"` is truthy, so an `if (await identify…)` still
+ * behaves identically; only an explicit `: boolean` annotation needs updating.
+ */
+export type IdentifyOnboardingBinding = "onboarding" | "app_session" | false;
+
 /**
  * Attach a host user id to an onboarding session AFTER the fact (post-registration), by sending
  * an `identify` client event to `/v1/events`. Resolves the contextId from an explicit
  * `contextId` or, failing that, from the persisted session in the host `storage`.
  *
- * Fire-and-forget under the hood (never throws, never blocks onboarding). Resolves to `true`
- * when an identify event was dispatched, `false` when it couldn't (no user id, no server url,
- * or no resolvable contextId).
+ * Fire-and-forget under the hood (never throws, never blocks onboarding). Resolves to the
+ * {@link IdentifyOnboardingBinding} that says WHICH id space was bound, or `false` when nothing could
+ * be (no user id, no server url, or no resolvable session).
  */
 export const identifyOnboarding = async (
   opts: IdentifyOnboardingOptions,
-): Promise<boolean> => {
+): Promise<IdentifyOnboardingBinding> => {
   const userId = sanitizeUserId(opts.userId);
   if (!userId || !opts.config?.serverUrl) return false;
 
@@ -101,15 +130,22 @@ export const identifyOnboarding = async (
       contextId = stored?.id;
     }
   }
-  // Last resort: bind to the LIVE per-open session (registered by `reportSessionStart`) so a
-  // post-flow identify with no captured contextId still attaches to a session the server saw,
-  // instead of no-oping. The onboarding contextId (above) is still preferred when available.
-  if (!contextId) contextId = getCurrentSessionId();
+  let space: Exclude<IdentifyOnboardingBinding, false> = "onboarding";
+  // The OPT-IN last resort (K3). Until 0.13.0 this ran unconditionally: with no captured contextId
+  // it posted the LIVE PER-OPEN session id in the `session_id` field — which on this endpoint means
+  // the ONBOARDING session — and then returned `true`. Two disjoint id spaces share that field, so
+  // the row it wrote could never join the onboarding funnel, and the host got a success signal for a
+  // bind that had not happened. It is now off unless the caller asks, and when it does fire it says
+  // so in the return value instead of impersonating an onboarding bind.
+  if (!contextId && opts.allowAppSessionFallback) {
+    contextId = getCurrentSessionId();
+    space = "app_session";
+  }
   if (!contextId) return false;
 
   reportClientEvent(
     { serverUrl: opts.config.serverUrl, apiKey: opts.config.apiKey },
     { event_type: "identify", session_id: contextId, user_id: userId },
   );
-  return true;
+  return space;
 };

package/src/index.ts

@@ -30,8 +30,6 @@ export { LoadingBlock } from "./components/LoadingBlock";
 export { LoadingScreen } from "./components/LoadingScreen";
 export { AnimatedSparkle } from "./components/AnimatedSparkle";
 export { ErrorBlock } from "./components/ErrorBlock";
-/** @deprecated No longer used internally — the terminal screen is CompletionView. */
-export { DoneBlock } from "./components/DoneBlock";
 export { CompletionView } from "./components/CompletionView";
 export { IllustrationProvider, useIllustration } from "./components/Illustration";
 export type { IllustrationRegistry } from "./components/Illustration";
@@ -147,7 +145,9 @@ export { detectNativeModel } from "./device/deviceModel";
 
 // ─── User identity (opaque pseudonymous id; late binding, dependency-free) ────
 export { identifyOnboarding, sanitizeUserId, looksLikeEmail, USER_ID_MAX_LENGTH } from "./identity/userIdentity";
-export type { IdentifyOnboardingOptions } from "./identity/userIdentity";
+export type { IdentifyOnboardingOptions, IdentifyOnboardingBinding } from "./identity/userIdentity";
+export { resolveIdentity, hostIdentity, resetIdentityProvenance } from "./identity/identityRecord";
+export type { IdentityRecord, IdentitySpace, IdentitySource } from "./identity/identityRecord";
 
 // ─── Rich user context (one object → every event's user_context; opt-in email PII) ────
 export {
@@ -159,7 +159,6 @@ export {
   clearPiiFromContext,
   analyticsUserIdStorageKey,
   activationJoinContext,
-  RESERVED_USER_CONTEXT_KEYS,
   EXTRA_KEY_PREFIX,
 } from "./context/userContext";
 export type {
@@ -182,6 +181,9 @@ export {
   // The awaitable sibling: resolves AFTER the persisted id has been read back, for a caller that can
   // afford one storage read and must not stamp a key minted a millisecond ago (the lifecycle mount).
   hydrateAutoDeviceKey,
+  // The PROVENANCE-carrying form of the same read: it also says whether the id was actually persisted,
+  // so a caller writing a cross-launch join key onto the wire can refuse a per-launch one.
+  hydrateDeviceIdentity,
   resetAutoDeviceKeys,
 } from "./context/deviceId";
 export type { DeviceKeyStorage, ResolveAutoDeviceKeyOptions } from "./context/deviceId";

package/src/session-analytics/useLifecycleEvents.ts

@@ -33,6 +33,7 @@ import { AppState, Platform, type AppStateStatus } from "react-native";
 import { createEventQueue, type EnvelopeSource, type EventQueue } from "../analytics/eventQueue";
 import { makeSessionId, type ClientEvent, type ClientEventTarget } from "../analytics/reportClientEvent";
 import { hydrateAutoDeviceKey, resolveAutoDeviceKey } from "../context/deviceId";
+import { resolveIdentity } from "../identity/identityRecord";
 import { collectDeviceContext } from "../device/deviceContext";
 import type { WireOnboardingStorage } from "../session/persistedSession";
 import { reportFirstOpen } from "./lifecycle";
@@ -137,7 +138,15 @@ export const useLifecycleEvents = (
       cfg: LifecycleConfig | undefined,
       opts: UseLifecycleEventsOptions,
     ): string | undefined => {
-      const host = typeof opts.deviceKey === "string" && opts.deviceKey.trim() ? opts.deviceKey : undefined;
+      // A HOST-supplied key is recorded on the process provenance registry, so a `<WireOnboarding>`
+      // mount that was not given one can tell "this app owns no device id" from "this app owns one
+      // and forgot it there" — the silent third id space (K9). Recording only; nothing reads it here.
+      const host = resolveIdentity({
+        value: opts.deviceKey,
+        space: "device",
+        source: "host",
+        scope: cfg?.appId,
+      })?.value;
       if (host) return host;
       if (!cfg?.storage) return undefined;
       return resolveAutoDeviceKey({ appId: cfg.appId, storage: cfg.storage });