@sendoracloud/sdk-react-native 1.40.0 → 1.41.1

package/dist/index.d.ts

@@ -127,6 +127,31 @@ interface SendoraConfig {
      * either drop that and use this, or expect `<yours><ours>key`.
      */
     storagePrefix?: string;
+    /**
+     * ADR-033 project guard (opt-in). The UUID of the Sendora project this build
+     * is bound to — set it from the same constant you use for `projectId`. When
+     * set, a stored, refreshed or restored session whose JWT `project` claim
+     * names a DIFFERENT project (or the org-wide pool) is `withheld` instead of
+     * being served: `auth.status()` reports `"withheld"`, `getWithheld()` says
+     * why, every auth verb rejects `AuthError{kind:'config', code:'SESSION_WITHHELD'}`,
+     * and NOTHING is written to storage — relaunching with the matching key
+     * (or calling `auth.discardWithheld()`) is the exit. A freshly minted or
+     * signed-in session that disagrees is rejected (`PROJECT_MISMATCH`) and its
+     * token revoked, so a wrong-key build fails loudly on first launch instead
+     * of installing a foreign session. Validated at init: must be a UUID and,
+     * when `projectId` is also set, equal to it. Default off (no `withheld`).
+     */
+    expectedProjectId?: string;
+    /**
+     * ADR-033 held guests. When the device is signed out and holds a guest that
+     * a previous sign-in displaced (`auth.getHeldGuests()`), `ensureSession()` /
+     * `signInAnonymously()` restore the NEWEST eligible one instead of minting a
+     * fresh guest — visibly, as `signed_in{cause:'restore'}` +
+     * `guest_released{reason:'restored'}`. Default `true`. `false` mints while
+     * the device holds fewer than 5 guests (at the cap a plain mint still
+     * restores). Guests left behind by `deleteAccount()` are never auto-restored.
+     */
+    autoRestoreHeldGuest?: boolean;
 }
 /**
  * Async key/value adapter for encrypted-at-rest auth storage. Compatible with a
@@ -241,62 +266,94 @@ declare class Storage {
     set(key: string, value: string): void;
     remove(key: string): void;
     /**
-     * Remove every sendora_*-prefixed key from both memory AND
-     * AsyncStorage, plus every secure key from the adapter. Uses
-     * getAllKeys() to find keys this process never cached (e.g. orphaned
-     * writes from a prior SDK version). Falls back to cache enumeration
-     * if the AsyncStorage backend doesn't expose getAllKeys.
+     * Clear this SDK's keys from memory, AsyncStorage and the secure adapter.
+     *
+     * **With `opts.keys` (ADR-033, the `reset()` path):** removes EXACTLY the
+     * listed bare keys of the active namespace — minus `opts.except` — from both
+     * stores. An exact list is what lets `Sendora.reset()` keep the held-guest
+     * slots by default (a guest's refresh token is its only credential, so
+     * sweeping them on logout would be deletion by assumption, s58.316), and it
+     * never touches a sibling `sendora_<env>_` keyspace that happens to share
+     * the prefix. Values kept in `except` stay in the cache too.
+     *
+     * **Without `opts` (legacy):** the pre-1.41 sweep — every prefixed
+     * AsyncStorage key (via `getAllKeys()`, falling back to the secure-key list)
+     * plus every secure key from the adapter.
      */
-    clearAll(): Promise<void>;
+    clearAll(opts?: {
+        keys: readonly string[];
+        except?: readonly string[];
+    }): Promise<void>;
 }
 
 /**
- * Auth Service surface for the React Native SDK.
+ * Auth Service surface for the React Native SDK — ADR-033 wave 1 (1.41.0),
+ * "One Slot, Two Verbs".
  *
- * Mirrors @sendoracloud/sdk-web's `auth` module. Three flows:
- *   signInAnonymously() — POST /auth-service/anonymous, mints a
- *       session for a user with no email yet.
- *   signUp(email, password) — if currently anonymous, calls
- *       /auth-service/upgrade with the stored refresh token; same
- *       user_id is preserved on success. Throws
- *       EmailAlreadyTakenError on 409. Otherwise calls
- *       /auth-service/signup as a fresh account.
- *   signIn(email, password) — POST /auth-service/login.
+ * THE MECHANISM (ADR-033 §3). The SDK has exactly ONE identity record and
+ * exactly ONE function that writes it: `commit()`. Every public method is sugar
+ * for one event of the shared transition table
+ * (`packages/shared/src/auth-machine/transitions.ts`, replayed by
+ * `test/auth-machine-conformance.test.ts`), and nothing outside `commit()`
+ * assigns `this.user` / the tokens, writes the auth storage keys, arms or stops
+ * the refresh cron, or decides which `onAuthStateChanged` event fires (INV-1).
  *
- * HARD INVARIANT — a failed auth attempt leaves the caller exactly as
- * it found them. Every credentialed path captures the anonymous
- * refresh token into a local (for the device-takeover hint), performs
- * its network call, validates the response, and only THEN clears the
- * old identity and persists the new one. Clearing first would drop the
- * refresh token — for an anonymous user the ONLY durable handle on the
- * account — so any failure after that point (offline, 5xx, a mistyped
- * OTP, a cancelled IdP callback) would orphan the account permanently.
- * A track() fired during the round-trip therefore attaches to the
- * still-anonymous identity, which is correct: the user is not
- * identified yet, and the backend reattributes it via the takeover.
+ *  - Proposal, then CAS (INV-2). A network call changes nothing until it
+ *    succeeds, and its result is applied only if the session it was derived from
+ *    is still current: identity-changing commits are keyed on the server session
+ *    family id `sid` (stable across token rotation), token commits on the
+ *    refresh token that was sent. A failed, abandoned or superseded attempt
+ *    leaves the caller exactly as found — there is no "wipe before the network
+ *    call" API left to misuse (the s58.271 class is unreachable).
+ *  - Sign-in never carries the guest (INV-3). No request body built here ever
+ *    contains `prevAnonRefreshToken`, `linkAnonymous` or `onCredentialInUse`.
+ *    A sign-in from a guest HOLDS the guest on the device (its live tokens go
+ *    into one of K=5 fixed secure slots `auth_held_0..4`) and switches; the
+ *    server row survives.
+ *  - Link is the only upgrade (INV-4). `signUp()`, `signInWith*({link:true})`,
+ *    `loginSocial({link:true})`, `link*()` and `link()` all go to `/me/link/*`
+ *    on the current Bearer session (same `sub`). `link:true` over an identified
+ *    session attaches or returns a typed error — it never switches (INV-14).
+ *  - Every session-installing event executes only from `signed_out` (INV-5);
+ *    in `unknown` it queues until the gap-fill refresh answers; in
+ *    `anonymous`/`identified` MINT returns the current user and the others link.
+ *  - The project guard (INV-15) is a commit guard: with `init({expectedProjectId})`
+ *    a stored/refreshed/restored session whose JWT `project` claim disagrees is
+ *    `withheld` — a fifth status, zero storage writes, every verb rejecting
+ *    `AuthError{kind:'config', code:'SESSION_WITHHELD'}`; a fresh mint that
+ *    disagrees is rejected (`PROJECT_MISMATCH`) and its refresh revoked.
  *
- * All public auth ops are serialized through a single-flight chain
- * so a UI double-submit can't mint two anonymous users or interleave
- * a signIn + signOut.
+ * STORAGE. The four frozen keys (`auth_access_token`, `auth_access_expires`,
+ * `auth_refresh_token`, `auth_user`) keep their 1.x format and are written on
+ * EVERY install commit (dual-write) so a downgrade to 1.40.0 reads a valid
+ * session. `auth_session` is the single-record form written beside them
+ * (read-first on hydrate, write-forward from the legacy keys). The held slots
+ * are five LITERAL key names — never built dynamically — so they are in
+ * `SECURE_KEYS` and route through the app's Keychain/Keystore adapter. Tokens
+ * persist in AsyncStorage BY DEFAULT (OWASP MASVS-L1); the opt-in
+ * `secureStorage` adapter (1.18.0) moves the secure keys into the Keychain.
  *
- * Tokens (including the refresh token) persist in AsyncStorage BY
- * DEFAULT — unencrypted app-sandbox storage: isolated from other apps
- * by the OS sandbox, but readable with filesystem/backup access to a
- * jailbroken/rooted or unlocked device (OWASP MASVS-L1). Since 1.18.0 an
- * OPTIONAL `secureStorage` adapter (`Sendora.init({ secureStorage })`,
- * wired in index.ts) routes the SECURE_KEYS (refresh/access/user) through
- * an app-supplied Keychain / Keystore adapter, with transparent
- * plaintext→secure migration; omit it and behaviour is unchanged. The
- * `auth_refresh_token` storage key stays frozen for back-compat either way.
- *
- * Response payloads are validated non-empty before persisting so a
- * malformed/MITM'd response can't 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.
+ * TOKEN LIVENESS is unchanged machinery (s58.281): two deadlines, the one-probe
+ * `clockSkewConfirmed` guard, single-flight refresh, 30 s-capped backoff. The
+ * token layer never decides identity except on the single server verdict
+ * `INVALID_REFRESH_TOKEN` (INV-6).
  */
 
+/** K — the held-guest capacity (ADR-033 §3.2, §8-Q19). */
+declare const HELD_GUEST_SLOTS = 5;
+/**
+ * The five client states (ADR-033 §3.2). `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.
+ *
+ * ⚠ NORMATIVE: consumers MUST default-branch on this value. `withheld` is new in
+ * 1.41.0; any LATER value ships opt-in-gated or in a MAJOR.
+ */
+type AuthStatus = "unknown" | "signed_out" | "anonymous" | "identified" | "withheld";
+/** `error.details.endReason` on an `INVALID_REFRESH_TOKEN` rejection (ADR-033 B11). */
+type RefreshEndReason = "expired" | "revoked" | "evicted" | "deleted" | "reuse" | "unknown";
+/** The `code` of the refusal when a destructive/identity held-guest verb omits `id` with 2+ guests held. */
+declare const AMBIGUOUS_HELD_GUEST = "AMBIGUOUS_HELD_GUEST";
 interface AuthUser {
     id: string;
     email: string | null;
@@ -315,6 +372,12 @@ 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 = the project; an EXPLICIT `null` = the org-wide
+     * pool; absent = a backend older than B17 (never read absent as null).
+     */
+    project?: string | null;
 }
 interface AuthTokens {
     accessToken: string;
@@ -340,6 +403,122 @@ interface GameCenterPayload {
 }
 /** @see AuthApiResponse.anonRetirement */
 type AnonRetirementOutcome = "retired" | "preserved" | "none";
+type SocialCredentialProvider = "google" | "github" | "apple" | "microsoft" | "linkedin" | "facebook" | "twitter" | "discord";
+/**
+ * One closed union instead of nine method signatures. Each member carries
+ * exactly the wire fields of its sign-in / link route MINUS the guest hint
+ * (INV-3: there is no field to put a guest credential in).
+ */
+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";
+} & GameCenterPayload) | {
+    kind: "playGames";
+    serverAuthCode: string;
+} | {
+    kind: "magicLink";
+    token: string;
+} | {
+    kind: "emailOtp";
+    email: string;
+    code: string;
+}
+/**
+ * React Native ships no WebAuthn authenticator; the kind is accepted for
+ * parity with the shared union. `assertion` is forwarded as the
+ * `passkeys/authenticate/finish` body (`{ response, userId }`); an object
+ * without a `response` key is wrapped as the response itself.
+ */
+ | {
+    kind: "passkey";
+    assertion: Record<string, unknown>;
+} | {
+    kind: "mfa";
+    challengeToken: string;
+    code: string;
+};
+type CredentialKind = Credential["kind"];
+/**
+ * `previous` is what the SWITCH replaced. `held: true` ⇔ the previous slot was
+ * anonymous and is now in a held slot. `previous.isAnonymous === false` ⇒ an
+ * identified → identified switch: skip `mergeAnon` 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 — a sign-in continuation on the same credential. */
+    verify(code: string): Promise<SignInResult>;
+};
+type LinkCollision = "identity" | "email";
+/**
+ * Three outcomes, nothing mutated on the two refusals (INV-12, B2).
+ *
+ *  - `done{alreadyLinked:true}` — a quiet 200: NO event, NO revoke, NO step-up (B13).
+ *  - `done{upgraded}` — true when the caller was anonymous (same `sub`, rotated pair).
+ *  - `credential_in_use` — owned by another account (409). `switchAccount()` is
+ *    the ONLY path from a refused link to a sign-in and is BOUND to the refused
+ *    credential (INV-14): same payload if under 5 min old, else re-fetched
+ *    natively (Game Center / Play Games) and compared, aborting with
+ *    `CREDENTIAL_CHANGED` on mismatch. From anonymous the guest is HELD; from
+ *    identified `previous:{isAnonymous:false, held:false}`.
+ *  - `recent_auth_required` — the credential is fine, the session is stale (403).
+ *    Deliberately NO `reauthenticate(credential)` closure: the credential being
+ *    linked must never serve as the re-auth.
+ */
+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";
+};
+/** What `getHeldGuests()` returns — the slot MINUS its tokens (never exposes tokens). */
+interface HeldGuestSummary {
+    userId: string;
+    heldAt: number;
+    autoRestore: boolean;
+    project: string | null;
+}
+/** `guest_released.reason` — every exit from a slot names one. */
+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;
+}
 declare class EmailAlreadyTakenError extends Error {
     constructor(message?: string);
 }
