@wireai/activation 0.12.2 → 0.13.0

package/CHANGELOG.md

@@ -3,6 +3,151 @@
 All notable changes to `@wireai/activation` (formerly `wireai-onboarding`).
 Historical entries below the rename keep the old package name on purpose.
 
+## [0.13.0] — 2026-07-27
+
+The identity-provenance release. Every id-layer defect fixed here is one omission wearing five faces:
+`session_id` and `device_key` are bare `string`s minted independently by four subsystems, and nothing
+anywhere recorded WHERE a given id came from. So a rejecting storage adapter's in-memory id was
+indistinguishable from a persisted one, an app-OPEN session id could be posted into a field meaning the
+ONBOARDING session, an auto-minted key could be injected beside a device id the host demonstrably owned
+on another surface, and the join key could change identity mid-mount — each of them silently, each of
+them returning success. This release gives ids provenance and teaches every consumer to refuse a
+fabricated one.
+
+Nothing here changes the wire for a correctly-wired host. The behaviour changes all move in one
+direction: the kit now declines and says so, where it used to fabricate and return `true`.
+
+### Added
+
+- **`resolveIdentity(...)`, `hostIdentity(...)` and the `IdentityRecord` type** (`identity/identityRecord.ts`) —
+  the substrate. One record, `{ value, space, source, durable }`, parked on the same `Symbol.for`
+  registry pattern the repo already uses for the current session id, the auto device key and activation
+  revalidation, so every inlined bundle copy addresses ONE registry. `space` is
+  `onboarding-session | app-session | device`, `source` is `host | auto`, and `durable` says whether the
+  value was actually persisted. A host-sourced record is recorded on a process-wide registry, which is
+  what lets one surface notice that another surface owns a device key it was not given.
+  ⚠️ Deliberately NOT a branded-types refactor — `OnboardingSessionId` / `AppSessionId` / `DeviceKey`
+  across every signature is real value and is deferred, because it touches every file.
+- **`hydrateDeviceIdentity(...)`** (`context/deviceId.ts`) — the provenance-carrying sibling of
+  `hydrateAutoDeviceKey`. Same awaited read, but it answers "is this an id this install will KEEP?"
+  instead of only "what is the id?". `hydrateAutoDeviceKey` is unchanged and still returns a bare string.
+- **`OnboardingProgress.slot_id`** — an optional STABLE per-slot identity for a screen, read off
+  `props.progress` by `readProgress` and preferred over `key` by `deriveAnswers`. `key` is authored from
+  the question's prompt text (tenant flows slugify it and cut at 32 chars), so re-wording a question mints
+  a NEW key and a host reading `answers.interests` silently starts reading `undefined`.
+  ⚠️ **INERT UNTIL THE SERVER EMITS IT.** No deployed server sends `slot_id` today. Against a server that
+  never sends it, every path degrades to byte-identical 0.12.2 behaviour. Every fallback is decided
+  PER CARD, never cached as a per-session "this backend supports slots" verdict, so a thread that mixes
+  slotted and unslotted cards — the real shape during a rollout — keys each card correctly.
+- **`allowAppSessionFallback` on `identifyOnboarding`** — the opt-in switch for the tier-3 behaviour
+  described under Changed. Default `false`.
+- **`resetEventQueueKeys()`** (`@wireai/activation/analytics`, test-only) — clears
+  the claimed-queue-key registry. A real relaunch is a new process; a test that simulates one in-process
+  needs this or its second queue reads as a concurrent sibling.
+- **A first test file for `deriveAnswers`** (`utils/deriveAnswers.test.ts`), table-driven over real thread
+  shapes: progress key present and absent, slugified prose, multi-select, every NL wrapper the SDK
+  produces, and the threads that must produce NO entry.
+
+### Changed
+
+- **⚠️ BEHAVIOR CHANGE: a `storage` adapter that FAILS no longer earns an injected join key.** The
+  auto-join gate was a bare presence check on the `storage` prop — never the SUCCESS of the write — and
+  `hydrateAutoDeviceKey` resolves to the in-memory mint on every failure branch, so a REJECTING adapter
+  (a locked / full / permission-denied AsyncStorage, the most common real breakage) injected a FRESH
+  `wdev_*` on every launch. Probe-verified: two launches, two different keys. That is strictly worse than
+  injecting nothing — the server counts `min_sessions` by distinct opens grouped on `device_key`, so a
+  per-launch key makes that counter structurally incapable of exceeding 1 AND inflates distinct-device
+  counts. The gate now reads `IdentityRecord.durable`, true only when the id was adopted from storage or
+  written to it successfully, so a broken adapter lands on the same "declined, and here is why" path as
+  no adapter at all. The existing dev warning was widened to name this third reason.
+  Who this changes: a host whose storage was silently broken. It was already getting corrupt data; it now
+  gets no join key and a warning that names the cause.
+- **⚠️ BEHAVIOR CHANGE: `identifyOnboarding` no longer binds to the app-open session by default, and its
+  return type widened to `"onboarding" | "app_session" | false`.** Tier 3 fell back to
+  `getCurrentSessionId()` — the per-OPEN session — and posted it in the `session_id` field, which on this
+  endpoint means the ONBOARDING session, then returned `true`. Two disjoint id spaces share that field, so
+  the row it wrote could never join the onboarding funnel while the host was told it had worked. It fired
+  in exactly the DOCUMENTED post-completion case, because completion clears the persisted session. The
+  fallback is now behind `allowAppSessionFallback` and, when it does fire, says so in the return value.
+  ⚠️ `"onboarding"` is truthy, so `if (await identifyOnboarding(...))` behaves identically at runtime;
+  only an explicit `: boolean` annotation needs updating.
+- **⚠️ BEHAVIOR CHANGE: `wire.track()` returns `false` for an event the server DISCARDED.**
+  `POST /v1/events` answers HTTP 200 with `{ ok, written, skipped }` and counts a refused event in
+  `skipped`, so `reportClientEventsAwait` — which read `res.ok` alone — resolved `true` for an event that
+  was 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. Backward compatible by
+  construction: ONLY an explicit positive `skipped` demotes a 200, so an old server that sends no such
+  field, an unparseable body, or a response with no `.json` at all still resolves `true` — the change can
+  produce no false negatives.
+- **The join decision is FROZEN at the moment the loader gate opens.** `userContext` feeds the `llm` memo
+  and wireai-rn recreates its A2A adapter whenever that identity changes, resetting `contextId`. So a host
+  resolving its device key ASYNCHRONOUSLY — the default shape of any host reading its id out of async
+  storage — rendered once without it, got `wdev_*` injected, then had the real key land a tick later and
+  rebuild the adapter, DROPPING the server-learned session id and RESTARTING the user's onboarding
+  mid-flow with an orphaned session left behind. The session-start metadata now reads a frozen snapshot,
+  exactly as `startupUserIdRef` already did for the user id. Client events deliberately keep reading the
+  LIVE context: they carry no adapter, so late host context enriches them at no risk.
+- **A host device key on ANOTHER surface is no longer silent.** 0.12.2 suppressed the missing-join-key
+  warning whenever injection succeeded — right when the host genuinely owns no device id, wrong when it
+  owns one and forgot it on this mount. That host went from a loud warning to a silent THIRD id space. Any
+  surface constructed with a host-supplied device key (`createAnalytics`, `createWireActivation`,
+  `useLifecycleEvents`, `<WireOnboarding userContext={...}>`) now records it, scoped per `appId`, and a mount
+  that injected its own key while the process demonstrably owns a host one warns and prints both. It warns
+  rather than declining, because declining would leave the onboarding side with no key at all; it does not
+  silently ADOPT the other key, because that is the kit guessing which of two ids a host meant on the
+  strength of construction order.
+- **Two event queues for one `appId` no longer share one storage slot.** The default key was derived from
+  `appId` alone, so two `createAnalytics` instances for one tenant — the documented double-wiring — shared
+  ONE persisted backlog while keeping SEPARATE in-memory buffers: each `persist()` overwrote the other's
+  blob, a queue draining to empty called `removeItem` and DELETED a sibling's still-pending events, and on
+  relaunch the survivors were loaded by both and sent twice. The second claimant of a default key now gets
+  `…#2` and a dev warning naming the fix. Only the appId-derived DEFAULT is ever rotated — an EXPLICIT
+  `storageKey` is a host declaring which slot it owns (`useLifecycleEvents` does exactly that and
+  re-creates its queue on every remount, where rotation would be a worse bug). Only claimed when there IS
+  storage; a storage-less queue never touches the key.
+- **A failed device-key hydration is retried instead of cached for the process lifetime.** A transient
+  cold-boot storage lock used to be permanent: the settled failure stayed parked on the registry and every
+  later caller joined it. A degraded outcome now releases its latches so the next caller starts a fresh read.
+- **The DISCARDED warning covers all FOUR send paths and stops naming a cause the kit never checked.** It
+  used to end "the usual cause is an event with a missing or empty `session_id`" — but since
+  `ensureCurrentSessionId` shipped, no kit path can emit an event without one, making that the LEAST likely
+  explanation and sending every reader to the one place the problem is not. It now reports what the server
+  actually said (`skipped`, `written`, and any per-event `reasons` once the server sends them) and admits
+  when the endpoint gave no reason. The two `reportClientEvent*` paths — which carry `dropped`, `identify`,
+  `client_fallback` and every `wire.track` — join the offline queue and session-start in consuming the ack.
+- **`validators` are looked up by `slot_id` first, then `progress.key`.** Host validators live in the SAME
+  key namespace `deriveAnswers` files answers under, so moving the answer key to the slot without moving
+  this lookup would have silently UNBOUND every host validator: no error, no warning, values simply stop
+  being checked. The fallback keeps a validator map written against today's keys working while a server
+  rolls slots out.
+
+### Removed
+
+- **`DoneBlock`** — self-`@deprecated` since 0.1.x, unused internally since the terminal screen became
+  `CompletionView`, and referenced by nothing in `src/` or the playground. The component file is deleted.
+- **`RESERVED_USER_CONTEXT_KEYS`** — read by nothing, including its own module: the namespacing it claims
+  to govern is enforced by `EXTRA_KEY_PREFIX`. It was a documentation constant shaped like an invariant.
+
+### Internal
+
+- The FOUR duplicate `warnInDev` copies (`WireOnboarding`, `config/wireConfigFromEnv`,
+  `analytics/analyticsFacade`, `analytics/currentSession`) collapse into `utils/warnInDev`, which returns
+  whether it ACTUALLY warned — the property `currentSession`'s once-flag depends on, and the only reason
+  its copy differed. The stated rationale for that copy (keeping the module import-free for the
+  tree-shaken analytics bundle) had already lapsed: it imports `makeSessionId` from a sibling. The new
+  module has no imports of its own, and the `treeShake` canary still holds the real guarantee.
+- The two byte-identical trim helpers (`context/userContext.cleanString`, `activation/wireActivation.clean`)
+  collapse into one shared `cleanString`, not re-exported from the barrel.
+- **The canary suite can observe a payload for the first time.** Every `onComplete` mock was typed with
+  ZERO parameters, so `OnboardingResult` was structurally unobservable and every assertion could only be a
+  call count — the mechanism behind "500 green tests, zero data". `flow.test.tsx` now captures the argument
+  and asserts the answers map end to end. The scripted `wireai-rn` mock also appends the USER turn to the
+  thread, as the real SDK does; without it the mocked thread was assistant-only, so `deriveAnswers` had
+  nothing to pair and `answers` was always `{}` under test regardless of the implementation.
+- `mountCanary` gained `rerender()`, the seam for a prop that arrives LATE. The churn loop runs entirely
+  inside the initial `act`, so without it there was no way to re-render a mount after an async gate had
+  settled — and the whole "value changed mid-flow" defect class was untestable.
+
 ## [0.12.2] — 2026-07-27
 
 The auto-join patch. 0.12.1 taught the kit to complain about a missing join key; this one teaches it

