@layers/amba-react-native 4.2.2 → 4.3.0

package/dist/index.js

@@ -62,6 +62,20 @@ var AsyncStoragePersistence = class {
 		if (v !== null) this.memoryCache.set(fullKey, v);
 		return v;
 	}
+	/**
+	* Read `key` from storage again, past the in-memory copy, and keep what
+	* it holds now. For a record whose first read came back incomplete (see
+	* `IdentityStore.recordStillUnreadable`).
+	*/
+	async reread(key) {
+		const fullKey = `${this.prefix}:${key}`;
+		const storage = await getStorage();
+		if (!storage) return this.memoryCache.get(fullKey) ?? null;
+		const v = await storage.getItem(fullKey);
+		if (v !== null) this.memoryCache.set(fullKey, v);
+		else this.memoryCache.delete(fullKey);
+		return v;
+	}
 	async write(key, value) {
 		const fullKey = `${this.prefix}:${key}`;
 		const storage = await getStorage();
@@ -613,11 +627,42 @@ var IdentityStore = class IdentityStore {
 	installId;
 	/** Whether the stored record carries `installId`. */
 	installIdStored;
-	constructor(persistence, seed, vault, plaintext, vaultUnreadable, seq) {
+	/** See `IdentitySnapshot.signInRequired`. */
+	signInRequired;
+	/**
+	* Advanced by every committed write that installs or ends a session (a
+	* sign-in, a sign-out, an ended session). A refresh or a link keeps it.
+	*/
+	generation = 0;
+	/** Set by `dispose`: the store commits and persists nothing after it. */
+	disposed = false;
+	/**
+	* Set while the record's credential part could not be read (see
+	* `PersistedIdentity.credentials_unreadable`). Writes wait for a read
+	* that succeeds, so a session this launch never loaded is not replaced.
+	*/
+	recordUnreadable;
+	/**
+	* Set while the anonymous id is a stand-in for one the unreadable
+	* credential part holds. It is never persisted.
+	*/
+	temporaryAnonymousId;
+	/** See `onStoredSessionLoaded`. */
+	storedSessionLoaded = null;
+	/** See `onAnonymousIdKnown`. */
+	anonymousIdKnown = null;
+	/** The refresh token the store held once created (see `continuesLaunchSession`). */
+	launchRefreshToken = null;
+	/** Sign-ins committed since the store was created. */
+	signInsSinceLaunch = 0;
+	constructor(persistence, seed, vault, plaintext, vaultUnreadable, seq, recordUnreadable, temporaryAnonymousId) {
 		this.persistence = persistence;
 		this.vault = vault;
 		this.plaintext = plaintext;
 		this.vaultUnreadable = vaultUnreadable;
+		this.recordUnreadable = recordUnreadable;
+		this.temporaryAnonymousId = temporaryAnonymousId;
+		this.signInRequired = seed.sign_in_required;
 		this.seq = seq;
 		this.installId = seed.install_id ?? uuidv4();
 		this.installIdStored = seed.install_id !== null;
@@ -653,21 +698,17 @@ var IdentityStore = class IdentityStore {
 		assertSecureRandomAvailable();
 		const raw = await persistence.read(IDENTITY_KEY);
 		let recordPresent = false;
+		let recordUnreadable = false;
+		let temporaryAnonymousId = false;
 		let seed;
 		if (raw) try {
 			const parsed = JSON.parse(raw);
-			seed = {
-				anonymous_id: parsed.anonymous_id ?? uuidv4(),
-				app_user_id: parsed.app_user_id ?? null,
-				session_token: parsed.session_token ?? null,
-				refresh_token: parsed.refresh_token ?? null,
-				expires_at: parsed.expires_at ?? null,
-				anonymous_session: typeof parsed.anonymous_session === "boolean" ? parsed.anonymous_session : null,
-				write_seq: seqOf(parsed.write_seq) ?? 0,
-				vault_seq: parsed.vault_seq === void 0 ? 0 : seqOf(parsed.vault_seq),
-				install_id: typeof parsed.install_id === "string" ? parsed.install_id : null
-			};
+			seed = seedFrom(parsed);
 			recordPresent = typeof parsed.anonymous_id === "string";
+			if (parsed.credentials_unreadable === true) {
+				recordUnreadable = true;
+				temporaryAnonymousId = !recordPresent;
+			}
 		} catch {
 			seed = freshSeed();
 		}
@@ -682,7 +723,8 @@ var IdentityStore = class IdentityStore {
 		} : null;
 		let vaultReadable = true;
 		let seq = seed.write_seq;
-		if (vault) {
+		if (vault && recordUnreadable) vaultReadable = false;
+		else if (vault) {
 			let fromVault = null;
 			try {
 				fromVault = await vault.read();
@@ -701,17 +743,10 @@ var IdentityStore = class IdentityStore {
 				seed.vault_seq = null;
 			}
 		}
-		if (vaultReadable && seed.session_token === null && seed.refresh_token === null) {
-			if (seed.app_user_id !== null && seed.anonymous_session === false) seed.anonymous_id = uuidv4();
-			seed.app_user_id = null;
-			seed.anonymous_session = null;
-		}
-		if (isExpired(seed.expires_at)) {
-			seed.session_token = null;
-			seed.expires_at = null;
-		}
-		const store = new IdentityStore(persistence, seed, vault, plaintext, !vaultReadable, seq);
+		settleSeed(seed, vaultReadable && !recordUnreadable);
+		const store = new IdentityStore(persistence, seed, vault, plaintext, !vaultReadable, seq, recordUnreadable, temporaryAnonymousId);
 		await store.flush({ hydrating: true });
+		store.launchRefreshToken = store.refreshToken;
 		return store;
 	}
 	snapshot() {
@@ -721,9 +756,184 @@ var IdentityStore = class IdentityStore {
 			sessionToken: this.sessionToken,
 			refreshToken: this.refreshToken,
 			expiresAt: this.expiresAt,
-			anonymousSession: this.anonymousSession
+			anonymousSession: this.anonymousSession,
+			signInRequired: this.signInRequired
 		};
 	}
+	/** The current generation (see `CommitFence`). */
+	getGeneration() {
+		return this.generation;
+	}
+	/**
+	* Whether the store still holds the session it was created with, renewed
+	* or ended since but never replaced by a sign-in: it was created holding
+	* `refreshToken`, and no sign-in has committed since.
+	*/
+	continuesLaunchSession(refreshToken) {
+		return this.launchRefreshToken === refreshToken && this.signInsSinceLaunch === 0;
+	}
+	/** See `IdentitySnapshot.signInRequired`. */
+	isSignInRequired() {
+		return this.signInRequired;
+	}
+	/**
+	* Detach the store (the SDK was configured again). Nothing commits or
+	* persists after this; the promise settles once the writes already under
+	* way have landed.
+	*/
+	dispose() {
+		this.disposed = true;
+		return this.flushChain;
+	}
+	/** Undo `dispose` (a `configure()` that failed before it replaced this store). */
+	reattach() {
+		this.disposed = false;
+	}
+	/** Whether a write under `fence` may commit now. */
+	mayCommit(fence) {
+		if (this.disposed) return false;
+		return fence.ifGeneration === void 0 || fence.ifGeneration === this.generation;
+	}
+	/** Commit bookkeeping: advance the generation unless the fence keeps it. */
+	committed(fence) {
+		if (fence.advance !== false) this.generation += 1;
+		return this.generation;
+	}
+	/**
+	* Called when a stored session that couldn't be read at launch (a locked
+	* vault or credential record) is loaded after it, so the SDK can tell its
+	* subscribers. A session loaded while the store is created is not
+	* reported.
+	*/
+	onStoredSessionLoaded(listener) {
+		this.storedSessionLoaded = listener;
+	}
+	/**
+	* Called when the stand-in anonymous id gives way to the device's own (see
+	* `temporaryAnonymousId`): a later read found it, or a sign-in gave one.
+	* A sign-out that rotates the id is not reported: it starts over.
+	*/
+	onAnonymousIdKnown(listener) {
+		this.anonymousIdKnown = listener;
+	}
+	/** Whether the anonymous id is a stand-in (see `temporaryAnonymousId`). */
+	hasStandInAnonymousId() {
+		return this.temporaryAnonymousId;
+	}
+	/** The stand-in gives way to a known anonymous id (see `onAnonymousIdKnown`). */
+	anonymousIdNowKnown() {
+		if (!this.temporaryAnonymousId) return;
+		this.temporaryAnonymousId = false;
+		if (!this.disposed) this.anonymousIdKnown?.();
+	}
+	/** Report a session a late read loaded (see `onStoredSessionLoaded`). */
+	reportStoredSession() {
+		if (this.signInsSinceLaunch === 0 && this.launchRefreshToken === null) this.launchRefreshToken = this.refreshToken;
+		if (this.disposed) return;
+		if (this.sessionToken === null && this.refreshToken === null) return;
+		this.storedSessionLoaded?.();
+	}
+	/**
+	* Whether the record's credential part still can't be read (see
+	* `PersistedIdentity.credentials_unreadable`). When the launch read
+	* failed, the record is read again first. A session it holds is loaded
+	* when nothing has replaced the launch state since; the stored anonymous
+	* id replaces the stand-in either way.
+	*/
+	async recordStillUnreadable() {
+		if (!this.recordUnreadable) return false;
+		let parsed = null;
+		try {
+			const raw = await this.persistence.reread(IDENTITY_KEY);
+			parsed = raw ? JSON.parse(raw) : null;
+		} catch {
+			return true;
+		}
+		if (!this.recordUnreadable) return false;
+		if (parsed?.credentials_unreadable === true) return true;
+		this.recordUnreadable = false;
+		const storedAnonymousId = parsed && typeof parsed.anonymous_id === "string" ? parsed.anonymous_id : null;
+		const untouched = this.generation === 0 && this.sessionToken === null && this.refreshToken === null;
+		if (parsed && storedAnonymousId !== null && untouched) {
+			if (!this.vault) {
+				const stored$1 = seedFrom(parsed);
+				settleSeed(stored$1, true);
+				this.anonymousId = stored$1.anonymous_id;
+				this.appUserId = stored$1.app_user_id;
+				this.sessionToken = stored$1.session_token;
+				this.refreshToken = stored$1.refresh_token;
+				this.expiresAt = stored$1.expires_at;
+				this.anonymousSession = stored$1.anonymous_session;
+				this.signInRequired = stored$1.sign_in_required;
+				this.seq = Math.max(this.seq, stored$1.write_seq);
+				this.reportStoredSession();
+				this.anonymousIdNowKnown();
+				return false;
+			}
+			const stored = seedFrom(parsed);
+			this.anonymousId = stored.anonymous_id;
+			const wasStandIn = this.temporaryAnonymousId;
+			this.temporaryAnonymousId = false;
+			this.appUserId = stored.app_user_id;
+			this.anonymousSession = stored.anonymous_session;
+			this.signInRequired = stored.sign_in_required;
+			this.recordSeq = stored.write_seq;
+			this.vaultSeq = stored.vault_seq;
+			this.seq = Math.max(this.seq, stored.write_seq);
+			await this.vaultStillUnreadable();
+			if (this.sessionToken === null && this.refreshToken === null && (stored.session_token !== null || stored.refresh_token !== null)) {
+				this.plaintext = {
+					appUserId: stored.app_user_id,
+					slice: {
+						session_token: stored.session_token,
+						refresh_token: stored.refresh_token,
+						expires_at: stored.expires_at
+					}
+				};
+				const expired = isExpired(stored.expires_at);
+				this.sessionToken = expired ? null : stored.session_token;
+				this.refreshToken = stored.refresh_token;
+				this.expiresAt = expired ? null : stored.expires_at;
+				this.reportStoredSession();
+			}
+			if (!this.vaultUnreadable && this.sessionToken === null && this.refreshToken === null) {
+				if (this.appUserId !== null && this.anonymousSession === false) this.anonymousId = uuidv4();
+				this.appUserId = null;
+				this.anonymousSession = null;
+			}
+			if (wasStandIn && !this.disposed) this.anonymousIdKnown?.();
+			return false;
+		}
+		if (this.temporaryAnonymousId && storedAnonymousId !== null) this.anonymousId = storedAnonymousId;
+		this.anonymousIdNowKnown();
+		return false;
+	}
+	/**
+	* Whether the stored session can't be read right now: the record's
+	* credential part (see `recordStillUnreadable`) or the vault (see
+	* `vaultStillUnreadable`). The record is read first: it binds the entry.
+	*/
+	async credentialsStillUnreadable() {
+		if (await this.recordStillUnreadable()) return true;
+		return this.vaultStillUnreadable();
+	}
+	/**
+	* Whether the stored credentials were unreadable at the last attempt. A
+	* call that needs a session reports `SECURE_STORE_UNAVAILABLE` then.
+	*/
+	credentialsUnknown() {
+		return this.recordUnreadable || this.vaultUnreadable;
+	}
+	/**
+	* Whether the anonymous id is still a stand-in after the record is read
+	* again (see `temporaryAnonymousId`). Anything sent under it would belong
+	* to nobody.
+	*/
+	async anonymousIdStillUnknown() {
+		if (!this.temporaryAnonymousId) return false;
+		await this.recordStillUnreadable();
+		return this.temporaryAnonymousId;
+	}
 	/**
 	* Whether the vault still can't be read. When the launch read failed, the
 	* vault is read again first, and a session it holds for this install is
@@ -732,6 +942,7 @@ var IdentityStore = class IdentityStore {
 	*/
 	async vaultStillUnreadable() {
 		if (!this.vault || !this.vaultUnreadable) return false;
+		if (this.recordUnreadable) return true;
 		let stored;
 		try {
 			stored = await this.vault.read();
@@ -740,7 +951,10 @@ var IdentityStore = class IdentityStore {
 		}
 		this.vaultUnreadable = false;
 		this.noteStoredSeq(stored);
-		if (this.sessionToken === null && this.refreshToken === null) this.adoptStored(stored);
+		if (this.sessionToken === null && this.refreshToken === null) {
+			this.adoptStored(stored);
+			this.reportStoredSession();
+		}
 		return false;
 	}
 	/** Keep the next sequence number above an entry read from the vault. */
@@ -777,30 +991,51 @@ var IdentityStore = class IdentityStore {
 	/**
 	* Store a session. `anonymous` records whether it is a purely anonymous
 	* one (true only for `/v1/client/auth/anonymous`); omit it to keep the
-	* current value (a token refresh of the same session).
+	* current value (a token refresh of the same session). A stored session
+	* ends a pending `signInRequired`.
+	*
+	* Resolves the generation the write committed at, or null when the fence
+	* refused it (nothing changed).
 	*/
-	async setSession(args) {
+	async setSession(args, fence = {}) {
+		if (!this.mayCommit(fence)) return null;
 		this.appUserId = args.appUserId;
 		this.sessionToken = args.sessionToken;
 		this.refreshToken = args.refreshToken;
 		this.expiresAt = args.expiresAt;
 		if (args.anonymous !== void 0) this.anonymousSession = args.anonymous;
+		this.signInRequired = false;
+		if (fence.advance !== false) this.signInsSinceLaunch += 1;
+		const generation = this.committed(fence);
 		await this.flush();
+		return generation;
 	}
-	/** The current session gained an identity (a link). */
-	async markIdentified() {
-		if (this.anonymousSession === false) return;
+	/**
+	* The current session gained an identity (a link). False when the fence
+	* refused the write.
+	*/
+	async markIdentified(fence = {}) {
+		if (!this.mayCommit(fence)) return false;
+		if (this.anonymousSession === false) return true;
 		this.anonymousSession = false;
 		await this.flush();
+		return true;
 	}
 	/**
 	* Adopt the anonymous id the server holds for this install's user: the id
 	* an anonymous sign-in answered with, or the fresh id a link gave the user.
+	* False when the fence refused the write.
 	*/
-	async setAnonymousId(anonymousId) {
-		if (anonymousId === this.anonymousId) return;
-		this.anonymousId = anonymousId;
-		await this.flush();
+	async setAnonymousId(anonymousId, fence = {}) {
+		if (!this.mayCommit(fence)) return false;
+		if (anonymousId !== this.anonymousId) {
+			this.anonymousId = anonymousId;
+			this.anonymousIdNowKnown();
+			await this.flush();
+			return true;
+		}
+		this.anonymousIdNowKnown();
+		return true;
 	}
 	/**
 	* End the session. The anonymous id is rotated when `rotateAnonymousId`
@@ -812,16 +1047,24 @@ var IdentityStore = class IdentityStore {
 	* anonymous sign-in).
 	*/
 	async clearSession(rotateAnonymousId, opts = {}) {
+		if (!this.mayCommit({ ifGeneration: opts.ifGeneration })) return false;
 		const hadSession = this.sessionToken !== null || this.refreshToken !== null;
+		const unreadSession = this.credentialsUnknown() && this.appUserId !== null;
+		if (opts.unlessSignedInSince !== void 0 && opts.unlessSignedInSince !== this.generation && hadSession) return false;
 		const identified = this.anonymousSession === false || this.anonymousSession === null && !opts.keepIdWhenKindUnknown;
-		const nextAnonymousId = rotateAnonymousId || hadSession && identified ? uuidv4() : this.anonymousId;
+		const rotate = rotateAnonymousId || (hadSession || unreadSession) && identified;
+		const nextAnonymousId = rotate ? uuidv4() : this.anonymousId;
+		if (rotate) this.temporaryAnonymousId = false;
 		this.appUserId = null;
 		this.sessionToken = null;
 		this.refreshToken = null;
 		this.expiresAt = null;
 		this.anonymousSession = null;
+		this.signInRequired = opts.signInRequired === true;
 		this.anonymousId = nextAnonymousId;
+		this.committed({});
 		await this.flush({ signingOut: true });
+		return true;
 	}
 	/**
 	* Persist the identity. `hydrating` marks the write that follows `create`:
@@ -831,11 +1074,13 @@ var IdentityStore = class IdentityStore {
 	* to a new anonymous id so the entry left behind no longer belongs to it.
 	*/
 	flush(opts) {
+		if (this.disposed) return Promise.resolve();
 		const run = this.flushChain.then(() => this.flushNow(opts));
 		this.flushChain = run.catch(() => void 0);
 		return run;
 	}
 	async flushNow(opts) {
+		if (await this.recordStillUnreadable() && this.generation === 0) return;
 		if (!this.vault) {
 			const seq$1 = ++this.seq;
 			const recordSeq$1 = opts?.hydrating ? this.recordSeq : seq$1;
@@ -846,9 +1091,11 @@ var IdentityStore = class IdentityStore {
 				refresh_token: this.refreshToken,
 				expires_at: this.expiresAt,
 				anonymous_session: this.anonymousSession,
+				sign_in_required: this.signInRequired,
 				write_seq: recordSeq$1,
 				vault_seq: null,
-				install_id: this.installId
+				install_id: this.installId,
+				...this.temporaryAnonymousId ? { anonymous_id_unknown: true } : {}
 			};
 			await this.persistence.write(IDENTITY_KEY, JSON.stringify(payload));
 			this.recordSeq = recordSeq$1;
@@ -927,9 +1174,11 @@ var IdentityStore = class IdentityStore {
 			refresh_token: keep?.refresh_token ?? null,
 			expires_at: keep?.expires_at ?? null,
 			anonymous_session: this.anonymousSession,
+			sign_in_required: this.signInRequired,
 			write_seq: recordSeq,
 			vault_seq: this.vaultSeq,
-			install_id: this.installId
+			install_id: this.installId,
+			...this.temporaryAnonymousId ? { anonymous_id_unknown: true } : {}
 		};
 	}
 };
@@ -941,11 +1190,47 @@ function freshSeed() {
 		refresh_token: null,
 		expires_at: null,
 		anonymous_session: null,
+		sign_in_required: false,
 		write_seq: 0,
 		vault_seq: null,
 		install_id: null
 	};
 }
+/** The identity a parsed record describes, with defaults for missing fields. */
+function seedFrom(parsed) {
+	return {
+		anonymous_id: parsed.anonymous_id ?? uuidv4(),
+		app_user_id: parsed.app_user_id ?? null,
+		session_token: parsed.session_token ?? null,
+		refresh_token: parsed.refresh_token ?? null,
+		expires_at: parsed.expires_at ?? null,
+		anonymous_session: typeof parsed.anonymous_session === "boolean" ? parsed.anonymous_session : null,
+		sign_in_required: parsed.sign_in_required === true,
+		write_seq: seqOf(parsed.write_seq) ?? 0,
+		vault_seq: parsed.vault_seq === void 0 ? 0 : seqOf(parsed.vault_seq),
+		install_id: typeof parsed.install_id === "string" ? parsed.install_id : null
+	};
+}
+/**
+* Settle a hydrated identity. With the credentials known (`readable`), a
+* user id with no token to act on is stale (memory storage after a
+* relaunch, a vault entry that was discarded): nobody is signed in, and the
+* session kind goes with it. A session that ended this way after it gained
+* an identity rotates the anonymous id, as `clearSession` would. An expired
+* session token is dropped; its refresh token stays so the session can be
+* renewed.
+*/
+function settleSeed(seed, readable) {
+	if (readable && seed.session_token === null && seed.refresh_token === null) {
+		if (seed.app_user_id !== null && seed.anonymous_session === false) seed.anonymous_id = uuidv4();
+		seed.app_user_id = null;
+		seed.anonymous_session = null;
+	}
+	if (isExpired(seed.expires_at)) {
+		seed.session_token = null;
+		seed.expires_at = null;
+	}
+}
 
 //#endregion
 //#region src/token-storage.ts
@@ -1638,14 +1923,18 @@ var EventBatchQueue = class {
 		if (this.events.length) await this.store.set(this.storageKey, JSON.stringify(this.events));
 		else await this.store.delete(this.storageKey);
 	}
-	enqueue(event, properties, telemetry) {
+	/**
+	* Queue an event. `timestamp` is when it happened, for an event that waited
+	* elsewhere before reaching the queue; it defaults to now.
+	*/
+	enqueue(event, properties, telemetry, timestamp) {
 		if (this.disposed) return Promise.reject(/* @__PURE__ */ new Error("Amba event queue disposed"));
 		const id = this.identity();
 		const item = {
 			event,
 			properties,
 			telemetry,
-			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+			timestamp: timestamp ?? (/* @__PURE__ */ new Date()).toISOString(),
 			idempotency_key: newIdempotencyKey(),
 			userId: id.sessionToken ? id.userId : null,
 			anonymousId: id.anonymousId
@@ -2780,7 +3069,9 @@ function delay(ms) {
 //#endregion
 //#region src/index.ts
 /** SDK semver — burned in at build time. Bump alongside package.json. */
-const SDK_VERSION = "4.2.2";
+const SDK_VERSION = "4.3.0";
+/** The most events held at once; the oldest goes first past it. */
+const MAX_HELD_EVENTS = 500;
 /**
 * Default host that serves deployed functions. `Amba.functions.invoke(name)`
 * targets `https://<projectId>.<DEFAULT_FUNCTIONS_HOST>/<name>` unless a
@@ -2797,6 +3088,23 @@ let state = null;
 * instead of disabling the now-active outbox.
 */
 let _offlineEnableToken = 0;
+/** The `configure()` running now, if any (see `liveState`). */
+let configuring = null;
+/** Serializes `configure()` calls, so each detaches the one before it. */
+let configureChain = Promise.resolve();
+/**
+* The state calls act on. While a `configure()` is running, waits for it,
+* so a sign-in, a link or a sign-out made meanwhile lands on the state it
+* installs (or on the earlier one, when it fails).
+*/
+async function liveState() {
+	while (configuring) await configuring.catch(() => void 0);
+	return getState();
+}
+/** Whether two states talk to the same project with the same stored identity. */
+function sameIdentityTarget(a, b) {
+	return a.projectId === b.projectId && a.clientKey === b.clientKey && a.baseUrl === b.baseUrl && a.persistence.prefix === b.persistence.prefix;
+}
 function getState() {
 	if (!state) throw new AmbaApiError("NOT_INITIALIZED", "@layers/amba-react-native: SDK not configured. Call Amba.configure({ projectId, clientKey }) at app start.");
 	return state;
@@ -2889,10 +3197,16 @@ function snapshotSession(user) {
 		expiresAt: ""
 	};
 }
-function notifyAuthSubscribers(session) {
+/**
+* Tell `onAuthStateChange` subscribers about an auth change of `state_`.
+* A state a later `configure()` replaced tells no one.
+*/
+function notifyAuthSubscribers(state_, session, reason) {
+	if (state_ !== state || state_.disposed) return;
 	if (session === null) experimentReporter.reset();
+	const event = { reason };
 	for (const cb of authSubscribers) try {
-		cb(session);
+		cb(session, event);
 	} catch (err) {
 		if (typeof console !== "undefined") console.error("[amba] onAuthStateChange callback threw", err);
 	}
@@ -2949,21 +3263,50 @@ function normalizeAuthResult(result) {
 		user: normalizeUserAuthProviders(result.user)
 	};
 }
-async function notifyFromAuthResult(result) {
-	notifyAuthSubscribers(snapshotSession(result.user));
+function notifyFromAuthResult(state_, result, reason) {
+	notifyAuthSubscribers(state_, snapshotSession(result.user), reason);
+}
+/** A call needs a session while the user must sign in again. */
+function signInRequiredError() {
+	return new AmbaApiError("SIGN_IN_REQUIRED", "the session ended and the user must sign in again; call a signIn* method, or Amba.auth.signInAnonymously() to start a new anonymous user");
+}
+function secureStoreUnavailableError() {
+	return new AmbaApiError("SECURE_STORE_UNAVAILABLE", "the stored session can't be read yet (the device may be locked); retry once it is unlocked");
+}
+function sessionChangedError(message) {
+	return new AmbaApiError("SESSION_CHANGED", message);
+}
+function isSessionChanged(err) {
+	return err instanceof AmbaApiError && err.code === "SESSION_CHANGED";
+}
+/**
+* The stored session token, for a call that needs one. Without a session
+* the call fails with `SIGN_IN_REQUIRED` while the user must sign in again,
+* and with `UNAUTHORIZED` otherwise.
+*/
+function requireSession(state_) {
+	const token = state_.identity.getSessionToken();
+	if (token) return token;
+	if (state_.identity.isSignInRequired()) throw signInRequiredError();
+	if (state_.identity.credentialsUnknown()) throw secureStoreUnavailableError();
+	throw new AmbaApiError("UNAUTHORIZED", "no active session — call signIn* first");
 }
 function expiresAtFromResult(result) {
 	if (result.expires_at && typeof result.expires_at === "string") return result.expires_at;
 	return new Date(Date.now() + 3600 * 1e3).toISOString();
 }
-async function persistAuthResult(state_, result, anonymous) {
-	await state_.identity.setSession({
+/**
+* Store an auth result under `fence`. Resolves the generation it committed
+* at, or null when the fence refused it.
+*/
+function persistAuthResult(state_, result, anonymous, fence = {}) {
+	return state_.identity.setSession({
 		appUserId: result.user.id,
 		sessionToken: result.session_token,
 		refreshToken: result.refresh_token,
 		expiresAt: expiresAtFromResult(result),
 		anonymous
-	});
+	}, fence);
 }
 function nonEmptyString(value) {
 	return typeof value === "string" && value.length > 0 ? value : null;
@@ -2975,14 +3318,31 @@ function nonEmptyString(value) {
 * request carried none). A link adopts the account's rotated anonymous id.
 * A refresh keeps the session's kind; every other sign-in records an
 * identified session.
+*
+* A sign-in the app asked for stores its session whatever happened
+* meanwhile: it is the newest thing the app asked for. The automatic
+* anonymous sign-in and a link pass a `fence` and fail with
+* `SESSION_CHANGED` (storing nothing) when the session changed while they
+* were in flight.
 */
-async function postAuth(state_, path, body) {
+async function postAuth(state_, path, body, fence = {}) {
 	const result = normalizeAuthResult((await state_.http.post(path, body)).data);
-	await persistAuthResult(state_, result, path === P.authAnonymous ? true : path === P.authRefresh ? void 0 : false);
+	const anonymous = path === P.authAnonymous ? true : path === P.authRefresh ? void 0 : false;
+	let target = state_;
+	let committedAt = await persistAuthResult(state_, result, anonymous, fence);
+	if (committedAt === null && fence.ifGeneration === void 0 && state_.disposed) {
+		const next = await liveState();
+		if (next === state_ ? !next.disposed : sameIdentityTarget(next, state_)) {
+			target = next;
+			committedAt = await persistAuthResult(next, result, anonymous);
+		}
+	}
+	if (committedAt === null) throw sessionChangedError("the session changed while this sign-in was in flight; the newer session stays");
+	state_ = target;
 	const adoptedAnonymousId = path === P.authAnonymous ? nonEmptyString(result.anonymous_id) ?? nonEmptyString(result.user?.anonymous_id) : path === P.authLink ? nonEmptyString(result.user?.anonymous_id) : null;
-	if (adoptedAnonymousId) await adoptAnonymousId(state_, adoptedAnonymousId);
+	if (adoptedAnonymousId) await adoptAnonymousId(state_, adoptedAnonymousId, committedAt);
 	state_.eventQueue?.flush();
-	await notifyFromAuthResult(result);
+	notifyFromAuthResult(state_, result, "signed_in");
 	return result;
 }
 /**
@@ -2991,16 +3351,86 @@ async function postAuth(state_, path, body) {
 * session; they are handed to the signed-in user first, so the id change
 * leaves them replayable.
 */
-async function adoptAnonymousId(state_, anonymousId) {
+async function adoptAnonymousId(state_, anonymousId, generation) {
 	const previous = state_.identity.getAnonymousId();
 	if (anonymousId === previous) return;
+	if (state_.identity.getGeneration() !== generation) return;
 	const appUserId = state_.identity.getAppUserId();
 	if (appUserId && state_.offlineEnabled) try {
 		await getOfflineQueue(state_).claimAnonymousOps(previous, appUserId);
 	} catch (err) {
 		if (typeof console !== "undefined") console.warn("[amba] could not reassign queued offline writes", err);
 	}
-	await state_.identity.setAnonymousId(anonymousId);
+	await state_.identity.setAnonymousId(anonymousId, { ifGeneration: generation });
+}
+/**
+* Hold an event `track()` got while the stored identity couldn't be read.
+* It keeps its call time and a copy of its properties; past
+* `MAX_HELD_EVENTS` the oldest is dropped.
+*/
+function holdEvent(state_, event, properties, options) {
+	const held = state_.heldEvents ??= [];
+	if (held.length >= MAX_HELD_EVENTS) {
+		held.shift();
+		state_.heldEventsDropped = (state_.heldEventsDropped ?? 0) + 1;
+	}
+	held.push({
+		event,
+		properties: snapshotProperties(properties),
+		options,
+		occurredAt: (/* @__PURE__ */ new Date()).toISOString(),
+		generation: state_.identity.getGeneration()
+	});
+}
+/** Report the held events dropped for `MAX_HELD_EVENTS`, once. */
+function reportHeldEventsDropped(state_) {
+	const dropped = state_.heldEventsDropped ?? 0;
+	state_.heldEventsDropped = 0;
+	if (dropped > 0 && typeof console !== "undefined") console.warn(`[amba] dropped ${dropped} event(s) tracked while the secure store was locked: more than ${MAX_HELD_EVENTS} were waiting`);
+}
+/** Drop the held events, with one warning that says why. */
+function dropHeldEvents(state_, why) {
+	const count = (state_.heldEvents ?? []).length + (state_.heldEventsDropped ?? 0);
+	state_.heldEvents = [];
+	state_.heldEventsDropped = 0;
+	if (count > 0 && typeof console !== "undefined") console.warn(`[amba] dropped ${count} event(s) tracked while the secure store was locked: ${why}`);
+}
+/**
+* Send the held events once the stored identity is known, oldest first,
+* through the path `track()` uses, under the identity that loaded. A session
+* renewal the load started finishes first. An event that fails is reported
+* and the rest go on; events tracked meanwhile join the end of the line.
+* An event goes out only while the session it belongs to is still the
+* stored one: the session that loaded for events held before, the session
+* of the moment for events tracked during the release. When the session
+* changed since (the renewal is refused and the session ends, a sign-in or
+* sign-out lands), the event is dropped, and one warning counts them.
+*/
+async function releaseHeldEvents(state_) {
+	if (state_.releasingHeldEvents || !state_.heldEvents?.length) return;
+	state_.releasingHeldEvents = true;
+	let stale = 0;
+	try {
+		const loadedAt = state_.identity.getGeneration();
+		await settleSessionInFlight(state_);
+		reportHeldEventsDropped(state_);
+		while (state_.heldEvents?.length && !state_.disposed) {
+			const next = state_.heldEvents.shift();
+			const belongsTo = Math.max(next.generation, loadedAt);
+			if (state_.identity.getGeneration() !== belongsTo) {
+				stale += 1;
+				continue;
+			}
+			try {
+				await sendEvent(state_, next.event, next.properties, next.options, next.occurredAt);
+			} catch (err) {
+				if (typeof console !== "undefined") console.warn(`[amba] could not send "${next.event}", tracked while the secure store was locked`, err);
+			}
+		}
+	} finally {
+		state_.releasingHeldEvents = false;
+		if (stale > 0 && typeof console !== "undefined") console.warn(`[amba] dropped ${stale} event(s) tracked while the secure store was locked: the session they belong to changed before they could be sent`);
+	}
 }
 /** Paths that must NOT trigger lazy anonymous sign-in. */
 function pathSkipsLazySession(path) {
@@ -3011,21 +3441,41 @@ function pathSkipsLazySession(path) {
 	if (path === P.flags || path.startsWith(`${P.flags}/`)) return true;
 	return false;
 }
+/**
+* Make sure a session is stored before an authenticated call. While the user
+* must sign in again (`sign_in_required`), the call fails with
+* `SIGN_IN_REQUIRED` and no anonymous user starts.
+*/
 async function ensureAnonymousSession(state_) {
 	if (state_.identity.getSessionToken()) return;
+	if (state_.identity.isSignInRequired()) throw signInRequiredError();
 	if (state_.anonSignInInflight) {
 		await state_.anonSignInInflight.catch(() => {});
 		if (state_.identity.getSessionToken()) return;
+		if (state_.identity.isSignInRequired()) throw signInRequiredError();
+	}
+	for (let attempt = 0; attempt < 2; attempt += 1) {
+		if (state_.identity.getSessionToken() || state_.disposed) return;
+		if (state_.identity.isSignInRequired()) throw signInRequiredError();
+		await anonymousSignInOnce(state_);
 	}
+	if (!state_.identity.getSessionToken() && state_.identity.isSignInRequired()) throw signInRequiredError();
+}
+/** One run of the lazy sign-in, shared by every caller that waits for it. */
+function anonymousSignInOnce(state_) {
 	if (!state_.anonSignInInflight) state_.anonSignInInflight = (async () => {
 		try {
+			await state_.identity.vaultStillUnreadable();
+			if (await state_.identity.anonymousIdStillUnknown()) throw secureStoreUnavailableError();
+			if (state_.identity.getSessionToken()) return;
 			if (await resumeWithRefreshToken(state_)) return;
-			await signInAnonymouslyFresh(state_);
+			if (state_.identity.getSessionToken() || state_.identity.isSignInRequired()) return;
+			await signInAnonymouslyAutomatic(state_);
 		} finally {
 			state_.anonSignInInflight = null;
 		}
 	})();
-	await state_.anonSignInInflight;
+	return state_.anonSignInInflight;
 }
 /**
 * Restore a stored session whose session token expired while the app was
@@ -3033,7 +3483,7 @@ async function ensureAnonymousSession(state_) {
 * `onAuthStateChange` show the signed-in user without waiting for an
 * authenticated call. Shares the in-flight slot with the lazy sign-in, so a
 * concurrent authenticated call waits for it. A rejected refresh token ends
-* the session (subscribers hear `null`); this never signs in anonymously.
+* the session (`endLostSession`); this never signs in anonymously.
 */
 function restoreStoredSession(state_) {
 	if (!state_.anonSignInInflight) state_.anonSignInInflight = (async () => {
@@ -3046,11 +3496,16 @@ function restoreStoredSession(state_) {
 	return state_.anonSignInInflight;
 }
 /**
-* Server answers that mean the refresh token's session is over. A 401
-* without the server's envelope (a proxy, a captive portal) maps to
-* `UNAUTHORIZED` and leaves the session in place.
+* Answers that mean the refresh token's session is over: the server
+* rejected or revoked it, or it renewed a different user than the stored
+* one (`OWNER_MISMATCH`). A 401 without the server's envelope (a proxy, a
+* captive portal) maps to `UNAUTHORIZED` and leaves the session in place.
 */
-const SESSION_ENDED_CODES = new Set(["INVALID_TOKEN", "SESSION_REVOKED"]);
+const SESSION_ENDED_CODES = new Set([
+	"INVALID_TOKEN",
+	"SESSION_REVOKED",
+	"OWNER_MISMATCH"
+]);
 function isSessionEnded(err) {
 	return err instanceof AmbaApiError && SESSION_ENDED_CODES.has(err.code);
 }
@@ -3077,8 +3532,8 @@ function trackLink(state_, link) {
 *     waited for first;
 *   - a session another flow stored after the call left is used as is;
 *   - otherwise the refresh token continues the session. A rejected refresh
-*     token ends it (subscribers hear `null`) and the call's own error
-*     reaches the app.
+*     token ends it (`endLostSession`) and the call's own error reaches the
+*     app.
 * A session of any other user (a sign-in meanwhile, or the anonymous user
 * a lazy sign-in starts after the session ended) answers false, and the
 * call fails with the server's code. Offline or a server error keeps the
@@ -3114,8 +3569,8 @@ async function recoverRefusedSession(state_, usedToken, usedUserId) {
 * reaction on that promise), so recovery never waits on itself.
 */
 async function withBodySession(state_, send) {
-	const usedToken = state_.identity.getSessionToken();
-	if (!usedToken) throw new AmbaApiError("UNAUTHORIZED", "no active session — call signIn* first");
+	await loadUnreadSession(state_);
+	const usedToken = requireSession(state_);
 	const usedUserId = state_.identity.getAppUserId();
 	try {
 		return await send(usedToken);
@@ -3128,78 +3583,136 @@ async function withBodySession(state_, send) {
 	}
 }
 /**
+* Read a store the launch couldn't read (a locked device) again. When that
+* loads a session, wait for the renewal it starts, so the caller acts on
+* the loaded session (a sign-out revokes it, a link sends it).
+*/
+async function loadUnreadSession(state_) {
+	if (!state_.identity.credentialsUnknown()) return;
+	await state_.identity.credentialsStillUnreadable();
+	if (!state_.identity.credentialsUnknown()) await settleSessionInFlight(state_);
+}
+/**
 * Before a read of the current session (`me`, `getSession`,
-* `getCurrentIdentifiers`) while no session token is stored: wait for the
-* launch restore or sign-in in flight, so a check made at launch sees the
-* session it restores.
+* `getCurrentIdentifiers`) while no session token is stored: load a stored
+* session the launch couldn't read yet, then wait for the launch restore or
+* sign-in in flight, so a check made at launch sees the session it
+* restores.
 */
 async function settleSessionInFlight(state_) {
+	if (state_.identity.getSessionToken()) return;
+	await state_.identity.credentialsStillUnreadable();
 	if (state_.identity.getSessionToken() || !state_.anonSignInInflight) return;
 	await state_.anonSignInInflight.catch(() => {});
 }
 /**
 * Continue the stored session with its refresh token. True when it did.
-* False when there is no refresh token, or the server rejected it: the
-* session is then cleared (the anonymous id rotates unless the session was
-* purely anonymous) and subscribers hear the sign-out. Any other failure
-* (offline, a 5xx) is thrown, so a flaky network never starts a new user.
+* False when there is no refresh token, or the session is over (the server
+* rejected the refresh token, or it renewed another user): the session then
+* ends through `endLostSession`. Any other failure (offline, a 5xx) is
+* thrown, so a flaky network never ends a session or starts a new user.
 */
 async function resumeWithRefreshToken(state_) {
 	const used = state_.identity.getRefreshToken();
 	if (!used) return false;
+	const startedAt = state_.identity.getGeneration();
 	try {
 		await refreshSession(state_);
 		return true;
 	} catch (err) {
 		if (state_.identity.getRefreshToken() !== used) return state_.identity.getSessionToken() !== null;
 		if (!isSessionEnded(err)) throw err;
-		await state_.identity.clearSession(false, { keepIdWhenKindUnknown: true });
-		notifyAuthSubscribers(null);
+		await endLostSession(state_, startedAt);
 		return false;
 	}
 }
 /**
-* `/v1/client/auth/anonymous` with the device's anonymous id. When the
-* server answers `IDENTITY_SIGN_IN_REQUIRED` (the id belongs to a user who
-* signs in with a linked identity), the device takes a new anonymous id and
-* signs in once more as a new anonymous user.
+* End a session that is over without a sign-out, once, unless the session
+* changed since `startedAt`.
+*
+* - A session that gained an identity (a sign-in other than anonymous, or a
+*   link) leaves the user to sign in again: its tokens are cleared, the
+*   anonymous id rotates (it belongs to the identified account), and
+*   subscribers hear `null` with `sign_in_required`. No new anonymous user
+*   starts; calls that need a session fail with `SIGN_IN_REQUIRED`.
+* - A purely anonymous session keeps its anonymous id, so the next call that
+*   needs a session resumes the same anonymous user through `/anonymous`
+*   (or the server starts a new one). Subscribers hear `null` with
+*   `session_ended`.
+* - A session of unknown kind (stored by an SDK before 4.0.14) is treated
+*   like an anonymous one: `/anonymous` resumes a still-anonymous user, and
+*   answers `IDENTITY_SIGN_IN_REQUIRED` for one who linked an identity,
+*   which then leaves the user to sign in again.
 */
-async function signInAnonymouslyFresh(state_) {
+async function endLostSession(state_, startedAt) {
+	if (state_.identity.snapshot().anonymousSession === false) {
+		if (await state_.identity.clearSession(false, {
+			signInRequired: true,
+			ifGeneration: startedAt
+		})) notifyAuthSubscribers(state_, null, "sign_in_required");
+		return;
+	}
+	if (await state_.identity.clearSession(false, {
+		keepIdWhenKindUnknown: true,
+		ifGeneration: startedAt
+	})) notifyAuthSubscribers(state_, null, "session_ended");
+}
+/**
+* The anonymous sign-in the SDK starts on its own before an authenticated
+* call: `/v1/client/auth/anonymous` with the device's anonymous id. It
+* stores its session only when nothing replaced the stored identity while
+* it was in flight; a sign-in that landed first wins and this answer is
+* dropped.
+*
+* When the server answers `IDENTITY_SIGN_IN_REQUIRED` (the id belongs to a
+* user who signs in with a linked identity), the stored session continues
+* when this device holds its refresh token. Otherwise the user must sign in
+* again (`sign_in_required`): no new anonymous user starts on its own.
+*/
+async function signInAnonymouslyAutomatic(state_) {
+	if (state_.disposed) return;
+	const startedAt = state_.identity.getGeneration();
 	try {
-		return await postAuth(state_, P.authAnonymous, { anonymous_id: state_.identity.getAnonymousId() });
+		await postAuth(state_, P.authAnonymous, { anonymous_id: state_.identity.getAnonymousId() }, { ifGeneration: startedAt });
 	} catch (err) {
+		if (isSessionChanged(err)) return;
 		if (!(err instanceof AmbaApiError) || err.code !== IDENTITY_SIGN_IN_REQUIRED) throw err;
-		return recoverFromHeldAnonymousId(state_);
+		if (await continueHeldSession(state_)) return;
+		if (await state_.identity.clearSession(true, {
+			signInRequired: true,
+			ifGeneration: startedAt
+		})) notifyAuthSubscribers(state_, null, "sign_in_required");
 	}
 }
 const IDENTITY_SIGN_IN_REQUIRED = "IDENTITY_SIGN_IN_REQUIRED";
 /**
 * After `/anonymous` answered `IDENTITY_SIGN_IN_REQUIRED`: continue the
-* stored session when this device holds its refresh token, and otherwise
-* take a new anonymous id and sign in as a new anonymous user. While the
-* secure store can't be read (an iOS device not yet unlocked since a
-* restart), the stored session is unknown, so the call fails with
-* `SECURE_STORE_UNAVAILABLE` and replaces nothing.
+* stored session when this device holds its refresh token. Null when it
+* holds none, or the server rejected it. While the stored session can't be
+* read (an iOS device not yet unlocked since a restart), it is unknown, so
+* the call fails with `SECURE_STORE_UNAVAILABLE` and replaces nothing.
 */
-async function recoverFromHeldAnonymousId(state_) {
-	if (await state_.identity.vaultStillUnreadable()) throw new AmbaApiError("SECURE_STORE_UNAVAILABLE", "the stored session can't be read yet (the device may be locked); retry once it is unlocked");
+async function continueHeldSession(state_) {
+	if (await state_.identity.credentialsStillUnreadable()) throw secureStoreUnavailableError();
 	const used = state_.identity.getRefreshToken();
-	if (used) try {
+	if (!used) return null;
+	try {
 		return await refreshSession(state_);
 	} catch (refreshErr) {
 		if (!isSessionEnded(refreshErr)) throw refreshErr;
 		const current = state_.identity.getRefreshToken();
 		if (current !== null && current !== used) throw refreshErr;
+		return null;
 	}
-	await state_.identity.clearSession(true);
-	return postAuth(state_, P.authAnonymous, { anonymous_id: state_.identity.getAnonymousId() });
 }
 /**
 * Rotate the session pair with the stored refresh token. The session keeps
 * its user and its kind (anonymous or identified), and auth-state
 * subscribers hear the refreshed session. The server includes the user; an
 * older server that leaves it out keeps the stored user id, and the result's
-* user then carries only that id.
+* user then carries only that id. A pair that renews a different user than
+* the stored one is never stored: the session ends (`endLostSession`) and
+* the call fails with `OWNER_MISMATCH`.
 */
 function refreshSession(state_) {
 	if (state_.refreshInflight) return state_.refreshInflight;
@@ -3212,32 +3725,66 @@ function refreshSession(state_) {
 	return inflight;
 }
 async function refreshSessionOnce(state_) {
+	if (state_.disposed) throw sessionChangedError("the SDK was configured again");
 	const refreshToken = state_.identity.getRefreshToken();
+	if (!refreshToken && state_.identity.isSignInRequired()) throw signInRequiredError();
 	if (!refreshToken) throw new AmbaApiError("UNAUTHORIZED", "no refresh token available — call signIn* first");
-	const env = await state_.http.post(P.authRefresh, { refresh_token: refreshToken });
-	if (state_.identity.getRefreshToken() !== refreshToken) throw new AmbaApiError("SESSION_CHANGED", "the session changed while it was being refreshed");
-	const appUserId = env.data.user?.id ?? state_.identity.getAppUserId();
-	if (!appUserId) throw new AmbaApiError("UNAUTHORIZED", "the refreshed session names no user — call signIn* first");
-	const user = env.data.user ? normalizeUserAuthProviders(env.data.user) : {
-		id: appUserId,
-		auth_providers: [],
-		properties: {}
-	};
-	const result = {
-		session_token: env.data.session_token,
-		refresh_token: env.data.refresh_token,
-		user,
-		expires_at: env.data.expires_at ?? null
-	};
-	await persistAuthResult(state_, result, void 0);
-	const anonymousId = nonEmptyString(user.anonymous_id);
-	if (anonymousId && anonymousId !== state_.identity.getAnonymousId() && state_.identity.getRefreshToken() === result.refresh_token) {
-		if (state_.identity.snapshot().anonymousSession === true) await state_.identity.markIdentified();
-		await adoptAnonymousId(state_, anonymousId);
+	const startedAt = state_.identity.getGeneration();
+	const exchange$1 = refreshExchangeFor(state_, refreshToken);
+	try {
+		const env = await exchange$1.response;
+		if (state_.identity.getRefreshToken() !== refreshToken || state_.identity.getGeneration() !== startedAt) throw sessionChangedError("the session changed while it was being refreshed");
+		const storedUserId = state_.identity.getAppUserId();
+		const renewedUserId = nonEmptyString(env.data.user?.id);
+		if (renewedUserId !== null && storedUserId !== null && renewedUserId !== storedUserId) {
+			await endLostSession(state_, startedAt);
+			throw new AmbaApiError("OWNER_MISMATCH", "the refreshed session belongs to a different user than the stored one; sign in again");
+		}
+		const appUserId = renewedUserId ?? storedUserId;
+		if (!appUserId) throw new AmbaApiError("UNAUTHORIZED", "the refreshed session names no user — call signIn* first");
+		const user = env.data.user ? normalizeUserAuthProviders(env.data.user) : {
+			id: appUserId,
+			auth_providers: [],
+			properties: {}
+		};
+		const result = {
+			session_token: env.data.session_token,
+			refresh_token: env.data.refresh_token,
+			user,
+			expires_at: env.data.expires_at ?? null
+		};
+		const committedAt = await persistAuthResult(state_, result, void 0, {
+			ifGeneration: startedAt,
+			advance: false
+		});
+		if (committedAt === null) throw sessionChangedError("the session changed while it was being refreshed");
+		const anonymousId = nonEmptyString(user.anonymous_id);
+		if (anonymousId && anonymousId !== state_.identity.getAnonymousId() && state_.identity.getRefreshToken() === result.refresh_token) {
+			if (state_.identity.snapshot().anonymousSession === true) await state_.identity.markIdentified({ ifGeneration: committedAt });
+			await adoptAnonymousId(state_, anonymousId, committedAt);
+		}
+		state_.eventQueue?.flush();
+		notifyFromAuthResult(state_, result, "token_refreshed");
+		return result;
+	} finally {
+		if (state_.refreshExchange === exchange$1) state_.refreshExchange = null;
 	}
-	state_.eventQueue?.flush();
-	await notifyFromAuthResult(result);
-	return result;
+}
+/**
+* The `/refresh` request for `refreshToken`: the one the previous state had
+* in flight for the same token when `configure()` ran again, or a new one.
+* It stays on the state until its answer is stored, so a `configure()`
+* meanwhile hands it on instead of presenting the token again.
+*/
+function refreshExchangeFor(state_, refreshToken) {
+	const inherited = state_.inheritedRefresh;
+	if (inherited) state_.inheritedRefresh = null;
+	const exchange$1 = inherited && inherited.token === refreshToken ? inherited : {
+		token: refreshToken,
+		response: state_.http.post(P.authRefresh, { refresh_token: refreshToken })
+	};
+	state_.refreshExchange = exchange$1;
+	return exchange$1;
 }
 /**
 * POST an OTP or email + password link. The request asks the server to
@@ -3254,6 +3801,11 @@ function postLink(state_, body) {
 	})));
 }
 async function postLinkOnce(state_, body) {
+	const startedAt = state_.identity.getGeneration();
+	const fence = {
+		ifGeneration: startedAt,
+		advance: false
+	};
 	const env = await state_.http.post(P.authLink, {
 		...body,
 		rotate_session: true
@@ -3261,7 +3813,7 @@ async function postLinkOnce(state_, body) {
 	const user = normalizeUserAuthProviders(env.data.user);
 	const sessionToken = nonEmptyString(env.data.session_token);
 	const refreshToken = nonEmptyString(env.data.refresh_token);
-	if (sessionToken && refreshToken) await state_.identity.setSession({
+	if (!(sessionToken && refreshToken ? await state_.identity.setSession({
 		appUserId: user.id,
 		sessionToken,
 		refreshToken,
@@ -3272,10 +3824,9 @@ async function postLinkOnce(state_, body) {
 			expires_at: env.data.expires_at ?? null
 		}),
 		anonymous: false
-	});
-	else await state_.identity.markIdentified();
+	}, fence) !== null : await state_.identity.markIdentified(fence))) throw sessionChangedError("the session changed while the link was in flight; the newer session stays");
 	const anonymousId = nonEmptyString(user.anonymous_id);
-	if (anonymousId) await adoptAnonymousId(state_, anonymousId);
+	if (anonymousId) await adoptAnonymousId(state_, anonymousId, startedAt);
 	return user;
 }
 /**
@@ -3286,7 +3837,7 @@ async function postUserNoRotate(state_, path, body) {
 	return normalizeUserAuthProviders((await state_.http.post(path, body)).data.user);
 }
 async function unlinkProvider(provider) {
-	const s = getState();
+	const s = await liveState();
 	return withBodySession(s, (sessionToken) => postUserNoRotate(s, P.authUnlink, {
 		provider,
 		session_token: sessionToken
@@ -3543,107 +4094,238 @@ function detectDeviceRegion() {
 	}
 }
 /**
-* Top-level SDK namespace for React Native.
+* The send path of `events.track()`: the event batch queue when batching is
+* on, otherwise the live request (with the offline outbox behind it when
+* enabled). `occurredAtOverride` is when the event happened, for one that
+* waited (see `releaseHeldEvents`).
 */
-const Amba = {
-	configure: async (config) => {
-		if (!config.projectId || config.projectId.trim() === "") throw new Error("Amba.configure: projectId is required");
-		if (!config.clientKey || config.clientKey.trim() === "") throw new Error("Amba.configure: clientKey is required");
-		const batchSize = config.events?.batchSize ?? 100;
-		const flushIntervalMs = config.events?.flushIntervalMs ?? 6e4;
-		const maxQueue = config.events?.maxQueue ?? 1e4;
-		if (config.events?.batching) {
-			if (!Number.isInteger(batchSize) || batchSize < 1 || batchSize > 500) throw new Error("Amba.configure: events.batchSize must be 1–500");
-			if (!Number.isInteger(flushIntervalMs) || flushIntervalMs < 0) throw new Error("Amba.configure: events.flushIntervalMs must be a non-negative integer");
-			if (!Number.isInteger(maxQueue) || maxQueue < 1) throw new Error("Amba.configure: events.maxQueue must be positive");
+async function sendEvent(s, event, properties, options, occurredAtOverride) {
+	if (s.eventQueue && !options?.immediate) return s.eventQueue.enqueue(event, properties, options?.telemetry === true, occurredAtOverride);
+	const occurredAt = occurredAtOverride ?? (/* @__PURE__ */ new Date()).toISOString();
+	const props = s.offlineEnabled ? snapshotProperties(properties) : properties;
+	const body = {
+		event,
+		properties: props ?? void 0,
+		anonymous_id: s.identity.getAnonymousId(),
+		timestamp: occurredAt
+	};
+	if (options?.telemetry) body["telemetry"] = true;
+	const idempotencyKey = s.offlineEnabled ? newIdempotencyKey() : void 0;
+	if (idempotencyKey && keyedLiveTrack(props, options?.telemetry)) body["idempotency_key"] = idempotencyKey;
+	const outboxTicket = s.offlineEnabled ? getOfflineQueue(s).ticket() : void 0;
+	try {
+		await s.http.post(P.events, body);
+	} catch (err) {
+		if (s.offlineEnabled && isOfflineError(err)) {
+			await getOfflineQueue(s).enqueue({
+				kind: "track",
+				event,
+				properties: props,
+				telemetry: options?.telemetry,
+				occurredAt,
+				idempotencyKey
+			}, outboxTicket);
+			return;
 		}
-		const deadlines = resolveRequestDeadlines(config);
-		const tokenStorage = config.tokenStorage ?? "secure";
-		if (!TOKEN_STORAGE_MODES.includes(tokenStorage)) throw new Error("Amba.configure: tokenStorage must be \"secure\", \"memory\" or \"asyncStorage\"");
-		const secureStorage = config.secureStorage;
-		if (secureStorage !== void 0 && (typeof secureStorage?.getItem !== "function" || typeof secureStorage?.setItem !== "function" || typeof secureStorage?.removeItem !== "function")) throw new Error("Amba.configure: secureStorage must provide getItem, setItem and removeItem");
-		const configDefaults = readConfigDefaults(config.configDefaults);
-		_pendingConfigDefaults = configDefaults;
-		const storagePrefix = config.storagePrefix ?? "amba";
-		const persistence = new AsyncStoragePersistence(storagePrefix);
-		if (config.events?.batching) await persistence.assertDurable();
-		await persistence.hydrate();
-		const vault = await resolveTokenVault(tokenStorage, storagePrefix, secureStorage);
-		const identity = await IdentityStore.create(persistence, vault);
-		const baseUrl = (config.apiUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
-		const remoteValues = new RemoteValuesCache(persistence, recordKey(baseUrl, config.clientKey), configDefaults ?? {}, () => identity.getAppUserId());
+		throw err;
+	}
+}
+/**
+* The local half of a sign-out on `state_`: clear the session (unless a
+* sign-in stored a newer one since `startedAt`), drop the signed-out
+* user's cached values and queued writes, and tell subscribers. False when
+* nothing was cleared.
+*/
+async function endSignedOutSession(state_, rotateAnonymousId, startedAt) {
+	const signedOutUser = state_.identity.getAppUserId();
+	if (!await state_.identity.clearSession(rotateAnonymousId, { unlessSignedInSince: startedAt })) return false;
+	dropHeldEvents(state_, "the device signed out before its identity could be read");
+	state_.remoteValues.clearForSignOut(signedOutUser);
+	await state_.remoteValues.flushed();
+	try {
+		await getOfflineQueue(state_).purge();
+	} catch (err) {
+		if (typeof console !== "undefined") console.warn("[amba] signOut could not clear the offline outbox", err);
+	}
+	state_.eventQueue?.flush();
+	notifyAuthSubscribers(state_, null, "signed_out");
+	return true;
+}
+/**
+* One `configure()`: build the state for `config` and install it in place
+* of the previous one (see `Amba.configure`).
+*/
+async function configureOnce(config) {
+	if (!config.projectId || config.projectId.trim() === "") throw new Error("Amba.configure: projectId is required");
+	if (!config.clientKey || config.clientKey.trim() === "") throw new Error("Amba.configure: clientKey is required");
+	const batchSize = config.events?.batchSize ?? 100;
+	const flushIntervalMs = config.events?.flushIntervalMs ?? 6e4;
+	const maxQueue = config.events?.maxQueue ?? 1e4;
+	if (config.events?.batching) {
+		if (!Number.isInteger(batchSize) || batchSize < 1 || batchSize > 500) throw new Error("Amba.configure: events.batchSize must be 1–500");
+		if (!Number.isInteger(flushIntervalMs) || flushIntervalMs < 0) throw new Error("Amba.configure: events.flushIntervalMs must be a non-negative integer");
+		if (!Number.isInteger(maxQueue) || maxQueue < 1) throw new Error("Amba.configure: events.maxQueue must be positive");
+	}
+	const deadlines = resolveRequestDeadlines(config);
+	const tokenStorage = config.tokenStorage ?? "secure";
+	if (!TOKEN_STORAGE_MODES.includes(tokenStorage)) throw new Error("Amba.configure: tokenStorage must be \"secure\", \"memory\" or \"asyncStorage\"");
+	const secureStorage = config.secureStorage;
+	if (secureStorage !== void 0 && (typeof secureStorage?.getItem !== "function" || typeof secureStorage?.setItem !== "function" || typeof secureStorage?.removeItem !== "function")) throw new Error("Amba.configure: secureStorage must provide getItem, setItem and removeItem");
+	const configDefaults = readConfigDefaults(config.configDefaults);
+	_pendingConfigDefaults = configDefaults;
+	const storagePrefix = config.storagePrefix ?? "amba";
+	const persistence = new AsyncStoragePersistence(storagePrefix);
+	if (config.events?.batching) await persistence.assertDurable();
+	await persistence.hydrate();
+	const vault = await resolveTokenVault(tokenStorage, storagePrefix, secureStorage);
+	const prior = state;
+	let inheritedRefresh = null;
+	const detached = prior !== null && !prior.disposed;
+	if (prior && detached) {
+		prior.disposed = true;
+		inheritedRefresh = prior.refreshExchange ?? prior.inheritedRefresh ?? null;
+		await prior.identity.dispose();
+	}
+	const baseUrl = (config.apiUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+	let identity;
+	let remoteValues;
+	try {
+		identity = await IdentityStore.create(persistence, vault);
+		const store = identity;
+		remoteValues = new RemoteValuesCache(persistence, recordKey(baseUrl, config.clientKey), configDefaults ?? {}, () => store.getAppUserId());
 		await remoteValues.load();
-		const sdkVersionHeader = `amba-sdk/${SDK_VERSION} ${`amba-react-native/${SDK_VERSION}`}`;
-		const http = new AmbaHttpClient({
-			apiKey: config.clientKey,
-			baseUrl,
-			sdkPlatform: "react-native",
-			sdkVersionHeader,
-			appVersion: normalizeAppVersion(config.appVersion),
-			deviceRegion: detectDeviceRegion(),
-			deviceOs: detectDeviceOs(),
-			identity,
-			requestTimeoutMs: deadlines.requestMs,
-			longRequestTimeoutMs: deadlines.longMs,
-			ensureSession: config.autoAnonymousSession === false ? void 0 : async (path) => {
-				if (pathSkipsLazySession(path)) return;
-				await ensureAnonymousSession(getState());
-			},
-			onSessionRefused: (usedToken, usedUserId) => recoverRefusedSession(getState(), usedToken, usedUserId)
+	} catch (err) {
+		if (prior && detached && state === prior) {
+			prior.disposed = false;
+			prior.identity.reattach();
+			prior.inheritedRefresh = inheritedRefresh;
+			if (inheritedRefresh && prior.identity.getRefreshToken() === inheritedRefresh.token) restoreStoredSession(prior).catch(() => {});
+		}
+		throw err;
+	}
+	const sdkVersionHeader = `amba-sdk/${SDK_VERSION} ${`amba-react-native/${SDK_VERSION}`}`;
+	const http = new AmbaHttpClient({
+		apiKey: config.clientKey,
+		baseUrl,
+		sdkPlatform: "react-native",
+		sdkVersionHeader,
+		appVersion: normalizeAppVersion(config.appVersion),
+		deviceRegion: detectDeviceRegion(),
+		deviceOs: detectDeviceOs(),
+		identity,
+		requestTimeoutMs: deadlines.requestMs,
+		longRequestTimeoutMs: deadlines.longMs,
+		ensureSession: async (path) => {
+			if (pathSkipsLazySession(path)) return;
+			if (state?.identity.isSignInRequired()) throw signInRequiredError();
+			if (config.autoAnonymousSession === false) return;
+			await ensureAnonymousSession(getState());
+		},
+		onSessionRefused: (usedToken, usedUserId) => recoverRefusedSession(getState(), usedToken, usedUserId)
+	});
+	_offlineEnableToken += 1;
+	if (prior?.offlineQueue) await prior.offlineQueue.dispose();
+	prior?.detachEventAppState?.();
+	prior?.detachIdentityAppState?.();
+	if (prior?.eventQueue) await prior.eventQueue.dispose();
+	experimentReporter.reset();
+	const nextState = {
+		http,
+		identity,
+		debug: config.debug ?? false,
+		projectId: config.projectId,
+		clientKey: config.clientKey,
+		baseUrl,
+		functionsBaseUrl: config.functionsBaseUrl ?? null,
+		resolvedFunctionsProjectId: null,
+		functionsProjectIdInflight: null,
+		persistence,
+		remoteValues,
+		refreshedFor: {
+			config: null,
+			flags: null
+		},
+		offlineEnabled: false,
+		offlineQueue: null,
+		eventQueue: null,
+		inheritedRefresh
+	};
+	if (prior?.heldEvents?.length || prior?.heldEventsDropped) if (sameIdentityTarget(prior, nextState)) {
+		const launchedAt = identity.getGeneration();
+		nextState.heldEvents = (prior.heldEvents ?? []).map((held) => ({
+			...held,
+			generation: launchedAt
+		}));
+		nextState.heldEventsDropped = prior.heldEventsDropped;
+		prior.heldEvents = [];
+		prior.heldEventsDropped = 0;
+	} else dropHeldEvents(prior, "the SDK was configured for another project");
+	state = nextState;
+	identity.onAnonymousIdKnown(() => {
+		releaseHeldEvents(nextState);
+	});
+	identity.onStoredSessionLoaded(() => {
+		const userId = identity.getAppUserId();
+		if (identity.getSessionToken() && userId) notifyAuthSubscribers(nextState, snapshotSession({
+			id: userId,
+			auth_providers: [],
+			properties: {}
+		}), "session_restored");
+		else if (config.autoAnonymousSession !== false && identity.getRefreshToken()) restoreStoredSession(nextState).catch(() => {});
+	});
+	try {
+		const { AppState } = require("react-native");
+		const sub = AppState.addEventListener("change", (status) => {
+			if (status === "active" && identity.credentialsUnknown()) identity.credentialsStillUnreadable();
 		});
-		const prior = state;
-		_offlineEnableToken += 1;
-		if (prior?.offlineQueue) await prior.offlineQueue.dispose();
-		prior?.detachEventAppState?.();
-		if (prior?.eventQueue) await prior.eventQueue.dispose();
-		experimentReporter.reset();
-		const nextState = {
-			http,
-			identity,
-			debug: config.debug ?? false,
-			projectId: config.projectId,
-			clientKey: config.clientKey,
-			baseUrl,
-			functionsBaseUrl: config.functionsBaseUrl ?? null,
-			resolvedFunctionsProjectId: null,
-			functionsProjectIdInflight: null,
-			persistence,
-			remoteValues,
-			refreshedFor: {
-				config: null,
-				flags: null
-			},
-			offlineEnabled: false,
-			offlineQueue: null,
-			eventQueue: null
+		nextState.detachIdentityAppState = () => sub.remove();
+	} catch {}
+	if (config.events?.batching) {
+		const queue = new EventBatchQueue(offlineStore(nextState), `event_outbox:${nextState.projectId}`, {
+			batchSize,
+			flushIntervalMs,
+			maxQueue,
+			onDrop: config.events.onDrop
+		}, () => ({
+			userId: nextState.identity.getAppUserId(),
+			anonymousId: nextState.identity.getAnonymousId(),
+			sessionToken: nextState.identity.getSessionToken()
+		}), (body, token) => nextState.http.postWithSession("/v1/client/events/batch", body, token), (body, token) => nextState.http.postWithSession(P.events, body, token));
+		nextState.eventQueue = queue;
+		await queue.start();
+		try {
+			const { AppState } = require("react-native");
+			const sub = AppState.addEventListener("change", (status) => {
+				if (status === "background") queue.flush();
+			});
+			nextState.detachEventAppState = () => sub.remove();
+		} catch {}
+	}
+	if (!nextState.functionsBaseUrl && !PROJECT_ID_PATTERN.test(nextState.projectId)) resolveFunctionsProjectId(nextState).catch(() => {});
+	if (nextState.heldEvents?.length && !identity.hasStandInAnonymousId()) releaseHeldEvents(nextState);
+	if (inheritedRefresh !== null && identity.getRefreshToken() === inheritedRefresh.token || config.autoAnonymousSession !== false && !identity.getSessionToken() && identity.getRefreshToken()) restoreStoredSession(nextState).catch(() => {});
+}
+/**
+* Top-level SDK namespace for React Native.
+*/
+const Amba = {
+	configure: (config) => {
+		const run = configuring ? configureChain.then(() => configureOnce(config)) : configureOnce(config);
+		configureChain = run.catch(() => void 0);
+		configuring = run;
+		const settle = () => {
+			if (configuring === run) configuring = null;
 		};
-		state = nextState;
-		if (config.events?.batching) {
-			const queue = new EventBatchQueue(offlineStore(nextState), `event_outbox:${nextState.projectId}`, {
-				batchSize,
-				flushIntervalMs,
-				maxQueue,
-				onDrop: config.events.onDrop
-			}, () => ({
-				userId: nextState.identity.getAppUserId(),
-				anonymousId: nextState.identity.getAnonymousId(),
-				sessionToken: nextState.identity.getSessionToken()
-			}), (body, token) => nextState.http.postWithSession("/v1/client/events/batch", body, token), (body, token) => nextState.http.postWithSession(P.events, body, token));
-			nextState.eventQueue = queue;
-			await queue.start();
-			try {
-				const { AppState } = require("react-native");
-				const sub = AppState.addEventListener("change", (status) => {
-					if (status === "background") queue.flush();
-				});
-				nextState.detachEventAppState = () => sub.remove();
-			} catch {}
-		}
-		if (!nextState.functionsBaseUrl && !PROJECT_ID_PATTERN.test(nextState.projectId)) resolveFunctionsProjectId(nextState).catch(() => {});
-		if (config.autoAnonymousSession !== false && !identity.getSessionToken() && identity.getRefreshToken()) restoreStoredSession(nextState).catch(() => {});
+		run.then(settle, settle);
+		return run;
 	},
 	_reset: () => {
+		if (state) {
+			state.disposed = true;
+			state.identity.dispose();
+		}
 		state?.detachEventAppState?.();
+		state?.detachIdentityAppState?.();
 		state?.eventQueue?.dispose();
 		state = null;
 		authSubscribers.clear();
@@ -3677,35 +4359,18 @@ const Amba = {
 	},
 	events: {
 		track: async (event, properties, options) => {
-			const s = getState();
-			if (s.eventQueue && !options?.immediate) return s.eventQueue.enqueue(event, properties, options?.telemetry === true);
-			const occurredAt = (/* @__PURE__ */ new Date()).toISOString();
-			const props = s.offlineEnabled ? snapshotProperties(properties) : properties;
-			const body = {
-				event,
-				properties: props ?? void 0,
-				anonymous_id: s.identity.getAnonymousId(),
-				timestamp: occurredAt
-			};
-			if (options?.telemetry) body["telemetry"] = true;
-			const idempotencyKey = s.offlineEnabled ? newIdempotencyKey() : void 0;
-			if (idempotencyKey && keyedLiveTrack(props, options?.telemetry)) body["idempotency_key"] = idempotencyKey;
-			const outboxTicket = s.offlineEnabled ? getOfflineQueue(s).ticket() : void 0;
-			try {
-				await s.http.post(P.events, body);
-			} catch (err) {
-				if (s.offlineEnabled && isOfflineError(err)) {
-					await getOfflineQueue(s).enqueue({
-						kind: "track",
-						event,
-						properties: props,
-						telemetry: options?.telemetry,
-						occurredAt,
-						idempotencyKey
-					}, outboxTicket);
-					return;
+			let s = getState();
+			for (let attempt = 0;; attempt += 1) {
+				const hold = (s.heldEvents?.length ?? 0) > 0 || await s.identity.anonymousIdStillUnknown();
+				if (s.disposed && attempt === 0) {
+					s = await liveState();
+					continue;
 				}
-				throw err;
+				if (!hold) return sendEvent(s, event, properties, options);
+				if (typeof event !== "string" || event.trim() === "") throw new AmbaApiError("VALIDATION_ERROR", "event name must be non-empty");
+				holdEvent(s, event, properties, options);
+				if (!s.identity.hasStandInAnonymousId()) releaseHeldEvents(s);
+				return;
 			}
 		},
 		flush: async () => getState().eventQueue?.flush() ?? {
@@ -3727,18 +4392,24 @@ const Amba = {
 	},
 	auth: {
 		signInAnonymously: async () => {
-			const s = getState();
+			const s = await liveState();
+			await loadUnreadSession(s);
+			if (await s.identity.anonymousIdStillUnknown()) throw secureStoreUnavailableError();
+			const startedAt = s.identity.getGeneration();
 			try {
 				return await postAuth(s, P.authAnonymous, { anonymous_id: s.identity.getAnonymousId() });
 			} catch (err) {
 				if (!(err instanceof AmbaApiError) || err.code !== IDENTITY_SIGN_IN_REQUIRED) throw err;
-				return recoverFromHeldAnonymousId(s);
+				const held = await continueHeldSession(s);
+				if (held) return held;
+				if (!await s.identity.clearSession(true, { unlessSignedInSince: startedAt })) throw sessionChangedError("a sign-in stored a newer session while this call was in flight");
+				return postAuth(s, P.authAnonymous, { anonymous_id: s.identity.getAnonymousId() });
 			}
 		},
 		signInWithEmail: async (email, password) => {
 			requireEmail(email);
 			if (password === "") throw new AmbaApiError("VALIDATION_ERROR", "password must not be empty");
-			return postAuth(getState(), P.authEmailLogin, {
+			return postAuth(await liveState(), P.authEmailLogin, {
 				email,
 				password
 			});
@@ -3746,14 +4417,14 @@ const Amba = {
 		signUpWithEmail: async (email, password) => {
 			requireEmail(email);
 			requirePassword(password);
-			return postAuth(getState(), P.authEmailSignup, {
+			return postAuth(await liveState(), P.authEmailSignup, {
 				email,
 				password
 			});
 		},
 		signInWithApple: async (identityToken, options) => {
 			if (identityToken.trim() === "") throw new AmbaApiError("VALIDATION_ERROR", "identity_token must not be empty");
-			return postAuth(getState(), P.authSocial, {
+			return postAuth(await liveState(), P.authSocial, {
 				provider: "apple",
 				id_token: identityToken,
 				...nonceField(options)
@@ -3761,7 +4432,7 @@ const Amba = {
 		},
 		signInWithGoogle: async (idToken, options) => {
 			if (idToken.trim() === "") throw new AmbaApiError("VALIDATION_ERROR", "id_token must not be empty");
-			return postAuth(getState(), P.authSocial, {
+			return postAuth(await liveState(), P.authSocial, {
 				provider: "google",
 				id_token: idToken,
 				...nonceField(options)
@@ -3774,7 +4445,7 @@ const Amba = {
 		verifyEmailOtp: async (email, code) => {
 			requireEmail(email);
 			requireOtpCode(code);
-			return postAuth(getState(), P.authEmailOtpVerify, {
+			return postAuth(await liveState(), P.authEmailOtpVerify, {
 				email,
 				code
 			});
@@ -3786,7 +4457,7 @@ const Amba = {
 		verifySmsOtp: async (phone, code) => {
 			requireE164Phone(phone);
 			requireOtpCode(code);
-			return postAuth(getState(), P.authSmsOtpVerify, {
+			return postAuth(await liveState(), P.authSmsOtpVerify, {
 				phone,
 				code
 			});
@@ -3797,24 +4468,27 @@ const Amba = {
 		},
 		verifyMagicLink: async (token) => {
 			if (token.trim() === "") throw new AmbaApiError("VALIDATION_ERROR", "token must not be empty");
-			return postAuth(getState(), P.authMagicLinkVerify, { token });
+			return postAuth(await liveState(), P.authMagicLinkVerify, { token });
 		},
 		linkAccount: async (provider, credential, options) => {
 			const providerTrimmed = provider?.trim() ?? "";
 			if (providerTrimmed === "") throw new AmbaApiError("VALIDATION_ERROR", "provider must not be empty");
 			if (typeof credential !== "string" || credential.trim() === "") throw new AmbaApiError("VALIDATION_ERROR", "credential must not be empty");
-			const s = getState();
+			const s = await liveState();
 			return withBodySession(s, (sessionToken) => trackLink(s, postAuth(s, P.authLink, {
 				provider: providerTrimmed,
 				token: credential,
 				session_token: sessionToken,
 				...nonceField(options)
+			}, {
+				ifGeneration: s.identity.getGeneration(),
+				advance: false
 			})));
 		},
 		linkSmsOtp: async (phone, code) => {
 			requireE164Phone(phone);
 			requireOtpCode(code);
-			return postLink(getState(), {
+			return postLink(await liveState(), {
 				provider: "sms_otp",
 				phone,
 				code
@@ -3823,7 +4497,7 @@ const Amba = {
 		linkEmailOtp: async (email, code) => {
 			requireEmail(email);
 			requireOtpCode(code);
-			return postLink(getState(), {
+			return postLink(await liveState(), {
 				provider: "email_otp",
 				email,
 				code
@@ -3832,7 +4506,7 @@ const Amba = {
 		linkEmailPassword: async (email, password) => {
 			requireEmail(email);
 			requirePassword(password);
-			return postLink(getState(), {
+			return postLink(await liveState(), {
 				provider: "email_password",
 				email,
 				password
@@ -3845,34 +4519,29 @@ const Amba = {
 		getCurrentIdentifiers: async () => {
 			const s = getState();
 			await settleSessionInFlight(s);
-			if (!s.identity.getSessionToken()) throw new AmbaApiError("UNAUTHORIZED", "no active session — call signIn* first");
+			requireSession(s);
 			return (await s.http.get(P.authIdentifiers)).data.identifiers;
 		},
 		signOut: async (rotateAnonymousId = false) => {
-			const s = getState();
+			const s = await liveState();
+			await loadUnreadSession(s);
+			const startedAt = s.identity.getGeneration();
+			const revoked = s.identity.getRefreshToken();
 			if (s.identity.getSessionToken()) try {
-				const refreshToken = s.identity.getRefreshToken();
-				await s.http.post(P.authLogout, refreshToken ? { refresh_token: refreshToken } : {});
+				await s.http.post(P.authLogout, revoked ? { refresh_token: revoked } : {});
 			} catch (err) {
 				if (typeof console !== "undefined") console.warn("[amba] signOut server call failed", err);
 			}
-			const signedOutUser = s.identity.getAppUserId();
-			await s.identity.clearSession(rotateAnonymousId);
-			s.remoteValues.clearForSignOut(signedOutUser);
-			await s.remoteValues.flushed();
-			try {
-				await getOfflineQueue(s).purge();
-			} catch (err) {
-				if (typeof console !== "undefined") console.warn("[amba] signOut could not clear the offline outbox", err);
-			}
-			s.eventQueue?.flush();
-			notifyAuthSubscribers(null);
+			if (await endSignedOutSession(s, rotateAnonymousId, startedAt)) return;
+			if (!s.disposed || revoked === null) return;
+			const next = await liveState();
+			if (next !== s && !next.disposed && sameIdentityTarget(next, s) && next.identity.continuesLaunchSession(revoked)) await endSignedOutSession(next, rotateAnonymousId, next.identity.getGeneration());
 		},
-		refresh: async () => refreshSession(getState()),
+		refresh: async () => refreshSession(await liveState()),
 		me: async () => {
 			const s = getState();
 			await settleSessionInFlight(s);
-			if (!s.identity.getSessionToken()) throw new AmbaApiError("UNAUTHORIZED", "no active session — call signIn* first");
+			requireSession(s);
 			return normalizeUserAuthProviders((await s.http.get(P.authMe)).data);
 		},
 		getSession: async () => {
@@ -3887,7 +4556,9 @@ const Amba = {
 			}
 		},
 		getAnonymousId: async () => {
-			return getState().identity.getAnonymousId();
+			const s = getState();
+			if (await s.identity.anonymousIdStillUnknown()) throw secureStoreUnavailableError();
+			return s.identity.getAnonymousId();
 		},
 		onAuthStateChange: (cb) => {
 			authSubscribers.add(cb);
@@ -3899,17 +4570,19 @@ const Amba = {
 	users: {
 		get: async (userId) => {
 			const s = getState();
-			if (!s.identity.getSessionToken()) throw new AmbaApiError("UNAUTHORIZED", "no active session — call signIn* first");
+			await settleSessionInFlight(s);
+			requireSession(s);
 			const path = userId === void 0 || userId === null || userId === "" ? P.usersMe : `${P.users}/${encodePathSegment(userId)}`;
 			return normalizeUserAuthProviders((await s.http.get(path)).data);
 		},
-		update: ((arg1, arg2) => {
+		update: (async (arg1, arg2) => {
 			const s = getState();
-			if (!s.identity.getSessionToken()) throw new AmbaApiError("UNAUTHORIZED", "no active session — call signIn* first");
+			await settleSessionInFlight(s);
+			requireSession(s);
 			const isById = typeof arg1 === "string";
 			const patch = isById ? arg2 ?? {} : arg1;
 			const path = isById ? `${P.users}/${encodePathSegment(arg1)}` : `${P.users}/me`;
-			return s.http.patch(path, patch).then((env) => normalizeUserAuthProviders(env.data));
+			return normalizeUserAuthProviders((await s.http.patch(path, patch)).data);
 		})
 	},
 	sessions: {