@@ -349,6 +528,7 @@ declare class EmailAlreadyTakenError extends Error {
  * current one — use `linkEmailPassword()` / `linkGoogle()` / … (ADR-030) to
  * add the credential to THIS account, or sign out first. Distinct from
  * `EmailAlreadyTakenError`: the email isn't the problem, the live session is.
+ * Decided LOCALLY since 1.41.0 (no round-trip).
  */
 declare class AlreadyIdentifiedError extends Error {
     constructor(message?: string);
@@ -356,7 +536,8 @@ declare class AlreadyIdentifiedError extends Error {
 /**
  * A credential you tried to LINK (ADR-030) is already attached to a DIFFERENT
  * account. Sendora never auto-merges two real accounts — sign in to that
- * account instead, or link a different credential.
+ * account instead (`switchAccount()` on the typed `link()` result, or
+ * `onCredentialInUse: "adopt"`), or link a different credential.
  */
 declare class CredentialInUseError extends Error {
     /** Always `"CREDENTIAL_IN_USE"`. */
@@ -380,11 +561,11 @@ declare class CredentialInUseError extends Error {
      * already linked to another account; `"email"` = the provider's verified
      * email already belongs to one. Absent on older backends.
      */
-    readonly collision?: "identity" | "email";
+    readonly collision?: LinkCollision;
     readonly status?: number;
     constructor(message?: string, opts?: {
         provider?: string;
-        collision?: "identity" | "email";
+        collision?: LinkCollision;
         status?: number;
     });
 }
@@ -392,42 +573,36 @@ declare class CredentialInUseError extends Error {
  * What a sign-in should do when the credential you present already belongs to
  * an account.
  *
- * **You usually want the default — omit this.** Since 1.32.0 the default is
- * safe by construction: adopt the other account silently when nothing would be
- * destroyed, and refuse when something would be.
- *
- * - **Fresh install / no guest session** → nothing to lose, so it adopts. This
- *   is the reinstall-recovery path: a Game Center / Play Games identity
- *   survives a reinstall server-side, so the "collision" is usually the SAME
- *   person's earlier account, and they get it back. Never refused.
- * - **Live guest session** → adopting would retire it (**its row is deleted**
- *   and `onDeviceTakeover` fires). Refused with `CredentialInUseError` so you
- *   can ask the player instead of the SDK guessing on their behalf.
- *
- * Override in either direction:
+ * **You usually want the default — omit this.** Since 1.41.0 a collision is
+ * only ever observed on a LINK (`link:true` from a guest or an identified
+ * session), where the server refuses with 409 `CREDENTIAL_IN_USE` and NOTHING
+ * is mutated: the guest account on this device is never deleted by a sign-in
+ * any more (ADR-033 INV-3). The question is only what to do next:
  *
- * - `"adopt"` — always adopt, even when it deletes the guest account. This is
- *   what every release before 1.30.0 did unconditionally.
- * - `"reject"` — always throw on a collision, even a harmless one.
+ * - **omitted / `"reject"`** — throw `CredentialInUseError` so you can ask the
+ *   player. The installed collision dialog keeps working unchanged.
+ * - **`"adopt"`** — fall through to a plain sign-in into the owning account
+ *   (explicit consent). From a guest the guest is HELD on the device (see
+ *   `getHeldGuests()`), not retired; from an identified session nothing is held.
  *
- * ⚠ A refusal blocks the switch; it does not merge the two accounts. To offer
- * "use my other account", catch the error and re-call with `"adopt"`, then
- * migrate your own data from `onDeviceTakeover`'s `retiredAnonUserId`.
+ * ⚠ A plain `signInWith*()` without `link:true` never sees a collision: with no
+ * guest hint on the wire there is nothing for the server to refuse — it signs
+ * into the owning account and holds the previous guest.
  */
 type CredentialCollisionPolicy = "adopt" | "reject";
 /** Options for the Game Center / Play Games sign-in methods. */
 type GameSignInOptions = {
     /**
-     * ADR-025 link-in-place. When this device is anonymous and the player
-     * identity is BRAND NEW, the anonymous account is promoted in place and the
-     * user id (sub) is preserved. Has no effect on a collision — see
-     * `onCredentialInUse` for that case.
+     * Attach-or-error (ADR-033 INV-14). In `anonymous` the guest is promoted in
+     * place (same user id); in `identified` the identity is attached to the
+     * current account — an identity already on it is a quiet no-op, one owned
+     * elsewhere throws `CredentialInUseError`, a stale session throws
+     * `RECENT_AUTH_REQUIRED`. In `signed_out` it is a plain sign-in.
      */
     link?: boolean;
     /**
-     * What to do when the player identity already belongs to an account.
-     * **Omit it** — the default refuses only when a live guest session would be
-     * deleted. See {@link CredentialCollisionPolicy}.
+     * What to do when `link:true` finds the identity on ANOTHER account. Omit it
+     * to be asked (`CredentialInUseError`); see {@link CredentialCollisionPolicy}.
      */
     onCredentialInUse?: CredentialCollisionPolicy;
 };
@@ -459,10 +634,9 @@ type UnlinkResult = {
  * Closed set of auth failure categories (1.28.0). Branch on `kind` instead of
  * string-matching the ~20 raw `code`s the backend and transport can produce.
  *
- * Pairs with the hard guarantee this release introduces: **a failed auth
- * attempt never changes the local session.** An offline sign-in, a mistyped
- * OTP, a dismissed Game Center sheet and a 429 all leave `getUserSync()` and
- * the stored refresh token exactly as they were.
+ * ⚠ CLOSED — mirrored by every SDK and compared by
+ * `packages/shared/src/auth-error-kind-parity.test.ts`. ADR-033's two project
+ * guard refusals REUSE `config` (`code: SESSION_WITHHELD | PROJECT_MISMATCH`).
  */
 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 {
@@ -484,12 +658,45 @@ declare class AuthError extends Error {
     readonly retryAfterSeconds?: number;
     /** HTTP status when the failure came from a response (absent when offline). */
     readonly status?: number;
+    /**
+     * ADR-033 B11: on an `INVALID_REFRESH_TOKEN` rejection, the server's own
+     * verdict (`expired | revoked | deleted | reuse | unknown`; `evicted`
+     * reserved). Absent on every other code and on an older backend.
+     */
+    readonly endReason?: RefreshEndReason;
     constructor(code: string, message: string, opts?: {
         status?: number;
         retryAfterSeconds?: number;
         kind?: AuthErrorKind;
+        retryable?: boolean;
+        endReason?: RefreshEndReason;
     });
 }
+/**
+ * The device holds K=5 guests and the requested mint would exceed the bound
+ * T = |held| + (current anonymous ? 1 : 0) ≤ K (ADR-033 §3.3): thrown by
+ * `signInAnonymously({forceNew:true})` at the cap, and by a plain mint /
+ * `ensureSession()` in `signed_out` when every slot is ineligible for
+ * auto-restore (all stamped `autoRestore:false` by `deleteAccount()`, or
+ * project-withheld — §8-Q22). Nothing was mutated; the app must
+ * `restoreHeldGuest(id)` or `discardHeldGuest(id)` first.
+ */
+declare class HeldGuestLimitError extends AuthError {
+    constructor(message?: string);
+}
+/**
+ * `restoreHeldGuest(id)` was refused CLIENT-SIDE: the slot's `project` claim
+ * recorded at HOLD (or on its refresh response) mismatches
+ * `expectedProjectId ?? config.projectId`. The slot is KEPT and excluded from
+ * auto-restore; no network call was made. Only `claimHeldGuest()` is
+ * server-guarded — the server does not enforce this on refresh.
+ */
+declare class HeldGuestProjectMismatch extends AuthError {
+    readonly userId: string;
+    readonly expectedProjectId: string;
+    readonly actualProjectId: string | null;
+    constructor(userId: string, expectedProjectId: string, actualProjectId: string | null);
+}
 interface AuthHooks {
     /** Storage shared with the parent SDK so re-hydration is consistent. */
     storage: Storage;
@@ -497,23 +704,39 @@ interface AuthHooks {
      *  identity (analytics userId, push token registration, etc). */
     onIdentityChange: (userId: string | null) => void;
     /**
-     * Called from `wipeLocalIdentity` whenever the local session is cleared. The
-     * `reason` lets the parent decide whether to rotate the anonymous analytics id:
-     * it rotates ONLY at a person-boundary ("user" = explicit signOut,
-     * "account_deleted"), never on a successful sign-in/upgrade ("replaced") or an
-     * involuntary session death ("session_expired") — those are the same person, and
-     * the anon id must survive so pre-auth analytics link to them (Firebase-FID
-     * semantics; the industry norm).
+     * Called from the clear funnel whenever the local session is cleared. The
+     * `reason` lets the parent decide whether to rotate the anonymous analytics
+     * id: it rotates ONLY at a person-boundary ("user" = explicit signOut,
+     * "account_deleted"), never on an involuntary session death
+     * ("session_expired" / the B11 reasons) — those are the same person, and the
+     * anon id must survive so pre-auth analytics link to them (Firebase-FID
+     * semantics). A successful sign-in or upgrade never calls this at all since
+     * 1.41.0: the guest is HELD, not wiped, and the anon id is untouched (s58.350).
      */
     onAnonymousWipe: (reason: WipeReason) => Promise<void>;
+    /**
+     * ADR-033 [2c] analytics quarantine hook: the stored session was refused by
+     * the project guard. The parent nulls its in-memory `userId` ONLY — the
+     * persisted `user_id` is untouched (zero storage writes in `withheld`).
+     */
+    onIdentityWithheld?: (info: WithheldInfo) => void;
     apiUrl: string;
     publicKey: string;
     debug: boolean;
+    /**
+     * Opt-in project guard (ADR-033 [2c]). Validated by `index.ts` (UUID; equal
+     * to `projectId` when both set). Produces the `withheld` status.
+     */
+    expectedProjectId?: string;
+    /** `config.projectId` — the fallback the held-slot project check compares against. */
+    projectId?: string;
+    /** Default true (§8-Q1): `ensureSession()` in `signed_out` restores the newest eligible held guest before minting. */
+    autoRestoreHeldGuest?: boolean;
 }
 /**
- * Detail handed to onDeviceTakeover subscribers. Fires once per
- * signIn / loginSocial / verifyMagicLink / verifyEmailOtp /
- * passkey-auth / SSO completion that retires an anonymous row.
+ * Detail handed to onDeviceTakeover subscribers. LEGACY (ADR-033): fires only
+ * when the SERVER reports a retirement, which this SDK never requests — a
+ * wave-1 sign-in carries no guest hint, so no guest is ever retired for it.
  */
 interface DeviceTakeoverEvent {
     /** The anonymous user_id Sendora just hard-deleted. */
@@ -535,30 +758,52 @@ interface DeletionCancelledEvent {
     at: Date;
 }
 /**
- * Why the local session ended (1.28.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.
  *
- * - `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.
+ * - `user`            — the app called `signOut()` (or `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.
  * - `account_deleted` — `deleteAccount()` succeeded.
+ * - `revoked` / `evicted` / `deleted` — ⚠ emitted by 1.41.0 ONLY, never since
+ *                       1.41.1. 1.41.0 put the server's `endReason` here, which
+ *                       renamed "account deleted elsewhere" / "sessions revoked"
+ *                       (both `session_expired` through 1.40.0) and silently
+ *                       broke listeners matching `session_expired`. Kept in the
+ *                       type so code written against 1.41.0 still compiles.
+ *
+ * Transient network failures and rate limits never produce any of these.
+ * Consumers default-branch (§3.5 NORMATIVE).
  */
-type AuthSignedOutReason = "user" | "session_expired" | "account_deleted";
+type AuthSignedOutReason = "user" | "session_expired" | "account_deleted" | "revoked" | "evicted" | "deleted";
 /**
- * A single auth-state transition (1.28.0). Subscribe with
- * `onAuthStateChanged` — one stream covering everything that used to need
- * separate listeners (or had none at all).
+ * Why a `signed_in` fired (ADR-033 §3.5). `restore` ⇒ 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
+ * (`signInWith*({link:true})`, `loginSocial({link:true})`, `signUp`) keep
+ * emitting (§8-Q18). Absent on a gap-fill recovery from `unknown` (1.29.0).
+ */
+type AuthSignedInCause = "mint" | "sign_in" | "restore" | "link";
+/** What changed the user object WITHOUT changing the `sub`. */
+type AuthUserUpdatedCause = "link" | "unlink" | "email_verified" | "refresh" | "merge";
+/**
+ * A single auth-state transition. Subscribe with `onAuthStateChanged` — one
+ * stream covering everything. The first four members are the pre-1.41.0
+ * contract verbatim (`signed_in` gaining an OPTIONAL `cause`); the rest are
+ * additive (ADR-033). ⚠ Default-branch on `event`.
  */
 type AuthStateChange = {
     event: "signed_in";
     user: AuthUser;
-} | {
+    cause?: AuthSignedInCause;
+}
+/** `endReason` (1.41.1) = the server's own verdict on a dead refresh token; absent on `user` / `account_deleted` and from an older backend. */
+ | {
     event: "signed_out";
     user: null;
     reason: AuthSignedOutReason;
+    endReason?: RefreshEndReason;
 } | {
     event: "device_takeover";
     user: AuthUser | null;
@@ -566,12 +811,47 @@ type AuthStateChange = {
 } | {
     event: "deletion_cancelled";
     user: AuthUser | null;
+}
+/** The settled boot state, exactly once per subscriber — INCLUDING `signed_out`, `unknown` and `withheld`. */
+ | {
+    event: "initial";
+    status: AuthStatus;
+    user: AuthUser | null;
+    withheld?: WithheldInfo;
+}
+/** Same `sub`, different user object (a link attach, an unlink, a claim, a refresh that changed the user). */
+ | {
+    event: "user_updated";
+    user: AuthUser;
+    cause: AuthUserUpdatedCause;
+}
+/** A guest was moved into a held slot (`count` = guests held after this one). */
+ | {
+    event: "guest_held";
+    userId: string;
+    count: number;
+    user: AuthUser;
+}
+/** A held slot was emptied. ⚠ `dead` = "unavailable when its token was presented", NOT an erasure signal. */
+ | {
+    event: "guest_released";
+    userId: string;
+    reason: GuestReleasedReason;
+    endReason?: RefreshEndReason;
+}
+/** An in-process transition INTO `withheld` (a refresh answered with a mismatching claim). Never replayed. */
+ | {
+    event: "session_withheld";
+    reason: "project_mismatch";
+    expectedProjectId: string;
+    actualProjectId: string | null;
+    userId: string;
 };
 type AuthStateListener = (change: AuthStateChange) => void;
 /**
- * Internal marker for a wipe that is immediately followed by a `persist()` of
- * a NEW session (the sign-in success path). Not a sign-out — emitting one
- * would make every successful sign-in look like a logout to subscribers.
+ * The reasons the clear funnel can be entered with. `replaced` is kept on the
+ * type for compatibility with hooks written against 1.38–1.40 but is no longer
+ * produced: a successful sign-in HOLDS the previous guest instead of wiping it.
  */
 type WipeReason = AuthSignedOutReason | "replaced";
 declare class Auth {
@@ -579,6 +859,16 @@ declare class Auth {
     private user;
     private accessToken;
     private accessExpiresAt;
+    /** The in-memory mirror of the K held slots (index = slot number). Written only by commit(). */
+    private held;
+    /** Non-null ⇔ `status() === "withheld"` (ADR-033 [2c]). Never persisted. */
+    private withheld;
+    /** The refresh token the withheld record carried — the CAS key of `discardWithheld()`. */
+    private withheldRefresh;
+    /** B15: held guests whose `POST /guest/held` report has not yet returned 2xx. Persisted in `auth_session`. */
+    private heldReportsPending;
+    /** The in-flight identity-changing proposal; the proactive cron pauses while it is set. */
+    private attempt;
     /**
      * Set once we have PROOF that this device's clock runs fast, which
      * releases the `exp` guard in `canServeCachedToken`.
@@ -603,15 +893,10 @@ declare class Auth {
     private inflight;
     private refreshInflight;
     /**
-     * Wave 62 — refresh failure back-pressure.
-     *
-     * Consecutive network-timeout failures don't wipe identity (refresh
-     * may still be valid; iOS NSURLSession was just stalled) but do
-     * back off so the next caller doesn't immediately fire another
-     * fetch that will also time out. After `REFRESH_FAILURE_COOLDOWN_MS`
-     * the counter resets + retries are allowed. AppState foreground
-     * also clears it so a user returning to the app gets an immediate
-     * fresh attempt.
+     * Wave 62 — refresh failure back-pressure. Consecutive network-timeout
+     * failures don't wipe identity (refresh may still be valid; iOS NSURLSession
+     * was just stalled) but do back off so the next caller doesn't immediately
+     * fire another fetch that will also time out. AppState foreground clears it.
      */
     private refreshFailureCount;
     private refreshCooldownUntil;
@@ -621,185 +906,132 @@ declare class Auth {
     private lastDeletionCancelled;
     private lastAnonRetirement;
     private lastTakeover;
-    /**
-     * 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). Before this, the MFA branch wiped the anon
-     * identity before the challenge resolved → the takeover hint was lost → one
-     * device ended with two user_ids + duplicate pushes (audit s58.203 fix).
-     */
-    private pendingAnonTakeover;
     /**
      * Resolves when the parent SDK has finished its async init() —
      * AsyncStorage hydrated + auth.hydrate() restored the cached
      * session. All public auth methods await this internally so a
      * customer who forgets `await sendora.init()` before showing the
-     * signup UI doesn't hit the cold-start race where the upgrade
-     * path's `storage.get(REFRESH_KEY)` returns null even though a
-     * valid anonymous session is sitting on disk.
-     *
-     * Industry-standard "SDK gates on internal readiness" pattern
-     * (Firebase Auth, Auth0, Clerk all do equivalent internal
-     * gating).
+     * signup UI doesn't hit the cold-start race.
      */
     private readyPromise;
     private resolveReady;
-    /**
-     * True once `hydrate()` has run. Distinguishes "no session restored YET"
-     * from "genuinely signed out" for `onAuthStateChanged`'s replay-on-subscribe.
-     */
+    /** True once `hydrate()` has run. Gates `onAuthStateChanged`'s replay-on-subscribe. */
     private hydrated;
     constructor(hooks: AuthHooks);
     /**
-     * Re-hydrate session from storage. Called by the parent SDK during
-     * init() after Storage.hydrate() has run. Marks the internal ready
-     * promise as resolved so queued auth calls unblock.
-     *
-     * s58.47 — restore the user even when the cached ACCESS token is
-     * missing/expired, as long as USER_KEY + REFRESH_KEY are present.
-     * Pre-s58.47 this required BOTH USER_KEY and TOKEN_KEY, which
-     * caused a cold-start regression: if the access token rotated out
-     * of storage (TTL elapsed, app killed between persists, partial
-     * write, AsyncStorage eviction) the user appeared signed out even
-     * though their refresh chain was still alive in storage. Hosts
-     * then called `signInAnonymously()` on every launch and minted a
-     * fresh anon user, fragmenting analytics across sessions
-     * (Pulse News symptom). With the refresh token present, the next
-     * `getAccessToken()` call will silently refresh + restore a valid
-     * access token without disturbing identity.
+     * Restore the session from storage. Called by the parent SDK during
+     * init() after Storage.hydrate() has run. Disk-only, never waits on the
+     * network; resolves the internal ready gate so queued auth calls unblock.
+     *
+     * Reads `auth_session` FIRST, then the four frozen keys. When the frozen keys
+     * carry a refresh token that differs from the record's, the FROZEN keys win:
+     * every SDK version writes them, so after a 1.41 → 1.40 → 1.41 round trip
+     * they are the fresher copy and the stale `auth_session` must not resurrect a
+     * rotated-away token. The record is then written forward from them.
+     *
+     * Coherence (INV-9): user ∧ refresh → judged by the project guard
+     * (match → installed; mismatch → `withheld`, ZERO writes; unknown → stay
+     * `unknown`, one gap-fill refresh re-judges it); refresh ∧ ¬user → `unknown`
+     * (LIMBO_A — never `signed_out`, never a mint; the refresh token is the only
+     * thing that can recover the account, 1.28.0); user ∧ ¬refresh → the stale
+     * blob is cleared → `signed_out`. Held slots: a slot whose `userId` equals the
+     * current user is dropped (current wins); a slot that fails to parse is KEPT
+     * and ignored, never cleared (P11).
      */
     hydrate(): void;
+    /** Read `auth_session` + the four frozen keys and reconcile them (see `hydrate()`). */
+    private readDiskSession;
+    /** Load the K slots into the in-memory mirror; dedupe against the current user (current wins); keep unparseable slots untouched. */
+    private hydrateHeldSlots;
+    /** Parse one slot off disk. `null` for an empty OR unparseable slot (the latter is left on disk, P11). */
+    private readSlot;
+    /**
+     * The closed boot/identity state. Synchronous, never waits on the network.
+     *
+     *  - `unknown`     — not hydrated yet, OR a refresh token is on disk but the
+     *                    user is not readable / not yet judged (the gap-fill
+     *                    refresh settles it). Session-installing verbs QUEUE here.
+     *  - `signed_out`  — no refresh token. The only state a mint executes in.
+     *  - `anonymous` / `identified` — a live session of that kind.
+     *  - `withheld`    — a stored session refused by `init({expectedProjectId})`.
+     *
+     * ⚠ This is the ONLY way to tell `withheld` and `unknown` from `signed_out`:
+     * `getUserSync()` is `null` and `isReady()` is `true` in all three. Consumers
+     * MUST default-branch — a later value ships opt-in-gated or in a MAJOR.
+     */
+    status(): AuthStatus;
+    /** Resolves after hydrate with the settled status — possibly `unknown` or `withheld`. Never waits on the network. */
+    authStateReady(): Promise<AuthStatus>;
     getCurrentUser(): AuthUser | null;
+    /** Alias of `getCurrentUser()` gated on hydration (parity with `Sendora.getUserSync()`). */
+    getUserSync(): AuthUser | null;
+    /** True once `hydrate()` has run. `true` in `withheld` and `unknown` too — read `status()`. */
+    isReady(): boolean;
     /**
-     * Subscribe to device-takeover events (s58.111+). Backend retires
-     * the anonymous user_id whenever a previously-anon device signs in
-     * to an identified account. Use this to clean up any local mirror
-     * keyed by the anonymous id — your own users table, an analytics
-     * cache, an audience filter — without needing a webhook receiver.
-     *
-     * Fires on EVERY identified sign-in path — `signIn`, `loginSocial`,
-     * `signInWithGameCenter`, `signInWithPlayGames`, `challengeMfa`,
-     * `verifyMagicLink`, `verifyEmailOtp`, passkey authentication, and SSO
-     * completion (`consumeSsoFragment`) — because it is fired centrally from
-     * `persist()` whenever the response carries `retiredAnonUserId`.
+     * Subscribe to device-takeover events (s58.111+). LEGACY after ADR-033: a
+     * wave-1 SDK never sends the guest hint, so the server never retires a guest
+     * for its sign-ins and this fires only if the SERVER reports a retirement.
+     * Kept callable; replace your handler with `onAuthStateChanged` +
+     * `guest_held` / `getHeldGuests()`. Returns an unsubscribe function.
      *
-     * ⚠ The two gaming paths are the ones that matter most here, and were
-     * missing from this list before 1.31.0. When the presented player identity
-     * already belongs to another account, the sign-in ADOPTS that account and
-     * the anonymous account on this device is retired — its row is DELETED
-     * server-side. This listener is the only client-side signal that happened;
-     * the call itself resolves successfully. If you would rather it not happen
-     * at all, pass `onCredentialInUse: "reject"`.
-     *
-     * Returns an unsubscribe function.
-     *
-     * Listeners are best-effort: errors thrown inside them are swallowed
-     * + logged in dev mode. Auth state never depends on listener success.
+     * Historically the account-DELETING paths were the gaming sign-ins —
+     * `signInWithGameCenter` / `signInWithPlayGames` (and `loginSocial`) adopting
+     * an existing account retired this device's guest row while the call itself
+     * resolved successfully. On 1.41.0 those calls HOLD the guest instead; a
+     * takeover can only be reported for a sign-in that reached the legacy path.
      */
     onDeviceTakeover(listener: (evt: DeviceTakeoverEvent) => void): () => void;
     /**
-     * Subscribe to every auth-state transition (1.28.0) — the single stream that
-     * answers "what happened to my session?". Firebase `onAuthStateChanged` /
-     * Supabase `onAuthStateChange` parity.
-     *
-     * The reason it exists: a session that dies in the BACKGROUND (the server
-     * 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" }`.
+     * Subscribe to every auth-state transition — the single stream that answers
+     * "what happened to my session?". Firebase `onAuthStateChanged` / Supabase
+     * `onAuthStateChange` parity.
      *
-     * Fires the CURRENT state immediately on subscribe once `init()` has
-     * hydrated (a `signed_in` when a session was restored from disk — including
-     * offline, since hydrate is disk-only), so a subscriber never misses the
-     * state it started in. Nothing is emitted for a signed-out cold start.
+     * Replays the SETTLED boot state exactly once on subscribe, once `init()` has
+     * hydrated, as `initial{status,user,withheld?}` — including `signed_out`,
+     * `unknown` and `withheld`, so a subscriber can never confuse "no session"
+     * with "not hydrated yet". With a live session (`anonymous` / `identified`)
+     * `initial` is FOLLOWED by the legacy `signed_in{user}` replay that
+     * 1.28.0–1.40.0 sent (kept — ADR-023); new code should read `initial` and
+     * ignore a `signed_in` that carries no `cause` right after it.
      *
      * A failed sign-in emits NOTHING: the session is unchanged, so there is no
      * transition to report — the rejected promise is the whole story.
      *
-     * ⚠ This is a TRANSITION stream, not a health or connectivity signal (1.40.0
-     * doc fix, reported by RopoLabs). A transient failure of the background
-     * token refresh — offline, timeout, HTTP 429, 5xx, an unparseable response —
-     * emits nothing: the stored refresh token is kept and the refresh retried
-     * with backoff, so no state changed. "No event" therefore means "no
-     * confirmed transition", never "the session is fine". Only a server-REJECTED
-     * refresh token produces `signed_out(session_expired)`. For liveness read
-     * `getAccessToken()` (null = no usable token right now).
+     * ⚠ This is a TRANSITION stream, not a health or connectivity signal. A
+     * transient failure of the background token refresh (offline, timeout, 429,
+     * 5xx) emits nothing: the stored refresh token is kept and the refresh retried
+     * with backoff. Only a server-REJECTED refresh token produces `signed_out`
+     * (reason `session_expired`, or the server's own `revoked` / `deleted`). For
+     * liveness read `getAccessToken()` (null = no usable token right now).
      *
-     * Listeners are best-effort; a throwing listener is swallowed (dev-logged)
-     * and never affects auth state. Returns an unsubscribe function.
+     * Replacing a guest with an account emits `guest_held` then ONE `signed_in`
+     * — no `signed_out`. Listeners are best-effort; a throwing listener is
+     * swallowed (dev-logged). Returns an unsubscribe function.
      */
     onAuthStateChanged(listener: AuthStateListener): () => void;
     /** Fan a state change out to subscribers. Never throws. */
     private emitAuthState;
-    /**
-     * Inspect the most recent device-takeover event observed by the
-     * SDK. Cleared on signOut. Returns null when no takeover has
-     * happened during this session — useful for late subscribers or
-     * post-sign-in side-effects (e.g. app-launch hydrate).
-     */
+    /** The most recent device-takeover event observed, or null. Cleared on signOut. */
     getLastDeviceTakeover(): DeviceTakeoverEvent | null;
-    /** Internal — fan out to subscribers + cache the latest. */
     private fireDeviceTakeover;
     /**
      * Subscribe to deletion-cancelled events (s58.269): fires when a sign-in
      * cancelled a pending self-service account deletion within its grace window
-     * (the account is restored, same user_id). Use it to show "your account
-     * deletion was cancelled" + reconcile local state. Fires from signIn /
-     * loginSocial / signInWithGameCenter / signInWithPlayGames. Returns an
-     * unsubscribe function; listener errors are swallowed (best-effort).
+     * (the account is restored, same user_id). Also surfaced as
+     * `SignInResult.reactivated`. Returns an unsubscribe function.
      */
     onDeletionCancelled(listener: (evt: DeletionCancelledEvent) => void): () => void;
     /** The most recent deletion-cancelled event this session, or null. Cleared on signOut. */
     getLastDeletionCancelled(): DeletionCancelledEvent | null;
     /**
-     * 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. `"retired"` means
-     * migrate from `onDeviceTakeover`'s id; `"none"` means there was nothing to
-     * reconcile. Cleared on signOut.
+     * What the last sign-in did with this device's guest account (s58.278).
+     * LEGACY: a wave-1 SDK never presents a guest token, so a current backend
+     * answers `"none"` for every sign-in. Read `getHeldGuests()` instead — the
+     * guest is on this device, held. Recorded only when the server states the
+     * field. Cleared on signOut.
      */
     getLastAnonRetirement(): AnonRetirementOutcome | null;
-    /** Internal — fan out deletion-cancelled to subscribers + cache the latest. */
     private fireDeletionCancelled;
-    /**
-     * Returns a VALID (non-expired) access token, or null.
-     *
-     * Hard contract (matches sdk-ios / sdk-android, and the industry
-     * token-client pattern — Supabase `_callRefreshToken`, Auth0
-     * `getTokenSilently`, Firebase `getIdToken`): this method 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. A token expired by hours is useless and yields a 401.
-     *
-     * Resolution order:
-     *  1. Cached token with comfortable life left (>= REFRESH_SAFETY_MS
-     *     before BOTH the tracked deadline and the token's own `exp`) →
-     *     return it. Fast path, no I/O. See `canServeCachedToken` for why
-     *     both are required and when the second is released.
-     *     Pass `{ forceRefresh: true }` to skip this step when the caller
-     *     knows the tracked deadline is wrong.
-     *  2. No cached token AND no refresh token in storage → genuinely
-     *     signed out → null.
-     *  3. Expired/near-expiry but a refresh chain exists:
-     *     a. A refresh is already inflight → AWAIT it and return the
-     *        fresh token. Concurrent callers coalesce onto the single
-     *        in-flight `/token/refresh` (single-flight) — nobody is
-     *        handed a stale token. The inflight fetch is
-     *        AbortController-bounded (http.ts caps `/auth-service/*` at
-     *        10s), so awaiting can NEVER hang the JS bridge. That
-     *        bounded-fetch guarantee — NOT the old stale-token return —
-     *        is what actually fixed the Wave-62 cold-launch hang.
-     *     b. A recent refresh failed and we're in backoff cooldown →
-     *        null. Honest "no usable token right now" rather than a
-     *        provably-expired one; the AppState foreground hook clears
-     *        the cooldown for an immediate retry on resume.
-     *     c. Otherwise → fire the refresh and await it.
-     */
     /**
      * The cached-token guard, and the single place the two deadlines are
      * combined. Both must agree before a cached token is served:
@@ -810,16 +1042,8 @@ declare class Auth {
      *     full offset on a constantly-wrong clock.
      *
      * Guard 2 is released once `clockSkewConfirmed` proves the second failure
-     * mode is the one we are actually in.
-     *
-     * The gap this closes: `accessExpiresAt` is written in the device's clock
-     * frame at mint and PERSISTED. Step the clock backwards between mint and
-     * read — an iPhone acquiring automatic time after a long power-off, a
-     * restore, or a manual set — and the deadline is stale by the size of the
-     * correction, surviving relaunches. The SDK then serves a provably dead
-     * token, every request 401s, and because the fast path returns before
-     * reaching `persist()` or `wipeLocalIdentity()` nothing emits
-     * `signed_out`. Reported by Word Hurdle with a token 1929s past its `exp`.
+     * mode is the one we are actually in. ⚠ NEVER derive one deadline from the
+     * other (`accessExpiresAt = exp * 1000` throws away skew-invariance).
      */
     private canServeToken;
     private canServeCachedToken;
@@ -835,84 +1059,102 @@ declare class Auth {
      * the correction, so a mint-time probe records "clock is fast", and the flag
      * then waves through the very token the guard exists to refuse. Probing here
      * — only on a refresh we performed BECAUSE `exp` contradicted a tracked
-     * deadline that still claimed life — separates the two cases, because by now
-     * the clock has either been corrected (fresh token reads live → stale
-     * deadline, guard holds) or is genuinely fast (fresh token still reads dead
-     * → release the guard, one probe, no loop).
+     * deadline that still claimed life — separates the two cases: one probe, no loop.
      */
     private refreshAndReconcile;
-    /**
-     * Record whether a token the server issued MOMENTS AGO already reads as
-     * expired. It cannot genuinely be — so a `false` here is proof the device
-     * clock runs fast, and releases the `exp` guard for this process.
-     *
-     * Call this at every site that installs a server-issued token, and only
-     * with a token that just arrived. Handing it a cached token would let a
-     * stale deadline confirm itself.
-     */
+    /** A token the server issued MOMENTS AGO already reads as expired ⇒ the clock runs fast; release the `exp` guard for this process. */
     private learnClockSkewFrom;
     /** True when a cached token is unusable ONLY because its `exp` contradicts a live tracked deadline. */
     private deadlinesDisagree;
+    /**
+     * Returns a VALID (non-expired) access token, or null.
+     *
+     * Hard contract (matches sdk-ios / sdk-android, and the industry
+     * token-client pattern — Supabase `_callRefreshToken`, Auth0
+     * `getTokenSilently`, Firebase `getIdToken`): this method NEVER returns a
+     * token past its `exp`. Callers attach the result as a Bearer to arbitrary
+     * resource servers that know nothing of Sendora's refresh grace, so a token
+     * must be either fresh or absent.
+     *
+     * Resolution order:
+     *  0. `withheld` → null, no refresh (ADR-033 [2c]: the refused session is
+     *     never served and never refreshed by this process).
+     *  1. Cached token with comfortable life left (>= 30 s before BOTH the
+     *     tracked deadline and the token's own `exp`) → return it. Fast path.
+     *     `{ forceRefresh: true }` skips it (the caller has out-of-band evidence
+     *     the tracked deadline is wrong); it does NOT bypass the single-flight or
+     *     the backoff cooldown.
+     *  2. No refresh token in storage → genuinely signed out → null.
+     *  3. Expired/near-expiry but a refresh chain exists: a refresh already
+     *     inflight → await it (single-flight, AbortController-bounded, can never
+     *     hang the bridge); in backoff cooldown → null (honest "no token now");
+     *     else fire the refresh and await it.
+     */
     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;
+    /**
+     * The currently-stored refresh token, or null when signed out (and in
+     * `withheld`). Kept for integrators that journal the guest token for the
+     * deprecated `merge()`; since 1.41.0 the guest is HELD on the device instead —
+     * read `getHeldGuests()`.
+     */
+    getRefreshToken(): string | null;
     /**
      * Return the current session, minting an anonymous one only when there is
      * none.
      *
-     * Reuses the existing session when there already is one — anonymous OR
-     * identified. The anonymous half is the same short-circuit Firebase's
-     * `signInAnonymously` performs. Without it, an app that calls this
-     * defensively on every cold launch (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.
-     *
-     * ⚠ The identified half closes the same hole from the other side (1.40.0,
-     * reported by RopoLabs). Until then the guard 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 anything; it persists over the
-     * top. An app that called it on a "looks signed out" reading silently turned
-     * a paying account into a fresh guest, and its own session-death listener
-     * never fired. The account itself survives (row + server session untouched,
-     * recoverable by its credential) but the device is now a stranger to it.
-     * Returning the identified session is a no-op for that caller and the honest
-     * answer to "make sure I have a session" — read `user.isAnonymous` if you
-     * need to know which kind you got.
-     *
-     * Pass `forceNew: true` to deliberately abandon the current session —
-     * whichever kind — and mint a separate anonymous one. That is the ONLY way
-     * this method replaces an identified session, and it does so silently (the
-     * caller asked for it); `signOut()` first if you want a `signed_out`.
+     * - `anonymous` / `identified` → returned as-is, no network (the 1.29 / 1.40.0
+     *   guards as one row). Read `user.isAnonymous` to know which kind you got.
+     * - `signed_out` → with `autoRestoreHeldGuest` on (default) and an eligible
+     *   held guest on the device, the NEWEST one is restored instead of minting —
+     *   visibly: `signed_in{cause:'restore'}` + `guest_released{reason:'restored'}`.
+     *   A dead slot is released (`guest_released{dead}`) and the next tried; none
+     *   left → a fresh mint in the same call. Otherwise `POST /anonymous` →
+     *   `signed_in{cause:'mint'}`.
+     * - `unknown` → queued until the gap-fill refresh settles the status.
+     * - `withheld` → rejects `AuthError{kind:'config', code:'SESSION_WITHHELD'}`.
+     *
+     * `forceNew: true` abandons the current session and mints a separate guest:
+     * from a guest the current guest is HELD (never deleted); from an identified
+     * session it is replaced silently (its refresh token revoked). At the held
+     * capacity (K=5) it throws `HeldGuestLimitError` and mutates nothing.
      */
     signInAnonymously(opts?: {
         name?: string;
         metadata?: Record<string, unknown>;
         forceNew?: boolean;
     }): Promise<AuthUser>;
-    /**
-     * Create an email/password account.
-     *
-     * Industry-standard upgrade-first flow (matches Firebase
-     * `linkWithCredential`, Auth0 anonymous-merge, Supabase
-     * `linkIdentity`): when a refresh token is present in storage we
-     * try `/auth-service/upgrade` first — backend validates the
-     * refresh, checks the bound user is anonymous, and promotes in
-     * place preserving `user.id`. If the bound user is NOT anonymous
-     * (already identified, expired refresh, etc.), backend rejects
-     * with FORBIDDEN_NON_ANONYMOUS / INVALID_REFRESH and we fall back
-     * to a fresh /signup.
-     *
-     * Why we don't gate on the cached `this.user.isAnonymous`
-     * boolean: the in-memory user can be stale during cold start or
-     * fast-refresh races. The refresh token in storage is the
-     * authoritative signal — if it's there, the upgrade path is
-     * worth attempting; backend has the source of truth.
+    /** Alias of `signInAnonymously()` — "make sure I have a session". */
+    ensureSession(): Promise<AuthUser>;
+    /** Row 6 (and row 11's second half): `POST /anonymous` → ProjectGuard on the RESPONSE → install. */
+    private mintFresh;
+    /**
+     * Row 7 — one auto-restore attempt for `signInAnonymously()`. Returns the
+     * restored user, or `null` when the slot was dead and released (the caller
+     * tries the next slot, then mints). A transient failure propagates.
+     */
+    private restoreSlotForMint;
+    /** The per-attempt B10 key: reuse the persisted one (a crash-retry) or mint a new one and persist it until MINT_OK. */
+    private currentMintKey;
+    /**
+     * Create an email/password account — routed by `status()`:
+     *
+     *  - `anonymous`  → `POST /me/link/email` on the current Bearer session: the
+     *                   guest is promoted IN PLACE (same `user.id`), the rotated
+     *                   pair is installed, `signed_in{cause:'link'}` fires. A
+     *                   taken email throws `EmailAlreadyTakenError` and changes
+     *                   nothing.
+     *  - `signed_out` → `POST /signup`, a fresh account.
+     *  - `identified` → `AlreadyIdentifiedError`, decided LOCALLY (no round-trip,
+     *                   nothing minted — use `linkEmailPassword()` instead).
+     *  - `unknown`    → waits for the status to settle, then routes as above.
+     *  - `withheld`   → rejects `SESSION_WITHHELD`.
+     *
+     * Never calls `/upgrade` (ADR-033 INV-4): a generic 401 there used to wipe
+     * the guest, and the "dead token → wipe → fresh signup" branch is gone.
      */
     signUp(email: string, password: string, opts?: {
         name?: string;
@@ -922,6 +1164,10 @@ declare class Auth {
      * Sign in with email + password. When the user has confirmed MFA,
      * returns `{mfaRequired, mfaChallengeToken}` instead of an
      * `AuthUser`; caller must follow up with `challengeMfa()`.
+     *
+     * A sign-in from a guest HOLDS the guest on this device (`guest_held`, then
+     * ONE `signed_in{cause:'sign_in'}`); the guest's server row survives. The
+     * request never carries the guest's refresh token (ADR-033 INV-3).
      */
     signIn(email: string, password: string): Promise<AuthUser | {
         mfaRequired: true;
@@ -932,11 +1178,18 @@ declare class Auth {
      * Verify an IdP-issued credential (authorization code OR id_token)
      * and mint a Sendora session. Customer's app handles the IdP
      * dance — typically via expo-auth-session / react-native-app-auth
-     * — then hands the result here. See web SDK for full provider
-     * matrix; mirrors that surface 1:1.
+     * — then hands the result here. Mirrors the web SDK's surface 1:1.
+     *
+     * `link: true` (ADR-033 INV-14) — attach-or-error, never a silent switch:
+     * from a guest the account is promoted IN PLACE (same `user.id`,
+     * `signed_in{cause:'link'}`); over an identified session the identity is
+     * attached (`user_updated{cause:'link'}`), an identity already on the account
+     * resolves quietly, one owned elsewhere throws `CredentialInUseError`
+     * (or switches when `onCredentialInUse: "adopt"`), a stale session throws
+     * `RECENT_AUTH_REQUIRED`. In `signed_out` it is a plain sign-in.
      */
     loginSocial(input: {
-        provider: "google" | "github" | "apple" | "microsoft" | "linkedin" | "facebook" | "twitter" | "discord";
+        provider: SocialCredentialProvider;
         code?: string;
         idToken?: string;
         redirectUri?: string;
@@ -945,21 +1198,7 @@ declare class Auth {
             firstName?: string;
             lastName?: string;
         };
-        /**
-         * ADR-025 link-in-place opt-in. When this device is anonymous and you set
-         * `link: true`, an anon→social upgrade KEEPS the same user id (sub) — the
-         * anon account is promoted in place (like Firebase linkWithCredential)
-         * instead of a device-takeover that mints a new id. No effect when the
-         * device isn't anonymous, or when the social identity already belongs to
-         * another account (collision → falls back to takeover/merge).
-         */
         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 guest session would be
-         * deleted. See {@link CredentialCollisionPolicy}.
-         */
         onCredentialInUse?: CredentialCollisionPolicy;
     }): Promise<AuthUser>;
     signInWithGoogle(code: string, redirectUri: string, link?: boolean): Promise<AuthUser>;
@@ -972,7 +1211,7 @@ declare class Auth {
             firstName?: string;
             lastName?: string;
         };
-        /** ADR-025: keep the same user id on an anon→Apple upgrade. See `loginSocial`. */
+        /** Attach-or-error (ADR-033 INV-14). See `loginSocial`. */
         link?: boolean;
     }): Promise<AuthUser>;
     signInWithMicrosoft(code: string, redirectUri: string): Promise<AuthUser>;
@@ -984,15 +1223,18 @@ declare class Auth {
      *
      * **No-arg (1.23.0, recommended):** `signInWithGameCenter()` drives Game
      * Center natively via the `@sendoracloud/sdk-react-native-gaming` companion
-     * (`fetchItems(forIdentityVerificationSignature:)`, base64 signature/salt,
-     * `teamPlayerID`, bundle id) and posts the result. Needs that companion + its
-     * config plugin `{ gameCenter: true }` + a Dev Client — NOT Expo Go.
+     * and posts the result. Needs that companion + its config plugin
+     * `{ gameCenter: true }` + a Dev Client — NOT Expo Go.
      *
      * **Explicit:** `signInWithGameCenter(payload)` posts a payload you obtained
      * from your OWN GameKit module (works anywhere, incl. bare RN).
      *
-     * `link: true` KEEPS the same user id when upgrading an anonymous device
-     * (ADR-025 link-in-place); no effect off-anon or on a collision.
+     * `link: true` = attach-or-error (ADR-033 INV-14): promotes a guest in place
+     * (same `user.id`); over an identified session attaches, resolves quietly when
+     * the identity is already on the account, throws `CredentialInUseError` when
+     * it is owned elsewhere (pass `onCredentialInUse: "adopt"` to switch — the
+     * guest is HELD on the device, never deleted). A plain call switches accounts
+     * and holds the previous guest.
      */
     signInWithGameCenter(opts?: GameSignInOptions): Promise<AuthUser>;
     signInWithGameCenter(payload: GameCenterPayload, opts?: GameSignInOptions): Promise<AuthUser>;
@@ -1000,26 +1242,79 @@ declare class Auth {
      * Google Play Games sign-in (email-less, Android-only).
      *
      * **No-arg (1.23.0, recommended):** `signInWithPlayGames()` drives Play Games
-     * natively via the `@sendoracloud/sdk-react-native-gaming` companion
-     * (`requestServerSideAccess(webClientId, false)`, web client id read from the
-     * config-plugin manifest meta-data) and posts the `serverAuthCode`. Needs that
-     * companion + its plugin `{ playGamesWebClientId, playGamesProjectId }` + a Dev
-     * Client — NOT Expo Go.
+     * natively via the companion and posts the `serverAuthCode`. Needs the
+     * companion + its plugin + a Dev Client — NOT Expo Go.
      *
      * **Explicit:** `signInWithPlayGames({ serverAuthCode })` posts a code you
      * obtained from your OWN Play Games module.
      *
-     * `link: true` = ADR-025 link-in-place (same user id on an anon upgrade).
+     * `link: true` = attach-or-error (ADR-033 INV-14); see `signInWithGameCenter`.
      */
     signInWithPlayGames(opts?: GameSignInOptions): Promise<AuthUser>;
     signInWithPlayGames(payload: {
         serverAuthCode: string;
     }, opts?: GameSignInOptions): Promise<AuthUser>;
+    /**
+     * Shared gaming-identity sign-in. Resolves the credential FIRST (for the
+     * no-arg native path this triggers the Game Center / Play Games sheet inside
+     * the serialized op — a cancelled sheet leaves the session untouched), then
+     * routes by `link` and `status()` exactly like `loginSocial`.
+     */
+    private gameIdentitySignIn;
+    /**
+     * The legacy-signature LINK (`signInWith*({link:true})`, `loginSocial({link:true})`)
+     * in `anonymous` / `identified` (ADR-033 rows 15–16, §8-Q18):
+     *  - a promotion / attach resolves with the user (`signed_in{cause:'link'}` on
+     *    the same-`sub` promotion — preserved from 1.30–1.40; `user_updated` on an
+     *    identified attach; NOTHING on `alreadyLinked`);
+     *  - 409 → `CredentialInUseError`, or with `onCredentialInUse: "adopt"` the
+     *    explicit switch to the owning account (the guest is HELD);
+     *  - 403 → `AuthError` `RECENT_AUTH_REQUIRED` (kind `recent_auth_required`).
+     */
+    private legacyLink;
+    /**
+     * Exchange the MFA challenge token from `signIn` for a real session by
+     * submitting a TOTP or recovery code. A wrong code throws and preserves the
+     * current session for a retry; success holds the guest (if any) and installs
+     * the account exactly like a direct sign-in.
+     */
+    challengeMfa(mfaChallengeToken: string, code: string): Promise<AuthUser>;
+    /**
+     * Plain sign-in / SWITCH with a typed credential. Never links: from a guest
+     * the guest is HELD (`previous.held === true`); from an identified account
+     * the previous session is replaced and its refresh token revoked
+     * (`previous.isAnonymous === false` ⇒ skip `mergeAnon`, reset local save
+     * state). The request never carries a guest credential (INV-3). MFA returns
+     * `{status:'mfa_required', verify(code)}`.
+     */
+    signInWith(credential: Credential): Promise<SignInResult>;
+    /**
+     * Attach a credential to the CURRENT session — the ONLY upgrade (INV-4).
+     * From a guest: promoted in place (same `user.id`, `upgraded: true`,
+     * `user_updated{cause:'link'}`). From an identified account: attached
+     * (`user_updated`), or `alreadyLinked: true` with no event. Owned elsewhere →
+     * `{status:'credential_in_use', switchAccount(), keepCurrent()}` with nothing
+     * mutated; stale session → `{status:'recent_auth_required'}`. Throws
+     * `NOT_SIGNED_IN` in `signed_out` (nothing to attach to) and
+     * `UNSUPPORTED_LINK_CREDENTIAL` for a kind that cannot be attached
+     * (`magicLink`, `emailOtp`, `passkey`, `mfa`).
+     */
+    link(credential: Credential): Promise<LinkResult>;
+    /**
+     * The ONLY path from a refused link to a sign-in, BOUND to the refused
+     * credential (INV-14): the same payload is reused while under 5 minutes old;
+     * older than that, a Game Center / Play Games credential is re-fetched
+     * natively and the Game Center `teamPlayerId` compared — a different player
+     * aborts with `CREDENTIAL_CHANGED` and nothing is mutated. (A Play Games
+     * server auth code carries no player id, so a re-fetched code is used as-is.)
+     */
+    private switchAccount;
+    private toSignInResult;
     /** Link email + password to the current account (sub preserved). */
     linkEmailPassword(email: string, password: string): Promise<AuthUser>;
     /** Link an OAuth social identity (verified idToken or code) to the current account. */
     linkSocial(input: {
-        provider: "google" | "github" | "apple" | "microsoft" | "linkedin" | "facebook" | "twitter" | "discord";
+        provider: SocialCredentialProvider;
         code?: string;
         idToken?: string;
         redirectUri?: string;
@@ -1059,76 +1354,39 @@ declare class Auth {
         serverAuthCode: string;
     }): Promise<AuthUser>;
     /**
-     * Shared link executor. POSTs the verified credential with the caller's
-     * end-user Bearer token, then refreshes the cached user object IN PLACE (no
-     * token rotation — the sub is unchanged). Deliberately NOT wrapped in
-     * serialize(): getAccessToken() serializes internally, so re-entering would
-     * deadlock — same non-serialized posture as deleteAccount().
+     * Shared `link*()` executor — the LINK row with the `link*()` emission
+     * (`user_updated{cause:'link'}`, never `signed_in`). A 409 throws
+     * `CredentialInUseError`; a 403 throws `RECENT_AUTH_REQUIRED`; no session →
+     * `NOT_SIGNED_IN` with no network call.
      */
     private linkCredential;
-    /**
-     * Refresh the cached user after a link — the sub is unchanged, so only the
-     * user object + its storage copy are updated (no token/identity rotation).
-     */
-    private updateLocalUser;
     /**
      * List the auth methods/identities linked to the current account (ADR-030
-     * read side, s58.270). Returns every social/gaming identity on this account
-     * plus a `hasPassword` flag — the cross-device / reinstall-durable source of
-     * truth for a "Connected: Game Center · Google" UI (an on-device tracker
-     * misses a link made on another device). Bearer-gated network read (NOT a
-     * cache read — `getUserSync()` only holds the primary `signupMethod`/
-     * `lastLoginMethod`). Resolves a FRESH access token first (mirrors
-     * `deleteAccount`). Firebase `user.providerData` / Supabase `user.identities`.
+     * read side, s58.270): every social/gaming identity plus a `hasPassword`
+     * flag — the cross-device / reinstall-durable source of truth for a
+     * "Connected: Game Center · Google" UI. Bearer-gated network read that
+     * resolves a FRESH access token first. Firebase `user.providerData` /
+     * Supabase `user.identities` parity.
      */
     listLinkedIdentities(): Promise<LinkedIdentitiesResponse>;
     /**
-     * Remove one linked provider from the signed-in account.
-     *
-     * The write half of `listLinkedIdentities()` — what a "Disconnect" button
-     * next to each entry on a Connected Accounts screen calls.
+     * Remove one linked provider from the signed-in account — the write half of
+     * `listLinkedIdentities()`.
      *
      * ⚠ The server REFUSES to remove the last way into the account, with
-     * `AuthError` `code: "LAST_CREDENTIAL"` / `kind: "last_credential"`. An
-     * account with no credentials still exists and still holds the user's data,
-     * but nothing can ever authenticate into it again — so this is a permanent
-     * lockout, not an inconvenience. A password counts as a credential.
-     *
-     * Prefer to prevent the tap rather than explain the refusal: read
-     * `listLinkedIdentities()` and disable Disconnect when
-     * `identities.length + (hasPassword ? 1 : 0) <= 1`. The error is the
-     * backstop, not the UX.
+     * `AuthError` `code: "LAST_CREDENTIAL"` / `kind: "last_credential"` — a
+     * permanent lockout, not an inconvenience. Prefer preventing the tap: disable
+     * Disconnect when `identities.length + (hasPassword ? 1 : 0) <= 1`.
      *
      * Throws `NOT_SIGNED_IN` when there is no session, and `NOT_FOUND` when the
-     * provider is not linked to this account. Removing an already-absent
-     * provider is NOT treated as success — a silent no-op would let a buggy
-     * screen report "disconnected" for a credential that is still attached.
+     * provider is not linked (an absent provider is NOT reported as removed).
      */
     unlink(provider: string): Promise<UnlinkResult>;
-    /**
-     * Shared gaming-identity sign-in. Mirrors `loginSocial`'s anon-takeover +
-     * ADR-025 link-in-place handling: reads the anon refresh BEFORE wiping local
-     * identity, forwards it as `prevAnonRefreshToken`, and opts into
-     * `linkAnonymous` when `link` is set. `persist()` fires `onDeviceTakeover`
-     * centrally from `retiredAnonUserId`.
-     */
-    private gameIdentitySignIn;
-    /**
-     * Read the stored anon refresh token if (and only if) the local
-     * subject is currently anonymous. Used by every identified-session
-     * mint path so the backend can run device-takeover (s58.111 +
-     * s58.112). Returns `undefined` when not anonymous — never forward
-     * an identified user's own refresh token.
-     */
-    private readPrevAnonRefreshToken;
-    /**
-     * Exchange the MFA challenge token from `signIn` for a real session
-     * by submitting a TOTP or recovery code from the user's authenticator.
-     */
-    challengeMfa(mfaChallengeToken: string, code: string): Promise<AuthUser>;
     sendMagicLink(email: string): Promise<void>;
+    /** A magic-link token is routinely expired or already consumed (mail scanners pre-fetch, users tap twice); a rejection never costs the session. */
     verifyMagicLink(token: string): Promise<AuthUser>;
     sendEmailOtp(email: string): Promise<void>;
+    /** Mistyping a 6-digit code is the most common outcome of this flow; the session survives for the retry. */
     verifyEmailOtp(email: string, code: string): Promise<AuthUser>;
     /** Trigger password-reset email. Resolves on 204 even when address is unknown (anti-enumeration). */
     requestPasswordReset(email: string): Promise<void>;
@@ -1138,6 +1396,81 @@ declare class Auth {
     verifyEmail(token: string): Promise<void>;
     /** Re-send the email-verification email for the currently-signed-in user. */
     sendVerificationEmail(): Promise<void>;
+    /**
+     * The guests held on this device, newest first (`heldAt` desc). Never exposes
+     * tokens. Best-effort: a guest may have been deleted server-side since it was
+     * held — that is only discovered when its token is presented (restore /
+     * claim / discard), as `guest_released{reason:'dead'}`.
+     *
+     * `autoRestore === false` ⇔ the slot was stamped by `deleteAccount()`: only an
+     * explicit `restoreHeldGuest(id)` revives it. `project` is the guest's JWT
+     * `project` claim at HOLD (`null` when it was unreadable).
+     */
+    getHeldGuests(): HeldGuestSummary[];
+    /** The newest held guest, or null. */
+    getHeldGuest(): {
+        userId: string;
+        heldAt: number;
+    } | null;
+    /**
+     * Fold a held guest INTO the current identified account (`POST /merge`):
+     * reassigns its events, profile, entities and push tokens, DELETES the guest
+     * row and fires `auth.user_merged`. Irreversible, Sendora-side only — it does
+     * not touch app data keyed on the guest's `sub`. ⚠ OPTIONAL: an app whose
+     * backend does not act on `auth.user_merged` MUST NOT call it.
+     *
+     * Identified only. `id` may be omitted only when exactly one guest is held
+     * (else `AMBIGUOUS_HELD_GUEST`). The held token is refreshed FIRST (proves
+     * liveness, repairs a spent parent inside the 60 s grace) and the rotation is
+     * persisted into the slot BEFORE the merge; a dead guest releases the slot
+     * (`guest_released{dead}`) and rejects `HELD_GUEST_GONE`. Emits
+     * `user_updated{cause:'merge'}` + `guest_released{reason:'claimed'}`.
+     */
+    claimHeldGuest(id?: string): Promise<{
+        user: AuthUser;
+        stats: MergeStats;
+    }>;
+    /**
+     * Sign back in AS a held guest without merging (the RESTORE row). From
+     * `signed_out` or an identified account (whose refresh token is revoked
+     * fire-and-forget); from a guest the CURRENT guest is held first (its slot is
+     * written before the chosen one is released, so there is never a window with
+     * zero handles to either). `id` may be omitted only when exactly one guest is
+     * held. Client-side project check FIRST: a slot whose recorded `project`
+     * mismatches `expectedProjectId ?? config.projectId` throws
+     * `HeldGuestProjectMismatch` with no network and the slot kept. A dead guest
+     * releases the slot and rejects `HELD_GUEST_GONE`. Emits
+     * `signed_in{cause:'restore'}` (re-register push) + `guest_released{restored}`.
+     */
+    restoreHeldGuest(id?: string): Promise<AuthUser>;
+    /**
+     * DELETE a held guest on the server (`POST /guest/discard` — a real erasure:
+     * data → credentials → row → `auth.user_deleted{reason:'guest_discarded'}`)
+     * and release its slot. The app is the requester on behalf of its player
+     * (s58.316); the SDK never calls this on its own. `id` may be omitted only
+     * when exactly one guest is held. A 2xx or a 404 (already gone) releases the
+     * slot; any other failure keeps it. Emits `guest_released{reason:'discarded'}`.
+     */
+    discardHeldGuest(id?: string): Promise<void>;
+    /** Shared body of `discardHeldGuest()` and `deleteAccount({alsoDiscardHeldGuests})`. */
+    private discardSlot;
+    /**
+     * While `status() === "withheld"`: why the stored session was refused. Never
+     * exposes tokens. `userId` lets a `sub`-keyed backend record oldSub → newSub
+     * before `discardWithheld()`. `null` in every other state.
+     */
+    getWithheld(): WithheldInfo | null;
+    /**
+     * Resolve `withheld` — the local counterpart of `signOut()` in that state
+     * (and what `signOut()` does there). Precondition `status() === "withheld"`
+     * (else resolves `false`, nothing mutated). CAS on the withheld refresh token;
+     * clears the session keys only; fire-and-forget `/token/revoke` like
+     * `signOut()`; LOCAL ONLY — never `/guest/discard`, never a server delete;
+     * KEEPS held slots, the event queue and the persisted `user_id`. Emits
+     * `signed_out{reason:'user'}`. The other exit is relaunching with the matching
+     * `expectedProjectId`.
+     */
+    discardWithheld(): Promise<boolean>;
     enrollMfa(): Promise<{
         secret: string;
         otpauthUrl: string;
@@ -1145,14 +1478,10 @@ declare class Auth {
     }>;
     confirmMfa(code: string): Promise<boolean>;
     /**
-     * Disable MFA.
-     *
-     * ⚠ STEP-UP gated (s58.319): a stale `auth_time` is refused with 403
-     * `RECENT_AUTH_REQUIRED` / kind `recent_auth_required`.
-     *
-     * ⚠ Discarded its response until s58.335, and `request()` never throws on a
-     * non-2xx (it warns and returns the Response), so the refusal had nowhere to
-     * surface — the app reported MFA as off while TOTP stayed enrolled.
+     * Disable MFA. ⚠ STEP-UP gated (s58.319): a stale `auth_time` is refused with
+     * 403 `RECENT_AUTH_REQUIRED` / kind `recent_auth_required`. The response is
+     * inspected (s58.335): `request()` never throws on a non-2xx, so a discarded
+     * return would report the refusal as success.
      */
     disableMfa(): Promise<void>;
     listMySessions(): Promise<Array<{
@@ -1162,174 +1491,236 @@ declare class Auth {
         lastUsedAt: string | null;
         createdAt: string;
     }>>;
-    /**
-     * Revoke one of the caller's own sessions ("sign out that device").
-     * ⚠ Discarded its response until s58.335 — a "sign out this device" button
-     * that reports success on a failure is the one place a user acts on the claim
-     * and then stops worrying.
-     */
+    /** Revoke one of the caller's own sessions ("sign out that device"). Inspects the response (s58.335). */
     revokeSession(sessionId: string): Promise<void>;
-    /** Revoke every session for the caller. Same reporting defect as `revokeSession`. */
+    /** Revoke every session for the caller. Inspects the response (s58.335). */
     revokeAllSessions(): Promise<void>;
     /**
      * Delete the signed-in user's account (Apple App Store Guideline 5.1.1(v)).
-     * Honors the project's configured grace period:
-     *   - `"purged"`  — hard-deleted immediately (grace = 0).
-     *   - `"pending"` — deactivated + all sessions revoked now; hard-deleted at
-     *     `scheduledPurgeAt`. The user can CANCEL by signing back in before then.
-     * Either outcome wipes local identity (the server has already revoked the
-     * session). Requires a signed-in user. Throws on a non-2xx response.
-     *
-     * Resolves a FRESH access token via `getAccessToken()` first (refreshing if
-     * the cached one expired) — unlike the other Bearer calls this is a one-shot
-     * destructive action, so a 401 from a stale token would silently strand the
-     * user with an undeleted account. A stale `this.accessToken` was the cause of
-     * the 401s seen in prod when a user tapped "delete" after the app sat idle.
-     */
-    deleteAccount(): Promise<{
+     * Honors the project's configured grace period: `"purged"` (hard-deleted
+     * now) or `"pending"` (deactivated + sessions revoked now, hard-deleted at
+     * `scheduledPurgeAt`; cancellable by signing back in). Resolves a FRESH access
+     * token first — a stale token's 401 would silently strand the user with an
+     * undeleted account.
+     *
+     * Held guests (ADR-033): deleting an account never touches a held guest, on
+     * the device or the server. By default they SURVIVE with auto-restore
+     * suppressed (`autoRestore: false` — only an explicit `restoreHeldGuest(id)`
+     * revives one; `ensureSession()` mints fresh). `alsoDiscardHeldGuests: true`
+     * is the player's explicit ask to erase them too: each is discarded after the
+     * 2xx, a slot that fails to discard stays held and is listed in
+     * `discardFailed`. `heldGuests` = guests still held afterwards. The queued
+     * analytics events are dropped (erasure completeness, 1.39.1).
+     */
+    deleteAccount(opts?: {
+        alsoDiscardHeldGuests?: boolean;
+    }): Promise<{
         status: "purged" | "pending";
         scheduledPurgeAt: string | null;
         graceDays: number;
+        heldGuests: number;
+        discardFailed: string[];
     }>;
     /**
-     * Start OIDC sign-in. Returns the IdP's authorization URL — caller
-     * opens it via React Native's `Linking.openURL()` (or
-     * `WebBrowser.openAuthSessionAsync` from `expo-web-browser` when
-     * inside Expo). The IdP redirects through Sendora's callback to the
-     * `returnTo` URL with `#sendora_oidc_token=...` in the fragment.
-     *
-     * On the customer's app side, `returnTo` MUST be a custom URL scheme
-     * registered in Info.plist (iOS) / AndroidManifest.xml intent-filter
-     * (Android), e.g. `myapp://oidc-callback`. When the deep link fires,
-     * call `consumeSsoFragment(url)` on the captured URL.
+     * Start OIDC sign-in. Returns the IdP's authorization URL — caller opens it
+     * via `Linking.openURL()` (or `WebBrowser.openAuthSessionAsync`). The IdP
+     * redirects through Sendora's callback to the `returnTo` URL with
+     * `#sendora_oidc_token=...` in the fragment; hand that URL to
+     * `consumeSsoFragment(url)`. `returnTo` MUST be a custom URL scheme
+     * registered in Info.plist / AndroidManifest. No guest hint travels (INV-3).
      */
     startSso(returnTo: string): Promise<{
         authorizationUrl: string;
     }>;
-    /**
-     * Kick off a SAML 2.0 SSO flow. Mirrors `startSso` for SAML —
-     * backend POST `/auth-service/sso/saml/start` returns the IdP
-     * AuthnRequest URL. Caller opens it with
-     * ASWebAuthenticationSession (iOS) / Custom Tabs (Android) /
-     * Linking, captures the callback URL via the standard
-     * `Linking.addEventListener` flow, then passes the captured URL to
-     * `consumeSsoFragment(url)`. consumeSsoFragment handles both OIDC
-     * and SAML fragments transparently.
-     */
+    /** Kick off a SAML 2.0 SSO flow. Mirrors `startSso`; `consumeSsoFragment` handles both fragments. */
     startSaml(returnTo: string): Promise<{
         authorizationUrl: string;
     }>;
     /**
-     * Consume an OIDC callback URL captured via React Native's
-     * `Linking.addEventListener('url', ...)`. Reads the fragment for
-     * `sendora_oidc_token`, exchanges it for a session, and persists.
-     * Throws AuthError on `sendora_oidc_error=...` fragment.
+     * Consume an OIDC/SAML callback URL captured via `Linking.addEventListener`.
+     * Reads the fragment for `sendora_oidc_token` / `sendora_saml_token`,
+     * exchanges it for a session via `/token/refresh`, and installs it as a
+     * sign-in (holding a guest, if any). The callback is parsed and exchanged
+     * FIRST — an IdP "Cancel" or a garbage fragment leaves the session untouched.
      */
     consumeSsoFragment(callbackUrl: string): Promise<AuthUser>;
+    /** Populate a user object from access-token claims when a response carries none (pre-B17 `/token/refresh`). */
+    private userFromClaims;
+    /**
+     * Build the Authorization header for end-user-authenticated routes. Awaits
+     * `getAccessToken()` (parity with sdk-web since 1.41.0), so a cold start with
+     * no cached access token or an expired token transparently refreshes first.
+     * Throws `NOT_SIGNED_IN` when there is genuinely no usable session.
+     */
     private bearerHeaders;
     private unwrap;
     /**
-     * Sign out: wipe local identity FIRST so the user is logged out on
-     * device even if the revoke network call hangs (airplane mode, 5xx).
-     * Revoke is fire-and-forget after the wipe.
+     * Sign out: clear the local session FIRST so the user is logged out on
+     * device even if the revoke network call hangs (airplane mode, 5xx); revoke
+     * is fire-and-forget after the clear. Rotates the analytics anon id (a
+     * person boundary). KEEPS held guests — a guest's refresh token is its only
+     * credential, so wiping the slots on logout would be deletion by assumption
+     * (use `discardHeldGuest()` / `reset({includeHeldGuests:true})` deliberately).
+     * In `withheld` this is `discardWithheld()`.
      */
     signOut(): Promise<void>;
-    private serialize;
     /**
-     * Hot-path token refresh. Single-flight via `refreshInflight` so a
-     * UI batch firing 10 simultaneous reads never produces 10 /refresh
-     * round-trips. Returns null on any failure so callers can decide
-     * whether to surface a sign-in prompt or proceed anonymously.
+     * @deprecated Transfer every event + trait from an anonymous user to the
+     * currently-signed-in (target) user, then delete the anonymous row.
      *
-     * s58.46 — on a `INVALID_REFRESH_TOKEN` (new backend error code) or
-     * HTTP 401 we WIPE the stored refresh token. Pre-s58.46 we caught
-     * the error and returned null but kept the stored token intact, so
-     * the very next caller would re-attempt the same dead token in an
-     * infinite loop (Pulse News iOS hammered /refresh ~1×/s for hours).
-     * The wipe forces the next op to fall through to /anonymous or
-     * surface NOT_SIGNED_IN to the host app instead of looping.
-     */
-    private refreshAccessToken;
+     * Since 1.41.0 the guest you signed in over is HELD on this device, so a
+     * token that matches a held slot (its current refresh token OR the token it
+     * was held with) routes to `claimHeldGuest(thatGuest)` — a DESTRUCTIVE claim.
+     * Any other token takes the raw `/merge` path as before. Prefer
+     * `claimHeldGuest(id)`; never call either from a backend that does not act
+     * on `auth.user_merged`.
+     */
+    merge(anonymousRefreshToken: string, targetRefreshToken?: string): Promise<MergeStats>;
+    /** `POST /merge` — bypasses `callAuth`'s `isAuthApiResponse` gate (`/merge` returns `{ ...stats, tokens, csrfToken }`, no `user`). */
+    private postMerge;
+    private http;
+    /** ADR-033 [2c]: in `withheld` every verb in REJECTED_IN_WITHHELD rejects with no network and no write. */
+    private rejectIfWithheld;
+    /** True in `anonymous` / `identified` — a live session a LINK can attach to. */
+    private hasSession;
+    private serialize;
     /**
-     * Wave 62 — AppState resume hook. Clears stuck backoff so a user
-     * who backgrounded the app during a network blip + returns now
-     * gets an immediate fresh refresh attempt instead of waiting on
-     * the cooldown timer.
-     *
-     * Called from the AppState 'active' listener registered in
-     * startProactiveRefreshCron. Idempotent + cheap — three field
-     * writes; no I/O.
+     * INV-5 — a session-installing verb in `unknown` QUEUES until the status
+     * settles: the single gap-fill refresh either installs the identity or
+     * reports the token dead (`signed_out`). Offline it keeps waiting with the
+     * refresh backoff (never minting, never wiping). Ends in `withheld` → rejects.
+     */
+    private awaitSettled;
+    /** An identity-changing attempt awaits any in-flight refresh at start AND at commit (ADR-033 §3.3 scheduling rule 1). */
+    private awaitRefreshQuiet;
+    private snapshotIdentity;
+    /** The identity CAS (INV-2): `sid` when both sides know it, else the `sub`; a signed-out side never matches a live one. */
+    private identityMatches;
+    /** The current session's JWT `project` claim (string | null), or undefined when unreadable. */
+    private claimProject;
+    /**
+     * The ProjectGuard (INV-15) as `commit()` applies it: the shared
+     * `projectVerdict()` over the access JWT, and — when the claim is unreadable
+     * — the B17 `user.project` field as the second source. Absent on both = `unknown`.
+     */
+    private verdictFor;
+    private heldCount;
+    private heldSorted;
+    /** Slot indices eligible for auto-restore, newest first (ADR-033 §3.3 "eligible"). */
+    private eligibleHeldSlots;
+    private freeSlotIndex;
+    /** The `id` rule shared by claim / restore / discard: omit it ONLY when exactly one guest is held. */
+    private resolveSlot;
+    private doSignInDone;
+    /**
+     * The SIGN_IN / SWITCH row (ADR-033 §3.3 row 18). The body carries NO guest
+     * hint; a success HOLDS a previous guest (post-refresh tokens) and installs
+     * the new session under the identity CAS; any failure leaves the caller
+     * exactly as found.
+     */
+    private doSignIn;
+    /** Commit a sign-in response as the SIGN_IN row; a CAS drop revokes the dropped refresh so server session B is not left live (row 19). */
+    private installSignIn;
+    /**
+     * The LINK / LINK-UPGRADE rows (ADR-033 §3.3 rows 15–16) on the current
+     * Bearer session. 200 with a rotated pair (`upgraded`) → ProjectGuard →
+     * install (same `sub`); 200 attached → user updated in place; 200
+     * `alreadyLinked` → nothing; 409 / 403 → typed outcomes, nothing mutated.
+     */
+    private doLink;
+    /**
+     * Present a held guest's refresh token to `/token/refresh` — the ONLY way a
+     * held token is ever refreshed (the proactive cron never touches a slot).
+     * The rotation is persisted INTO THE SLOT under a per-slot CAS before anything
+     * else happens; a dead verdict releases the slot only for `endReason ∈
+     * deleted|revoked|expired` (`reuse`/absent keep it: `kept`).
+     */
+    private refreshHeld;
+    /** The RESTORE row's install half: ProjectGuard on the refresh response, install BEFORE releasing the slot. */
+    private installRestored;
+    /**
+     * Hot-path token refresh. Single-flight via `refreshInflight` so a UI batch
+     * firing 10 simultaneous reads never produces 10 `/refresh` round-trips.
+     * Returns null on any failure so callers can decide whether to surface a
+     * sign-in prompt or proceed anonymously.
+     *
+     * The result is applied ONLY if the token that was sent is still the one on
+     * disk (token CAS, INV-2): a refresh landing after `signOut()` must not
+     * resurrect the session, and an OLD token's rejection must not wipe a newer
+     * one. A rotation is not a transition; the user object is adopted when the
+     * SDK has none (gap-fill from `unknown`, 1.29.0) and re-judged by the project
+     * guard before install (a mismatch → `withheld`, INV-15).
      */
+    private refreshAccessToken;
+    /** Wave 62 — AppState resume hook: clear stuck backoff so a returning user gets an immediate attempt. */
     private resetRefreshState;
     /**
-     * Proactive refresh (s58.72). Fires when access-token age crosses
-     * ~80% of TTL. Pairs with the AppState foreground listener so a
-     * backgrounded app coming back to active state immediately runs
-     * a tick — much better UX than waiting 60s for the next interval.
-     * Stopped on signOut() / wipeLocalIdentity().
+     * Proactive refresh (s58.72). Fires when access-token age crosses ~80% of
+     * TTL, repairs a stale deadline the combined guard can see, and performs the
+     * single gap-fill refresh for an `unknown` record. Armed ONLY by `commit()`
+     * (install / hydrate), stopped by the clear and withhold paths. ⚠ Never
+     * starts a refresh while an identity attempt is pending (ADR-033 §3.3
+     * scheduling rule 2) and never refreshes a held guest.
      */
     private proactiveRefreshTimer;
     private proactiveRefreshAppStateUnsub;
     private startProactiveRefreshCron;
     private stopProactiveRefreshCron;
-    /**
-     * Returns the currently-stored refresh token (or null when signed out).
-     * Primary use: capture the anonymous refresh token BEFORE calling
-     * `signIn()` so it can be transferred via `merge()` after the existing
-     * account is authenticated. See the "Anonymous → identified" section
-     * of the SDK README + /docs/quickstart-react-native#anon-existing-email.
-     */
-    getRefreshToken(): string | null;
-    /**
-     * Transfer every event + trait from an anonymous user to the
-     * currently-signed-in (target) user, then delete the anonymous row.
-     * `targetRefreshToken` defaults to the SDK's currently-stored refresh
-     * token — call this AFTER a successful `signIn()` so the storage
-     * already holds the target's refresh.
-     *
-     * Throws AuthError when:
-     *   - `anonymousRefreshToken` is invalid / expired / revoked,
-     *   - the bound source row is not anonymous (CONFLICT — use upgrade),
-     *   - the target is anonymous (CONFLICT — sign in first),
-     *   - both tokens resolve to the same user (CONFLICT — no-op).
-     *
-     * Mirrors Auth0 `accounts.link` + Firebase manual transfer semantics.
-     */
-    merge(anonymousRefreshToken: string, targetRefreshToken?: string): Promise<{
-        mergedUserId: string;
-        deletedAnonymousId: string;
-        eventsReassigned: number;
-        profilesReassigned: number;
-        profilesDropped: number;
-        entitiesReassigned: number;
-        entitiesDropped: number;
-    }>;
+    private revokeFireAndForget;
+    /** B15: report a held guest, fire-and-forget; the pending flag is cleared only on a 2xx and retried on hydrate. */
+    private reportHeldFireAndForget;
+    private retryPendingHeldReports;
+    /** `Sendora.reset({includeHeldGuests:true})`: release every slot locally (NO server delete), via commit. */
+    releaseAllHeldGuests(): void;
     private callAuth;
-    private persist;
-    /**
-     * Drop the local session.
-     *
-     * `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 — subscribers see one `signed_in`,
-     * not a spurious logout/login pair.
-     *
-     * ⚠ 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.
-     */
+    private commit;
+    /** `commit()` for the clear path, awaiting the parent's `onAnonymousWipe` hook before resolving (the emission has already fired). */
+    private commitAsync;
+    private pendingWipeHook;
+    private commitInstall;
+    private commitClear;
     /**
-     * True when `sent` is still the refresh token on disk — 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.
+     * The parent-SDK half of a clear: rotate the analytics anon id at a person
+     * boundary (`"user"` / `"account_deleted"`), drop the queue on deletion, null
+     * the analytics user id. Kept as its own method so its reasons stay pinned.
      */
-    private tokenStillCurrent;
     private wipeLocalIdentity;
+    private commitUser;
+    private commitRelease;
+    /** Row 21 — a refresh of the CURRENT token answered with a mismatching claim: persist the rotation (token CAS) and withhold. */
+    private commitWithhold;
+    /** Enter `withheld`: in-memory only (ZERO storage writes), no cron, analytics quarantined; emits `session_withheld` only for an in-process transition. */
+    private enterWithheld;
+    /** Row 14 — `discardWithheld()` / `signOut()` in `withheld`: LOCAL ONLY, keeps held slots + queue + `user_id`. */
+    private commitDiscardWithheld;
+    /** A rotated pair for the current session when no user is known to install (pre-B17 gap-fill). Token CAS. */
+    private commitTokens;
+    /** Row 22 — CAS PER SLOT: re-read the slot at write time; if it no longer holds `sent`, DROP. */
+    private commitSlotTokens;
+    /** RESTORE row: a `null` slot project judged on the refresh response records the claim it saw. */
+    private commitSlotProject;
+    private commitHeldReport;
+    /** Dual-write: the four frozen keys (downgrade-readable) + the `auth_session` record. */
+    private writeSessionRecord;
+    /** Hydrate's write-forward: ONLY the `auth_session` record (the frozen keys already hold the session untouched). */
+    private writeSessionRecordOnly;
+    /** The rotated pair only (the user is unchanged) — frozen keys + the record's token fields. */
+    private writeTokens;
+    /** Clear EXACTLY the session keys (the four frozen + the record). Held slots, the queue and `user_id` are never touched here. */
+    private clearSessionKeys;
+    /** Keep the B15 pending-report flags on disk even with no session (a stub record); remove the record when nothing is pending. */
+    private persistPendingReports;
+    private writeSlot;
+}
+/** What `/merge` (and `claimHeldGuest()`) moved. */
+interface MergeStats {
+    mergedUserId: string;
+    deletedAnonymousId: string;
+    eventsReassigned: number;
+    profilesReassigned: number;
+    profilesDropped: number;
+    entitiesReassigned: number;
+    entitiesDropped: number;
 }
 
 /**
@@ -1616,6 +2007,56 @@ declare class Links {
     attachLinkingApi(opts?: AttachLinkingApiOptions): Promise<() => void>;
 }
 
+/**
+ * ADR-033 INV-15 — `projectVerdict()`, the ProjectGuard every InstallTx is
+ * judged by BEFORE any assignment (§3.3 `commit()` header).
+ *
+ * ⚠ VERBATIM PORT of `packages/shared/src/auth-machine/project-verdict.ts`
+ * (ADR-033 B8). The published SDK cannot import the internal `@sendora/shared`
+ * package at runtime, so the function lives here as a copy; the conformance
+ * suite (`test/auth-machine-conformance.test.ts`) drives THIS copy over every
+ * `projectVerdictCases` entry of the shared golden fixture, which is what keeps
+ * the two from drifting.
+ *
+ * WHY A PURE FUNCTION. `withheld` (§3.2) is "a pure function of (disk record,
+ * config), recomputed every hydrate, never persisted" — so a re-init with the
+ * right key or a rollback needs no migration. That property only holds if the
+ * verdict reads nothing but its two arguments: no `Date` (expiry is
+ * irrelevant — a stale token still names its project truthfully), no network,
+ * no storage, no `atob` (Hermes/JSC/browsers/Node disagree on its presence and
+ * its handling of non-ASCII, and a verdict that depends on the host's `atob`
+ * is a verdict that differs per platform).
+ *
+ * The three answers, and why absent ≠ match (§3.3, §8-Q13, TODO.md:52 superseded):
+ *
+ *   expected unset                                   → "match"    (guard off)
+ *   token missing / undecodable / claim KEY absent   → "unknown"  (NOT match: a
+ *       pre-s58.276 token says nothing about its project; the SDK stays
+ *       `unknown` and lets the refresh answer — the server emits the claim
+ *       ALWAYS since s58.276, so one refresh settles it)
+ *   claim === null                                   → "mismatch" (the server
+ *       emits an EXPLICIT null for the org-wide pool; under a project-bound
+ *       expectedProjectId an org-wide session is the wrong tenant)
+ *   claim is a string                                → equal ? "match" : "mismatch"
+ *
+ * ⚠ The guard is ADVISORY (a client consistency check against a wrong-key
+ * build), not an authorization boundary, and it never produces a dead-token
+ * verdict (INV-6/INV-15).
+ */
+type ProjectVerdict = "match" | "mismatch" | "unknown";
+declare function projectVerdict(expectedProjectId: string | undefined, accessJwt: string | null | undefined): ProjectVerdict;
+/**
+ * Decode a compact JWS payload (`header.payload.signature`) WITHOUT verifying
+ * the signature. The verdict only needs to READ a claim from a token the SDK
+ * already holds (the server verifies on every request); verification here
+ * would need the JWKS, i.e. the network, which the verdict must not touch.
+ *
+ * Returns `null` for anything that is not a three-segment token whose second
+ * segment base64url-decodes to a UTF-8 JSON object. Arrays, scalars and
+ * malformed input are all "undecodable".
+ */
+declare function decodeJwtPayload(token: string | null | undefined): Record<string, unknown> | null;
+
 /**
  * @sendoracloud/sdk-react-native — React Native + Expo SDK.
  *
@@ -1651,6 +2092,8 @@ declare class SendoraSDK {
     private sessionId;
     private autoTrackCleanup;
     private eventQueue;
+    /** ADR-033 [2c]: subscribers to `onIdentityWithheld`. */
+    private withheldListeners;
     private engEnabled;
     private engScreen;
     private engAccumMs;
@@ -2142,17 +2585,34 @@ declare class SendoraSDK {
     private _chatbotSessionId;
     private chatbotSessionId;
     /**
-     * Clear identity + rotate the anonymous id. Call on logout. Awaits
-     * the AsyncStorage writes so a caller who kills the app immediately
-     * after doesn't leave stale identity on disk.
-     *
-     * Signs out through `auth` rather than just clearing storage: `clearAll()`
-     * removes the auth keys too, so doing it directly left `Auth` holding an
-     * in-memory user and reporting itself signed in while its refresh token was
-     * already gone — with the server-side session never revoked and no
-     * `onAuthStateChanged` emission telling the app the session had ended.
+     * ADR-033 [2c]: subscribe to the project guard refusing a stored session
+     * (`auth.status() === "withheld"`). Fires once per withhold with
+     * `getWithheld()`'s payload, after the SDK has nulled its in-memory
+     * analytics user id. Record `info.userId` (oldSub) in your backend before
+     * calling `auth.discardWithheld()`. Returns an unsubscribe function.
      */
-    reset(): Promise<void>;
+    onIdentityWithheld(cb: (info: WithheldInfo) => void): () => void;
+    /**
+     * Clear identity + rotate the anonymous id. Call on logout. Awaits
+     * the storage writes so a caller who kills the app immediately after
+     * doesn't leave stale identity on disk.
+     *
+     * Signs out through `auth` (so the server session is revoked and
+     * `onAuthStateChanged` fires `signed_out`), drops the queued events, then
+     * clears EXACTLY this SDK's keys in the active namespace.
+     *
+     * ⚠ KEEPS the held guests by default (ADR-033). A guest displaced by a
+     * sign-in is held on the device (`auth.getHeldGuests()`), and its refresh
+     * token is its only credential — wiping the slots on logout would strand a
+     * guest whose progress the player may still want. Pass
+     * `{ includeHeldGuests: true }` to release every slot too (locally only —
+     * `guest_released{reason:'reset'}` per guest, NO server delete; use
+     * `auth.discardHeldGuest(id)` for that). In `withheld` this resolves the
+     * withheld session like `auth.discardWithheld()` and keeps the slots too.
+     */
+    reset(opts?: {
+        includeHeldGuests?: boolean;
+    }): Promise<void>;
     /** Tear down auto-track listeners. Call in test harnesses. */
     destroy(): void;
     /**
@@ -2172,4 +2632,4 @@ declare class SendoraSDK {
 }
 declare const SendoraCloud: SendoraSDK;
 
-export { AlreadyIdentifiedError, type AnonRetirementOutcome, type AttachLinkingApiOptions, Auth, AuthError, type AuthErrorKind, type AuthSignedOutReason, type AuthStateChange, type AuthTokens, type AuthUser, type CredentialCollisionPolicy, CredentialInUseError, type DeletionCancelledEvent, type DeviceTakeoverEvent, EmailAlreadyTakenError, type GameSignInOptions, type IdentifyTraits, type LinkCreateInput, type LinkCreateResult, type LinkData, LinkError, type LinkErrorCode, type LinkMatchInput, type LinkOpenedEvent, type LinkOpenedHandler, type LinkStats, type LinkedIdentitiesResponse, type LinkedIdentity, Links, type PushTokenReceipt, type PushTokenRegistration, SendoraCloud, type SendoraConfig, type TrackProperties, type UnlinkResult, computeDeviceFingerprint, SendoraCloud as default, extractShortcodeFromUrl, getPlayInstallReferrer };
+export { AMBIGUOUS_HELD_GUEST, AlreadyIdentifiedError, type AnonRetirementOutcome, type AttachLinkingApiOptions, Auth, AuthError, type AuthErrorKind, type AuthSignedInCause, type AuthSignedOutReason, type AuthStateChange, type AuthStatus, type AuthTokens, type AuthUser, type AuthUserUpdatedCause, type Credential, type CredentialCollisionPolicy, CredentialInUseError, type CredentialKind, type DeletionCancelledEvent, type DeviceTakeoverEvent, EmailAlreadyTakenError, type GameCenterPayload, type GameSignInOptions, type GuestReleasedReason, HELD_GUEST_SLOTS, HeldGuestLimitError, HeldGuestProjectMismatch, type HeldGuestSummary, type IdentifyTraits, type LinkCollision, type LinkCreateInput, type LinkCreateResult, type LinkData, LinkError, type LinkErrorCode, type LinkMatchInput, type LinkOpenedEvent, type LinkOpenedHandler, type LinkResult, type LinkStats, type LinkedIdentitiesResponse, type LinkedIdentity, Links, type MergeStats, type ProjectVerdict, type PushTokenReceipt, type PushTokenRegistration, type RefreshEndReason, SendoraCloud, type SendoraConfig, type SignInResult, type SocialCredentialProvider, type TrackProperties, type UnlinkResult, type WithheldInfo, computeDeviceFingerprint, decodeJwtPayload, SendoraCloud as default, extractShortcodeFromUrl, getPlayInstallReferrer, projectVerdict };