@sendoracloud/sdk-web 3.23.0 → 3.24.1

package/dist/index.d.ts

@@ -61,6 +61,30 @@ interface SendoraConfig {
      * silently no-op'd and tokens still hit localStorage. It is now real.
      */
     tokenStore?: "local" | "memory";
+    /**
+     * ADR-033 wave 1 (3.24.0) — OPT-IN project guard. A UUID; must equal
+     * `projectId` when both are set (validated at `init()`, throws otherwise).
+     * When set, a stored or refreshed session whose JWT `project` claim is a
+     * different string or an explicit `null` (the org-wide pool) is WITHHELD:
+     * `auth.status()` reports `"withheld"`, `getAccessToken()` is null, every
+     * sign-in / link / mint verb rejects `AuthError{kind:'config',
+     * code:'SESSION_WITHHELD'}`, and NOTHING is written to storage — a re-init
+     * with the matching id, or `auth.discardWithheld()`, are the two exits. A
+     * session minted by THIS process under the wrong id rejects
+     * `PROJECT_MISMATCH` and is revoked, so a wrong-key build fails loudly at
+     * first launch instead of looping. Absent = guard off (every token matches).
+     * `status()` is the only call that tells `withheld` from `signed_out`.
+     */
+    expectedProjectId?: string;
+    /**
+     * ADR-033 wave 1 (3.24.0) — default `true`: in `signed_out`, `ensureSession()`
+     * / `signInAnonymously()` RESTORE the newest eligible held guest (visibly:
+     * `signed_in{cause:'restore'}` + `guest_released{restored}`) instead of
+     * minting. `false` mints while fewer than 5 guests are held (at the cap a
+     * plain mint still restores). A guest stamped `autoRestore:false` by
+     * `deleteAccount()` is never auto-restored either way.
+     */
+    autoRestoreHeldGuest?: boolean;
     /** Idle threshold (ms) for session expiry; default 30 minutes. */
     sessionIdleMs?: number;
     /** Event queue flush interval in ms (default 5000) */
@@ -209,6 +233,14 @@ declare class Storage {
     get(key: string): string | null;
     set(key: string, value: string): void;
     remove(key: string): void;
+    /**
+     * True when values reach `localStorage` (and therefore other tabs). False
+     * under `tokenStore: "memory"` or when localStorage is unavailable — then
+     * there is no disk for a `storage` event to describe (ADR-033 wave 1 (e)).
+     */
+    isPersistent(): boolean;
+    /** Strip this instance's namespace off a raw localStorage key; `null` when the key is not ours. */
+    relativeKey(fullKey: string): string | null;
     /** Remove every key matching a prefix (relative, without the sendora_ namespace). */
     clearPrefix(prefix: string): void;
     private checkLocalStorage;
@@ -327,10 +359,18 @@ declare class Analytics {
      * unchanged.
      */
     reset(rotateAnonymousId?: boolean): void;
+    /**
+     * ADR-033 [2c] analytics quarantine: the stored session was WITHHELD (its
+     * JWT `project` claim disagrees with `expectedProjectId`), so stop
+     * attributing events to that user — IN MEMORY ONLY. The persisted `user_id`
+     * is deliberately untouched: a withheld hydrate performs zero storage writes
+     * so a re-init with the matching id (or a rollback) sees identical bytes.
+     */
+    withholdIdentity(): void;
     /**
      * Drop any pending events without flushing. Used by Auth on
-     * cross-account signin to ensure the prior identity's queued
-     * events don't surface under the next user.
+     * `deleteAccount()` (the s58.353 rule) so a deleted identity's queued
+     * events are not POSTed after the account is gone.
      */
     dropQueue(): void;
     flush(): Promise<void>;
@@ -439,40 +479,64 @@ declare class Chatbot {
 }
 
 /**
- * Auth Service surface for the web SDK.
+ * ADR-033 wave 1 (3.24.0) — the SDK's OWN copy of the auth-machine vocabulary.
  *
- * Three flows:
- *   signInAnonymously()           — mint a session with no email yet.
- *   signUp(email, password)       — if currently anonymous, upgrades
- *                                   the same row (preserves user_id);
- *                                   otherwise creates a fresh account.
- *   signIn(email, password)       — log in to an existing account.
+ * `packages/shared/src/auth-machine/` is the law (states, events, the transition
+ * table, the result unions); this file mirrors the shapes a running SDK needs,
+ * because the published package has zero runtime dependencies and cannot import
+ * `@sendora/shared`. `test/auth-machine-conformance.test.ts` loads the shared
+ * conformance JSON and asserts these constants EQUAL the fixture's, so a drift
+ * between the two is red, not a comment somebody has to notice.
  *
- * Identity ordering — a failed auth attempt leaves the caller exactly
- * as it found them. Every credentialed path captures the anonymous
- * refresh token into a local, makes the call, validates the response,
- * and only THEN clears the outgoing identity and persists the new one.
- * The stored refresh token is the only durable handle on an anonymous
- * account, so a clear that isn't followed by a successful persist
- * strands it permanently. (Cost of the ordering: a track() fired during
- * the round-trip attaches to the prior identity — correct, the user
- * isn't identified until the response says so, and the backend
- * reattributes those events via the device takeover.) All public auth
- * operations are serialized through a single-flight chain so a
- * double-submit can't mint two anonymous users or interleave a
- * signIn + signOut.
- *
- * Tokens are validated non-empty before persisting (rejects malformed
- * responses that would otherwise install an `id = ""` user). Access
- * token expiry is tracked locally; getAccessToken() returns null past
- * expiry and triggers a single-flight refresh on the next call.
+ * ⚠ ADDITIVE ONLY (ADR-023 §1.1). Never remove a member, never make an optional
+ * field required, never narrow a type — an installed app runs a frozen SDK
+ * forever. Consumers MUST default-branch on every closed union here (§3.5
+ * NORMATIVE): a later additive member must not crash a `switch`.
+ */
+/**
+ * The five client states. `unknown` ≠ `signed_out` and `withheld` ≠ `signed_out`
+ * — `status()` is the only call that tells them apart, because `getUserSync()`
+ * is `null` and `isReady()` is `true` in all three.
  *
- * Storage is localStorage by default — XSS-readable. Hosts that need
- * stricter isolation can pass an in-memory storage adapter via the
- * `tokenStore: "memory"` config flag, which keeps tokens off disk
- * (session lost on page reload).
+ *  - `unknown`     hydrated with a refresh token but no readable user (or an
+ *                  unreadable `project` claim under `expectedProjectId`). MINT is
+ *                  QUEUED here, never run; the single gap-fill refresh settles it.
+ *  - `signed_out`  no refresh token. The ONLY state in which MINT executes.
+ *  - `anonymous`   refresh token + `user.isAnonymous === true`.
+ *  - `identified`  refresh token + `user.isAnonymous === false`.
+ *  - `withheld`    a stored session refused because its JWT `project` claim
+ *                  disagrees with `init({expectedProjectId})`. A pure function of
+ *                  (disk record, config); never persisted.
  */
-
+declare const AUTH_STATES: readonly ["unknown", "signed_out", "anonymous", "identified", "withheld"];
+type AuthStatus = (typeof AUTH_STATES)[number];
+/** K — the held-guest capacity (§3.2, §8-Q19). FIXED slots, bound at MINT: T = |held| + (current anonymous ? 1 : 0) ≤ K. */
+declare const HELD_GUEST_SLOTS = 5;
+/** The ONLY server code that means "this refresh token is dead" (INV-6). A project mismatch is NEVER mapped onto it (INV-15). */
+declare const DEAD_CODES: readonly ["INVALID_REFRESH_TOKEN"];
+/** `error.details.endReason` on an `INVALID_REFRESH_TOKEN` rejection (B11). */
+declare const REFRESH_END_REASONS: readonly ["expired", "revoked", "evicted", "deleted", "reuse", "unknown"];
+type RefreshEndReason = (typeof REFRESH_END_REASONS)[number];
+/**
+ * A HELD slot is released on a dead verdict ONLY for these end reasons (§3.3
+ * REFRESH_DEAD-held row). On `reuse` or an ABSENT `endReason` the slot is KEPT
+ * and a retryable `RESTORE_FAILED` surfaces instead — a reuse verdict on a
+ * preserved-family guest does not prove the guest is gone (s58.316).
+ */
+declare const RELEASE_HELD_ON_END_REASONS: readonly ["deleted", "revoked", "expired"];
+/** The refusal code when a destructive/identity held-guest verb is called with no `id` while 2+ guests are held (§3.5). */
+declare const AMBIGUOUS_HELD_GUEST: "AMBIGUOUS_HELD_GUEST";
+/**
+ * Every verb family that `withheld` refuses with
+ * `AuthError{kind:'config', code:'SESSION_WITHHELD', retryable:false}` — no
+ * network, no storage write (§3.2). Mirrors the shared `REJECTED_IN_WITHHELD`.
+ */
+declare const REJECTED_IN_WITHHELD: readonly ["MINT", "SIGN_IN", "LINK", "CLAIM", "RESTORE", "DISCARD", "DELETE", "SESSION_VERB"];
+/** The two project-guard refusals REUSE the closed `config` kind (§3.5 [2c]); `AuthErrorKind` is NOT widened. */
+declare const AUTH_WITHHELD_CODES: {
+    readonly SESSION_WITHHELD: "SESSION_WITHHELD";
+    readonly PROJECT_MISMATCH: "PROJECT_MISMATCH";
+};
 interface AuthUser {
     id: string;
     email: string | null;
@@ -491,7 +555,210 @@ interface AuthUser {
      */
     signupMethod?: string | null;
     lastLoginMethod?: string | null;
+    /**
+     * The account's project pool (ADR-033 B17) — the same value as the JWT
+     * `project` claim. A string, an EXPLICIT `null` for the org-wide pool, or
+     * absent against a pre-B17 backend. Never read absent as null. sdk-web 3.24.0+.
+     */
+    project?: string | null;
+}
+type SocialCredentialProvider = "google" | "github" | "apple" | "microsoft" | "linkedin" | "facebook" | "twitter" | "discord";
+type Credential = {
+    kind: "password";
+    email: string;
+    password: string;
+} | {
+    kind: SocialCredentialProvider;
+    code?: string;
+    idToken?: string;
+    redirectUri?: string;
+    codeVerifier?: string;
+    appleName?: {
+        firstName?: string;
+        lastName?: string;
+    };
+} | {
+    kind: "gameCenter";
+    publicKeyUrl: string;
+    signature: string;
+    salt: string;
+    timestamp: number;
+    teamPlayerId: string;
+    bundleId: string;
+} | {
+    kind: "playGames";
+    serverAuthCode: string;
+} | {
+    kind: "magicLink";
+    token: string;
+} | {
+    kind: "emailOtp";
+    email: string;
+    code: string;
+}
+/** The WebAuthn assertion as the SDK's own encoder produces it; forwarded to `passkeys/authenticate/finish`. */
+ | {
+    kind: "passkey";
+    assertion: Record<string, unknown>;
+    userId?: string | null;
+} | {
+    kind: "mfa";
+    challengeToken: string;
+    code: string;
+};
+/** Alias — the DOM lib also declares a global `Credential`; import this name when the collision bites. */
+type AuthCredential = Credential;
+type CredentialKind = Credential["kind"];
+/**
+ * `previous` is what the SWITCH replaced. `held: true` ⇔ the previous slot was
+ * anonymous and is now in a held slot (§3.1.1). `previous.isAnonymous === false`
+ * ⇒ an identified → identified switch: the app must skip any merge and reset
+ * local save state. `reactivated` surfaces a cancelled pending self-service
+ * deletion (s58.269).
+ */
+type SignInResult = {
+    status: "done";
+    user: AuthUser;
+    previous: {
+        userId: string;
+        isAnonymous: boolean;
+        held: boolean;
+    } | null;
+    reactivated: boolean;
+} | {
+    status: "mfa_required";
+    challengeToken: string;
+    /** Completes the challenge. The MFA context lives on the attempt, never in a nullable field cleared by hand (§3.2). */
+    verify(code: string): Promise<SignInResult>;
+};
+type LinkCollision = "identity" | "email";
+/**
+ * Three outcomes, nothing mutated on the two refusals (INV-12, B2).
+ *
+ *  - `done{alreadyLinked:true}` — the same identity is already on this account:
+ *    a quiet 200, NO event, NO revoke of other sessions, NO step-up (B13).
+ *  - `done{attached}` — `upgraded` is true when the caller was anonymous (same
+ *    `sub`, rotated pair); false on an identified attach (no rotation).
+ *  - `credential_in_use` — owned by another account (409, B14 payload).
+ *    `switchAccount()` is the ONLY path from a refused link to a sign-in and is
+ *    BOUND to the refused credential (INV-14): the same payload while it is
+ *    under 5 min old; after that web has no native re-fetch, so it rejects
+ *    `CREDENTIAL_STALE` and the app re-collects the credential.
+ *  - `recent_auth_required` — the credential is fine, the session is stale
+ *    (403). State unchanged. There is deliberately NO `reauthenticate()`
+ *    closure that accepts the credential being linked (Q8).
+ */
+type LinkResult = {
+    status: "done";
+    user: AuthUser;
+    upgraded: boolean;
+    alreadyLinked: boolean;
+} | {
+    status: "credential_in_use";
+    provider: string;
+    collision: LinkCollision;
+    switchAccount(): Promise<SignInResult>;
+    keepCurrent(): void;
+} | {
+    status: "recent_auth_required";
+};
+/**
+ * ONE held slot as persisted at `auth_held_<i>`. Written ONLY by a HOLD, by a
+ * per-slot REFRESH_OK routed by token, or by DELETE stamping `autoRestore:false`.
+ * ⚠ NO access token and NO user blob: restore/claim always refresh first.
+ */
+interface HeldGuest {
+    v: 1;
+    userId: string;
+    sid: string;
+    refreshToken: string;
+    tokenAtHold: string;
+    heldAt: number;
+    project: string | null;
+    autoRestore: boolean;
+}
+/** What `getHeldGuests()` returns — the slot MINUS its tokens (§3.5: "never exposes tokens"). */
+type HeldGuestSummary = Pick<HeldGuest, "userId" | "heldAt" | "autoRestore" | "project">;
+/** `guest_released.reason` — every exit from a slot names one. `dead` is NOT an erasure signal. */
+type GuestReleasedReason = "claimed" | "restored" | "discarded" | "dead" | "reset";
+/** What `getWithheld()` returns while `status() === "withheld"`. Never exposes tokens. */
+interface WithheldInfo {
+    reason: "project_mismatch";
+    expectedProjectId: string;
+    actualProjectId: string | null;
+    userId: string;
+    isAnonymous: boolean;
 }
+/**
+ * Why a `signed_in` fired. `restore` ⇒ the app must re-register push (the held
+ * guest's push tokens were erased if it had been deleted elsewhere); `link` =
+ * the legacy same-`sub` promotion the legacy-signature methods
+ * (`loginSocial({link:true})`, `signInWith*({link:true})`, `signUp`) keep
+ * emitting (§8-Q18, ADR-023). Optional on the wire: a replayed `signed_in` and a
+ * cross-tab re-hydrate carry none.
+ */
+type AuthSignedInCause = "mint" | "sign_in" | "restore" | "link";
+/** What changed the user object without changing the `sub`. */
+type AuthUserUpdatedCause = "link" | "unlink" | "email_verified" | "refresh" | "merge";
+/** The server's own counters from `POST /merge` (s58.317: real numbers, not placeholders). */
+interface MergeStats {
+    mergedUserId: string;
+    deletedAnonymousId: string;
+    eventsReassigned: number;
+    profilesReassigned: number;
+    entitiesReassigned: number;
+    pushTokensReassigned: number;
+}
+/** `deleteAccount()` result — the pre-wave fields plus the additive `heldGuests` count (§3.5). */
+interface DeleteAccountResult {
+    status: "purged" | "pending";
+    scheduledPurgeAt: string | null;
+    graceDays: number;
+    /** Held guests still on this device after the delete (each stamped `autoRestore:false`). */
+    heldGuests: number;
+    /** Under `alsoDiscardHeldGuests:true`: the guest ids whose `/guest/discard` FAILED (still held). Absent otherwise. */
+    discardFailed?: string[];
+}
+
+/**
+ * Auth Service surface for the web SDK — ADR-033 wave 1 (3.24.0): "One Slot,
+ * Two Verbs". Full design: `docs/decisions/033-sdk-auth-mechanism.md`.
+ *
+ * THE MECHANISM IN FOUR SENTENCES.
+ *   1. Sign-in never carries the guest. A sign-in from a guest device HOLDS the
+ *      guest in one of K = 5 fixed on-device slots (`auth_held_0..4`) and
+ *      switches; the server row survives. No request body of this SDK ever
+ *      contains `prevAnonRefreshToken`, `linkAnonymous` or `onCredentialInUse`
+ *      (INV-3) — the legacy device-takeover path is unreachable from here.
+ *   2. Link is the only upgrade. `signUp()`, `loginSocial({link:true})`,
+ *      `link*()` and the typed `link()` go to `/me/link/*` on the current
+ *      Bearer session (same `sub`); a collision is a typed value, never a merge.
+ *   3. One slot, one writer. `commit()` below is the ONLY code that assigns
+ *      `user`/tokens, writes the frozen keys + `auth_session`, arms/stops the
+ *      cron, decides the emitted event and tells analytics the wipe reason.
+ *      Every public method computes a PROPOSAL (a network call that changes
+ *      nothing) and hands it to `commit()`, which applies it only if the
+ *      session it was derived from is still current — `sid` for identity
+ *      commits, the sent refresh token for token commits (INV-2).
+ *   4. Boot is observable. `status()` is `unknown | signed_out | anonymous |
+ *      identified | withheld`; `authStateReady()` resolves after hydrate and
+ *      never waits on the network.
+ *
+ * The transition table lives as DATA in `packages/shared/src/auth-machine/`
+ * and `test/auth-machine-conformance.test.ts` replays every row against this
+ * file (INV-11). Storage key names live in `auth-storage.ts` and nowhere else
+ * (INV-1); the ProjectGuard is the verbatim `project-verdict.ts` (INV-15).
+ *
+ * Token liveness machinery (two-deadline guard, `clockSkewConfirmed`, single-
+ * flight, capped backoff, `visibilitychange` reset) is kept verbatim from
+ * 3.18.0 — it never decides identity except through the single dead verdict
+ * `INVALID_REFRESH_TOKEN` (INV-6).
+ *
+ * Storage is localStorage by default — XSS-readable. Hosts that need stricter
+ * isolation pass `tokenStore: "memory"`, which keeps every auth key (incl. the
+ * held slots) in a JS `Map` for the life of the tab.
+ */
+
 interface AuthTokens {
     accessToken: string;
     refreshToken: string;
@@ -509,44 +776,80 @@ interface DeviceTakeoverEvent {
     at: Date;
 }
 type DeviceTakeoverListener = (evt: DeviceTakeoverEvent) => void;
+/** @see AuthApiResponse.anonRetirement */
+type AnonRetirementOutcome = "retired" | "preserved" | "none";
 /**
  * Detail handed to `onDeletionCancelled` subscribers (s58.269). Fires once
  * per sign-in that cancelled a pending self-service deletion within grace —
  * the account is restored with the SAME user_id.
  */
-/** @see AuthApiResponse.anonRetirement */
-type AnonRetirementOutcome = "retired" | "preserved" | "none";
 interface DeletionCancelledEvent {
     userId: string;
     at: Date;
 }
 type DeletionCancelledListener = (evt: DeletionCancelledEvent) => void;
 /**
- * Why the local session ended (3.12.0). Before this, a session that died in
- * the background emitted NOTHING — an app could not tell a deliberate sign-out
- * apart from an expired refresh token, and only discovered the difference when
- * `getAccessToken()` started returning null.
+ * Why the local session ended (3.12.0; widened additively in 3.24.0 — ADR-033 B11).
  *
- * - `user`            — the app called `signOut()`.
- * - `session_expired` — the server rejected the stored refresh token (revoked,
- *                       expired, rotated away). Transient network failures and
- *                       rate limits do NOT produce this.
- * - `account_deleted` — a self-service account deletion succeeded (the native
- *                       SDKs' `deleteAccount()`; reserved here for parity).
+ * - `user`            — the app called `signOut()` / `discardWithheld()`.
+ * - `session_expired` — the server rejected the stored refresh token. EVERY
+ *                       dead verdict, whatever the server's detail: read the
+ *                       event's `endReason` (`revoked` / `deleted` / `expired` /
+ *                       `reuse` / `unknown`) for that. Transient network
+ *                       failures and rate limits do NOT produce this.
+ * - `account_deleted` — `deleteAccount()` succeeded.
+ * - `revoked` / `evicted` / `deleted` — ⚠ emitted by 3.24.0 ONLY, never since
+ *                       3.24.1. 3.24.0 put the server's `endReason` here, which
+ *                       renamed "account deleted elsewhere" / "sessions revoked"
+ *                       (both `session_expired` through 3.23.0) and silently
+ *                       broke listeners matching `session_expired`. Kept in the
+ *                       type so code written against 3.24.0 still compiles.
+ * ⚠ Consumers MUST default-branch — later values are additive.
  */
-type AuthSignedOutReason = "user" | "session_expired" | "account_deleted";
+type AuthSignedOutReason = "user" | "session_expired" | "account_deleted" | "revoked" | "evicted" | "deleted";
 /**
- * A single auth-state transition (3.12.0). Subscribe with
- * `onAuthStateChanged` — one stream covering everything that used to need
- * separate listeners (or had none at all).
+ * A single auth-state transition (3.12.0; ADR-033 members added in 3.24.0).
+ * Subscribe with `onAuthStateChanged` — one stream covering everything.
+ *
+ * - `signed_in`         — a session was established or replaced. `cause`
+ *                         (3.24.0): `mint` | `sign_in` | `restore` (re-register
+ *                         push) | `link` (the legacy same-`sub` promotion
+ *                         `signUp()` / `loginSocial({link:true})` keep emitting).
+ *                         Absent on the subscribe-time replay and on a cross-tab
+ *                         re-hydrate.
+ * - `signed_out`        — the local session is gone; `reason` says why.
+ *                         `endReason` (3.24.1) = the server's own verdict on a
+ *                         dead refresh token; absent otherwise.
+ * - `device_takeover`   — LEGACY: an anonymous row was retired server-side. A
+ *                         3.24.0 sign-in never requests that, so it fires only
+ *                         when the SERVER reports one (it will not for this SDK).
+ * - `deletion_cancelled`— a sign-in cancelled a pending self-service deletion.
+ * - `initial`           — the settled boot state, exactly once per subscriber,
+ *                         INCLUDING `signed_out`, `unknown` and `withheld`.
+ * - `user_updated`      — same `sub`, different user object (`link` / `unlink` /
+ *                         `email_verified` / `refresh` / `merge`). Never a
+ *                         `signed_in` — the identity did not change.
+ * - `guest_held`        — a guest was moved into a held slot (`count` = slots
+ *                         now held).
+ * - `guest_released`    — a held slot was emptied; `reason` names the exit.
+ *                         ⚠ `dead` = "the server said unavailable when the
+ *                         token was presented", NOT an erasure signal — say
+ *                         "unavailable", never "lost".
+ * - `session_withheld`  — an in-process transition INTO `withheld` (a refresh
+ *                         answered with a mismatching `project` claim). Never
+ *                         replayed: a hydrate that lands in `withheld` emits
+ *                         `initial{status:'withheld'}` instead.
+ * ⚠ Consumers MUST default-branch on `event`.
  */
 type AuthStateChange = {
     event: "signed_in";
     user: AuthUser;
+    cause?: AuthSignedInCause;
 } | {
     event: "signed_out";
     user: null;
     reason: AuthSignedOutReason;
+    endReason?: RefreshEndReason;
 } | {
     event: "device_takeover";
     user: AuthUser | null;
@@ -554,6 +857,30 @@ type AuthStateChange = {
 } | {
     event: "deletion_cancelled";
     user: AuthUser | null;
+} | {
+    event: "initial";
+    status: AuthStatus;
+    user: AuthUser | null;
+    withheld?: WithheldInfo;
+} | {
+    event: "user_updated";
+    user: AuthUser;
+    cause: AuthUserUpdatedCause;
+} | {
+    event: "guest_held";
+    userId: string;
+    count: number;
+} | {
+    event: "guest_released";
+    userId: string;
+    reason: GuestReleasedReason;
+    endReason?: RefreshEndReason;
+} | {
+    event: "session_withheld";
+    reason: "project_mismatch";
+    expectedProjectId: string;
+    actualProjectId: string | null;
+    userId: string;
 };
 type AuthStateListener = (change: AuthStateChange) => void;
 declare class EmailAlreadyTakenError extends Error {
@@ -563,7 +890,8 @@ declare class EmailAlreadyTakenError extends Error {
  * `signUp()` was called on a session already signed in with an identity (not
  * anonymous). Creating a second account would orphan the current one — use
  * `linkEmailPassword()` / `linkGoogle()` / … (ADR-030) to add the credential
- * to THIS account, or sign out first.
+ * to THIS account, or sign out first. Since 3.24.0 this is decided LOCALLY from
+ * `status()`, with no round-trip.
  */
 declare class AlreadyIdentifiedError extends Error {
     constructor(message?: string);
@@ -599,21 +927,18 @@ declare class CredentialInUseError extends Error {
     });
 }
 /**
- * What a sign-in should do when the credential you present already belongs to
- * an account (3.14.0).
+ * What `loginSocial({ link: true, onCredentialInUse })` does when the credential
+ * you present already belongs to another account (3.14.0; re-based on ADR-033
+ * in 3.24.0).
  *
- * **You usually want the default — omit this.** It adopts the other account
- * silently when nothing would be destroyed, and refuses when a live anonymous
- * session would be deleted.
+ * - `"adopt"` — fall through to a plain sign-in with the SAME credential: an
+ *   explicit, consented SWITCH. From a guest the guest is HELD on this device
+ *   (never deleted); from an identified session nothing is held.
+ * - `"reject"` / omitted — throw `CredentialInUseError`; nothing changes.
  *
- * - `"adopt"` — always adopt, even when it retires this browser's anonymous
- *   account (its row is deleted server-side). Pre-3.14.0 behaviour.
- * - `"reject"` — always throw `CredentialInUseError`, even on a harmless
- *   collision.
- *
- * Mirrors Firebase `linkWithCredential` (`auth/credential-already-in-use`) and
- * Supabase `linkIdentity` (`identity_already_exists`), both of which fail
- * rather than adopt. `"reject"` blocks the switch; it does not merge.
+ * ⚠ Since 3.24.0 NOTHING here reaches the server as a field: the collision is
+ * decided on the link route (409) and the policy is applied client-side.
+ * Nothing on the server can delete a guest as a side effect of a sign-in.
  */
 type CredentialCollisionPolicy = "adopt" | "reject";
 /**
@@ -624,6 +949,10 @@ type CredentialCollisionPolicy = "adopt" | "reject";
  * attempt never changes the local session.** An offline sign-in, a mistyped
  * OTP, a dismissed passkey sheet and a 429 all leave `getCurrentUser()` and the
  * stored refresh token exactly as they were.
+ *
+ * ⚠ ADR-033 deliberately does NOT widen this set: `SESSION_WITHHELD` and
+ * `PROJECT_MISMATCH` are `kind: "config"`; the held-guest refusals reuse the
+ * existing kinds (see `classifyAuthErrorKind`).
  */
 type AuthErrorKind = "network" | "server" | "rate_limited" | "invalid_credential" | "account_locked" | "credential_in_use" | "last_credential" | "recent_auth_required" | "already_identified" | "cancelled" | "config" | "unknown";
 declare class AuthError extends Error {
@@ -651,6 +980,31 @@ declare class AuthError extends Error {
         kind?: AuthErrorKind;
     });
 }
+/**
+ * T == K (ADR-033 §3.3): every held slot is occupied and the verb would need
+ * one more. Thrown by `signInAnonymously({forceNew:true})` at the cap, and by
+ * a plain mint in `signed_out` when every slot is ineligible for auto-restore
+ * (each stamped `autoRestore:false` by `deleteAccount()`, or project-withheld)
+ * — the one boot corner that does not self-heal (§8-Q22). Nothing is mutated;
+ * the app must `restoreHeldGuest(id)` or `discardHeldGuest(id)`.
+ */
+declare class HeldGuestLimitError extends AuthError {
+    readonly heldGuests: number;
+    constructor(heldGuests: number, message?: string);
+}
+/**
+ * The held slot's `project` claim (recorded at HOLD, or judged on the refresh
+ * response when it was unreadable at HOLD) disagrees with
+ * `expectedProjectId ?? config.projectId` (ADR-033 §3.5). A CLIENT-SIDE check:
+ * the server does not enforce it on refresh. The slot is KEPT, excluded from
+ * auto-restore, and still counts toward T.
+ */
+declare class HeldGuestProjectMismatch extends AuthError {
+    readonly userId: string;
+    readonly expectedProjectId: string;
+    readonly actualProjectId: string | null;
+    constructor(userId: string, expectedProjectId: string, actualProjectId: string | null);
+}
 /** One credential linked to an account (ADR-030 read side, s58.270). */
 type LinkedIdentity = {
     provider: string;
@@ -673,15 +1027,33 @@ type LinkedIdentitiesResponse = {
     identities: LinkedIdentity[];
     hasPassword: boolean;
 };
+/** Hooks the parent SDK wires in (`index.ts`). */
+interface AuthHooks {
+    /** ADR-033 [2c]: null the analytics `userId` IN MEMORY only — the persisted `user_id` is untouched. */
+    onIdentityWithheld?: () => void;
+}
 declare class Auth {
     private http;
     private storage;
+    private store;
     private analytics;
     private flags;
     private chatbot;
+    private hooks;
+    /** ADR-033 [2c]: the opt-in project guard. Validated by `index.ts` (UUID, equal to `projectId` when both set). */
+    private readonly expectedProjectId;
+    /** The project a held slot is judged against on RESTORE: `expectedProjectId ?? config.projectId`. */
+    private readonly slotProjectAnchor;
+    /** §8-Q1: restore the newest eligible held guest before minting (default ON). */
+    private readonly autoRestoreHeldGuest;
+    private state;
+    /** The installed session, or null in `unknown` / `signed_out` / `withheld`. */
+    private record;
     private user;
     private accessToken;
     private accessExpiresAt;
+    /** `withheld` only: what was refused, and the refresh token the discard CAS keys on. Never persisted. */
+    private withheld;
     /**
      * Set once we have PROOF the clock runs fast: a token the server minted
      * SECONDS AGO already reads past its own `exp`. A fresh token is never
@@ -699,6 +1071,14 @@ declare class Auth {
     private clockSkewConfirmed;
     private inflight;
     private refreshInflight;
+    /**
+     * True while an identity-changing attempt (mint / sign-in / link / claim /
+     * restore) is on the wire. The proactive cron does not START a refresh while
+     * it is set (§3.3 scheduling rule 2); the attempt itself awaits any in-flight
+     * refresh at start AND at commit (rule 1), which is what makes the sid-CAS a
+     * backstop rather than the first line.
+     */
+    private attemptInFlight;
     /**
      * Wave 63 — refresh failure back-pressure (parity with sdk-react-
      * native 1.1.0 Wave 62 fix). http.ts already times out at 10s; this
@@ -713,31 +1093,38 @@ declare class Auth {
     private visibilityResetUnsub;
     private proactiveRefreshTimer;
     private proactiveRefreshCleanup;
+    /** 3.24.0 (e): another tab wrote one of our auth keys → re-run HYDRATE through commit. */
+    private storageEventUnsub;
+    private rehydrateScheduled;
     private takeoverListeners;
     private lastTakeover;
     private deletionCancelledListeners;
     private lastDeletionCancelled;
     private lastAnonRetirement;
     private authStateListeners;
-    /**
-     * Anon refresh token captured at `signIn()` time, stashed keyed to the
-     * issued `mfaChallengeToken` so the later `challengeMfa()` can forward it
-     * for device-takeover (s58.111). The MFA branch returns without persisting,
-     * so the anon identity has to survive the whole challenge round-trip —
-     * clearing it at signIn() time both orphaned the anon row (two user_ids on
-     * one device, duplicate pushes) and, for an abandoned challenge, left the
-     * account with no local handle at all.
-     */
-    private pendingAnonTakeover;
+    private identityWithheldListeners;
     /**
      * True once the constructor has finished restoring from storage.
      * Distinguishes "no session restored YET" from "genuinely signed out" for
      * `onAuthStateChanged`'s replay-on-subscribe.
      */
     private hydrated;
-    constructor(_config: SendoraConfig, http: HttpClient, storage: Storage, analytics: Analytics, flags: FeatureFlags, chatbot: Chatbot);
-    /** Returns the cached current user or null if signed out. */
+    constructor(config: SendoraConfig, http: HttpClient, storage: Storage, analytics: Analytics, flags: FeatureFlags, chatbot: Chatbot, hooks?: AuthHooks);
+    /**
+     * The settled client state — a closed enum. `unknown` ≠ `signed_out` and
+     * `withheld` ≠ `signed_out`; this is the ONLY call that tells them apart
+     * (`getCurrentUser()` is null and `isReady()` is true in all three).
+     * ⚠ Default-branch: later values are additive.
+     */
+    status(): AuthStatus;
+    /** Resolves after hydrate with the settled status — never waits on the network. May be `unknown` or `withheld`. */
+    authStateReady(): Promise<AuthStatus>;
+    /** Returns the cached current user or null if signed out (also null in `unknown` and `withheld`). */
     getCurrentUser(): AuthUser | null;
+    /** Alias of `getCurrentUser()` (parity with the native SDKs' synchronous verified-principal accessor). */
+    getUserSync(): AuthUser | null;
+    /** True once storage has been read. Always true after `init()` on web (hydrate is synchronous). */
+    isReady(): boolean;
     /**
      * Register a callback fired when the backend retires an anon
      * `user_id` during a signin on this tab. Use it to delete the
@@ -745,20 +1132,22 @@ declare class Auth {
      * records are already cleaned up server-side. Returns an
      * unsubscribe function.
      *
-     * Fires on every identified-signin path: signIn, loginSocial,
-     * verifyMagicLink, verifyEmailOtp, challengeMfa, signInWithPasskey,
-     * consumeSsoTokenFromUrl — fired centrally from `persist()` whenever the
-     * response carries `retiredAnonUserId`.
+     * ⚠ LEGACY after ADR-033 (3.24.0). This SDK never sends the guest hint
+     * that triggers a server-side retirement, so for a 3.24.0 sign-in this
+     * listener NEVER fires: the device's guest is HELD on this device instead
+     * (`onAuthStateChanged` → `guest_held`, `getHeldGuests()`). It stays
+     * registered and fires only when the SERVER reports a retirement, which
+     * only a pre-3.24.0 sign-in can request.
      *
      * ⚠ A takeover means the anonymous account on this device was retired —
      * its row is DELETED server-side — and the call still resolved
-     * SUCCESSFULLY. This listener is the only client-side signal. On the
-     * native SDKs the same applies to the Game Center / Play Games sign-ins,
-     * where an already-owned player identity is adopted; pass
-     * `onCredentialInUse: "reject"` if you would rather it not happen.
+     * SUCCESSFULLY. This listener is the only client-side signal for THAT
+     * (legacy) path. On the native SDKs the same applied to the Game Center /
+     * Play Games sign-ins, where an already-owned player identity was adopted.
      *
      * Local-only — survives webhook receiver downtime. For server-pipeline
-     * cleanup also subscribe to the `auth.device_takeover` webhook.
+     * cleanup also subscribe to the `auth.device_takeover` webhook (legacy
+     * SDK sign-ins only) and `auth.user_merged` (the explicit `claimHeldGuest()`).
      */
     onDeviceTakeover(listener: DeviceTakeoverListener): () => void;
     /**
@@ -776,11 +1165,14 @@ declare class Auth {
      * rejected the stored refresh token) used to emit no signal whatsoever, so
      * an app could not distinguish it from a deliberate sign-out and only
      * noticed when `getAccessToken()` began returning null. That transition is
-     * now `{ event: "signed_out", reason: "session_expired" }`.
+     * now `{ event: "signed_out", reason: "session_expired" }`, with the server's
+     * own verdict in `endReason` (3.24.1; 3.24.0 alone put it in `reason`).
      *
-     * Fires the CURRENT state immediately on subscribe when a session was
-     * restored from storage (`signed_in`), so a subscriber never misses the
-     * state it started in. Nothing is emitted for a signed-out cold start.
+     * Replay on subscribe (3.24.0): `initial{status, user, withheld?}` is emitted
+     * exactly once per subscriber, INCLUDING `signed_out`, `unknown` and
+     * `withheld`; when a session is installed the pre-3.24.0 `signed_in{user}`
+     * replay follows it (kept for ADR-023 — nothing a 3.12.0 subscriber relied on
+     * is removed; it carries no `cause`).
      *
      * A failed sign-in emits NOTHING: the session is unchanged, so there is no
      * transition to report — the rejected promise is the whole story.
@@ -798,13 +1190,20 @@ declare class Auth {
      * affects auth state. Returns an unsubscribe function.
      */
     onAuthStateChanged(listener: AuthStateListener): () => void;
+    /**
+     * ADR-033 [2c] analytics quarantine hook: fires when a stored session is
+     * WITHHELD (hydrate or refresh under a mismatching `expectedProjectId`), so
+     * the parent SDK stops attributing events to that user IN MEMORY. The
+     * persisted `user_id` is untouched. Returns an unsubscribe function.
+     */
+    onIdentityWithheld(listener: () => void): () => void;
     /** Fan a state change out to subscribers. Never throws. */
     private emitAuthState;
     /**
      * Internal — called from every identified-signin path with the
      * `retiredAnonUserId` parsed off the backend response (or off
      * the SSO redirect fragment). Snapshot + dispatch synchronously
-     * since handlers run on the same event loop turn as persist().
+     * since handlers run on the same event loop turn as the install.
      *
      * Validates UUID shape before dispatch. The value comes from a URL
      * fragment / response body that — under XSS — could be controlled.
@@ -826,46 +1225,72 @@ declare class Auth {
      * What the last sign-in did with this device's guest account, or null if no
      * sign-in has happened this session (s58.278).
      *
-     * The one worth acting on is `"preserved"`: a guest account was presented,
-     * was NOT retired, and is therefore still alive server-side — so "recover
-     * your other account" is a real offer rather than a guess. Cleared on signOut.
+     * ⚠ Since 3.24.0 a sign-in from this SDK never presents the guest, so the
+     * server's answer is always `"none"` — the guest is HELD on this device and
+     * answerable synchronously via `getHeldGuests()`. Kept for apps reading it;
+     * recorded ONLY when the server states it. Cleared on signOut.
      */
     getLastAnonRetirement(): AnonRetirementOutcome | null;
     private fireDeletionCancelled;
     /**
-     * Returns the stored anon refresh token iff the local subject is
-     * currently anonymous. Used by every identified-session-mint path
-     * so the backend can run device-takeover (s58.111+).
+     * Record what the SERVER said about a sign-in response, after the install
+     * commit: the guest outcome (only when stated — an older backend omits it,
+     * which is not `none`), a cancelled deletion, and the legacy retirement id.
      */
-    private takeoverHint;
+    private recordServerSignals;
     /**
-     * Returns a VALID (non-expired) access token, or null.
+     * Apply one transaction, or drop it. Returns `true` when applied.
      *
-     * Hard contract (parity with sdk-react-native / sdk-ios / sdk-android
-     * and the industry token-client pattern — Supabase
-     * `_callRefreshToken`, Auth0 `getTokenSilently`, Firebase
-     * `getIdToken`): NEVER returns a token past its `exp`. Callers attach
-     * the result as a Bearer to arbitrary resource servers — including
-     * third-party backends (PostgREST/Supabase) that have NO knowledge of
-     * Sendora's own refresh grace window — so a token must be either
-     * fresh or absent.
+     * Everything that mutates identity happens here and nowhere else: the
+     * in-memory slot (`state` / `record` / `user` / tokens / `withheld`), the
+     * storage keys (via `SessionStore`), the proactive cron, the analytics /
+     * flags / chatbot hooks, and the emitted `onAuthStateChanged` event. Public
+     * methods only build proposals.
      *
-     *  1. Cached token with comfortable life left (>= REFRESH_SAFETY_MS
-     *     skew before exp) → return it. Fast path, no I/O.
-     *  2. No cached token AND no refresh token in storage → null.
-     *  3. Expired/near-expiry but a refresh chain exists:
-     *     a. A refresh is already inflight → AWAIT it and return the
-     *        fresh token. Single-flight: concurrent callers coalesce
-     *        onto one `/token/refresh`, nobody is handed a stale token.
-     *        The inflight fetch is AbortController-bounded (http.ts caps
-     *        `/auth-service/*` at 10s) so awaiting never hangs — that
-     *        bounded fetch, not the old stale-token return, is the real
-     *        cold-launch hang fix.
-     *     b. In backoff cooldown after a failed refresh → null (honest
-     *        "no usable token", not a provably-expired one; the
-     *        `visibilitychange` hook clears the cooldown on tab focus).
-     *     c. Otherwise → fire the refresh and await it.
-     */
+     * CAS (INV-2): an identity commit names the `sid` it was derived from
+     * (`expectSid`); a token commit names the refresh token it sent
+     * (`expectRefresh`). A result that no longer matches the current session is
+     * DROPPED here — the caller then revokes its server copy (sign-in) or simply
+     * returns (refresh), and the device is left exactly as found.
+     */
+    private commit;
+    private commitInstall;
+    private commitClear;
+    private commitWithhold;
+    /**
+     * Read the disk and commit the state it describes. `boot` = the
+     * constructor (emits nothing; subscribers get `initial`). `storage_event` =
+     * another tab changed our keys (3.24.0 (e)); the same rules, applied as
+     * transitions from the current in-memory state, CAS-safe because every
+     * branch is a commit.
+     */
+    private hydrateFromDisk;
+    /**
+     * 3.24.0 (e) — the Web Locks cross-tab mutex is GONE (Supabase removed the
+     * same lock in 2.107.0 after seven failure classes). Cross-tab coherence is
+     * now: the token CAS (a rotation another tab performed is on disk and the
+     * refresh sends what is on disk) + this re-hydrate on the `storage` event,
+     * which fires in every tab EXCEPT the writer. Memory-mode has no disk and no
+     * other tab can see it, so nothing to listen to.
+     */
+    private startStorageEventRehydrate;
+    /** Detach the cross-tab listener (tests / `destroy()`). */
+    stopStorageEventRehydrate(): void;
+    /** The server session family id of the current session — the identity CAS key. `null` = no session (or unreadable). */
+    private currentSid;
+    /** The ProjectGuard (INV-15) — `match` whenever `expectedProjectId` is unset. */
+    private judge;
+    /** The JWT `project` claim as a string or explicit null; `null` when unreadable. */
+    private projectClaim;
+    private withheldInfo;
+    private heldCount;
+    /** The current guest as a held slot: its POST-refresh tokens and its `project` claim at HOLD. */
+    private buildHeld;
+    /** Fire-and-forget server-side revoke of a refresh token; the device state never waits on it. */
+    private revokeFireAndForget;
+    /** B15 — tell the server a guest was held. Silent 200 either way; the pending flag clears on success. */
+    private reportHeld;
+    private withheldError;
     /**
      * The cached-token guard, and the only place the two deadlines are combined.
      * Both must agree: the locally-tracked deadline (immune to a constantly-wrong
@@ -901,77 +1326,203 @@ declare class Auth {
      * reads live, guard holds) or genuinely fast (still dead, guard releases).
      */
     private refreshAndReconcile;
+    /**
+     * Returns a VALID (non-expired) access token, or null.
+     *
+     * Hard contract (parity with sdk-react-native / sdk-ios / sdk-android
+     * and the industry token-client pattern — Supabase
+     * `_callRefreshToken`, Auth0 `getTokenSilently`, Firebase
+     * `getIdToken`): NEVER returns a token past its `exp`. Callers attach
+     * the result as a Bearer to arbitrary resource servers — including
+     * third-party backends (PostgREST/Supabase) that have NO knowledge of
+     * Sendora's own refresh grace window — so a token must be either
+     * fresh or absent.
+     *
+     *  1. Cached token with comfortable life left (>= REFRESH_SAFETY_MS
+     *     skew before exp) → return it. Fast path, no I/O.
+     *  2. No cached token AND no refresh token in storage → null.
+     *  3. Expired/near-expiry but a refresh chain exists:
+     *     a. A refresh is already inflight → AWAIT it and return the
+     *        fresh token. Single-flight: concurrent callers coalesce
+     *        onto one `/token/refresh`, nobody is handed a stale token.
+     *     b. In backoff cooldown after a failed refresh → null.
+     *     c. Otherwise → fire the refresh and await it.
+     *
+     * ⚠ `withheld` (3.24.0): always null — no refresh, no cron, no gap-fill.
+     * The withheld record is not this project's session.
+     */
     getAccessToken(options?: {
         forceRefresh?: boolean;
     }): Promise<string | null>;
-    /** Sync read — returns whatever's cached even if expired. Prefer the async variant. */
+    /** Sync read — returns whatever's cached even if expired (null in `withheld`). Prefer the async variant. */
     getAccessTokenSync(): string | null;
     /**
-     * Mint (or return) an anonymous session.
+     * The stored refresh token, or null (always null in `withheld`). Kept for
+     * integrators that journal it; since 3.24.0 the SDK journals a replaced guest
+     * itself in a held slot (`getHeldGuests()`), so most callers no longer need it.
+     */
+    getRefreshToken(): string | null;
+    /**
+     * Hot-path token refresh. Single-flight via `refreshInflight` so a
+     * burst of in-flight reads doesn't fan out into duplicate /refresh
+     * round-trips. Returns null on any failure so callers can decide
+     * whether to surface re-auth or proceed anonymously.
+     *
+     * Dead-token signal = `INVALID_REFRESH_TOKEN` ONLY (`isDeadRefreshError`);
+     * a rate limit or a generic 401 is transient. The verdict is applied
+     * through commit() with the sent token as the CAS key, so a refresh that
+     * lands after a sign-out / switch can neither resurrect a session nor
+     * wipe a newer one (§3.3 rows 20–26).
+     *
+     * ⚠ 3.24.0: no Web Locks. Each tab single-flights its own refresh; a sibling
+     * tab's rotation reaches this tab through the `storage` event re-hydrate,
+     * and the server's 60 s rotation grace covers the race where both tabs
+     * present the same parent.
+     */
+    private refreshAccessToken;
+    private performRefresh;
+    /**
+     * Present a HELD slot's refresh token (restore / claim / auto-restore — the
+     * ONLY places a held token is ever refreshed; the cron never touches a slot).
+     * Persists the rotation INTO the slot before anything else happens with it
+     * (§3.3 "persist rotations before the next step"), via a per-slot CAS.
+     *
+     * Dead verdict handling is the §3.3 REFRESH_DEAD-held row: release the slot
+     * ONLY for `endReason ∈ deleted | revoked | expired`; `reuse` or an ABSENT
+     * `endReason` KEEPS the slot and surfaces a retryable `RESTORE_FAILED` — a
+     * reuse verdict on a preserved-family guest does not prove it is gone.
+     */
+    private refreshHeld;
+    /**
+     * `unknown` → settled. The queue of INV-5: every session-installing verb
+     * (MINT, SIGN-IN, LINK, RESTORE) waits here until the single gap-fill
+     * refresh answers — success installs, `INVALID_REFRESH_TOKEN` clears to
+     * `signed_out`; a transient failure retries after the backoff window (so an
+     * offline cold start resolves when connectivity returns). Never executes the
+     * verb's network call in `unknown`.
+     */
+    private settle;
+    /**
+     * Wave 63 — arm exponential backoff after a transient refresh
+     * failure. Caps at 30s. getAccessToken consults
+     * `refreshCooldownUntil` and returns null during the window
+     * instead of queueing a fresh fetch into a network we already know
+     * is stalled.
+     */
+    private armBackoff;
+    /**
+     * Wave 63 — clears backoff state. Called from the visibilitychange
+     * listener so a user returning to a previously-backgrounded tab
+     * gets an immediate fresh refresh attempt instead of waiting on
+     * the cooldown timer.
+     */
+    private resetRefreshState;
+    /**
+     * Wave 63 — start visibilitychange listener. Browser equivalent of
+     * RN AppState 'active'. Armed by every install commit alongside
+     * `startProactiveRefreshCron`. Idempotent.
+     */
+    private startVisibilityRefreshReset;
+    private stopVisibilityRefreshReset;
+    /**
+     * Proactive refresh (s58.72). Fires when access-token age crosses
+     * ~80% of TTL — refresh becomes a scheduled event, never a 401-
+     * driven race. Armed by every install commit (incl. hydrate — the Word
+     * Hurdle cold-launch fix) and by the `unknown` commit (the single gap-fill),
+     * stopped by every clear / withhold. Pauses while an identity attempt is on
+     * the wire (§3.3 scheduling rule 2).
+     */
+    private startProactiveRefreshCron;
+    private stopProactiveRefreshCron;
+    private serialize;
+    /**
+     * Build the Authorization header for end-user-authenticated routes.
      *
-     * Reuses the existing anonymous user when there already is one — the same
-     * short-circuit Firebase's `signInAnonymously` performs. Without it, an app
-     * that calls this defensively on every page load (the most natural thing to
-     * write) mints a fresh `user_id` each time, and `persist()` overwrites the
-     * stored refresh token — the previous anonymous account's only durable
-     * handle — with no takeover, no webhook and no state event. That is the same
-     * silent progress loss as a failed sign-in wiping the session, except it
-     * happens on a *healthy* network.
+     * Awaits `getAccessToken()` so a cold-start (re-hydrated from storage
+     * with no cached access token) or an expired token transparently
+     * refreshes via the stored refresh token before the call. Throws if there's
+     * genuinely no usable session; in `withheld` the refusal is
+     * `SESSION_WITHHELD` (no network — §3.3 row 12).
+     */
+    private bearerHeaders;
+    /**
+     * Mint (or return) an anonymous session.
      *
-     * The guard is `cached user` AND `refresh token in storage`, both read INSIDE
-     * the serialized op: the refresh token is what actually keeps the account
-     * reachable (a cached user without one must still mint), and reading after
-     * the chain has drained is what collapses concurrent calls onto a single
-     * mint — the second call runs only once the first has persisted, so it takes
-     * the reuse branch instead of minting a sibling.
+     * Reuses the existing session when there is one — the same short-circuit
+     * Firebase's `signInAnonymously` performs, covering an IDENTIFIED session
+     * too (3.23.0, RopoLabs A2): a defensive call on every page load returns
+     * the current user whatever its kind; read `user.isAnonymous` to know which.
      *
-     * ⚠ The guard also covers an IDENTIFIED session (3.23.0, reported by
-     * RopoLabs on the RN SDK; same code here). Until then it was
-     * `existing.isAnonymous`, so a plain `signInAnonymously()` over a live
-     * account session fell through, minted a guest and overwrote the account's
-     * tokens locally — with no `signed_out`, because this path never wipes, it
-     * persists over the top. The account survives server-side (recoverable by
-     * its credential) but the device is now a stranger to it. Returning the
-     * identified session is a no-op for a defensive caller and the honest
-     * answer to "make sure I have a session" — read `user.isAnonymous` to know
-     * which kind you got.
+     * 3.24.0 (ADR-033): MINT executes ONLY in `signed_out` (INV-5). In `unknown`
+     * it waits for the gap-fill refresh to settle the status; in `withheld` it
+     * rejects `SESSION_WITHHELD` (opt-in only — unlike the no-op over identified).
+     * In `signed_out` a HELD guest is restored before anything is minted
+     * (`autoRestoreHeldGuest`, default ON, §8-Q1) — visibly, as
+     * `signed_in{cause:'restore'}` + `guest_released{restored}`; a dead held
+     * guest is released (`guest_released{dead}`) and the next one tried, and a
+     * fresh mint happens in the same call when none is left. The capacity bound
+     * T = |held| + (current anonymous ? 1 : 0) ≤ 5 is enforced HERE: `forceNew`
+     * at the cap throws `HeldGuestLimitError`; a plain mint at the cap restores.
      *
      * Pass `forceNew: true` to deliberately abandon the current session —
-     * whichever kind — and mint a separate anonymous one. That is the only way
-     * this replaces an identified session, and it does so silently.
+     * whichever kind — and mint a separate anonymous one. A current GUEST is
+     * HELD (never orphaned); a current identified session is replaced and its
+     * refresh token revoked server-side.
+     *
+     * Every mint carries a per-attempt `mintKey` (B10): a retried mint after a
+     * lost response returns the SAME guest instead of an orphan.
      */
     signInAnonymously(opts?: {
         name?: string;
         metadata?: Record<string, unknown>;
         forceNew?: boolean;
     }): Promise<AuthUser>;
-    /**
-     * Create an email/password account. Upgrade-first flow (matches
-     * Firebase `linkWithCredential` / Auth0 anonymous-merge): if a
-     * refresh token is present, attempt /upgrade first — backend
-     * preserves user.id when the bound user is anonymous. On
-     * non-anonymous-bound refresh / invalid-or-expired refresh, fall
-     * back to fresh /signup. We don't gate on the cached
-     * `this.user.isAnonymous` boolean — refresh-token presence is the
-     * authoritative signal (cached user can be stale during cold
-     * start / fast-refresh). Backend has source of truth.
-     */
-    signUp(email: string, password: string, opts?: {
-        name?: string;
-        metadata?: Record<string, unknown>;
-    }): Promise<AuthUser>;
+    /** Alias of `signInAnonymously()` — "make sure I have a session". */
+    ensureSession(): Promise<AuthUser>;
+    /** A slot is ineligible for auto-restore when its recorded project is a string that disagrees with the anchor (null = judged later). */
+    private slotProjectMismatches;
+    /** The fresh mint (row 6): `POST /anonymous` (+ `mintKey`) → ProjectGuard on the response → install. */
+    private mintFresh;
+    /**
+     * ProjectGuard on a session minted by THIS process under THIS key (mint /
+     * sign-in / promotion response): a mismatch installs nothing, revokes the
+     * minted refresh fire-and-forget and rejects `PROJECT_MISMATCH` — the
+     * wrong-key build fails loudly at first launch, never a relaunch lockout
+     * loop (§8-Q14). An unreadable claim on a FRESH response is treated as a
+     * mismatch here (the server emits it ALWAYS since s58.276).
+     */
+    private guardMinted;
+    /**
+     * The one switch path every credentialed sign-in runs through. The request
+     * carries NO guest hint (INV-3). On success the previous GUEST (if any) is
+     * HELD with its post-refresh tokens, a previous IDENTIFIED session with a
+     * different sub has its refresh revoked (§8-Q12), and the new record is
+     * installed through commit() keyed on the `sid` the attempt started from.
+     * `mfaRequired` leaves the state untouched and returns the challenge.
+     */
+    private performSwitch;
     /**
      * Sign in with email + password. When the account has confirmed
      * MFA, returns a `mfaRequired` discriminator instead of the user
      * — caller must then call `challengeMfa(challengeToken, code)`
      * with the TOTP / recovery code to mint a real session. Pre-MFA
      * accounts get a normal `AuthUser` back.
+     *
+     * 3.24.0: a guest on this device is HELD, never retired (`guest_held`
+     * then ONE `signed_in{cause:'sign_in'}`, no `signed_out`).
      */
     signIn(email: string, password: string): Promise<AuthUser | {
         mfaRequired: true;
         mfaChallengeToken: string;
         userId: string;
     }>;
+    /**
+     * Exchange the `mfaChallengeToken` from `signIn` for a real
+     * session by submitting a 6-digit TOTP code or a 17-char recovery
+     * code from the user's authenticator app. A wrong or expired code
+     * leaves the current session in place so the user can retry.
+     */
+    challengeMfa(mfaChallengeToken: string, code: string): Promise<AuthUser>;
     /**
      * Verify an IdP-issued credential (authorization code OR id_token)
      * and mint a Sendora session. Customer's app handles the IdP
@@ -985,13 +1536,18 @@ declare class Auth {
      *     by design — see backend service.ts)
      *   - `idToken` (Apple-native flow)
      *
-     * Apple's first-time prompt also yields name fields — pass via
-     * `appleName: { firstName, lastName }`. Apple only sends them
-     * once; re-sign-ins will return null name from the IdP.
+     * `link: true` (ADR-025 → ADR-033): in `anonymous` AND `identified` the
+     * call goes to `/me/link/social` on the current Bearer and ATTACHES or
+     * errors — it never switches (INV-14). From a guest that is the same-`sub`
+     * promotion (ONE `signed_in{cause:'link'}`); over an identified account a
+     * new attach emits `user_updated{cause:'link'}`, the same identity is a quiet
+     * 200 (`alreadyLinked`, no event, no revoke), a credential owned elsewhere
+     * throws `CredentialInUseError` (or switches when `onCredentialInUse:
+     * "adopt"` — the guest is then HELD), and a stale session throws
+     * `RECENT_AUTH_REQUIRED` (kind `recent_auth_required`). In `signed_out` it
+     * is a plain sign-in; in `unknown` it waits for the status to settle.
      *
-     * Returns the AuthUser on success. Throws AuthError on backend
-     * refusal — most commonly the verified-email gate (Twitter,
-     * unverified Discord, etc).
+     * Without `link`, this is a plain SWITCH: the device's guest is HELD.
      */
     loginSocial(input: {
         provider: "google" | "github" | "apple" | "microsoft" | "linkedin" | "facebook" | "twitter" | "discord";
@@ -1003,23 +1559,12 @@ declare class Auth {
             firstName?: string;
             lastName?: string;
         };
-        /**
-         * ADR-025 link-in-place opt-in. When anonymous and `link: true`, an
-         * anon→social upgrade KEEPS the same user id (sub) — promoted in place
-         * (like Firebase linkWithCredential) instead of a device-takeover that
-         * mints a new id. No effect off-anon or on a collision (identity already
-         * owned → falls back to takeover/merge).
-         */
+        /** Client ROUTING hint (ADR-033 §4): anonymous | identified → `/me/link/social`; signed_out → plain sign-in; unknown → wait. Never sent to the server. */
         link?: boolean;
-        /**
-         * What to do if this social identity (or its verified email) already
-         * belongs to an account. **Omit it** — the default adopts when nothing
-         * would be destroyed and refuses when a live anonymous session would be
-         * deleted. See {@link CredentialCollisionPolicy}.
-         */
+        /** See {@link CredentialCollisionPolicy}. Applied client-side on a 409 from the link route; never sent to the server. */
         onCredentialInUse?: CredentialCollisionPolicy;
     }): Promise<AuthUser>;
-    /** Convenience: Google authorization-code login. `link` = ADR-025 keep-the-sub on an anon upgrade. */
+    /** Convenience: Google authorization-code login. `link` = attach to the current account (see `loginSocial`). */
     signInWithGoogle(code: string, redirectUri: string, link?: boolean): Promise<AuthUser>;
     /** Convenience: GitHub authorization-code login. */
     signInWithGitHub(code: string, redirectUri: string): Promise<AuthUser>;
@@ -1037,7 +1582,7 @@ declare class Auth {
             firstName?: string;
             lastName?: string;
         };
-        /** ADR-025: keep the same user id on an anon→Apple upgrade. See `loginSocial`. */
+        /** Attach to the current account instead of switching. See `loginSocial`. */
         link?: boolean;
     }): Promise<AuthUser>;
     /** Convenience: Microsoft Azure AD authorization-code login. */
@@ -1046,6 +1591,63 @@ declare class Auth {
     signInWithLinkedIn(code: string, redirectUri: string): Promise<AuthUser>;
     /** Convenience: Facebook Graph login. Refuses if email permission not granted. */
     signInWithFacebook(code: string, redirectUri: string): Promise<AuthUser>;
+    /** Convenience: Discord OAuth2. Refuses if `verified !== true`. */
+    signInWithDiscord(code: string, redirectUri: string): Promise<AuthUser>;
+    /**
+     * Typed sign-in (ADR-033 §3.5) — a plain SWITCH for every credential kind.
+     * `previous` tells you what it replaced; `previous.held === true` means the
+     * device's guest is in a held slot (`getHeldGuests()`), `previous.isAnonymous
+     * === false` means an identified → identified switch (reset local save state).
+     * `mfa_required` carries a `verify(code)` that completes the challenge.
+     */
+    signInWith(credential: AuthCredential): Promise<SignInResult>;
+    /**
+     * The one link path. Bearer `POST /me/link/*`; outcomes per the table:
+     *  - 200 `upgraded` (caller was anonymous) → ProjectGuard → install the
+     *    rotated pair, same `sub`. `legacyMode` decides the event: the legacy-
+     *    signature methods keep ONE `signed_in{cause:'link'}` (§8-Q18); the typed
+     *    verbs emit `user_updated{cause:'link'}`. Never both.
+     *  - 200 `alreadyLinked` → nothing: no event, no write, no revoke (B13).
+     *  - 200 attached (identified, no rotation) → `user_updated{cause:'link'}`.
+     *  - 409 → `credential_in_use{provider, collision}`, nothing mutated (B14).
+     *  - 403 `RECENT_AUTH_REQUIRED` → `recent_auth_required`, nothing mutated.
+     */
+    private performLink;
+    /**
+     * Typed link (ADR-033 §3.5): attach a credential to the CURRENT account —
+     * from a guest this is the same-`sub` promotion (`user_updated{cause:'link'}`,
+     * `upgraded: true`); from an identified account a new attach, a quiet
+     * `alreadyLinked`, a typed `credential_in_use` (with `switchAccount()` bound
+     * to this exact credential and `keepCurrent()`), or `recent_auth_required`.
+     * In `signed_out` there is nothing to attach to, so it is a plain sign-in; in
+     * `unknown` it waits for the status to settle. Linkable kinds: password,
+     * the social providers, gameCenter, playGames.
+     */
+    link(credential: AuthCredential): Promise<LinkResult>;
+    /** `signInWith()` for callers already inside the serialize chain (link() in signed_out). */
+    private signInWithUnserialized;
+    /**
+     * Create an email/password account.
+     *
+     * 3.24.0 (ADR-033 INV-4) — routed by `status()`, locally:
+     *   - `anonymous`  → `POST /me/link/email` on the current Bearer: the guest
+     *                    is promoted IN PLACE (same `sub`), ONE
+     *                    `signed_in{cause:'link'}`. A taken email throws
+     *                    `EmailAlreadyTakenError` with nothing mutated.
+     *   - `signed_out` → `POST /signup` (a brand-new account).
+     *   - `identified` → `AlreadyIdentifiedError`, with NO round-trip.
+     *   - `unknown`    → waits for the status to settle, then routes.
+     *   - `withheld`   → `SESSION_WITHHELD`.
+     * `/upgrade` is never called; its private dead-token list is gone with it
+     * (a generic 401 there used to wipe the guest).
+     *
+     * ⚠ `opts.name` / `opts.metadata` reach the server only on the `/signup`
+     * path — the link route's schema carries exactly `email` + `password`.
+     */
+    signUp(email: string, password: string, opts?: {
+        name?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<AuthUser>;
     /** Link email + password to the current account (sub preserved). */
     linkEmailPassword(email: string, password: string): Promise<AuthUser>;
     /** Link an OAuth social identity (verified idToken or authorization code) to the current account. */
@@ -1076,15 +1678,122 @@ declare class Auth {
             lastName?: string;
         };
     }): Promise<AuthUser>;
+    /** The `link*()` family: typed `link()` surfaced through the pre-3.24.0 throw-on-refusal contract. */
+    private linkLegacy;
+    /**
+     * Every guest held on this device, newest first. Never exposes tokens.
+     * Best-effort: `dead` is observed ONLY when a held token is presented
+     * (restore / claim / discard), so a guest the server has since deleted may
+     * still be listed. `autoRestore:false` = stamped by `deleteAccount()`; only
+     * an explicit `restoreHeldGuest(id)` revives it. There is NO expiry: neither
+     * the SDK nor the server releases a held guest by age (s58.316).
+     */
+    getHeldGuests(): HeldGuestSummary[];
+    /** The newest held guest, or null. */
+    getHeldGuest(): HeldGuestSummary | null;
+    /**
+     * Resolve the slot a held-guest verb acts on. `id` may be omitted ONLY when
+     * exactly one guest is held — with two or more it is `AMBIGUOUS_HELD_GUEST`
+     * (the prepend-between-dialog-and-tap TOCTOU), nothing mutated.
+     */
+    private resolveSlot;
+    /**
+     * CLAIM (§3.3 row 29): fold a held guest INTO the current IDENTIFIED account
+     * via `POST /merge` — Sendora-side reassignment of events / profiles /
+     * entities / push tokens, then the guest row is hard-deleted
+     * (`auth.user_merged`). OPTIONAL and IRREVERSIBLE (INV-8): an app whose
+     * backend does not act on `auth.user_merged` MUST NOT call it. The held
+     * token is refreshed first (repairs a spent parent inside the 60 s grace and
+     * proves liveness; the rotation is persisted into the slot BEFORE the merge).
+     * Emits `user_updated{cause:'merge'}` then `guest_released{claimed}`.
+     */
+    claimHeldGuest(id?: string): Promise<{
+        user: AuthUser;
+        stats: MergeStats;
+    }>;
     /**
-     * Shared link executor. POSTs the verified credential with the caller's Bearer
-     * access token, then refreshes the cached user IN PLACE (no token rotation —
-     * the sub is unchanged). NOT serialized (mirrors sendVerificationEmail;
-     * getAccessToken() coalesces refresh single-flight internally).
+     * RESTORE (§3.3 rows 30–31): sign back in AS the held guest, without
+     * merging. Project check FIRST, client-side (`HeldGuestProjectMismatch`,
+     * slot KEPT, no network); then the held token is refreshed; a dead guest
+     * releases the slot and rejects `HELD_GUEST_GONE`. A current identified
+     * session has its refresh revoked; a current GUEST is held in a free slot
+     * first. Emits `signed_in{cause:'restore'}` (re-register push) then
+     * `guest_released{restored}`.
      */
-    private linkCredential;
-    /** Refresh the cached user after a link — same sub, so only the user object + its storage copy change (no token/identity rotation). */
-    private updateLocalUser;
+    restoreHeldGuest(id?: string): Promise<AuthUser>;
+    /**
+     * The restore body shared by `restoreHeldGuest()` and the MINT auto-restore.
+     * Returns null when the slot was DEAD and has been released (the mint falls
+     * through to the next slot / a fresh mint); throws `HeldGuestProjectMismatch`
+     * when the slot belongs to another project (client-side, or judged on the
+     * refresh response for a slot whose project was unreadable at HOLD).
+     */
+    private restoreSlot;
+    /**
+     * DISCARD (§3.3 row 32): a REAL server delete of a held guest — `POST
+     * /guest/discard` with the guest's own refresh token (the only proof of
+     * ownership), immediate purge, `auth.user_deleted{reason:'guest_discarded'}`.
+     * The app is the requester (s58.316); the SDK never calls this on its own.
+     * A 2xx or a 404 (already gone / not ours) releases the slot; a 5xx or a
+     * network failure keeps it. Emits `guest_released{discarded}`.
+     */
+    discardHeldGuest(id?: string): Promise<void>;
+    private discardSlot;
+    /**
+     * DEPRECATED alias (ADR-033 §3.5): merge a guest into the current account by
+     * its refresh token. A token that matches a held slot (its current token OR
+     * the one it had at HOLD) routes to `claimHeldGuest(thatId)` — a DESTRUCTIVE
+     * claim (INV-8). Any other token is the raw `/merge` the integrator-journalled
+     * path always was. Prefer `claimHeldGuest(id)`.
+     */
+    merge(anonymousRefreshToken: string): Promise<MergeStats>;
+    /**
+     * While `status() === "withheld"`: what was refused and why. `userId` lets a
+     * `sub`-keyed backend record oldSub → newSub BEFORE `discardWithheld()`.
+     * Never exposes tokens. Null in every other state.
+     */
+    getWithheld(): WithheldInfo | null;
+    /**
+     * Leave `withheld` (§3.3 row 14): clears exactly the stored session (the
+     * four frozen keys + their `auth_session` mirror), revokes the withheld
+     * refresh token server-side fire-and-forget like `signOut()` (§8-Q15), and
+     * KEEPS the held slots, the event queue and the analytics ids. LOCAL ONLY —
+     * never `/guest/discard`, never a server delete. Emits
+     * `signed_out{reason:'user'}`. Resolves `false` (nothing done) in any other
+     * state. `signOut()` in `withheld` does exactly this.
+     */
+    discardWithheld(): Promise<boolean>;
+    private discardWithheldNow;
+    /**
+     * Sign out: wipe local identity FIRST so the user is logged out on
+     * device even if the revoke network call hangs (airplane mode, 5xx,
+     * circuit breaker open) — the one deliberate local-first exception, it has
+     * a rollback. Revoke is fire-and-forget after the wipe. Keeps the held
+     * guests (a guest's refresh token is its only credential — stranding it is
+     * deletion by assumption, s58.316) and the event queue. In `withheld` this is
+     * `discardWithheld()`. In `signed_out` it emits nothing (no transition).
+     */
+    signOut(): Promise<void>;
+    /**
+     * Delete the signed-in user's account (3.24.0 on web; parity with the
+     * native SDKs). Honours the project's grace: `purged` = hard-deleted now,
+     * `pending` = deactivated, hard-deleted at `scheduledPurgeAt` (cancellable by
+     * signing back in). Either way the local session is cleared with
+     * `signed_out{reason:'account_deleted'}`, the event queue is dropped
+     * (s58.353) and the anonymous analytics id rotates.
+     *
+     * ⚠ Held guests SURVIVE on the device AND the server (the server has no
+     * owner link; deleting A keys on A only). Each slot is stamped
+     * `autoRestore:false`, so the next `ensureSession()` mints a fresh guest and
+     * only an explicit `restoreHeldGuest(id)` revives one. Pass
+     * `alsoDiscardHeldGuests: true` — the player's explicit ask — to run
+     * `/guest/discard` on every slot after the 2xx; failures stay held and are
+     * reported in `discardFailed`. Your privacy copy must say deleting an account
+     * does not delete a guest saved on the device unless that option is used.
+     */
+    deleteAccount(opts?: {
+        alsoDiscardHeldGuests?: boolean;
+    }): Promise<DeleteAccountResult>;
     /**
      * List the auth methods/identities linked to the current account (ADR-030
      * read side, s58.270). Returns every social identity linked to this account
@@ -1115,14 +1824,6 @@ declare class Auth {
      * attached tells the user something untrue about their account.
      */
     unlink(provider: string): Promise<UnlinkResult>;
-    /** Convenience: Discord OAuth2. Refuses if `verified !== true`. */
-    signInWithDiscord(code: string, redirectUri: string): Promise<AuthUser>;
-    /**
-     * Exchange the `mfaChallengeToken` from `signIn` for a real
-     * session by submitting a 6-digit TOTP code or a 17-char recovery
-     * code from the user's authenticator app.
-     */
-    challengeMfa(mfaChallengeToken: string, code: string): Promise<AuthUser>;
     /**
      * Send a magic-link email to `email`. Caller's app should display
      * "check your inbox" copy after success. Always resolves
@@ -1138,10 +1839,19 @@ declare class Auth {
     sendEmailOtp(email: string): Promise<void>;
     /**
      * Verify a typed 6-digit code + the email it was sent to. Mints
-     * a session on success. First-time users are auto-created with
-     * `emailVerified=true`.
+     * a session on success (a SWITCH: the device's guest is HELD). First-time
+     * users are auto-created with `emailVerified=true`. A mistyped code leaves
+     * the current session exactly as it was.
      */
     verifyEmailOtp(email: string, code: string): Promise<AuthUser>;
+    /**
+     * Verify a magic-link token (extracted from the URL query string of
+     * the page the link points to) and mint a session (a SWITCH: the device's
+     * guest is HELD). First-time users are auto-created with
+     * `emailVerified=true`. An expired or already-consumed token leaves the
+     * current session exactly as it was.
+     */
+    verifyMagicLink(token: string): Promise<AuthUser>;
     /**
      * Trigger a password-reset email. Backend always resolves 204 even
      * when the address is unknown — prevents account enumeration.
@@ -1168,12 +1878,6 @@ declare class Auth {
      * after signup.
      */
     sendVerificationEmail(): Promise<void>;
-    /**
-     * Verify a magic-link token (extracted from the URL query string of
-     * the page the link points to) and mint a session. First-time
-     * users are auto-created with `emailVerified=true`.
-     */
-    verifyMagicLink(token: string): Promise<AuthUser>;
     /**
      * Begin MFA enrollment. Returns the otpauth:// URL (render as a
      * QR code) + recovery codes (display + offer download — these are
@@ -1216,7 +1920,9 @@ declare class Auth {
     /**
      * Sign in with a passkey. Browser shows the credential picker UI;
      * `userId` is optional — when omitted, uses the resident-key flow
-     * so the user picks their account from the prompt.
+     * so the user picks their account from the prompt. Three fallible steps
+     * precede the session (start, the picker, finish) and each leaves the
+     * current session exactly as it was; the success is a SWITCH (guest HELD).
      */
     signInWithPasskey(userId?: string | null): Promise<AuthUser>;
     listPasskeys(): Promise<Array<{
@@ -1260,6 +1966,9 @@ declare class Auth {
      * redirects through the Sendora callback back to `returnTo` with
      * a `#sendora_oidc_token=...` URL fragment. Call
      * `consumeSsoTokenFromUrl()` on the returnTo page to mint a session.
+     *
+     * 3.24.0: no guest hint travels with the start request (INV-3) — the guest
+     * is HELD on this device when the fragment is consumed.
      */
     startSso(returnTo: string): Promise<{
         authorizationUrl: string;
@@ -1290,113 +1999,17 @@ declare class Auth {
      * success, null when no fragment present, throws on
      * `sendora_oidc_error=...`. Call this once on the returnTo page
      * (typically from a top-level effect / page-load hook).
-     */
-    consumeSsoTokenFromUrl(): Promise<AuthUser | null>;
-    /**
-     * Build the Authorization header for end-user-authenticated routes.
      *
-     * Awaits `getAccessToken()` so a cold-start (re-hydrated from storage
-     * with no cached access token) or an expired token transparently
-     * refreshes via the stored refresh token before the call — matching
-     * `sendVerificationEmail`. Throws if there's genuinely no usable
-     * session; the caller should handle this as an unauthenticated state.
+     * 3.24.0 (e): the install goes through `commit()` like every other sign-in
+     * (it was hand-installed before) — so it is a SWITCH: the device's guest is
+     * HELD, the CAS applies, the cron is armed, and `signed_in{cause:'sign_in'}`
+     * is the emission. The exchange happens FIRST; a stale bookmark or a crafted
+     * `#sendora_oidc_token=junk` link leaves the current session untouched.
      */
-    private bearerHeaders;
-    /**
-     * Sign out: wipe local identity FIRST so the user is logged out on
-     * device even if the revoke network call hangs (airplane mode, 5xx,
-     * circuit breaker open). Revoke is fire-and-forget after the wipe.
-     */
-    signOut(): Promise<void>;
-    private serialize;
-    /**
-     * Hot-path token refresh. Single-flight via `refreshInflight` so a
-     * burst of in-flight reads doesn't fan out into duplicate /refresh
-     * round-trips. Returns null on any failure so callers can decide
-     * whether to surface re-auth or proceed anonymously.
-     *
-     * s58.46 — on a dead-token signal (INVALID_REFRESH_TOKEN /
-     * UNAUTHORIZED / HTTP_401) we WIPE the stored refresh token.
-     * Pre-s58.46 we returned null but kept the dead token in
-     * storage, so the next caller re-tried the same token forever
-     * (Pulse News iOS hit /refresh ~1×/s for hours). The wipe forces
-     * the next op to fall through to /anonymous or surface the signed-
-     * out state to the host app instead of looping. A rate limit is NOT
-     * such a signal — see `isDeadRefreshError`.
-     */
-    private refreshAccessToken;
-    /**
-     * Wave 63 — arm exponential backoff after a transient refresh
-     * failure. Caps at 30s. getAccessToken consults
-     * `refreshCooldownUntil` and returns stale cached during the window
-     * instead of queueing a fresh fetch into a network we already know
-     * is stalled.
-     */
-    private armBackoff;
-    /**
-     * Wave 63 — clears backoff state. Called from the visibilitychange
-     * listener so a user returning to a previously-backgrounded tab
-     * gets an immediate fresh refresh attempt instead of waiting on
-     * the cooldown timer.
-     */
-    private resetRefreshState;
-    /**
-     * Wave 63 — start visibilitychange listener. Browser equivalent of
-     * RN AppState 'active'. Called from `persist()` (after signin /
-     * signup) alongside `startProactiveRefreshCron`. Idempotent.
-     */
-    private startVisibilityRefreshReset;
-    private stopVisibilityRefreshReset;
-    /**
-     * Proactive refresh (s58.72). Fires when access-token age crosses
-     * ~80% of TTL — refresh becomes a scheduled event, never a 401-
-     * driven race. Started by `init()` and cleared by `signOut()`.
-     * Internally uses the same `refreshAccessToken()` path so Web Locks
-     * coordinates across tabs.
-     */
-    private startProactiveRefreshCron;
-    private stopProactiveRefreshCron;
-    private persist;
-    /**
-     * Clear the outgoing identity immediately before a CONFIRMED `persist()`.
-     * Flushes first so the prior identity's queued events reach the backend
-     * before `dropQueue()` discards them. No-op when already signed out.
-     *
-     * `"replaced"` suppresses the signed_out emission — subscribers see one
-     * `signed_in`, not a spurious logout/login pair.
-     */
-    private replaceLocalIdentity;
-    /**
-     * Wipe everything tied to the current user identity. The anonymous id is
-     * regenerated by analytics.reset() ONLY at a person-boundary (reason "user" /
-     * "account_deleted") so two people on a shared device don't merge; on a
-     * sign-in/upgrade ("replaced") or session death ("session_expired") it SURVIVES
-     * (same person — pre-auth analytics link to them). Chat session is reset so
-     * cross-account chat history can't bleed on a shared device. Pending analytics
-     * events are dropped — they're tied to the prior identity and shouldn't surface
-     * under the next.
-     *
-     * `reason` drives the `onAuthStateChanged` emission: a real sign-out reason
-     * emits `signed_out`, while `"replaced"` (the internal pre-`persist()` clear
-     * on a SUCCESSFUL sign-in) emits nothing.
-     *
-     * ⚠ Never call this before a fallible network request. A failed sign-in must
-     * leave the caller exactly as it found them; for an anonymous session the
-     * refresh token dropped here is the ONLY durable handle on the account, so a
-     * pre-call wipe that is not followed by a successful `persist()` orphans the
-     * account permanently (offline: deterministically). Capture the anon refresh
-     * into a local, make the call, and wipe only after the response validates.
-     */
-    /**
-     * True when `sent` is still the refresh token in storage — i.e. nothing
-     * replaced or cleared the session while a request carrying it was in
-     * flight. Guards both directions of the refresh race: installing a rotated
-     * token over a session that has since been signed out or replaced, and
-     * wiping a fresh session because an OLD token was rejected.
-     */
-    private tokenStillCurrent;
-    private wipeLocalIdentity;
+    consumeSsoTokenFromUrl(): Promise<AuthUser | null>;
 }
+/** Re-exported for tests / advanced integrators: the literal held-slot keys this SDK writes (`auth_held_0..4`). */
+declare const AUTH_HELD_SLOT_KEYS: readonly ["auth_held_0", "auth_held_1", "auth_held_2", "auth_held_3", "auth_held_4"];
 
 /**
  * Browser Web Push (RFC 8030) helper.
@@ -1785,6 +2398,18 @@ declare class KnowledgeBase {
     }): Promise<KbArticle[]>;
 }
 
+/**
+ * ⚠ VERBATIM PORT of `packages/shared/src/auth-machine/project-verdict.ts` (ADR-033 B8 / INV-15).
+ *
+ * The published SDK has ZERO runtime dependencies and cannot import `@sendora/shared`, so the
+ * ProjectGuard is copied here byte-for-byte from the first `export` onwards. The test
+ * `test/project-verdict-parity.test.ts` reads both files and fails on ANY divergence below the
+ * banner, so a fix to the shared verdict that is not mirrored here is red, not silent.
+ * Edit the shared file first, then copy; never edit this one by hand.
+ */
+type ProjectVerdict = "match" | "mismatch" | "unknown";
+declare function projectVerdict(expectedProjectId: string | undefined, accessJwt: string | null | undefined): ProjectVerdict;
+
 /**
  * Return the URL if it is http/https; otherwise undefined.
  * Rejects javascript:, data:, vbscript:, and other script-bearing schemes.
@@ -1869,9 +2494,33 @@ declare class SendoraCloud {
     track(eventType: string, properties?: Record<string, unknown>): void;
     page(properties?: Record<string, unknown>): void;
     identify(userId: string, traits?: UserTraits, opts?: IdentifyOptions): void;
-    reset(): void;
+    /**
+     * Reset the analytics identity (rotates the anonymous id), feature-flag
+     * context and the chat session. Unchanged since 3.x.
+     *
+     * ⚠ NOT an auth verb on web, and NOT a sign-out: the auth session, its four
+     * stored keys and the held guests are untouched — call `auth.signOut()` to
+     * sign out. (The ADR-033 RESET row describes the React Native SDK, where
+     * `reset()` is the documented logout call; on web it never was, and making
+     * it sign users out would be a behaviour change a MINOR cannot ship —
+     * ADR-023.)
+     *
+     * `opts.includeHeldGuests` (3.24.0) is accepted for API parity with the
+     * native SDKs and is a no-op on auth state here: held guests are released
+     * only by `auth.claimHeldGuest` / `restoreHeldGuest` / `discardHeldGuest`.
+     */
+    reset(opts?: {
+        includeHeldGuests?: boolean;
+    }): void;
+    /**
+     * ADR-033 [2c]: fires when a stored session is WITHHELD (its JWT `project`
+     * claim disagrees with `init({expectedProjectId})`). The SDK has already
+     * stopped attributing analytics to that user in memory; use this to do the
+     * same in your own code. Returns an unsubscribe function.
+     */
+    onIdentityWithheld(listener: () => void): () => void;
     flush(): Promise<void>;
     destroy(): void;
 }
 
-export { AlreadyIdentifiedError, Analytics, type AnonRetirementOutcome, type Audience, type AudienceRule, type AudienceRuleGroup, Audiences, Auth, AuthError, type AuthErrorKind, type AuthSignedOutReason, type AuthStateChange, type AuthTokens, type AuthUser, Chatbot, Consent, type CreateAudienceInput, type CredentialCollisionPolicy, CredentialInUseError, type DeletionCancelledEvent, type DeviceTakeoverEvent, EmailAlreadyTakenError, FeatureFlags, type FlagValue, type IdentifyOptions, type InAppMessage, InAppMessaging, type LinkCreateInput, type LinkCreateResult, type LinkData, LinkError, type LinkErrorCode, type LinkStats, type LinkedIdentitiesResponse, type LinkedIdentity, Links, SendoraCloud, type SendoraConfig, type SurveyConfig, type SurveyQuestion, Surveys, type TrackEvent, type UnlinkResult, type UpdateAudienceInput, type UserTraits, ValidationError, WebPush, SendoraCloud as default, extractShortcodeFromUrl, safeUrl, sanitizeHtml };
+export { AMBIGUOUS_HELD_GUEST, AUTH_HELD_SLOT_KEYS, AUTH_STATES, AUTH_WITHHELD_CODES, AlreadyIdentifiedError, Analytics, type AnonRetirementOutcome, type Audience, type AudienceRule, type AudienceRuleGroup, Audiences, Auth, type AuthCredential, AuthError, type AuthErrorKind, type AuthHooks, type AuthSignedInCause, type AuthSignedOutReason, type AuthStateChange, type AuthStatus, type AuthTokens, type AuthUser, type AuthUserUpdatedCause, Chatbot, Consent, type CreateAudienceInput, type Credential, type CredentialCollisionPolicy, CredentialInUseError, type CredentialKind, DEAD_CODES, type DeleteAccountResult, type DeletionCancelledEvent, type DeviceTakeoverEvent, EmailAlreadyTakenError, FeatureFlags, type FlagValue, type GuestReleasedReason, HELD_GUEST_SLOTS, HeldGuestLimitError, HeldGuestProjectMismatch, type HeldGuestSummary, type IdentifyOptions, type InAppMessage, InAppMessaging, type LinkCollision, type LinkCreateInput, type LinkCreateResult, type LinkData, LinkError, type LinkErrorCode, type LinkResult, type LinkStats, type LinkedIdentitiesResponse, type LinkedIdentity, Links, type MergeStats, type ProjectVerdict, REFRESH_END_REASONS, REJECTED_IN_WITHHELD, RELEASE_HELD_ON_END_REASONS, type RefreshEndReason, SendoraCloud, type SendoraConfig, type SignInResult, type SocialCredentialProvider, type SurveyConfig, type SurveyQuestion, Surveys, type TrackEvent, type UnlinkResult, type UpdateAudienceInput, type UserTraits, ValidationError, WebPush, type WithheldInfo, SendoraCloud as default, extractShortcodeFromUrl, projectVerdict, safeUrl, sanitizeHtml };