@wireai/activation 0.12.2 → 0.13.2

package/dist/{currentSession-BxEB37xt.d.ts → currentSession-DOVZEWJl.d.ts}

@@ -153,15 +153,24 @@ type ClientEvent = {
      */
     user_id?: string;
     /**
-     * Client-stamped epoch-ms timestamp of when the event was ENQUEUED on the device. Optional and
-     * ADDITIVE: the offline queue stamps it at enqueue time (see `createEventQueue`) so two otherwise
-     * byte-identical events fired seconds apart (a genuine repeat, e.g. the user taps "share" twice)
-     * are NOT collapsed by the queue's identical-JSON de-dup — while two truly simultaneous
-     * re-enqueues of the same instant (a redundant re-render) still share a `ts` and collapse. A raw
-     * `Date.now()`, never a wall-clock the server trusts (the server derives its own receive time);
-     * an old/strict server that does not model it simply ignores the unknown field.
-     */
-    ts?: number;
+     * Client-stamped timestamp of when the event was ENQUEUED on the device. Optional and ADDITIVE.
+     *
+     * TWO REPRESENTATIONS, on purpose:
+     *  - INTERNAL (epoch-ms `number`): what the offline queue stamps at enqueue time (see
+     *    `createEventQueue`), so two otherwise byte-identical events fired seconds apart (a genuine
+     *    repeat, e.g. the user taps "share" twice) are NOT collapsed by the queue's identical-JSON
+     *    de-dup — while two truly simultaneous re-enqueues of the same instant (a redundant
+     *    re-render) still share a `ts` and collapse. The de-dup signature depends on this number.
+     *  - WIRE (ISO8601 UTC `string`): what actually leaves the device. {@link buildEventsRequest}
+     *    converts the number on its way out, because the server declares `ts: str | None` and
+     *    pydantic v2 does NOT coerce a number into it — a numeric `ts` made the server answer HTTP
+     *    200 with `{written: 0, skipped: N, errors: [{field: "ts", reason: "validation_error"}]}`,
+     *    silently discarding EVERY `app_event` through 0.13.0.
+     *
+     * A caller-set ISO string is passed through as-is. Never a wall-clock the server trusts (it
+     * derives its own receive time); an old/strict server that does not model it ignores the field.
+     */
+    ts?: number | string;
 };
 /** Where to POST. Derived from `WireOnboardingConfig` (`serverUrl` + `apiKey`). */
 type ClientEventTarget = {
@@ -190,13 +199,238 @@ declare const reportClientEvent: (target: ClientEventTarget | undefined, event:
  * `/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.
  */
 declare const reportClientEventsAwait: (target: ClientEventTarget | undefined, events: ClientEvent[]) => Promise<boolean>;
 /** Convenience single-event wrapper around {@link reportClientEventsAwait}. */
 declare const reportClientEventAwait: (target: ClientEventTarget | undefined, event: ClientEvent) => Promise<boolean>;
 
+/**
+ * permissionCopy - the rationale a priming screen shows, and the kit-quality defaults behind it.
+ *
+ * Same job the `copy` prop does for the loaders: the kit ships English that is good enough to
+ * ship as-is, and a host overrides any single line without having to restate the rest.
+ *
+ * PURE, no React, no React Native - so the resolution is unit-testable and the same function can
+ * later resolve copy a server sent.
+ */
+
+/** Every string a permission screen can render. Both states (the ask and the blocked route). */
+type PermissionScreenCopy = {
+    /** Headline for the ask. */
+    title: string;
+    /** The rationale. The one thing that decides whether the primary gets tapped. */
+    message: string;
+    /** Primary button. Tapping it is the ONLY thing that can open the OS dialog. */
+    primaryLabel: string;
+    /** Secondary button. Advances the flow and does NOT spend the one native prompt. */
+    secondaryLabel: string;
+    /** Headline once the OS says the permission is permanently refused. */
+    blockedTitle: string;
+    /** Rationale for the blocked state, where the only remaining route is the settings app. */
+    blockedMessage: string;
+    /** Primary button on the blocked route. */
+    settingsLabel: string;
+    /** Primary button when there is nothing left to ask for (already granted, or no `request`). */
+    continueLabel: string;
+};
+/**
+ * The notification default. Written to the same bar as the kit's other shipped copy: it names the
+ * benefit in the user's terms and promises a limit, because "we would like to send you
+ * notifications" is exactly the sentence that spends the one iOS prompt on a no.
+ */
+declare const NOTIFICATIONS_PERMISSION_COPY: PermissionScreenCopy;
+/** The fallback for any permission the kit ships no copy for. A host overriding `copy` replaces it. */
+declare const GENERIC_PERMISSION_COPY: PermissionScreenCopy;
+/** The kit's shipped defaults, by permission. Anything not listed falls back to the generic set. */
+declare const DEFAULT_PERMISSION_COPY: Record<string, PermissionScreenCopy>;
+/**
+ * The kit default for `permission`, with the host's overrides applied on top.
+ *
+ * An override key whose value is `undefined` is IGNORED rather than allowed to blank the default:
+ * hosts build this object from their i18n layer, and a missing translation resolving to `undefined`
+ * would otherwise render an empty button.
+ */
+declare const resolvePermissionCopy: (permission: WirePermissionKind, overrides?: Partial<PermissionScreenCopy>) => PermissionScreenCopy;
+
+/**
+ * Public types for the injectable mid-flow permission screens.
+ *
+ * THE ONE RULE THIS WHOLE MODULE EXISTS TO ENFORCE: the OS permission dialog is reached from the
+ * user's explicit primary tap and from nowhere else. iOS grants an app exactly ONE native
+ * notification prompt for its entire lifetime, so firing it on mount (the shape almost every app
+ * ships) spends the single ask on a user who has not been told why. A priming screen spends a
+ * cheap in-app screen first and only forwards the ones who said yes.
+ *
+ * DEPENDENCY-FREE, the RevenueCat-bridge idiom: the kit imports NO native permission module. The
+ * host passes `request` (and optionally `getStatus` / `openSettings`) in, exactly the way it hands
+ * the RevenueCat bridge real `CustomerInfo` objects. Wiring `expo-notifications` is five lines in
+ * the host and zero dependencies here.
+ *
+ * A PERMISSION SCREEN IS NOT A QUESTION. It mints no `key` and no `slot_id`, sends nothing to the
+ * backend, and never enters the thread, so `deriveAnswers` / `readProgress` and every completion
+ * semantic are byte-identical whether or not one is configured. Completion NEVER blocks on a grant.
+ */
+
+/**
+ * Which OS permission a screen primes. `notifications` is the one the kit ships copy for; any other
+ * string is accepted (the host supplies the copy) so a host can prime tracking, health or location
+ * without waiting on a kit release.
+ */
+type WirePermissionKind = "notifications" | (string & {});
+/**
+ * What the host's `request` / `getStatus` answers.
+ *  - `granted`: the user allowed it.
+ *  - `denied`: not allowed right now, but the OS would still show a dialog if asked again
+ *    (Android, or an iOS provisional state).
+ *  - `blocked`: permanently refused. Asking again shows NOTHING, so the only route left is Settings.
+ */
+type WirePermissionStatus = "granted" | "denied" | "blocked";
+/** How a permission screen ENDED. `skipped` is the secondary tap, which never burns the OS prompt. */
+type WirePermissionOutcome = WirePermissionStatus | "skipped";
+/**
+ * The moments a permission screen reports. One stage, one canonical event name (see
+ * `permissionEventName`), so the funnel reads the same across every tenant.
+ *  - `shown`: the primer screen became visible. The denominator.
+ *  - `accepted`: the user tapped the primary, so the OS dialog is ABOUT to open. The gap between
+ *    `shown` and `accepted` is the only number that tells a host whether its rationale copy works.
+ *  - `granted` / `denied`: what the OS answered (a `blocked` answer reports as `denied` and carries
+ *    `status: "blocked"`, so the two are one funnel step and still distinguishable).
+ *  - `skipped`: the secondary tap. The prompt was NOT spent.
+ *  - `settings`: the user was redirected to the OS settings page (the `blocked` route).
+ */
+type PermissionStage = "shown" | "accepted" | "granted" | "denied" | "skipped" | "settings";
+/**
+ * WHERE a screen sits in the server-driven stream. The flow length is decided by the backend and
+ * varies per user, so every position is resolved against the card the flow is ABOUT to render:
+ *  - `"start"`: before the first card.
+ *  - `{ afterCard: n }`: after `n` cards have been shown (`{ afterCard: 2 }` sits between card 2
+ *    and card 3). An `n` past the end of a shorter-than-expected stream degrades to `"beforeEnd"`
+ *    rather than silently never showing.
+ *  - `"beforeEnd"`: immediately before the terminal recap. The default.
+ */
+type PermissionPlacement = "start" | "beforeEnd" | {
+    afterCard: number;
+};
+/**
+ * One injectable permission screen.
+ *
+ * ```tsx
+ * import * as Notifications from "expo-notifications";
+ *
+ * <WireOnboarding
+ *   permissionScreens={[
+ *     {
+ *       permission: "notifications",
+ *       placement: "beforeEnd",
+ *       request: async () => {
+ *         const { status, canAskAgain } = await Notifications.requestPermissionsAsync();
+ *         return status === "granted" ? "granted" : canAskAgain ? "denied" : "blocked";
+ *       },
+ *     },
+ *   ]}
+ * />
+ * ```
+ */
+type PermissionScreenConfig = {
+    /** Which permission this screen primes. Drives the default copy and every event's `permission`. */
+    permission: WirePermissionKind;
+    /**
+     * Stable id for the once-only / resume record. Defaults to `<permission>:<index in the array>`,
+     * which is right until you reorder the array; set it explicitly if you configure two screens for
+     * the same permission or intend to reorder them between releases.
+     */
+    id?: string;
+    /** Where the screen sits in the stream. Default `"beforeEnd"`. */
+    placement?: PermissionPlacement;
+    /**
+     * THE ONLY FUNCTION THE KIT CALLS THAT CAN OPEN AN OS DIALOG, and it is called from the primary
+     * press handler alone. Never from mount, never from an effect, never from a status probe.
+     */
+    request: () => Promise<WirePermissionStatus>;
+    /**
+     * Optional NON-PROMPTING status read (`Notifications.getPermissionsAsync()`), used only to pick
+     * which primary action the screen offers: a `blocked` user gets "Open settings" instead of an
+     * "Enable" button that would open nothing, and an already-granted user gets a plain Continue.
+     * Leave it out and the screen simply always offers the ask.
+     */
+    getStatus?: () => Promise<WirePermissionStatus>;
+    /** Open the OS settings page (`Linking.openSettings()`). Only reachable on the `blocked` route. */
+    openSettings?: () => void | Promise<void>;
+    /** Rationale copy overrides. Anything left out keeps the kit default for this permission. */
+    copy?: Partial<PermissionScreenCopy>;
+    /**
+     * Name of a host illustration (the existing `illustrations` registry). Defaults to the
+     * permission name, so registering `illustrations={{ notifications: <MyBell/> }}` is enough. The
+     * kit ships a dependency-free default so the screen is never a blank box.
+     */
+    illustration?: string;
+    /**
+     * Fired once, with the outcome this screen produced. This is the seam for scheduling a local
+     * notification the moment a grant lands; the kit deliberately schedules nothing itself. It can
+     * never break the flow: a throw here is caught and the flow continues.
+     */
+    onResult?: (permission: WirePermissionKind, outcome: WirePermissionOutcome) => void;
+};
+
+/**
+ * permissionEvents - the canonical Wire names for a permission-priming funnel.
+ *
+ * Same job `purchaseEvents.ts` does for the subscription funnel and `analyticsEvent.ts` does for
+ * the onboarding funnel: every app was naming these itself (`push_permission`, `NOTIF_PROMPT`,
+ * `notifications_allowed`), so the same funnel read differently per tenant and no cross-app report
+ * was possible. These are the ONE set of names.
+ *
+ * They are `app_event` `question_key` values on the wire, exactly like `WIRE_PURCHASE_EVENTS`, so
+ * they are ALSO the exact strings a review / questionnaire firing trigger matches on. Never rename
+ * one: a rename silently unfires every trigger configured against the old string.
+ *
+ * PURE + dependency-free: no React, no React Native, no transport, no imports outside the type
+ * declarations - so an analytics-only bundle can carry the names without carrying a screen.
+ */
+
+declare const WIRE_PERMISSION_EVENTS: {
+    /** The priming screen became visible. The denominator for every rate below. */
+    readonly screenShown: "wire_permission_screen_shown";
+    /** The user tapped the primary, so the OS dialog is about to open. The rationale worked. */
+    readonly primerAccepted: "wire_permission_primer_accepted";
+    /** The OS granted it. */
+    readonly granted: "wire_permission_granted";
+    /** The OS refused it (a permanently blocked answer reports here too, with `status: "blocked"`). */
+    readonly denied: "wire_permission_denied";
+    /** The user took the secondary. The one native prompt was NOT spent. */
+    readonly skipped: "wire_permission_skipped";
+    /** A blocked user was redirected to the OS settings page. */
+    readonly settingsOpened: "wire_permission_settings_opened";
+};
+type WirePermissionEventName = (typeof WIRE_PERMISSION_EVENTS)[keyof typeof WIRE_PERMISSION_EVENTS];
+/** The canonical event name for a stage. Exhaustive over the union (a new stage is a compile error). */
+declare const permissionEventName: (stage: PermissionStage) => WirePermissionEventName;
+/**
+ * The small, non-PII props that ride a permission event. `permission` is always present so one
+ * funnel can be sliced per permission; `status` only appears when the OS actually answered, which
+ * is what keeps a `blocked` refusal distinguishable from a plain `denied` without a second event.
+ */
+declare const permissionEventProps: (permission: WirePermissionKind, status?: WirePermissionStatus) => Record<string, string>;
+/**
+ * Normalize whatever the host's `request` / `getStatus` actually returned.
+ *
+ * A native permission bridge is the host's code, and hosts return `"undetermined"`, `true`, or a
+ * whole Expo response object. Anything the kit does not recognise is treated as `denied`: it is the
+ * only reading that cannot invent a grant, and every outcome continues the flow anyway.
+ */
+declare const normalizePermissionStatus: (value: unknown) => WirePermissionStatus;
+
 /** Transport + tenant config for the managed Wire AI onboarding backend (A2A). */
 type WireOnboardingConfig = {
     /** Tenant API key (resolves the app server-side). */
@@ -254,6 +488,10 @@ type OnboardingResult = {
  *  - `fallback`: retries are exhausted; the kit degraded to the static `fallbackFlow`
  *               (or handed off to `onError`). This is the client-side mirror of the
  *               backend's `llm_fallback` reliability event.
+ *  - `permission`: an injected permission screen moved (`shown` / `accepted` / `granted` /
+ *               `denied` / `skipped` / `settings`). Carries NO funnel weight: a permission screen
+ *               is not a question, so it never appears in `answers` and never gates completion.
+ *               `toAnalyticsEvent` maps it to the canonical `wire_permission_*` name.
  */
 type OnboardingEvent = {
     type: "started";
@@ -275,6 +513,12 @@ type OnboardingEvent = {
 } | {
     type: "fallback";
     reason: "backend" | "timeout";
+} | {
+    type: "permission";
+    permission: WirePermissionKind;
+    stage: PermissionStage;
+    /** What the OS actually answered, when it answered. Absent on `shown` / `accepted`. */
+    status?: WirePermissionStatus;
 };
 /**
  * Copy overrides for the kit's built-in (English) strings, so a host can localize
@@ -319,6 +563,48 @@ type WireOnboardingProps = {
     icons?: Record<string, React.ReactNode>;
     /** Per-step validators keyed by base-question key, e.g. `{ username: checkUsername }`. */
     validators?: Record<string, StepValidator>;
+    /**
+     * PERMISSION SCREENS injected into the server-driven flow at a position you choose.
+     *
+     * The screen explains why the app wants the permission and asks the OS **only** on the primary
+     * tap. That priming pattern is not decoration: iOS grants an app exactly ONE native notification
+     * prompt for its whole lifetime, and firing it on mount spends it on a user who was told nothing.
+     * "Maybe later" advances the flow with the prompt still unspent.
+     *
+     * ```tsx
+     * import * as Notifications from "expo-notifications";
+     *
+     * <WireOnboarding
+     *   permissionScreens={[
+     *     {
+     *       permission: "notifications",
+     *       placement: "beforeEnd",
+     *       request: async () => {
+     *         const { status, canAskAgain } = await Notifications.requestPermissionsAsync();
+     *         return status === "granted" ? "granted" : canAskAgain ? "denied" : "blocked";
+     *       },
+     *       getStatus: async () => {
+     *         const { status, canAskAgain } = await Notifications.getPermissionsAsync();
+     *         return status === "granted" ? "granted" : canAskAgain ? "denied" : "blocked";
+     *       },
+     *       onResult: (_p, outcome) => { if (outcome === "granted") scheduleFirstReminder(); },
+     *     },
+     *   ]}
+     * />
+     * ```
+     *
+     * The kit adds NO dependency for this: it imports no `expo-notifications`, no
+     * `react-native-permissions`, nothing native. You inject `request`, exactly the way you hand the
+     * RevenueCat bridge real RevenueCat objects.
+     *
+     * A permission screen is NOT a question. It sends nothing to the backend, never enters the
+     * thread, mints no `key` / `slot_id`, and never appears in `onComplete`'s `answers`. Completion
+     * never blocks on a grant: grant, deny, skip and blocked all continue the flow. Each screen is
+     * shown at most once per session, and with `storage` that survives an app kill (a resumed session
+     * does not re-ask). Analytics ride `onEvent` (`type: "permission"`) and the canonical
+     * `wire_permission_*` events, stamped with the same `device_key` as the rest of the funnel.
+     */
+    permissionScreens?: PermissionScreenConfig[];
     /** Fired once the flow reaches its terminal StatusCard. */
     onComplete: (result: OnboardingResult) => void;
     /**
@@ -472,6 +758,23 @@ type OnboardingProgress = {
     total: number;
     /** Base-question key for the CURRENT screen, when known (used to pick a validator). */
     key?: string;
+    /**
+     * STABLE per-slot identity for the CURRENT screen, when the backend sends one. Preferred over
+     * {@link key} for both the answer key and the validator lookup.
+     *
+     * WHY IT EXISTS: `key` is authored from the question's prompt text (the tenant flows slugify it and
+     * cut at 32 chars), so re-wording a question mints a NEW key — the answer a host reads as
+     * `answers.interests` silently becomes `answers.what_are_you_into_v2`, with no error anywhere. A
+     * slot is the question's identity independent of its wording.
+     *
+     * FULLY ADDITIVE, AND LIVE SINCE 2026-07-28 (server `47dae92`). The deployed server sends it on
+     * `progress` for every AI-GENERATED question, as `adaptive_<n>` 1-based over adaptive answers, and
+     * for a CONFIGURED question only when the tenant set one. Where the tenant set none the field is
+     * simply absent. Every fallback is PER-CARD, so a thread that mixes slotted and unslotted cards
+     * (the real shape during a rollout) keys each one correctly, and a backend or tenant that never
+     * sends it produces byte-identical behaviour to 0.12.2.
+     */
+    slot_id?: string;
     /** Whether the CURRENT screen may be skipped (backend-marked; default false → no Skip shown). */
     skippable?: boolean;
 };
@@ -507,7 +810,12 @@ declare const WIRE_ONBOARDING_EVENTS: {
 };
 type WireOnboardingEventName = (typeof WIRE_ONBOARDING_EVENTS)[keyof typeof WIRE_ONBOARDING_EVENTS];
 type AnalyticsEvent = {
-    name: WireOnboardingEventName;
+    /**
+     * A permission screen maps to its own canonical `wire_permission_*` name rather than to an
+     * onboarding one: it is a distinct funnel (see `permissions/permissionEvents.ts`), and folding it
+     * into `wire_onboarding_turn` would make every permission rate unreadable.
+     */
+    name: WireOnboardingEventName | WirePermissionEventName;
     params?: Record<string, unknown>;
 };
 /**
@@ -638,6 +946,10 @@ type EventQueue = {
     /** Current pending (in-memory) count. */
     size(): number;
 };
+/** Test-only: forget every claimed queue key. A real RELAUNCH is a new process, so a test that
+ *  simulates one in-process must call this or its second queue reads as a concurrent sibling.
+ *  Exported from `@wireai/activation/analytics`, matching `resetAutoDeviceKeys` / `resetCurrentSessionId`. */
+declare const resetEventQueueKeys: () => void;
 /**
  * Create an offline-first event queue. Loads any persisted backlog on creation so a
  * killed-and-relaunched app resumes where it left off. Returns the {@link EventQueue} surface.
@@ -705,8 +1017,6 @@ interface ResolvedUserContext {
     /** The `user_context` bucket (device_key, app_version, user_email[+ _hashed], custom.*). */
     userContext?: Record<string, string | number | boolean>;
 }
-/** Reserved `user_context` keys the kit itself writes; host `extra` is namespaced away from these. */
-declare const RESERVED_USER_CONTEXT_KEYS: readonly ["device_key", "app_version", "app_build", "network_type", "session_count", "returning", "platform", "user_email", "user_email_hashed"];
 /** The prefix applied to every host `extra` key so it can never collide with a reserved key. */
 declare const EXTRA_KEY_PREFIX: "custom.";
 /** A finite scalar the wire accepts. Non-finite numbers (NaN/Infinity) are NOT scalars here. */
@@ -831,17 +1141,127 @@ 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.
+ */
+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).
  */
-declare const identifyOnboarding: (opts: IdentifyOnboardingOptions) => Promise<boolean>;
+declare const identifyOnboarding: (opts: IdentifyOnboardingOptions) => Promise<IdentifyOnboardingBinding>;
+
+/**
+ * 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.
+ */
+type IdentitySpace = "onboarding-session" | "app-session" | "device";
+/** Where the value came from: the host handed it over, or the kit minted it. */
+type IdentitySource = "host" | "auto";
+/** An id plus everything a consumer needs to decide whether it may use it. */
+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. */
+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;
+};
+/**
+ * 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.
+ */
+declare const resolveIdentity: (input: ResolveIdentityInput) => IdentityRecord | undefined;
+/**
+ * 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?"
+ */
+declare const hostIdentity: (space: IdentitySpace, scope?: string) => string | undefined;
+/** Test-only: forget every recorded host identity so a unit test starts from a clean registry. */
+declare const resetIdentityProvenance: () => void;
 
 /**
  * deviceId — mint a stable, NON-PII, per-install device id the kit owns when the host supplies
@@ -862,6 +1282,7 @@ declare const identifyOnboarding: (opts: IdentifyOnboardingOptions) => Promise<b
  * A host that wants its OWN device id still wins: pass `WireUserContext.deviceKey` and the kit uses
  * that verbatim and never mints/persists an auto id.
  */
+
 /** Prefix so an auto-minted id is visibly the kit's (distinguishable from a host-supplied `deviceKey`). */
 declare const AUTO_DEVICE_ID_PREFIX = "wdev_";
 /** The storage key the façade persists the auto-minted id under (namespaced per `appId`). */
@@ -917,6 +1338,22 @@ declare const resolveAutoDeviceKey: (opts?: ResolveAutoDeviceKeyOptions) => stri
  * with no `storage` it resolves immediately (there is nothing to hydrate from).
  */
 declare const hydrateAutoDeviceKey: (opts?: ResolveAutoDeviceKeyOptions) => Promise<string>;
+/**
+ * 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.
+ */
+declare const hydrateDeviceIdentity: (opts?: ResolveAutoDeviceKeyOptions) => Promise<IdentityRecord | undefined>;
 /** Test-only: forget every auto id + hydration flag so a unit test starts from a clean registry. */
 declare const resetAutoDeviceKeys: () => void;
 
@@ -948,4 +1385,4 @@ declare const resetCurrentSessionId: () => void;
  */
 declare const ensureCurrentSessionId: () => string;
 
-export { hydrateAutoDeviceKey as $, AUTO_DEVICE_ID_PREFIX as A, resolveAutoDeviceKey as B, type ClearUserContextOptions as C, type DeviceKeyStorage as D, type EventQueueOptions as E, setCurrentSessionId as F, toAnalyticsEvent as G, type WireOnboardingProps as H, type WireOnboardingConfig as I, type OnboardingEvent as J, type OnboardingCopy as K, type DeviceContext as L, type DeviceFormFactor as M, EXTRA_KEY_PREFIX as N, type OnboardingResult as O, type IdentifyOnboardingOptions as P, type OnboardingProgress as Q, type ResolveAutoDeviceKeyOptions as R, type StepValidator as S, RESERVED_USER_CONTEXT_KEYS as T, type ResolveUserContextOptions as U, type ResolvedUserContext as V, type WireUserContext as W, USER_ID_MAX_LENGTH as X, activationJoinContext as Y, collectDeviceContext as Z, hashEmailFnv1a as _, type AnalyticsEvent as a, identifyOnboarding as a0, isWireScalar as a1, mintDeviceId as a2, namespaceExtra as a3, resolveUserContext as a4, sanitizeUserId as a5, type ClientEvent as b, type ClientEventTarget as c, type ClientEventType as d, type ContextEnvelope as e, type ContextEnvelopeInput as f, type EnvelopeSource as g, type EventQueue as h, WIRE_ONBOARDING_EVENTS as i, type WireOnboardingEventName as j, analyticsUserIdStorageKey as k, buildContextEnvelope as l, clearPiiFromContext as m, clearUserContext as n, createEventQueue as o, deviceIdStorageKey as p, ensureCurrentSessionId as q, getCurrentSessionId as r, looksLikeEmail as s, makeSessionId as t, reportClientEvent as u, reportClientEventAwait as v, reportClientEvents as w, reportClientEventsAwait as x, resetAutoDeviceKeys as y, resetCurrentSessionId as z };
+export { type IdentifyOnboardingOptions as $, AUTO_DEVICE_ID_PREFIX as A, resetEventQueueKeys as B, type ClearUserContextOptions as C, type DeviceKeyStorage as D, type EventQueueOptions as E, resolveAutoDeviceKey as F, setCurrentSessionId as G, toAnalyticsEvent as H, type WireOnboardingProps as I, type WireOnboardingConfig as J, type WirePermissionStatus as K, type WirePermissionOutcome as L, type OnboardingEvent as M, type OnboardingCopy as N, type OnboardingResult as O, type PermissionStage as P, type DeviceContext as Q, type ResolveAutoDeviceKeyOptions as R, type StepValidator as S, type PermissionScreenConfig as T, type PermissionPlacement as U, DEFAULT_PERMISSION_COPY as V, type WireUserContext as W, type DeviceFormFactor as X, EXTRA_KEY_PREFIX as Y, GENERIC_PERMISSION_COPY as Z, type IdentifyOnboardingBinding as _, type AnalyticsEvent as a, type IdentityRecord as a0, type IdentitySource as a1, type IdentitySpace as a2, NOTIFICATIONS_PERMISSION_COPY as a3, type OnboardingProgress as a4, type PermissionScreenCopy as a5, type ResolveUserContextOptions as a6, type ResolvedUserContext as a7, USER_ID_MAX_LENGTH as a8, WIRE_PERMISSION_EVENTS as a9, type WirePermissionEventName as aa, type WirePermissionKind as ab, activationJoinContext as ac, collectDeviceContext as ad, hashEmailFnv1a as ae, hostIdentity as af, hydrateAutoDeviceKey as ag, hydrateDeviceIdentity as ah, identifyOnboarding as ai, isWireScalar as aj, mintDeviceId as ak, namespaceExtra as al, normalizePermissionStatus as am, permissionEventName as an, permissionEventProps as ao, resetIdentityProvenance as ap, resolveIdentity as aq, resolvePermissionCopy as ar, resolveUserContext as as, sanitizeUserId as at, type ClientEvent as b, type ClientEventTarget as c, type ClientEventType as d, type ContextEnvelope as e, type ContextEnvelopeInput as f, type EnvelopeSource as g, type EventQueue as h, WIRE_ONBOARDING_EVENTS as i, type WireOnboardingEventName as j, analyticsUserIdStorageKey as k, buildContextEnvelope as l, clearPiiFromContext as m, clearUserContext as n, createEventQueue as o, deviceIdStorageKey as p, ensureCurrentSessionId as q, getCurrentSessionId as r, looksLikeEmail as s, makeSessionId as t, reportClientEvent as u, reportClientEventAwait as v, reportClientEvents as w, reportClientEventsAwait as x, resetAutoDeviceKeys as y, resetCurrentSessionId as z };