package/README.md

@@ -234,7 +234,7 @@ import { WireOnboarding } from "@wireai/activation";
 | `onComplete` | `(result: { answers, raw }) => void` | Fires when the user taps the terminal recap's CTA. **Required.** |
 | `theme` | `Partial<OnboardingTheme>` | Brand colors/fonts/radius/spacing, deep-merged over a neutral default. |
 | `illustrations` | `Record<string, ReactNode>` | App artwork for `InterstitialCard`, keyed by name. |
-| `validators` | `Record<string, StepValidator>` | Per-step, keyed by base-question key (e.g. `username`). Blocks advance + shows an inline error. |
+| `validators` | `Record<string, StepValidator>` | Per-step, keyed by base-question key (e.g. `username`). Blocks advance + shows an inline error. When the backend sends a `progress.slot_id` for a screen, the kit looks up that slot FIRST and falls back to the question key, so a validator map written against today's keys keeps working. |
 | `onSkip` | `() => void` | User skipped. |
 | `onError` | `(err) => void` | Backend error/timeout — host owns recovery (e.g. route to a static flow). Without it, the kit shows an inline retry. |
 | `onEvent` | `(e: OnboardingEvent) => void` | `started` / `turn` / `error` — recover per-turn analytics since the kit owns the loop. |
@@ -247,7 +247,7 @@ import { WireOnboarding } from "@wireai/activation";
 | `sessionTtlMs` | `number` | How long a persisted session id stays resumable. Default `3600000` (1h, the backend's session TTL). With `storage` only. |
 | `persistKey` | `string` | Override the storage key (default `wireai:session:<appId>`). Scope per-user if one device can onboard multiple accounts mid-flow. With `storage` only. |
 | `userContext` | `Record<string, string \| number \| boolean>` | **This is where the join key goes.** `user_context.device_key` is the only thing that joins this onboarding session to the app's later events, so pass `userContext={activationJoinContext(deviceKey)}` (or `activationJoinContext(resolveAutoDeviceKey({ appId, storage }))` if your app owns no device id). Since 0.12.2, omitting it no longer empties the funnel silently: with `storage`, the kit injects its own key (see [The join key](#the-join-key-device_key-never-session_id) and `autoJoinKey` below). Second job: any other non-PII context the app already knows (signup method, referral, plan, a HASHED user id), forwarded on session metadata + client events for funnel segmentation. **No PII on THIS prop** (no raw emails/names); primitives only; the server caps size/keys. See [Device & user context](#device--user-context). ⚠️ Distinct from the analytics/activation **`WireUserContext`** object (`createAnalytics` / `useWireActivation`), which additionally accepts an opt-in raw `userEmail` — see [Rich user context & PII](#rich-user-context--pii). |
-| `autoJoinKey` | `boolean` | Opt OUT of the automatic join key. Default `true`. When this prop is left alone, `storage` is present, and `userContext` carries no `device_key`, the kit injects its own per-install key (the same id `createAnalytics` / `createWireActivation` mint and persist), so the `activated` funnel joins with no host wiring. Pass `autoJoinKey={false}` if you genuinely want an UNLINKED onboarding session: that restores the pre-0.12.2 behavior exactly, and the dev warning fires again. It never overrides a `device_key` you passed, and it cannot inject without `storage` (see [The join key](#the-join-key-device_key-never-session_id)). |
+| `autoJoinKey` | `boolean` | Opt OUT of the automatic join key. Default `true`. When this prop is left alone, `storage` is present **and actually persists** (0.13.0: a `storage` adapter that rejects or throws is treated exactly like no `storage` — the kit declines and says so, because a key it cannot persist is a different key on every launch, which corrupts `min_sessions` rather than merely leaving the join empty), and `userContext` carries no `device_key`, the kit injects its own per-install key (the same id `createAnalytics` / `createWireActivation` mint and persist), so the `activated` funnel joins with no host wiring. Pass `autoJoinKey={false}` if you genuinely want an UNLINKED onboarding session: that restores the pre-0.12.2 behavior exactly, and the dev warning fires again. It never overrides a `device_key` you passed, and it cannot inject without `storage` (see [The join key](#the-join-key-device_key-never-session_id)). |
 | `userId` | `string` | Your own OPAQUE user id, so onboarding sessions reconcile to real users later (console sessions to your user table / GA4 users). Optional and supports **late binding**: present at mount it rides the session-start metadata; if it changes mid-session (the user just registered) the kit emits an `identify` event; available only after the flow, use `identifyOnboarding(...)`. **No PII** (not an email/name/phone); trimmed and capped at 128 chars. See [User identity](#user-identity). |
 
 ## Helpers (the reusable substrate)
@@ -340,7 +340,9 @@ const contextIdRef = useRef<string>();
 await identifyOnboarding({ config, userId: newUser.id, contextId: contextIdRef.current });
 ```
 
-If you passed `storage` to `<WireOnboarding>`, you can omit `contextId` and hand `identifyOnboarding` the same `storage` (plus `appId` or `persistKey`) and it recovers the persisted session id itself. That works while the session is still persisted (before completion clears it), so the captured-`contextId` path above is the safe one post-completion. `identifyOnboarding` is fire-and-forget and never throws; it resolves `true` when it dispatched an `identify` and `false` when it could not (no user id, no server url, or no resolvable session).
+If you passed `storage` to `<WireOnboarding>`, you can omit `contextId` and hand `identifyOnboarding` the same `storage` (plus `appId` or `persistKey`) and it recovers the persisted session id itself. That works while the session is still persisted (before completion clears it), so the captured-`contextId` path above is the safe one post-completion. `identifyOnboarding` is fire-and-forget and never throws. Since 0.13.0 it resolves the id SPACE it bound rather than a bare boolean: `"onboarding"` when it attached to the A2A `contextId` (the one that attributes the funnel), `"app_session"` when you opted into `allowAppSessionFallback` and it fell back to the live per-open app session, and `false` when it could not bind at all (no user id, no server url, or no resolvable session). `"onboarding"` is truthy, so an existing `if (await identifyOnboarding(...))` behaves identically.
+
+⚠️ **The app-session fallback is now opt-in and off by default.** Before 0.13.0 it ran unconditionally: with no captured `contextId` it posted the per-OPEN session id in the `session_id` field — which on this endpoint means the ONBOARDING session — and returned `true`. Those are two different id spaces sharing one wire field, so the row it wrote could never join the onboarding funnel while the caller was told it had worked.
 
 **No PII.** The onboarding `userId` prop is length-bound only; the kit cannot detect an email for you. Keep it opaque, the same rule as the onboarding `userContext` prop.
 

package/dist/analytics/index.d.mts

@@ -1,6 +1,6 @@
 export { R as ReportAppEventOptions, r as reportAppEvent } from '../transport-CF_eHwzC.mjs';
-import { W as WireUserContext, E as EventQueueOptions } from '../currentSession-BlCeDP0f.mjs';
-export { A as AUTO_DEVICE_ID_PREFIX, a as AnalyticsEvent, C as ClearUserContextOptions, b as ClientEvent, c as ClientEventTarget, d as ClientEventType, e as ContextEnvelope, f as ContextEnvelopeInput, D as DeviceKeyStorage, g as EnvelopeSource, h as EventQueue, R as ResolveAutoDeviceKeyOptions, i as WIRE_ONBOARDING_EVENTS, j as WireOnboardingEventName, k as analyticsUserIdStorageKey, l as buildContextEnvelope, m as clearPiiFromContext, n as clearUserContext, o as createEventQueue, p as deviceIdStorageKey, q as ensureCurrentSessionId, r as getCurrentSessionId, s as looksLikeEmail, t as makeSessionId, u as reportClientEvent, v as reportClientEventAwait, w as reportClientEvents, x as reportClientEventsAwait, y as resetAutoDeviceKeys, z as resetCurrentSessionId, B as resolveAutoDeviceKey, F as setCurrentSessionId, G as toAnalyticsEvent } from '../currentSession-BlCeDP0f.mjs';
+import { W as WireUserContext, E as EventQueueOptions } from '../currentSession-_GynvhzT.mjs';
+export { A as AUTO_DEVICE_ID_PREFIX, a as AnalyticsEvent, C as ClearUserContextOptions, b as ClientEvent, c as ClientEventTarget, d as ClientEventType, e as ContextEnvelope, f as ContextEnvelopeInput, D as DeviceKeyStorage, g as EnvelopeSource, h as EventQueue, R as ResolveAutoDeviceKeyOptions, i as WIRE_ONBOARDING_EVENTS, j as WireOnboardingEventName, k as analyticsUserIdStorageKey, l as buildContextEnvelope, m as clearPiiFromContext, n as clearUserContext, o as createEventQueue, p as deviceIdStorageKey, q as ensureCurrentSessionId, r as getCurrentSessionId, s as looksLikeEmail, t as makeSessionId, u as reportClientEvent, v as reportClientEventAwait, w as reportClientEvents, x as reportClientEventsAwait, y as resetAutoDeviceKeys, z as resetCurrentSessionId, B as resetEventQueueKeys, F as resolveAutoDeviceKey, G as setCurrentSessionId, H as toAnalyticsEvent } from '../currentSession-_GynvhzT.mjs';
 import '../types-CNUqMK0D.mjs';
 import '../types-BKfpdZzX.mjs';
 import '../types-BcmagF6K.mjs';

package/dist/analytics/index.d.ts

@@ -1,6 +1,6 @@
 export { R as ReportAppEventOptions, r as reportAppEvent } from '../transport-DsRe4epC.js';
-import { W as WireUserContext, E as EventQueueOptions } from '../currentSession-BxEB37xt.js';
-export { A as AUTO_DEVICE_ID_PREFIX, a as AnalyticsEvent, C as ClearUserContextOptions, b as ClientEvent, c as ClientEventTarget, d as ClientEventType, e as ContextEnvelope, f as ContextEnvelopeInput, D as DeviceKeyStorage, g as EnvelopeSource, h as EventQueue, R as ResolveAutoDeviceKeyOptions, i as WIRE_ONBOARDING_EVENTS, j as WireOnboardingEventName, k as analyticsUserIdStorageKey, l as buildContextEnvelope, m as clearPiiFromContext, n as clearUserContext, o as createEventQueue, p as deviceIdStorageKey, q as ensureCurrentSessionId, r as getCurrentSessionId, s as looksLikeEmail, t as makeSessionId, u as reportClientEvent, v as reportClientEventAwait, w as reportClientEvents, x as reportClientEventsAwait, y as resetAutoDeviceKeys, z as resetCurrentSessionId, B as resolveAutoDeviceKey, F as setCurrentSessionId, G as toAnalyticsEvent } from '../currentSession-BxEB37xt.js';
+import { W as WireUserContext, E as EventQueueOptions } from '../currentSession-D7zabMXK.js';
+export { A as AUTO_DEVICE_ID_PREFIX, a as AnalyticsEvent, C as ClearUserContextOptions, b as ClientEvent, c as ClientEventTarget, d as ClientEventType, e as ContextEnvelope, f as ContextEnvelopeInput, D as DeviceKeyStorage, g as EnvelopeSource, h as EventQueue, R as ResolveAutoDeviceKeyOptions, i as WIRE_ONBOARDING_EVENTS, j as WireOnboardingEventName, k as analyticsUserIdStorageKey, l as buildContextEnvelope, m as clearPiiFromContext, n as clearUserContext, o as createEventQueue, p as deviceIdStorageKey, q as ensureCurrentSessionId, r as getCurrentSessionId, s as looksLikeEmail, t as makeSessionId, u as reportClientEvent, v as reportClientEventAwait, w as reportClientEvents, x as reportClientEventsAwait, y as resetAutoDeviceKeys, z as resetCurrentSessionId, B as resetEventQueueKeys, F as resolveAutoDeviceKey, G as setCurrentSessionId, H as toAnalyticsEvent } from '../currentSession-D7zabMXK.js';
 import '../types-Buj9Lw9t.js';
 import '../types-BKfpdZzX.js';
 import '../types-BcmagF6K.js';

package/dist/analytics/index.js

@@ -413,28 +413,35 @@ var buildEventsRequest = (target, events) => {
     return null;
   }
 };
-var warnOnSkippedEvents = (res) => {
-  if (typeof __DEV__ === "undefined" || !__DEV__) return;
-  if (typeof console === "undefined" || !console.warn) return;
+var readEventsAck = async (res) => {
   try {
     const json = res == null ? void 0 : res.json;
-    if (typeof json !== "function") return;
-    void Promise.resolve(json.call(res)).then((body) => {
-      const skipped = body == null ? void 0 : body.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) \u2014 they are gone, not retried. The usual cause is an event with a missing or empty session_id.`
-      );
-    }).catch(() => {
-    });
+    if (typeof json !== "function") return void 0;
+    const body = await Promise.resolve(json.call(res));
+    const skipped = body == null ? void 0 : body.skipped;
+    if (typeof skipped !== "number" || !Number.isFinite(skipped)) return void 0;
+    const reasons = Array.isArray(body == null ? void 0 : body.errors) ? body.errors.map((e) => e == null ? void 0 : e.reason).filter((r) => typeof r === "string") : [];
+    return { written: typeof (body == null ? void 0 : body.written) === "number" ? body.written : void 0, skipped, reasons };
   } catch {
+    return void 0;
   }
 };
+var describeDiscarded = (ack) => `[wireai] the server ACCEPTED the /v1/events POST but DISCARDED ${ack.skipped} event(s) (skipped in the response body) \u2014 they are gone, not retried. The server reported: skipped=${ack.skipped}${ack.written !== void 0 ? `, 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.");
+var warnOnSkippedEvents = (res) => {
+  if (typeof __DEV__ === "undefined" || !__DEV__) return;
+  if (typeof console === "undefined" || !console.warn) return;
+  void readEventsAck(res).then((ack) => {
+    if (!ack || ack.skipped <= 0) return;
+    console.warn(describeDiscarded(ack));
+  });
+};
 var reportClientEvents = (target, events) => {
   try {
     const req = buildEventsRequest(target, events);
     if (!req) return;
-    void fetch(req.url, req.init).catch(() => {
+    void fetch(req.url, req.init).then((res) => {
+      warnOnSkippedEvents(res);
+    }).catch(() => {
     });
   } catch {
   }
@@ -445,13 +452,28 @@ var reportClientEventsAwait = async (target, events) => {
     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;
+    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 {
     return false;
   }
 };
 var reportClientEventAwait = (target, event) => reportClientEventsAwait(target, [event]);
 
+// src/utils/warnInDev.ts
+var warnInDev = (message) => {
+  if (typeof __DEV__ !== "undefined" && __DEV__ && typeof console !== "undefined" && console.warn) {
+    console.warn(message);
+    return true;
+  }
+  return false;
+};
+
 // src/analytics/currentSession.ts
 var CURRENT_SESSION_ID_SLOT = /* @__PURE__ */ Symbol.for(
   "@wireai/activation:currentSessionId"
@@ -466,13 +488,6 @@ var getCurrentSessionId = () => globalSlot[CURRENT_SESSION_ID_SLOT];
 var resetCurrentSessionId = () => {
   globalSlot[CURRENT_SESSION_ID_SLOT] = void 0;
 };
-var warnInDev = (message) => {
-  if (typeof __DEV__ !== "undefined" && __DEV__ && typeof console !== "undefined" && console.warn) {
-    console.warn(message);
-    return true;
-  }
-  return false;
-};
 var MINT_WARNING = "[wireai] No app-open session was registered, so a session id was minted for this event (the server drops an event that has no session_id, and still answers 200). Mount useLifecycleEvents at your app root so events correlate to a real app-open.";
 var MINT_WARNED_SLOT = /* @__PURE__ */ Symbol.for(
   "@wireai/activation:currentSessionIdMintWarned"
@@ -820,6 +835,31 @@ var DEFAULTS = {
   maxRetries: 6
 };
 var READ_TIMEOUT_MS = 1500;
+var QUEUE_KEY_SLOT = /* @__PURE__ */ Symbol.for("@wireai/activation:eventQueueKeys");
+var queueKeyGlobal = globalThis;
+var claimedQueueKeys = () => {
+  const existing = queueKeyGlobal[QUEUE_KEY_SLOT];
+  if (existing) return existing;
+  const created = /* @__PURE__ */ new Set();
+  queueKeyGlobal[QUEUE_KEY_SLOT] = created;
+  return created;
+};
+var claimQueueKey = (preferred, explicit) => {
+  const claimed = claimedQueueKeys();
+  if (explicit || !claimed.has(preferred)) {
+    claimed.add(preferred);
+    return preferred;
+  }
+  let ordinal = 2;
+  while (claimed.has(`${preferred}#${ordinal}`)) ordinal++;
+  const key = `${preferred}#${ordinal}`;
+  claimed.add(key);
+  warnInDev(
+    `[wireai] a second event queue was created for the same appId, and "${preferred}" is already claimed by a live one. Two queues sharing one storage slot overwrite each other's backlog, delete each other's pending events when one drains to empty, and double-send on relaunch, so this queue was given "${key}" instead. Prefer ONE analytics instance per app; if you really need two, pass an explicit \`storageKey\` to each so the slots are yours to reason about.`
+  );
+  return key;
+};
+var resetEventQueueKeys = () => claimedQueueKeys().clear();
 var withTimeout = (p, ms) => {
   let timer;
   const timeout = new Promise((resolve) => {
@@ -851,7 +891,8 @@ var createEventQueue = (options) => {
   var _a2, _b, _c, _d, _e, _f, _g;
   const target = options.target;
   const storage = options.storage;
-  const key = (_b = options.storageKey) != null ? _b : `wireai:evtq:${(_a2 = options.appId) != null ? _a2 : "default"}`;
+  const defaultKey = (_b = options.storageKey) != null ? _b : `wireai:evtq:${(_a2 = options.appId) != null ? _a2 : "default"}`;
+  const key = storage ? claimQueueKey(defaultKey, options.storageKey !== void 0) : defaultKey;
   const maxSize = (_c = options.maxSize) != null ? _c : DEFAULTS.maxSize;
   const batchSize = (_d = options.batchSize) != null ? _d : DEFAULTS.batchSize;
   const baseBackoffMs = (_e = options.baseBackoffMs) != null ? _e : DEFAULTS.baseBackoffMs;
@@ -1102,6 +1143,29 @@ var resolveUserContext = (ctx = {}, opts = {}) => {
   return result;
 };
 
+// src/identity/identityRecord.ts
+var IDENTITY_PROVENANCE_SLOT = /* @__PURE__ */ Symbol.for("@wireai/activation:identityProvenance");
+var provenanceGlobal = globalThis;
+var provenanceRegistry = () => {
+  const existing = provenanceGlobal[IDENTITY_PROVENANCE_SLOT];
+  if (existing) return existing;
+  const created = { host: /* @__PURE__ */ new Map() };
+  provenanceGlobal[IDENTITY_PROVENANCE_SLOT] = created;
+  return created;
+};
+var provenanceKey = (space, scope) => `${space}:${scope != null ? scope : "default"}`;
+var resolveIdentity = (input) => {
+  var _a2;
+  if (typeof input.value !== "string") return void 0;
+  const value = input.value.trim();
+  if (!value) return void 0;
+  const durable = (_a2 = input.durable) != null ? _a2 : input.source === "host";
+  {
+    provenanceRegistry().host.set(provenanceKey(input.space, input.scope), value);
+  }
+  return { value, space: input.space, source: input.source, durable };
+};
+
 // src/context/deviceId.ts
 var AUTO_DEVICE_ID_PREFIX = "wdev_";
 var deviceIdStorageKey = (appId) => `wireai:analytics:deviceKey:${appId != null ? appId : "default"}`;
@@ -1124,24 +1188,37 @@ var startHydration = (registry, appId, storage, minted) => {
   const existing = registry.pending.get(appId);
   if (existing) return existing;
   const slot = deviceIdStorageKey(appId);
-  const settled = () => {
+  const degraded = () => {
     var _a2;
-    return (_a2 = registry.keys.get(appId)) != null ? _a2 : minted;
+    return { value: (_a2 = registry.keys.get(appId)) != null ? _a2 : minted, durable: false };
   };
+  const adopted = (value) => ({ value, durable: true });
   let run;
   try {
     run = Promise.resolve(storage.getItem(slot)).then((saved) => {
       const persisted = typeof saved === "string" && saved.trim() ? saved.trim() : void 0;
       if (persisted) {
         registry.keys.set(appId, persisted);
-        return persisted;
+        return adopted(persisted);
       }
-      return Promise.resolve(storage.setItem(slot, minted)).then(settled, settled);
-    }).catch(settled);
+      return Promise.resolve(storage.setItem(slot, minted)).then(
+        () => {
+          var _a2;
+          return adopted((_a2 = registry.keys.get(appId)) != null ? _a2 : minted);
+        },
+        degraded
+      );
+    }).catch(degraded);
   } catch {
-    run = Promise.resolve(settled());
+    run = Promise.resolve(degraded());
   }
   registry.pending.set(appId, run);
+  void run.then((outcome) => {
+    var _a2;
+    if (outcome.durable) return;
+    (_a2 = registry.pending) == null ? void 0 : _a2.delete(appId);
+    registry.hydrating.delete(appId);
+  });
   return run;
 };
 var resolveAutoDeviceKey = (opts = {}) => {
@@ -1169,11 +1246,6 @@ var resetAutoDeviceKeys = () => {
 };
 
 // src/analytics/analyticsFacade.ts
-var warnInDev2 = (message) => {
-  if (typeof __DEV__ !== "undefined" && __DEV__ && typeof console !== "undefined" && console.warn) {
-    console.warn(message);
-  }
-};
 var createAnalytics = (config, options = {}) => {
   var _a2, _b, _c;
   const resolveSessionId = () => {
@@ -1181,13 +1253,19 @@ var createAnalytics = (config, options = {}) => {
     return (_a3 = config.sessionId) != null ? _a3 : ensureCurrentSessionId();
   };
   if (config.sessionId) {
-    warnInDev2(
+    warnInDev(
       "[wireai] createAnalytics({ sessionId }) PINS every event from this instance to that one frozen id and opts out of the live per-open session (app.session_started) \u2014 lifecycle analytics collapse onto a single device-scoped id. Remove it unless your host runs its own session lifecycle."
     );
   }
   const detectedAppVersion = detectAppVersion();
   let userContext = { ...(_a2 = config.userContext) != null ? _a2 : {} };
   const hostDeviceKeyAtInit = typeof ((_b = config.userContext) == null ? void 0 : _b.deviceKey) === "string" && config.userContext.deviceKey.trim() ? config.userContext.deviceKey.trim() : void 0;
+  resolveIdentity({
+    value: hostDeviceKeyAtInit,
+    space: "device",
+    source: "host",
+    scope: config.appId
+  });
   const autoDeviceKeyOptions = {
     appId: config.appId,
     // A host-supplied deviceKey opts out of minting AND persisting (unchanged contract).
@@ -1233,7 +1311,7 @@ var createAnalytics = (config, options = {}) => {
   };
   const guardUserId = (clean) => {
     if (config.allowEmailAsUserId || !looksLikeEmail(clean)) return clean;
-    warnInDev2(
+    warnInDev(
       "[wireai] identify() was called with an email-shaped id. A raw email must NOT be the opaque user_id (PII leak) \u2014 pass it as userContext.userEmail instead. Binding was skipped. Set allowEmailAsUserId:true on createAnalytics if your user id genuinely is an email."
     );
     return void 0;
@@ -1354,6 +1432,7 @@ exports.reportClientEvents = reportClientEvents;
 exports.reportClientEventsAwait = reportClientEventsAwait;
 exports.resetAutoDeviceKeys = resetAutoDeviceKeys;
 exports.resetCurrentSessionId = resetCurrentSessionId;
+exports.resetEventQueueKeys = resetEventQueueKeys;
 exports.resolveAutoDeviceKey = resolveAutoDeviceKey;
 exports.screenTrackingHandler = screenTrackingHandler;
 exports.setCurrentSessionId = setCurrentSessionId;