@sendoracloud/sdk-react-native 1.39.1 → 1.41.0

package/dist/index.cjs

@@ -30,18 +30,24 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  AMBIGUOUS_HELD_GUEST: () => AMBIGUOUS_HELD_GUEST,
   AlreadyIdentifiedError: () => AlreadyIdentifiedError,
   Auth: () => Auth,
   AuthError: () => AuthError,
   CredentialInUseError: () => CredentialInUseError,
   EmailAlreadyTakenError: () => EmailAlreadyTakenError,
+  HELD_GUEST_SLOTS: () => HELD_GUEST_SLOTS,
+  HeldGuestLimitError: () => HeldGuestLimitError,
+  HeldGuestProjectMismatch: () => HeldGuestProjectMismatch,
   LinkError: () => LinkError,
   Links: () => Links,
   SendoraCloud: () => SendoraCloud,
   computeDeviceFingerprint: () => computeDeviceFingerprint,
+  decodeJwtPayload: () => decodeJwtPayload,
   default: () => index_default,
   extractShortcodeFromUrl: () => extractShortcodeFromUrl,
-  getPlayInstallReferrer: () => getPlayInstallReferrer
+  getPlayInstallReferrer: () => getPlayInstallReferrer,
+  projectVerdict: () => projectVerdict
 });
 module.exports = __toCommonJS(index_exports);
 var import_react_native_get_random_values = require("react-native-get-random-values");
@@ -186,13 +192,42 @@ var Storage = class {
     });
   }
   /**
-   * 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.
    */
-  async clearAll() {
+  async clearAll(opts) {
+    if (opts) {
+      const except = new Set(opts.except ?? []);
+      const store2 = await getAsyncStorage();
+      for (const k of opts.keys) {
+        if (except.has(k)) continue;
+        this.cache.delete(k);
+        if (this.isSecure(k)) {
+          try {
+            await this.secure.removeItem(this.secureName(k));
+          } catch {
+          }
+        }
+        if (store2) {
+          try {
+            await store2.removeItem(this.prefix + k);
+          } catch {
+          }
+        }
+      }
+      return;
+    }
     this.cache.clear();
     if (this.secure) {
       for (const k of this.secureKeys) {
@@ -228,7 +263,7 @@ var Storage = class {
 // package.json
 var package_default = {
   name: "@sendoracloud/sdk-react-native",
-  version: "1.39.1",
+  version: "1.41.0",
   description: "Sendora Cloud React Native + Expo SDK \u2014 analytics, identity, push-token registration, auth (incl. Game Center / Play Games), deep links (Branch / Firebase Dynamic Links parity). Auth + analytics + deep links work in Expo Go; push-token registration and the no-arg Game Center / Play Games sign-in require a Dev Client (EAS Build or `npx expo prebuild`).",
   type: "module",
   main: "./dist/index.cjs",
@@ -250,6 +285,7 @@ var package_default = {
     "dist",
     "examples",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE",
     "app.plugin.js",
     "plugin"
@@ -284,7 +320,7 @@ var package_default = {
   scripts: {
     build: "tsup src/index.ts src/contact-widget.tsx --format esm,cjs --dts --clean --external react --external react-native --external react-native-webview",
     typecheck: "tsc --noEmit",
-    test: "tsx test/secure-storage.test.ts && tsx test/integration-storage.test.ts && tsx test/plugin.test.ts && tsx test/game-auth.test.ts && tsx test/link.test.ts && tsx test/session-preservation.test.ts && tsx test/credential-collision.test.ts && tsx test/token-expiry.test.ts && tsx test/unlink.test.ts && tsx test/deferred-match.test.ts && tsx test/anon-id-stability.test.ts && tsx test/event-queue.test.ts"
+    test: "tsx test/secure-storage.test.ts && tsx test/integration-storage.test.ts && tsx test/plugin.test.ts && tsx test/game-auth.test.ts && tsx test/link.test.ts && tsx test/session-preservation.test.ts && tsx test/credential-collision.test.ts && tsx test/token-expiry.test.ts && tsx test/unlink.test.ts && tsx test/deferred-match.test.ts && tsx test/anon-id-stability.test.ts && tsx test/event-queue.test.ts && tsx test/anonymous-over-account.test.ts && tsx test/auth-machine-conformance.test.ts && tsx test/held-guests.test.ts"
   },
   devDependencies: {
     "@types/react": "^19.2.16",
@@ -295,10 +331,6 @@ var package_default = {
     typescript: "^5.0.0"
   },
   license: "MIT",
-  repository: {
-    type: "git",
-    url: "https://github.com/sendoracloud/sdk-react-native"
-  },
   homepage: "https://sendoracloud.com/sdks"
 };
 
@@ -423,29 +455,149 @@ function requireOptionalNativeModule(name) {
   return void 0;
 }
 
+// src/project-verdict.ts
+var PROJECT_CLAIM = "project";
+function projectVerdict(expectedProjectId, accessJwt) {
+  if (expectedProjectId === void 0) return "match";
+  const payload = decodeJwtPayload(accessJwt);
+  if (payload === null) return "unknown";
+  if (!Object.prototype.hasOwnProperty.call(payload, PROJECT_CLAIM)) return "unknown";
+  const claim = payload[PROJECT_CLAIM];
+  if (claim === null) return "mismatch";
+  if (typeof claim === "string") return claim === expectedProjectId ? "match" : "mismatch";
+  return "mismatch";
+}
+function decodeJwtPayload(token) {
+  if (typeof token !== "string" || token.length === 0) return null;
+  const parts = token.split(".");
+  if (parts.length !== 3) return null;
+  const bytes = decodeBase64Url(parts[1]);
+  if (bytes === null) return null;
+  const json = decodeUtf8(bytes);
+  if (json === null) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(json);
+  } catch {
+    return null;
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+  return parsed;
+}
+var B64_LOOKUP = (() => {
+  const table = new Int16Array(128).fill(-1);
+  const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+  for (let i = 0; i < alphabet.length; i++) table[alphabet.charCodeAt(i)] = i;
+  table["-".charCodeAt(0)] = 62;
+  table["_".charCodeAt(0)] = 63;
+  table["+".charCodeAt(0)] = 62;
+  table["/".charCodeAt(0)] = 63;
+  return table;
+})();
+function decodeBase64Url(input) {
+  let end = input.length;
+  while (end > 0 && input.charCodeAt(end - 1) === 61) end--;
+  if (end % 4 === 1) return null;
+  const out = new Uint8Array(Math.floor(end * 3 / 4));
+  let buffer = 0;
+  let bits = 0;
+  let o = 0;
+  for (let i = 0; i < end; i++) {
+    const code = input.charCodeAt(i);
+    const v = code < 128 ? B64_LOOKUP[code] : -1;
+    if (v < 0) return null;
+    buffer = buffer << 6 | v;
+    bits += 6;
+    if (bits >= 8) {
+      bits -= 8;
+      out[o++] = buffer >> bits & 255;
+    }
+  }
+  return o === out.length ? out : out.subarray(0, o);
+}
+function decodeUtf8(bytes) {
+  let out = "";
+  let i = 0;
+  const n = bytes.length;
+  while (i < n) {
+    const b0 = bytes[i];
+    let cp;
+    let need;
+    if (b0 < 128) {
+      cp = b0;
+      need = 0;
+    } else if (b0 >= 194 && b0 <= 223) {
+      cp = b0 & 31;
+      need = 1;
+    } else if (b0 >= 224 && b0 <= 239) {
+      cp = b0 & 15;
+      need = 2;
+    } else if (b0 >= 240 && b0 <= 244) {
+      cp = b0 & 7;
+      need = 3;
+    } else {
+      return null;
+    }
+    if (i + need >= n) return null;
+    for (let k = 1; k <= need; k++) {
+      const b = bytes[i + k];
+      if ((b & 192) !== 128) return null;
+      cp = cp << 6 | b & 63;
+    }
+    if (need === 2 && cp < 2048 || need === 3 && (cp < 65536 || cp > 1114111) || cp >= 55296 && cp <= 57343) {
+      return null;
+    }
+    if (cp > 65535) {
+      const v = cp - 65536;
+      out += String.fromCharCode(55296 + (v >> 10), 56320 + (v & 1023));
+    } else {
+      out += String.fromCharCode(cp);
+    }
+    i += need + 1;
+  }
+  return out;
+}
+
 // src/auth.ts
 var import_react_native2 = require("react-native");
 var TOKEN_KEY = "auth_access_token";
 var TOKEN_EXPIRES_KEY = "auth_access_expires";
 var REFRESH_KEY = "auth_refresh_token";
 var USER_KEY = "auth_user";
+var SESSION_KEY = "auth_session";
+var MINT_KEY_KEY = "auth_mint_key";
+var HELD_GUEST_SLOTS = 5;
+var HELD_SLOT_KEYS = ["auth_held_0", "auth_held_1", "auth_held_2", "auth_held_3", "auth_held_4"];
+var AUTH_SECURE_KEYS = [REFRESH_KEY, TOKEN_KEY, USER_KEY, SESSION_KEY, ...HELD_SLOT_KEYS];
+var AUTH_HYDRATE_KEYS = [TOKEN_KEY, TOKEN_EXPIRES_KEY, REFRESH_KEY, USER_KEY, SESSION_KEY, MINT_KEY_KEY, ...HELD_SLOT_KEYS];
 var REFRESH_SAFETY_MS = 3e4;
+var SWITCH_CREDENTIAL_MAX_AGE_MS = 5 * 6e4;
+var DEAD_CODES = ["INVALID_REFRESH_TOKEN"];
+var RELEASE_HELD_ON_END_REASONS = ["deleted", "revoked", "expired"];
+var AMBIGUOUS_HELD_GUEST = "AMBIGUOUS_HELD_GUEST";
 function isAuthApiResponse(v) {
   if (!v || typeof v !== "object") return false;
   const r = v;
   const user = r.user;
   const tokens = r.tokens;
-  if (!user || typeof user.id !== "string" || user.id.length === 0) return false;
+  if (!isAuthUserShape(user)) return false;
   if (!tokens) return false;
   if (typeof tokens.accessToken !== "string" || tokens.accessToken.length === 0) return false;
   if (typeof tokens.refreshToken !== "string" || tokens.refreshToken.length === 0) return false;
   if (typeof tokens.expiresIn !== "number" || tokens.expiresIn <= 0) return false;
-  if (user.isAnonymous !== void 0 && typeof user.isAnonymous !== "boolean") return false;
-  if (user.email !== void 0 && user.email !== null && typeof user.email !== "string") return false;
-  if (user.emailVerified !== void 0 && typeof user.emailVerified !== "boolean") return false;
-  if (user.name !== void 0 && user.name !== null && typeof user.name !== "string") return false;
-  if (user.signupMethod !== void 0 && user.signupMethod !== null && typeof user.signupMethod !== "string") return false;
-  if (user.lastLoginMethod !== void 0 && user.lastLoginMethod !== null && typeof user.lastLoginMethod !== "string") return false;
+  return true;
+}
+function isAuthUserShape(user) {
+  if (!user || typeof user !== "object") return false;
+  const u = user;
+  if (typeof u.id !== "string" || u.id.length === 0) return false;
+  if (u.isAnonymous !== void 0 && typeof u.isAnonymous !== "boolean") return false;
+  if (u.email !== void 0 && u.email !== null && typeof u.email !== "string") return false;
+  if (u.emailVerified !== void 0 && typeof u.emailVerified !== "boolean") return false;
+  if (u.name !== void 0 && u.name !== null && typeof u.name !== "string") return false;
+  if (u.signupMethod !== void 0 && u.signupMethod !== null && typeof u.signupMethod !== "string") return false;
+  if (u.lastLoginMethod !== void 0 && u.lastLoginMethod !== null && typeof u.lastLoginMethod !== "string") return false;
+  if (u.project !== void 0 && u.project !== null && typeof u.project !== "string") return false;
   return true;
 }
 var EmailAlreadyTakenError = class extends Error {
@@ -492,6 +644,11 @@ function readCollisionDetails(parsed) {
     collision: d.collision === "identity" || d.collision === "email" ? d.collision : void 0
   };
 }
+function readEndReason(parsed) {
+  const details = parsed?.error?.details;
+  const v = details?.endReason;
+  return v === "expired" || v === "revoked" || v === "evicted" || v === "deleted" || v === "reuse" || v === "unknown" ? v : void 0;
+}
 var RETRYABLE_KINDS = /* @__PURE__ */ new Set([
   "network",
   "server",
@@ -534,6 +691,9 @@ function classifyAuthErrorKind(code, status) {
     case "PLAY_GAMES_UNAVAILABLE":
     case "ENTITLEMENT_ERROR":
     case "tier_required":
+    // ADR-033 §3.5 [2c]: the two project-guard refusals reuse the `config` kind.
+    case "SESSION_WITHHELD":
+    case "PROJECT_MISMATCH":
       return "config";
     case "UNAUTHORIZED":
     case "INVALID_CREDENTIALS":
@@ -559,11 +719,30 @@ var AuthError = class extends Error {
     this.name = "AuthError";
     this.code = code;
     this.kind = opts?.kind ?? classifyAuthErrorKind(code, opts?.status);
-    this.retryable = RETRYABLE_KINDS.has(this.kind);
+    this.retryable = opts?.retryable ?? RETRYABLE_KINDS.has(this.kind);
     this.retryAfterSeconds = opts?.retryAfterSeconds;
     this.status = opts?.status;
+    this.endReason = opts?.endReason;
+  }
+};
+var HeldGuestLimitError = class extends AuthError {
+  constructor(message = `This device already holds ${HELD_GUEST_SLOTS} guest accounts; restore or discard one before minting another`) {
+    super("HELD_GUEST_LIMIT", message, { kind: "unknown" });
+    this.name = "HeldGuestLimitError";
+  }
+};
+var HeldGuestProjectMismatch = class extends AuthError {
+  constructor(userId, expectedProjectId, actualProjectId) {
+    super("HELD_GUEST_PROJECT_MISMATCH", "The held guest belongs to a different project than this app is bound to", { kind: "unknown" });
+    this.name = "HeldGuestProjectMismatch";
+    this.userId = userId;
+    this.expectedProjectId = expectedProjectId;
+    this.actualProjectId = actualProjectId;
   }
 };
+function withheldError(code, message) {
+  return new AuthError(code, message, { kind: "config", retryable: false });
+}
 function asAuthError(err) {
   if (err instanceof AuthError) return err;
   if (err instanceof EmailAlreadyTakenError || err instanceof AlreadyIdentifiedError || err instanceof CredentialInUseError) {
@@ -624,11 +803,113 @@ async function fetchPlayGamesAuthCodeNative() {
   }
   return { serverAuthCode };
 }
+var LOGIN_PATH = "/api/v1/auth-service/login";
+var SOCIAL_LOGIN_PATH = "/api/v1/auth-service/login/social";
+var GAME_CENTER_LOGIN_PATH = "/api/v1/auth-service/login/game-center";
+var PLAY_GAMES_LOGIN_PATH = "/api/v1/auth-service/login/play-games";
+var MFA_CHALLENGE_PATH = "/api/v1/auth-service/mfa/challenge";
+var MAGIC_LINK_VERIFY_PATH = "/api/v1/auth-service/magic-link/verify";
+var EMAIL_OTP_VERIFY_PATH = "/api/v1/auth-service/email-otp/verify";
+var PASSKEY_FINISH_PATH = "/api/v1/auth-service/passkeys/authenticate/finish";
+var LINK_EMAIL_PATH = "/api/v1/auth-service/me/link/email";
+var LINK_SOCIAL_PATH = "/api/v1/auth-service/me/link/social";
+var LINK_GAME_CENTER_PATH = "/api/v1/auth-service/me/link/game-center";
+var LINK_PLAY_GAMES_PATH = "/api/v1/auth-service/me/link/play-games";
+var REFRESH_PATH = "/api/v1/auth-service/token/refresh";
+var REVOKE_PATH = "/api/v1/auth-service/token/revoke";
+var SOCIAL_KINDS = /* @__PURE__ */ new Set(["google", "github", "apple", "microsoft", "linkedin", "facebook", "twitter", "discord"]);
+function signInWire(credential) {
+  switch (credential.kind) {
+    case "password":
+      return { path: LOGIN_PATH, body: { email: credential.email, password: credential.password } };
+    case "gameCenter": {
+      const { kind: _k, ...payload } = credential;
+      return { path: GAME_CENTER_LOGIN_PATH, body: { ...payload } };
+    }
+    case "playGames":
+      return { path: PLAY_GAMES_LOGIN_PATH, body: { serverAuthCode: credential.serverAuthCode } };
+    case "magicLink":
+      return { path: MAGIC_LINK_VERIFY_PATH, body: { token: credential.token } };
+    case "emailOtp":
+      return { path: EMAIL_OTP_VERIFY_PATH, body: { email: credential.email, code: credential.code } };
+    case "passkey": {
+      const a = credential.assertion;
+      const body = "response" in a ? { ...a } : { response: a, userId: null };
+      return { path: PASSKEY_FINISH_PATH, body };
+    }
+    case "mfa":
+      return { path: MFA_CHALLENGE_PATH, body: { challengeToken: credential.challengeToken, code: credential.code } };
+    default: {
+      const { kind, ...rest } = credential;
+      return { path: SOCIAL_LOGIN_PATH, body: { provider: kind, ...stripUndefined(rest) } };
+    }
+  }
+}
+function linkWire(credential) {
+  switch (credential.kind) {
+    case "password":
+      return { path: LINK_EMAIL_PATH, body: { email: credential.email, password: credential.password } };
+    case "gameCenter": {
+      const { kind: _k, ...payload } = credential;
+      return { path: LINK_GAME_CENTER_PATH, body: { ...payload } };
+    }
+    case "playGames":
+      return { path: LINK_PLAY_GAMES_PATH, body: { serverAuthCode: credential.serverAuthCode } };
+    case "magicLink":
+    case "emailOtp":
+    case "passkey":
+    case "mfa":
+      return null;
+    default: {
+      const { kind, ...rest } = credential;
+      return SOCIAL_KINDS.has(kind) ? { path: LINK_SOCIAL_PATH, body: { provider: kind, ...stripUndefined(rest) } } : null;
+    }
+  }
+}
+function stripUndefined(o) {
+  const out = {};
+  for (const [k, v] of Object.entries(o)) if (v !== void 0) out[k] = v;
+  return out;
+}
+function providerLabel(credential) {
+  switch (credential.kind) {
+    case "password":
+      return "password";
+    case "gameCenter":
+      return "gamecenter";
+    case "playGames":
+      return "playgames";
+    case "magicLink":
+      return "magic_link";
+    case "emailOtp":
+      return "email_otp";
+    default:
+      return credential.kind;
+  }
+}
+function generateMintKey() {
+  const g = globalThis;
+  if (!g.crypto?.getRandomValues) return null;
+  const bytes = new Uint8Array(16);
+  g.crypto.getRandomValues(bytes);
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
 var Auth = class {
   constructor(hooks) {
+    // ── The ONE identity slot (written only by commit()) ──────────────────
     this.user = null;
     this.accessToken = null;
     this.accessExpiresAt = 0;
+    /** The in-memory mirror of the K held slots (index = slot number). Written only by commit(). */
+    this.held = HELD_SLOT_KEYS.map(() => null);
+    /** Non-null ⇔ `status() === "withheld"` (ADR-033 [2c]). Never persisted. */
+    this.withheld = null;
+    /** The refresh token the withheld record carried — the CAS key of `discardWithheld()`. */
+    this.withheldRefresh = null;
+    /** B15: held guests whose `POST /guest/held` report has not yet returned 2xx. Persisted in `auth_session`. */
+    this.heldReportsPending = /* @__PURE__ */ new Set();
+    /** The in-flight identity-changing proposal; the proactive cron pauses while it is set. */
+    this.attempt = null;
     /**
      * Set once we have PROOF that this device's clock runs fast, which
      * releases the `exp` guard in `canServeCachedToken`.
@@ -653,15 +934,10 @@ var Auth = class {
     this.inflight = Promise.resolve();
     this.refreshInflight = null;
     /**
-     * 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.
      */
     this.refreshFailureCount = 0;
     this.refreshCooldownUntil = 0;
@@ -671,107 +947,237 @@ var Auth = class {
     this.lastDeletionCancelled = null;
     this.lastAnonRetirement = null;
     this.lastTakeover = null;
-    /**
-     * 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).
-     */
-    this.pendingAnonTakeover = null;
-    /**
-     * 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. */
     this.hydrated = false;
     /**
-     * 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.
      */
     this.proactiveRefreshTimer = null;
     this.proactiveRefreshAppStateUnsub = null;
+    this.pendingWipeHook = null;
     this.hooks = hooks;
     this.readyPromise = new Promise((res) => {
       this.resolveReady = res;
     });
   }
+  // ============================================================
+  // HYDRATE (ADR-033 §3.3 rows 1–4; INV-9 hydrate coherence)
+  // ============================================================
   /**
-   * 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.
+   * 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.
    *
-   * 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.
+   * 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() {
-    const cachedUser = this.hooks.storage.get(USER_KEY);
-    const cachedToken = this.hooks.storage.get(TOKEN_KEY);
-    const cachedRefresh = this.hooks.storage.get(REFRESH_KEY);
-    const cachedExpires = this.hooks.storage.get(TOKEN_EXPIRES_KEY);
-    if (cachedUser && (cachedToken || cachedRefresh)) {
+    const disk = this.readDiskSession();
+    this.heldReportsPending = new Set(disk.heldReportsPending);
+    const hadRefresh = !!disk.refreshToken;
+    if (disk.refreshToken && disk.user) {
+      const verdict = this.verdictFor(disk.user, disk.accessToken);
+      if (verdict === "mismatch") {
+        this.enterWithheld(disk.user, disk.accessToken, disk.refreshToken);
+      } else if (verdict === "match") {
+        this.commit({
+          kind: "install",
+          reason: "hydrate",
+          record: {
+            user: disk.user,
+            accessToken: disk.accessToken ?? "",
+            refreshToken: disk.refreshToken,
+            expiresIn: 0
+          },
+          accessExpiresAt: disk.accessToken ? disk.accessExpiresAt : 0,
+          writeForward: disk.legacyOnly
+        });
+      } else {
+        this.startProactiveRefreshCron();
+      }
+    } else if (disk.refreshToken) {
+      this.startProactiveRefreshCron();
+    } else if (disk.user || this.hooks.storage.get(USER_KEY) || this.hooks.storage.get(SESSION_KEY)) {
+      this.commit({ kind: "clear", reason: "stale_blob" });
+    }
+    this.hydrateHeldSlots();
+    this.hydrated = true;
+    this.resolveReady();
+    if (hadRefresh && this.status() === "unknown") {
+      setTimeout(() => {
+        void this.refreshAccessToken();
+      }, 0);
+    }
+    this.retryPendingHeldReports();
+  }
+  /** Read `auth_session` + the four frozen keys and reconcile them (see `hydrate()`). */
+  readDiskSession() {
+    const st = this.hooks.storage;
+    let record = null;
+    const raw = st.get(SESSION_KEY);
+    if (raw) {
+      try {
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === "object" && parsed.v === 2) record = parsed;
+      } catch {
+      }
+    }
+    const legacyUserRaw = st.get(USER_KEY);
+    const legacyToken = st.get(TOKEN_KEY);
+    const legacyRefresh = st.get(REFRESH_KEY);
+    const legacyExpires = st.get(TOKEN_EXPIRES_KEY);
+    let legacyUser = null;
+    if (legacyUserRaw) {
       try {
-        const parsed = JSON.parse(cachedUser);
-        if (typeof parsed.id !== "string" || parsed.id.length === 0) throw new Error("invalid cache");
-        this.user = parsed;
-        if (cachedToken) {
-          this.accessToken = cachedToken;
-          this.accessExpiresAt = cachedExpires ? Number(cachedExpires) : 0;
+        const parsed = JSON.parse(legacyUserRaw);
+        if (isAuthUserShape(parsed)) legacyUser = parsed;
+      } catch {
+      }
+    }
+    const pending = Array.isArray(record?.heldReportsPending) ? record.heldReportsPending.filter((x) => typeof x === "string") : [];
+    const recordRefresh = typeof record?.refreshToken === "string" && record.refreshToken ? record.refreshToken : null;
+    const recordUser = record?.user && isAuthUserShape(record.user) ? record.user : null;
+    const useRecord = recordRefresh !== null && legacyRefresh !== null && legacyRefresh === recordRefresh;
+    if (useRecord) {
+      return {
+        user: recordUser ?? legacyUser,
+        accessToken: typeof record.accessToken === "string" && record.accessToken ? record.accessToken : legacyToken,
+        accessExpiresAt: typeof record.accessExpiresAt === "number" ? record.accessExpiresAt : legacyExpires ? Number(legacyExpires) : 0,
+        refreshToken: recordRefresh,
+        heldReportsPending: pending,
+        legacyOnly: false
+      };
+    }
+    return {
+      user: legacyUser,
+      accessToken: legacyToken,
+      accessExpiresAt: legacyExpires ? Number(legacyExpires) : 0,
+      refreshToken: legacyRefresh,
+      heldReportsPending: pending,
+      legacyOnly: legacyRefresh !== null
+    };
+  }
+  /** Load the K slots into the in-memory mirror; dedupe against the current user (current wins); keep unparseable slots untouched. */
+  hydrateHeldSlots() {
+    const seen = /* @__PURE__ */ new Set();
+    for (let i = 0; i < HELD_SLOT_KEYS.length; i++) {
+      const rec = this.readSlot(i);
+      if (!rec) continue;
+      if (this.user && rec.userId === this.user.id) {
+        this.writeSlot(i, null);
+        continue;
+      }
+      if (seen.has(rec.userId)) {
+        const j = this.held.findIndex((h) => h?.userId === rec.userId);
+        const other = this.held[j];
+        if (rec.heldAt >= other.heldAt) {
+          this.writeSlot(j, null);
+          this.held[i] = rec;
         } else {
-          this.accessToken = null;
-          this.accessExpiresAt = 0;
+          this.writeSlot(i, null);
         }
-        this.hooks.onIdentityChange(this.user.id);
-      } catch {
-        this.hooks.storage.remove(USER_KEY);
-        this.hooks.storage.remove(TOKEN_KEY);
-        this.hooks.storage.remove(TOKEN_EXPIRES_KEY);
+        continue;
       }
+      seen.add(rec.userId);
+      this.held[i] = rec;
     }
-    this.hydrated = true;
-    if (this.user && this.hooks.storage.get(REFRESH_KEY)) this.startProactiveRefreshCron();
-    this.resolveReady();
   }
-  getCurrentUser() {
-    return this.user;
+  /** Parse one slot off disk. `null` for an empty OR unparseable slot (the latter is left on disk, P11). */
+  readSlot(i) {
+    const raw = this.hooks.storage.get(HELD_SLOT_KEYS[i]);
+    if (!raw) return null;
+    try {
+      const p = JSON.parse(raw);
+      if (!p || typeof p !== "object" || p.v !== 1) return null;
+      if (typeof p.userId !== "string" || !p.userId) return null;
+      if (typeof p.refreshToken !== "string" || !p.refreshToken) return null;
+      return {
+        v: 1,
+        userId: p.userId,
+        sid: typeof p.sid === "string" ? p.sid : "",
+        refreshToken: p.refreshToken,
+        tokenAtHold: typeof p.tokenAtHold === "string" && p.tokenAtHold ? p.tokenAtHold : p.refreshToken,
+        heldAt: typeof p.heldAt === "number" && Number.isFinite(p.heldAt) ? p.heldAt : 0,
+        project: typeof p.project === "string" ? p.project : null,
+        autoRestore: p.autoRestore !== false
+      };
+    } catch {
+      return null;
+    }
   }
+  // ============================================================
+  // STATUS + READINESS (ADR-033 §3.5)
+  // ============================================================
   /**
-   * 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`.
+   * The closed boot/identity state. Synchronous, never waits on the network.
    *
-   * ⚠ 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"`.
+   *  - `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})`.
    *
-   * Returns an unsubscribe function.
+   * ⚠ 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() {
+    if (this.withheld) return "withheld";
+    if (!this.hydrated) return "unknown";
+    const refresh = this.hooks.storage.get(REFRESH_KEY);
+    if (!refresh) return "signed_out";
+    if (!this.user) return "unknown";
+    return this.user.isAnonymous ? "anonymous" : "identified";
+  }
+  /** Resolves after hydrate with the settled status — possibly `unknown` or `withheld`. Never waits on the network. */
+  async authStateReady() {
+    await this.readyPromise;
+    return this.status();
+  }
+  getCurrentUser() {
+    return this.user;
+  }
+  /** Alias of `getCurrentUser()` gated on hydration (parity with `Sendora.getUserSync()`). */
+  getUserSync() {
+    return this.hydrated ? this.user : null;
+  }
+  /** True once `hydrate()` has run. `true` in `withheld` and `unknown` too — read `status()`. */
+  isReady() {
+    return this.hydrated;
+  }
+  // ============================================================
+  // LISTENERS
+  // ============================================================
+  /**
+   * 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.
    *
-   * 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) {
     this.takeoverListeners.add(listener);
@@ -780,36 +1186,55 @@ var Auth = class {
     };
   }
   /**
-   * Subscribe to every auth-state transition (1.28.0) — the single stream that
-   * answers "what happened to my session?". Firebase `onAuthStateChanged` /
-   * Supabase `onAuthStateChange` parity.
+   * Subscribe to every auth-state transition — 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" }`.
-   *
-   * 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.
    *
-   * Listeners are best-effort; a throwing listener is swallowed (dev-logged)
-   * and never affects auth state. Returns an unsubscribe function.
+   * ⚠ 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).
+   *
+   * 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) {
     this.authStateListeners.add(listener);
-    if (this.hydrated && this.user) {
-      const user = this.user;
+    if (this.hydrated) {
+      const status = this.status();
+      const change = {
+        event: "initial",
+        status,
+        user: this.user,
+        ...this.withheld ? { withheld: this.withheld } : {}
+      };
       try {
-        listener({ event: "signed_in", user });
+        listener(change);
       } catch (err) {
         if (this.hooks.debug) console.warn("[Sendora] onAuthStateChanged listener threw", err);
       }
+      const user = this.user;
+      if (user && (status === "anonymous" || status === "identified") && this.authStateListeners.has(listener)) {
+        try {
+          listener({ event: "signed_in", user });
+        } catch (err) {
+          if (this.hooks.debug) console.warn("[Sendora] onAuthStateChanged listener threw", err);
+        }
+      }
     }
     return () => {
       this.authStateListeners.delete(listener);
@@ -825,16 +1250,10 @@ var Auth = class {
       }
     }
   }
-  /**
-   * 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() {
     return this.lastTakeover;
   }
-  /** Internal — fan out to subscribers + cache the latest. */
   fireDeviceTakeover(retiredAnonUserId, identifiedUserId) {
     const evt = { retiredAnonUserId, identifiedUserId, at: /* @__PURE__ */ new Date() };
     this.lastTakeover = evt;
@@ -849,10 +1268,8 @@ var Auth = class {
   /**
    * 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) {
     this.deletionCancelledListeners.add(listener);
@@ -865,19 +1282,15 @@ var Auth = class {
     return this.lastDeletionCancelled;
   }
   /**
-   * 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() {
     return this.lastAnonRetirement;
   }
-  /** Internal — fan out deletion-cancelled to subscribers + cache the latest. */
   fireDeletionCancelled(userId) {
     const evt = { userId, at: /* @__PURE__ */ new Date() };
     this.lastDeletionCancelled = evt;
@@ -889,42 +1302,9 @@ var Auth = class {
       }
     }
   }
-  /**
-   * 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.
-   */
+  // ============================================================
+  // TOKEN LIVENESS (s58.281 — unchanged machinery)
+  // ============================================================
   /**
    * The cached-token guard, and the single place the two deadlines are
    * combined. Both must agree before a cached token is served:
@@ -935,16 +1315,8 @@ var Auth = class {
    *     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).
    */
   canServeToken(token, expiresAt, nowMs) {
     if (!token || !expiresAt) return false;
@@ -969,10 +1341,7 @@ var Auth = class {
    * 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.
    */
   async refreshAndReconcile(nowMs) {
     const reconciling = this.deadlinesDisagree(nowMs);
@@ -980,15 +1349,7 @@ var Auth = class {
     if (reconciling && token) this.learnClockSkewFrom(token, Date.now());
     return token;
   }
-  /**
-   * 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. */
   learnClockSkewFrom(freshToken, nowMs) {
     if (!accessTokenExpIsFuture(freshToken, nowMs)) this.clockSkewConfirmed = true;
   }
@@ -996,7 +1357,32 @@ var Auth = class {
   deadlinesDisagree(nowMs) {
     return this.trackedDeadlineAlive(nowMs) && !this.canServeCachedToken(nowMs);
   }
+  /**
+   * 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.
+   */
   async getAccessToken(options) {
+    if (this.withheld) return null;
     if (!options?.forceRefresh && this.canServeCachedToken(Date.now())) {
       return this.accessToken;
     }
@@ -1005,188 +1391,245 @@ var Auth = class {
     if (Date.now() < this.refreshCooldownUntil) return null;
     return this.refreshAndReconcile(Date.now());
   }
-  /** 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() {
+    if (this.withheld) return null;
     return this.accessToken;
   }
   /**
-   * Mint (or return) an anonymous session.
+   * 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() {
+    if (this.withheld) return null;
+    return this.hooks.storage.get(REFRESH_KEY) ?? null;
+  }
+  // ============================================================
+  // MINT (ADR-033 §3.3 rows 6–11)
+  // ============================================================
+  /**
+   * Return the current session, minting an anonymous one only when there is
+   * none.
    *
-   * Reuses the existing anonymous user when there already is one — the same
-   * short-circuit Firebase's `signInAnonymously` performs. Without it, an app
-   * that calls this defensively on every 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.
+   * - `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'}`.
    *
-   * Pass `forceNew: true` to deliberately abandon the current anonymous
-   * session and mint a separate one.
+   * `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) {
     return this.serialize(async () => {
+      this.rejectIfWithheld("signInAnonymously");
+      await this.awaitSettled();
       const existing = this.user;
-      if (!opts?.forceNew && existing?.isAnonymous && this.hooks.storage.get(REFRESH_KEY)) {
+      if (!opts?.forceNew && existing && this.hooks.storage.get(REFRESH_KEY)) {
         return existing;
       }
-      const data = await this.callAuth("/api/v1/auth-service/anonymous", {
-        name: opts?.name,
-        metadata: opts?.metadata
+      const heldCount = this.heldCount();
+      const t = heldCount + (this.status() === "anonymous" ? 1 : 0);
+      if (opts?.forceNew && t >= HELD_GUEST_SLOTS) {
+        throw new HeldGuestLimitError();
+      }
+      if (!opts?.forceNew && this.status() === "signed_out") {
+        const eligible = this.eligibleHeldSlots();
+        if (eligible.length > 0 && (this.hooks.autoRestoreHeldGuest !== false || t >= HELD_GUEST_SLOTS)) {
+          for (const i of eligible) {
+            const restored = await this.restoreSlotForMint(i);
+            if (restored) return restored;
+          }
+        } else if (t >= HELD_GUEST_SLOTS) {
+          throw new HeldGuestLimitError();
+        }
+      }
+      return this.mintFresh({ name: opts?.name, metadata: opts?.metadata, forceNew: opts?.forceNew === true });
+    });
+  }
+  /** Alias of `signInAnonymously()` — "make sure I have a session". */
+  ensureSession() {
+    return this.signInAnonymously();
+  }
+  /** Row 6 (and row 11's second half): `POST /anonymous` → ProjectGuard on the RESPONSE → install. */
+  async mintFresh(opts) {
+    this.attempt = { kind: "mint", expect: this.snapshotIdentity() };
+    try {
+      await this.awaitRefreshQuiet();
+      const expect = this.snapshotIdentity();
+      this.attempt = { kind: "mint", expect };
+      const mintKey = this.currentMintKey();
+      const body = {};
+      if (opts.name !== void 0) body.name = opts.name;
+      if (opts.metadata !== void 0) body.metadata = opts.metadata;
+      if (mintKey) body.mintKey = mintKey;
+      const data = await this.callAuth("/api/v1/auth-service/anonymous", body);
+      await this.awaitRefreshQuiet();
+      const outcome = this.commit({
+        kind: "install",
+        reason: "mint",
+        record: { user: data.user, accessToken: data.tokens.accessToken, refreshToken: data.tokens.refreshToken, expiresIn: data.tokens.expiresIn },
+        expect,
+        holdPrevious: opts.forceNew,
+        response: data
       });
-      this.persist(data);
+      if (outcome.status === "project_mismatch") {
+        this.revokeFireAndForget(data.tokens.refreshToken);
+        throw withheldError("PROJECT_MISMATCH", "The minted session belongs to a different project than init({expectedProjectId}); nothing was installed");
+      }
+      if (outcome.status === "held_limit") {
+        this.revokeFireAndForget(data.tokens.refreshToken);
+        throw new HeldGuestLimitError();
+      }
+      if (outcome.status !== "applied") {
+        this.revokeFireAndForget(data.tokens.refreshToken);
+        throw new AuthError("ATTEMPT_SUPERSEDED", "The session changed while the mint was in flight; nothing was installed", { kind: "unknown" });
+      }
+      this.hooks.storage.remove(MINT_KEY_KEY);
       return data.user;
-    });
+    } finally {
+      this.attempt = null;
+    }
+  }
+  /**
+   * 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.
+   */
+  async restoreSlotForMint(i) {
+    const slot = this.held[i];
+    if (!slot) return null;
+    const expect = this.snapshotIdentity();
+    this.attempt = { kind: "restore", expect };
+    try {
+      const refreshed = await this.refreshHeld(i);
+      if (refreshed.outcome === "dead") return null;
+      if (refreshed.outcome === "kept") {
+        throw new AuthError("RESTORE_FAILED", "The held guest could not be refreshed right now; it is still held", { kind: "server", retryable: true });
+      }
+      return this.installRestored(i, refreshed.data, expect);
+    } finally {
+      this.attempt = null;
+    }
+  }
+  /** The per-attempt B10 key: reuse the persisted one (a crash-retry) or mint a new one and persist it until MINT_OK. */
+  currentMintKey() {
+    const existing = this.hooks.storage.get(MINT_KEY_KEY);
+    if (existing && existing.length >= 16 && existing.length <= 128) return existing;
+    const fresh = generateMintKey();
+    if (fresh) this.hooks.storage.set(MINT_KEY_KEY, fresh);
+    return fresh;
   }
+  // ============================================================
+  // SIGN UP (ADR-033 §3.5 upgrade)
+  // ============================================================
   /**
-   * Create an email/password account.
+   * Create an email/password account — routed by `status()`:
    *
-   * 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.
+   *  - `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`.
    *
-   * 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.
+   * 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, password, opts) {
     return this.serialize(async () => {
-      const refresh = this.hooks.storage.get(REFRESH_KEY);
-      if (refresh) {
+      this.rejectIfWithheld("signUp");
+      await this.awaitSettled();
+      const status = this.status();
+      if (status === "identified") throw new AlreadyIdentifiedError();
+      if (status === "anonymous") {
+        const body = { email, password };
+        if (opts?.name !== void 0) body.name = opts.name;
+        const result = await this.doLink(LINK_EMAIL_PATH, body, { legacyEmit: true, label: "password" });
+        if (result.status === "credential_in_use") throw new EmailAlreadyTakenError();
+        if (result.status === "recent_auth_required") {
+          throw new AuthError("RECENT_AUTH_REQUIRED", "Re-authenticate before adding a password", { status: 403 });
+        }
+        return result.user;
+      }
+      const expect = this.snapshotIdentity();
+      this.attempt = { kind: "sign_in", expect };
+      try {
+        const body = { email, password };
+        if (opts?.name !== void 0) body.name = opts.name;
+        if (opts?.metadata !== void 0) body.metadata = opts.metadata;
+        let data;
         try {
-          const data = await this.callAuth("/api/v1/auth-service/upgrade", {
-            refreshToken: refresh,
-            email,
-            password,
-            name: opts?.name
-          });
-          this.persist(data);
-          return data.user;
+          data = await this.callAuth("/api/v1/auth-service/signup", body);
         } catch (err) {
-          if (err instanceof AuthError && (err.code === "NOT_ANONYMOUS" || err.code === "FORBIDDEN_NON_ANONYMOUS")) {
-            throw new AlreadyIdentifiedError(err.message);
-          }
           if (err instanceof AuthError && (err.code === "CONFLICT" || err.code === "EMAIL_ALREADY_TAKEN")) {
             throw new EmailAlreadyTakenError(err.message);
           }
-          if (err instanceof AuthError && (err.code === "INVALID_REFRESH" || err.code === "UNAUTHORIZED" || err.code === "REFRESH_EXPIRED")) {
-            await this.wipeLocalIdentity("session_expired");
-          } else {
-            throw err;
-          }
+          throw err;
         }
-      }
-      try {
-        const data = await this.callAuth("/api/v1/auth-service/signup", {
-          email,
-          password,
-          name: opts?.name,
-          metadata: opts?.metadata
-        });
-        this.persist(data);
+        this.installSignIn(data, expect);
         return data.user;
-      } catch (err) {
-        if (err instanceof AuthError && err.code === "CONFLICT") {
-          throw new EmailAlreadyTakenError(err.message);
-        }
-        throw err;
+      } finally {
+        this.attempt = null;
       }
     });
   }
+  // ============================================================
+  // SIGN-IN (ADR-033 §3.3 rows 17–19: SIGN_IN = switch) — legacy signatures
+  // ============================================================
   /**
    * 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, password) {
     return this.serialize(async () => {
-      const prevAnonRefreshToken = this.readPrevAnonRefreshToken();
-      const res = await post(
-        { apiUrl: this.hooks.apiUrl, publicKey: this.hooks.publicKey, debug: this.hooks.debug },
-        "/api/v1/auth-service/login",
-        prevAnonRefreshToken ? { email, password, prevAnonRefreshToken } : { email, password }
-      );
-      if (!res) throw new AuthError("NETWORK_ERROR", "Network request failed");
-      let parsed;
-      try {
-        parsed = await res.json();
-      } catch {
-        throw new AuthError("PARSE_ERROR", `HTTP ${res.status}`, { status: res.status });
-      }
-      if (!res.ok || !parsed.success || !parsed.data) {
-        throw new AuthError(
-          parsed.error?.code ?? `HTTP_${res.status}`,
-          parsed.error?.message ?? `HTTP ${res.status}`,
-          { status: res.status, retryAfterSeconds: readRetryAfterSeconds(parsed) }
-        );
-      }
-      const r = parsed.data;
-      if (r.mfaRequired === true && typeof r.mfaChallengeToken === "string") {
-        if (prevAnonRefreshToken) {
-          this.pendingAnonTakeover = { challengeToken: r.mfaChallengeToken, prevAnonRefreshToken };
-        }
-        const u = r.user;
-        return { mfaRequired: true, mfaChallengeToken: r.mfaChallengeToken, userId: u?.id ?? "" };
-      }
-      if (!isAuthApiResponse(parsed.data)) {
-        throw new AuthError(parsed.error?.code ?? "AUTH_ERROR", parsed.error?.message ?? "Login failed");
-      }
-      if (this.user !== null) await this.wipeLocalIdentity();
-      this.persist(parsed.data);
-      return parsed.data.user;
+      this.rejectIfWithheld("signIn");
+      await this.awaitSettled();
+      const r = await this.doSignIn({ kind: "password", email, password });
+      if (r.kind === "mfa") return { mfaRequired: true, mfaChallengeToken: r.challengeToken, userId: r.userId };
+      return r.user;
     });
   }
   /**
    * 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) {
+    const { link, onCredentialInUse, ...socialInput } = input;
+    const credential = { ...socialInput, kind: input.provider };
     return this.serialize(async () => {
-      const prevAnonRefreshToken = this.readPrevAnonRefreshToken();
-      const { link, onCredentialInUse, ...socialInput } = input;
-      const payload = { ...socialInput };
-      if (prevAnonRefreshToken) payload.prevAnonRefreshToken = prevAnonRefreshToken;
-      if (link) payload.linkAnonymous = true;
-      if (onCredentialInUse) payload.onCredentialInUse = onCredentialInUse;
-      const res = await post(
-        { apiUrl: this.hooks.apiUrl, publicKey: this.hooks.publicKey, debug: this.hooks.debug },
-        "/api/v1/auth-service/login/social",
-        payload
-      );
-      if (!res) throw new AuthError("NETWORK_ERROR", "Network request failed");
-      let parsed;
-      try {
-        parsed = await res.json();
-      } catch {
-        throw new AuthError("PARSE_ERROR", `HTTP ${res.status}`, { status: res.status });
-      }
-      if (!res.ok || !parsed.success || !isAuthApiResponse(parsed.data)) {
-        if (parsed.error?.code === "CREDENTIAL_IN_USE") {
-          throw new CredentialInUseError(parsed.error.message, {
-            ...readCollisionDetails(parsed),
-            status: res.status
-          });
-        }
-        throw new AuthError(
-          parsed.error?.code ?? "SOCIAL_LOGIN_FAILED",
-          parsed.error?.message ?? "Social login failed",
-          { status: res.status, retryAfterSeconds: readRetryAfterSeconds(parsed) }
-        );
-      }
-      if (this.user !== null) await this.wipeLocalIdentity("replaced");
-      this.persist(parsed.data);
-      return parsed.data.user;
+      this.rejectIfWithheld("loginSocial");
+      await this.awaitSettled();
+      if (link && this.hasSession()) return this.legacyLink(credential, onCredentialInUse);
+      return (await this.doSignInDone(credential)).user;
     });
   }
   signInWithGoogle(code, redirectUri, link) {
@@ -1211,66 +1654,198 @@ var Auth = class {
     return this.loginSocial({ provider: "discord", code, redirectUri });
   }
   signInWithGameCenter(payloadOrOpts, maybeOpts) {
-    const path = "/api/v1/auth-service/login/game-center";
     if (payloadOrOpts && "publicKeyUrl" in payloadOrOpts) {
-      return this.gameIdentitySignIn(path, { ...payloadOrOpts }, maybeOpts);
+      const payload = payloadOrOpts;
+      return this.gameIdentitySignIn(async () => ({ kind: "gameCenter", ...payload }), maybeOpts);
     }
     return this.gameIdentitySignIn(
-      path,
-      async () => await fetchGameCenterPayloadNative(),
+      async () => ({ kind: "gameCenter", ...await fetchGameCenterPayloadNative() }),
       payloadOrOpts
     );
   }
   signInWithPlayGames(payloadOrOpts, maybeOpts) {
-    const path = "/api/v1/auth-service/login/play-games";
     if (payloadOrOpts && "serverAuthCode" in payloadOrOpts) {
       const { serverAuthCode } = payloadOrOpts;
-      return this.gameIdentitySignIn(path, { serverAuthCode }, maybeOpts);
+      return this.gameIdentitySignIn(async () => ({ kind: "playGames", serverAuthCode }), maybeOpts);
     }
     return this.gameIdentitySignIn(
-      path,
-      async () => await fetchPlayGamesAuthCodeNative(),
+      async () => ({ kind: "playGames", ...await fetchPlayGamesAuthCodeNative() }),
       payloadOrOpts
     );
   }
-  // ============================================================
-  // IDENTITY LINKING (ADR-030) — attach a SECOND credential to the
-  // CURRENT signed-in account, preserving the same user id (sub).
-  // ============================================================
-  //
-  // Unlike signUp() / loginSocial({link}) — which only preserve the sub from
-  // an ANONYMOUS session — these operate on an ALREADY-IDENTIFIED account.
-  // No token rotation (the session is unchanged); they refresh the cached user
-  // object in place. Require a signed-in user (throws NOT_SIGNED_IN otherwise).
-  //
-  // Primary use: ONE account across platforms. A Game Center player on iOS
-  // links email/Google; on Android they sign in with that same credential and
-  // land on the SAME sub, progress intact. Collision (the credential already
-  // belongs to another account) → CredentialInUseError (never merges).
-  /** Link email + password to the current account (sub preserved). */
-  linkEmailPassword(email, password) {
-    return this.linkCredential("/api/v1/auth-service/me/link/email", { email, password });
-  }
-  /** Link an OAuth social identity (verified idToken or code) to the current account. */
-  linkSocial(input) {
-    return this.linkCredential("/api/v1/auth-service/me/link/social", input);
-  }
-  /** Convenience: link a Google identity (native idToken, or web code+redirectUri). */
-  linkGoogle(input) {
-    return this.linkSocial({ provider: "google", ...input });
-  }
-  /** Convenience: link an Apple identity (native idToken, or web code+redirectUri). */
-  linkApple(input) {
-    return this.linkSocial({ provider: "apple", ...input });
-  }
   /**
-   * Link an Apple Game Center identity to the current account. No-arg drives the
-   * native GameKit fetch (needs `@sendoracloud/sdk-react-native-gaming`); or pass
-   * an explicit payload obtained from your own GameKit bridge.
+   * 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`.
    */
-  async linkGameCenter(payload) {
+  gameIdentitySignIn(credentialOf, opts) {
+    return this.serialize(async () => {
+      this.rejectIfWithheld("signInWithGameCenter/PlayGames");
+      await this.awaitSettled();
+      const credential = await credentialOf();
+      if (opts?.link && this.hasSession()) return this.legacyLink(credential, opts.onCredentialInUse);
+      return (await this.doSignInDone(credential)).user;
+    });
+  }
+  /**
+   * 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`).
+   */
+  async legacyLink(credential, policy) {
+    const wire = linkWire(credential);
+    if (!wire) return (await this.doSignInDone(credential)).user;
+    const r = await this.doLink(wire.path, wire.body, { legacyEmit: true, label: providerLabel(credential) });
+    if (r.status === "done") return r.user;
+    if (r.status === "credential_in_use") {
+      if (policy === "adopt") return (await this.doSignInDone(credential)).user;
+      throw new CredentialInUseError(r.message, { provider: r.provider, collision: r.collision, status: r.httpStatus });
+    }
+    throw new AuthError("RECENT_AUTH_REQUIRED", r.message, { status: 403 });
+  }
+  /**
+   * 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, code) {
+    return this.serialize(async () => {
+      this.rejectIfWithheld("challengeMfa");
+      await this.awaitSettled();
+      return (await this.doSignInDone({ kind: "mfa", challengeToken: mfaChallengeToken, code })).user;
+    });
+  }
+  // ============================================================
+  // TYPED VERBS (ADR-033 §3.5) — signInWith / link / switchAccount
+  // ============================================================
+  /**
+   * 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) {
+    return this.serialize(async () => {
+      this.rejectIfWithheld("signInWith");
+      await this.awaitSettled();
+      return this.toSignInResult(await this.doSignIn(credential));
+    });
+  }
+  /**
+   * 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) {
+    return this.serialize(async () => {
+      this.rejectIfWithheld("link");
+      await this.awaitSettled();
+      const wire = linkWire(credential);
+      if (!wire) {
+        throw new AuthError("UNSUPPORTED_LINK_CREDENTIAL", `A ${credential.kind} credential cannot be attached to an account; sign in with it instead`, { kind: "config" });
+      }
+      if (!this.hasSession()) throw new AuthError("NOT_SIGNED_IN", "Sign in before linking a credential");
+      const r = await this.doLink(wire.path, wire.body, { legacyEmit: false, label: providerLabel(credential) });
+      if (r.status === "done") return { status: "done", user: r.user, upgraded: r.upgraded, alreadyLinked: r.alreadyLinked };
+      if (r.status === "recent_auth_required") return { status: "recent_auth_required" };
+      const refusedAt = Date.now();
+      return {
+        status: "credential_in_use",
+        provider: r.provider,
+        collision: r.collision,
+        switchAccount: () => this.switchAccount(credential, refusedAt),
+        keepCurrent: () => void 0
+      };
+    });
+  }
+  /**
+   * 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.)
+   */
+  switchAccount(credential, refusedAt) {
+    return this.serialize(async () => {
+      this.rejectIfWithheld("switchAccount");
+      await this.awaitSettled();
+      let bound = credential;
+      if (Date.now() - refusedAt > SWITCH_CREDENTIAL_MAX_AGE_MS) {
+        if (credential.kind === "gameCenter") {
+          const fresh = await fetchGameCenterPayloadNative();
+          if (fresh.teamPlayerId !== credential.teamPlayerId) {
+            throw new AuthError("CREDENTIAL_CHANGED", "The Game Center player on this device is no longer the one whose link was refused", { kind: "invalid_credential" });
+          }
+          bound = { kind: "gameCenter", ...fresh };
+        } else if (credential.kind === "playGames") {
+          bound = { kind: "playGames", ...await fetchPlayGamesAuthCodeNative() };
+        }
+      }
+      return this.toSignInResult(await this.doSignIn(bound));
+    });
+  }
+  toSignInResult(r) {
+    if (r.kind === "mfa") {
+      const challengeToken = r.challengeToken;
+      return {
+        status: "mfa_required",
+        challengeToken,
+        verify: (code) => this.signInWith({ kind: "mfa", challengeToken, code })
+      };
+    }
+    return { status: "done", user: r.user, previous: r.previous, reactivated: r.reactivated };
+  }
+  // ============================================================
+  // IDENTITY LINKING (ADR-030) — legacy link*() verbs
+  // ============================================================
+  //
+  // Attach a SECOND credential to the CURRENT account, preserving the `sub`.
+  // From an identified account: no token rotation; the cached user is refreshed
+  // in place (`user_updated{cause:'link'}`). From a guest (1.30.0 / ADR-033
+  // INV-4): the server promotes the guest in place and ROTATES the session; the
+  // returned pair is installed (the old refresh token is revoked server-side).
+  // Collision → `CredentialInUseError` (never merges). Require a session
+  // (throw NOT_SIGNED_IN otherwise).
+  /** Link email + password to the current account (sub preserved). */
+  linkEmailPassword(email, password) {
+    return this.linkCredential(LINK_EMAIL_PATH, { email, password }, "password");
+  }
+  /** Link an OAuth social identity (verified idToken or code) to the current account. */
+  linkSocial(input) {
+    return this.linkCredential(LINK_SOCIAL_PATH, stripUndefined(input), input.provider);
+  }
+  /** Convenience: link a Google identity (native idToken, or web code+redirectUri). */
+  linkGoogle(input) {
+    return this.linkSocial({ provider: "google", ...input });
+  }
+  /** Convenience: link an Apple identity (native idToken, or web code+redirectUri). */
+  linkApple(input) {
+    return this.linkSocial({ provider: "apple", ...input });
+  }
+  /**
+   * Link an Apple Game Center identity to the current account. No-arg drives the
+   * native GameKit fetch (needs `@sendoracloud/sdk-react-native-gaming`); or pass
+   * an explicit payload obtained from your own GameKit bridge.
+   */
+  async linkGameCenter(payload) {
     const body = payload ?? await fetchGameCenterPayloadNative();
-    return this.linkCredential("/api/v1/auth-service/me/link/game-center", { ...body });
+    return this.linkCredential(LINK_GAME_CENTER_PATH, { ...body }, "gamecenter");
   }
   /**
    * Link a Google Play Games identity to the current account. No-arg drives the
@@ -1278,74 +1853,41 @@ var Auth = class {
    */
   async linkPlayGames(payload) {
     const body = payload ?? await fetchPlayGamesAuthCodeNative();
-    return this.linkCredential("/api/v1/auth-service/me/link/play-games", { ...body });
+    return this.linkCredential(LINK_PLAY_GAMES_PATH, { ...body }, "playgames");
   }
   /**
-   * 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.
    */
-  async linkCredential(path, body) {
-    const token = await this.getAccessToken();
-    if (!token) throw new AuthError("NOT_SIGNED_IN", "Sign in before linking a credential");
-    const res = await post(
-      { apiUrl: this.hooks.apiUrl, publicKey: this.hooks.publicKey, debug: this.hooks.debug },
-      path,
-      body,
-      { Authorization: `Bearer ${token}` }
-    );
-    if (!res) throw new AuthError("NETWORK_ERROR", "Network request failed");
-    let parsed;
-    try {
-      parsed = await res.json();
-    } catch {
-      throw new AuthError("PARSE_ERROR", `HTTP ${res.status}`, { status: res.status });
-    }
-    if (!res.ok || !parsed.success || !parsed.data) {
-      const code = parsed.error?.code ?? `HTTP_${res.status}`;
-      if (code === "CREDENTIAL_IN_USE") {
-        throw new CredentialInUseError(parsed.error?.message, {
-          ...readCollisionDetails(parsed),
-          status: res.status
-        });
+  linkCredential(path, body, label) {
+    return this.serialize(async () => {
+      this.rejectIfWithheld("link");
+      await this.awaitSettled();
+      if (!this.hasSession()) throw new AuthError("NOT_SIGNED_IN", "Sign in before linking a credential");
+      const r = await this.doLink(path, body, { legacyEmit: false, label });
+      if (r.status === "done") return r.user;
+      if (r.status === "credential_in_use") {
+        throw new CredentialInUseError(r.message, { provider: r.provider, collision: r.collision, status: r.httpStatus });
       }
-      throw new AuthError(code, parsed.error?.message ?? "Failed to link credential", {
-        status: res.status,
-        retryAfterSeconds: readRetryAfterSeconds(parsed)
-      });
-    }
-    if (parsed.data.upgraded && isAuthApiResponse(parsed.data)) {
-      this.persist(parsed.data);
-      return parsed.data.user;
-    }
-    if (parsed.data.user) this.updateLocalUser(parsed.data.user);
-    return parsed.data.user ?? this.user;
-  }
-  /**
-   * 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).
-   */
-  updateLocalUser(user) {
-    this.user = user;
-    this.hooks.storage.set(USER_KEY, JSON.stringify(user));
+      throw new AuthError("RECENT_AUTH_REQUIRED", r.message, { status: 403 });
+    });
   }
   /**
    * 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.
    */
   async listLinkedIdentities() {
+    this.rejectIfWithheld("listLinkedIdentities");
     const token = await this.getAccessToken();
     if (!token) throw new AuthError("NOT_SIGNED_IN", "Sign in before listing linked identities");
     const res = await getJson(
-      { apiUrl: this.hooks.apiUrl, publicKey: this.hooks.publicKey, debug: this.hooks.debug },
+      this.http(),
       "/api/v1/auth-service/me/identities",
       { Authorization: `Bearer ${token}` }
     );
@@ -1362,32 +1904,23 @@ var Auth = class {
     return { identities: parsed.data.identities ?? [], hasPassword: Boolean(parsed.data.hasPassword) };
   }
   /**
-   * 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).
    */
   async unlink(provider) {
+    this.rejectIfWithheld("unlink");
     const token = await this.getAccessToken();
     if (!token) throw new AuthError("NOT_SIGNED_IN", "Sign in before unlinking an identity");
     const res = await del(
-      { apiUrl: this.hooks.apiUrl, publicKey: this.hooks.publicKey, debug: this.hooks.debug },
+      this.http(),
       `/api/v1/auth-service/me/identities/${encodeURIComponent(provider)}`,
       { Authorization: `Bearer ${token}` }
     );
@@ -1411,129 +1944,35 @@ var Auth = class {
       remaining: Number(parsed.data.remaining ?? 0)
     };
   }
-  /**
-   * 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`.
-   */
-  gameIdentitySignIn(path, identityBody, opts) {
-    const link = opts?.link;
-    const onCredentialInUse = opts?.onCredentialInUse;
-    return this.serialize(async () => {
-      const body = typeof identityBody === "function" ? await identityBody() : identityBody;
-      const prevAnonRefreshToken = this.readPrevAnonRefreshToken();
-      const payload = { ...body };
-      if (prevAnonRefreshToken) payload.prevAnonRefreshToken = prevAnonRefreshToken;
-      if (link) payload.linkAnonymous = true;
-      if (onCredentialInUse) payload.onCredentialInUse = onCredentialInUse;
-      const res = await post(
-        { apiUrl: this.hooks.apiUrl, publicKey: this.hooks.publicKey, debug: this.hooks.debug },
-        path,
-        payload
-      );
-      if (!res) throw new AuthError("NETWORK_ERROR", "Network request failed");
-      let parsed;
-      try {
-        parsed = await res.json();
-      } catch {
-        throw new AuthError("PARSE_ERROR", `HTTP ${res.status}`, { status: res.status });
-      }
-      if (!res.ok || !parsed.success || !isAuthApiResponse(parsed.data)) {
-        if (parsed.error?.code === "CREDENTIAL_IN_USE") {
-          throw new CredentialInUseError(parsed.error.message, {
-            ...readCollisionDetails(parsed),
-            status: res.status
-          });
-        }
-        throw new AuthError(
-          parsed.error?.code ?? "GAME_LOGIN_FAILED",
-          parsed.error?.message ?? "Game sign-in failed",
-          { status: res.status, retryAfterSeconds: readRetryAfterSeconds(parsed) }
-        );
-      }
-      if (this.user !== null) await this.wipeLocalIdentity("replaced");
-      this.persist(parsed.data);
-      return parsed.data.user;
-    });
-  }
-  /**
-   * 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.
-   */
-  readPrevAnonRefreshToken() {
-    if (!this.user?.isAnonymous) return void 0;
-    return this.hooks.storage.get(REFRESH_KEY) ?? void 0;
-  }
-  /**
-   * 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, code) {
-    return this.serialize(async () => {
-      const stashed = this.pendingAnonTakeover?.challengeToken === mfaChallengeToken ? this.pendingAnonTakeover.prevAnonRefreshToken : void 0;
-      const prevAnonRefreshToken = stashed ?? this.readPrevAnonRefreshToken();
-      const body = {
-        challengeToken: mfaChallengeToken,
-        code
-      };
-      if (prevAnonRefreshToken) body.prevAnonRefreshToken = prevAnonRefreshToken;
-      const data = await this.callAuth("/api/v1/auth-service/mfa/challenge", body);
-      if (this.user !== null) await this.wipeLocalIdentity();
-      this.persist(data);
-      return data.user;
-    });
-  }
   // ============================================================
-  // MAGIC LINK
+  // MAGIC LINK / EMAIL OTP (sign-in continuations — SIGN_IN row)
   // ============================================================
   async sendMagicLink(email) {
-    const res = await post(
-      { apiUrl: this.hooks.apiUrl, publicKey: this.hooks.publicKey, debug: this.hooks.debug },
-      "/api/v1/auth-service/magic-link/request",
-      { email }
-    );
+    const res = await post(this.http(), "/api/v1/auth-service/magic-link/request", { email });
     if (!res || !res.ok) {
       throw new AuthError("MAGIC_LINK_REQUEST_FAILED", "Failed to send link");
     }
   }
+  /** 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) {
     return this.serialize(async () => {
-      const prevAnonRefreshToken = this.readPrevAnonRefreshToken();
-      const body = { token };
-      if (prevAnonRefreshToken) body.prevAnonRefreshToken = prevAnonRefreshToken;
-      const data = await this.callAuth("/api/v1/auth-service/magic-link/verify", body);
-      if (this.user !== null) await this.wipeLocalIdentity("replaced");
-      this.persist(data);
-      return data.user;
+      this.rejectIfWithheld("verifyMagicLink");
+      await this.awaitSettled();
+      return (await this.doSignInDone({ kind: "magicLink", token })).user;
     });
   }
-  // ============================================================
-  // EMAIL OTP (6-digit cross-device code)
-  // ============================================================
   async sendEmailOtp(email) {
-    const res = await post(
-      { apiUrl: this.hooks.apiUrl, publicKey: this.hooks.publicKey, debug: this.hooks.debug },
-      "/api/v1/auth-service/email-otp/request",
-      { email }
-    );
+    const res = await post(this.http(), "/api/v1/auth-service/email-otp/request", { email });
     if (!res || !res.ok) {
       throw new AuthError("EMAIL_OTP_REQUEST_FAILED", "Failed to send code");
     }
   }
+  /** Mistyping a 6-digit code is the most common outcome of this flow; the session survives for the retry. */
   verifyEmailOtp(email, code) {
     return this.serialize(async () => {
-      const prevAnonRefreshToken = this.readPrevAnonRefreshToken();
-      const body = { email, code };
-      if (prevAnonRefreshToken) body.prevAnonRefreshToken = prevAnonRefreshToken;
-      const data = await this.callAuth("/api/v1/auth-service/email-otp/verify", body);
-      if (this.user !== null) await this.wipeLocalIdentity("replaced");
-      this.persist(data);
-      return data.user;
+      this.rejectIfWithheld("verifyEmailOtp");
+      await this.awaitSettled();
+      return (await this.doSignInDone({ kind: "emailOtp", email, code })).user;
     });
   }
   // ============================================================
@@ -1541,153 +1980,282 @@ var Auth = class {
   // ============================================================
   /** Trigger password-reset email. Resolves on 204 even when address is unknown (anti-enumeration). */
   async requestPasswordReset(email) {
-    const res = await post(
-      { apiUrl: this.hooks.apiUrl, publicKey: this.hooks.publicKey, debug: this.hooks.debug },
-      "/api/v1/auth-service/password/forgot",
-      { email }
-    );
+    const res = await post(this.http(), "/api/v1/auth-service/password/forgot", { email });
     if (!res || !res.ok) {
       throw new AuthError("PASSWORD_RESET_REQUEST_FAILED", "Failed to send reset email");
     }
   }
   /** Pair the reset-email token with the new password to complete the reset. */
   async resetPassword(token, newPassword) {
-    const res = await post(
-      { apiUrl: this.hooks.apiUrl, publicKey: this.hooks.publicKey, debug: this.hooks.debug },
-      "/api/v1/auth-service/password/reset",
-      { token, newPassword }
-    );
+    const res = await post(this.http(), "/api/v1/auth-service/password/reset", { token, newPassword });
     if (!res || !res.ok) {
       throw new AuthError("PASSWORD_RESET_FAILED", "Reset failed");
     }
   }
   /** Verify the email-address token from the link Sendora sent on signup. */
   async verifyEmail(token) {
-    const res = await post(
-      { apiUrl: this.hooks.apiUrl, publicKey: this.hooks.publicKey, debug: this.hooks.debug },
-      "/api/v1/auth-service/email/verify",
-      { token }
-    );
+    const res = await post(this.http(), "/api/v1/auth-service/email/verify", { token });
     if (!res || !res.ok) {
       throw new AuthError("EMAIL_VERIFICATION_FAILED", "Verification failed");
     }
   }
   /** Re-send the email-verification email for the currently-signed-in user. */
   async sendVerificationEmail() {
-    const headers = this.bearerHeaders();
-    if (!headers) throw new AuthError("UNAUTHORIZED", "Sign in before requesting a verification email");
-    const res = await post(
-      { apiUrl: this.hooks.apiUrl, publicKey: this.hooks.publicKey, debug: this.hooks.debug },
-      "/api/v1/auth-service/email/verify/resend",
-      {},
-      headers
-    );
+    this.rejectIfWithheld("sendVerificationEmail");
+    const headers = await this.bearerHeaders();
+    const res = await post(this.http(), "/api/v1/auth-service/email/verify/resend", {}, headers);
     if (!res || !res.ok) {
       throw new AuthError("VERIFICATION_RESEND_FAILED", "Failed to send verification email");
     }
   }
   // ============================================================
-  // TOTP MFA — enrollment management (Bearer-authenticated)
+  // HELD GUESTS (ADR-033 §3.5) — getHeldGuests / claim / restore / discard
+  // ============================================================
+  /**
+   * 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() {
+    return this.heldSorted().map((h) => ({ userId: h.userId, heldAt: h.heldAt, autoRestore: h.autoRestore, project: h.project }));
+  }
+  /** The newest held guest, or null. */
+  getHeldGuest() {
+    const newest = this.heldSorted()[0];
+    return newest ? { userId: newest.userId, heldAt: newest.heldAt } : 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) {
+    return this.serialize(async () => {
+      this.rejectIfWithheld("claimHeldGuest");
+      await this.awaitSettled();
+      const status = this.status();
+      if (status !== "identified") {
+        throw new AuthError(
+          "CLAIM_REQUIRES_IDENTIFIED",
+          status === "anonymous" ? "claimHeldGuest() merges a guest INTO an identified account; the current session is a guest" : "Sign in to an account before claiming a held guest",
+          { kind: "unknown" }
+        );
+      }
+      const i = this.resolveSlot(id);
+      const expect = this.snapshotIdentity();
+      this.attempt = { kind: "claim", expect };
+      try {
+        const refreshed = await this.refreshHeld(i);
+        if (refreshed.outcome === "dead") throw new AuthError("HELD_GUEST_GONE", "The held guest is no longer available on the server", { kind: "unknown" });
+        if (refreshed.outcome === "kept") throw new AuthError("RESTORE_FAILED", "The held guest could not be refreshed right now; it is still held", { kind: "server", retryable: true });
+        const heldRefresh = refreshed.data.tokens.refreshToken;
+        const target = this.hooks.storage.get(REFRESH_KEY);
+        if (!target) throw new AuthError("NOT_SIGNED_IN", "Sign in before claiming a held guest");
+        const merged = await this.postMerge(heldRefresh, target);
+        await this.awaitRefreshQuiet();
+        const user = this.user;
+        if (!user) throw new AuthError("NOT_SIGNED_IN", "The session ended while the claim was in flight");
+        const outcome = this.commit({
+          kind: "install",
+          reason: "claim",
+          record: { user, accessToken: merged.tokens.accessToken, refreshToken: merged.tokens.refreshToken, expiresIn: merged.tokens.expiresIn },
+          expect,
+          expectRefresh: target
+        });
+        if (outcome.status !== "applied") {
+          throw new AuthError("ATTEMPT_SUPERSEDED", "The session changed while the claim was in flight", { kind: "unknown" });
+        }
+        this.commit({ kind: "release", reason: "claimed", slot: i, userId: refreshed.data.user.id });
+        return { user, stats: merged.stats };
+      } finally {
+        this.attempt = null;
+      }
+    });
+  }
+  /**
+   * 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) {
+    return this.serialize(async () => {
+      this.rejectIfWithheld("restoreHeldGuest");
+      await this.awaitSettled();
+      const i = this.resolveSlot(id);
+      const slot = this.held[i];
+      const expectedProject = this.hooks.expectedProjectId ?? this.hooks.projectId;
+      if (expectedProject !== void 0 && slot.project !== null && slot.project !== expectedProject) {
+        throw new HeldGuestProjectMismatch(slot.userId, expectedProject, slot.project);
+      }
+      const status = this.status();
+      if (status === "anonymous" && this.freeSlotIndex() === -1) throw new HeldGuestLimitError();
+      const expect = this.snapshotIdentity();
+      this.attempt = { kind: "restore", expect };
+      try {
+        const refreshed = await this.refreshHeld(i);
+        if (refreshed.outcome === "dead") throw new AuthError("HELD_GUEST_GONE", "The held guest is no longer available on the server", { kind: "unknown" });
+        if (refreshed.outcome === "kept") throw new AuthError("RESTORE_FAILED", "The held guest could not be refreshed right now; it is still held", { kind: "server", retryable: true });
+        return this.installRestored(i, refreshed.data, expect);
+      } finally {
+        this.attempt = null;
+      }
+    });
+  }
+  /**
+   * 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) {
+    return this.serialize(async () => {
+      this.rejectIfWithheld("discardHeldGuest");
+      await this.awaitSettled();
+      const i = this.resolveSlot(id);
+      await this.discardSlot(i);
+    });
+  }
+  /** Shared body of `discardHeldGuest()` and `deleteAccount({alsoDiscardHeldGuests})`. */
+  async discardSlot(i) {
+    const slot = this.held[i];
+    if (!slot) return;
+    this.attempt = { kind: "discard", expect: this.snapshotIdentity() };
+    try {
+      const res = await post(this.http(), "/api/v1/auth-service/guest/discard", { refreshToken: slot.refreshToken });
+      if (!res) throw new AuthError("NETWORK_ERROR", "Network request failed");
+      if (!res.ok && res.status !== 404) {
+        const parsed = await res.json().catch(() => ({}));
+        throw new AuthError(parsed.error?.code ?? `HTTP_${res.status}`, parsed.error?.message ?? `HTTP ${res.status}`, {
+          status: res.status,
+          retryAfterSeconds: readRetryAfterSeconds(parsed)
+        });
+      }
+      this.commit({ kind: "release", reason: "discarded", slot: i, userId: slot.userId });
+    } finally {
+      this.attempt = null;
+    }
+  }
+  // ============================================================
+  // WITHHELD (ADR-033 [2c]) — getWithheld / discardWithheld
+  // ============================================================
+  /**
+   * 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() {
+    return this.withheld;
+  }
+  /**
+   * 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() {
+    return this.serialize(async () => {
+      if (!this.withheld) return false;
+      return this.commit({ kind: "discard_withheld" }).status === "applied";
+    });
+  }
+  // ============================================================
+  // SESSION VERBS (Bearer; NOT transitions — reject in `withheld`)
   // ============================================================
   async enrollMfa() {
-    const res = await post(
-      { apiUrl: this.hooks.apiUrl, publicKey: this.hooks.publicKey, debug: this.hooks.debug },
-      "/api/v1/auth-service/mfa/enroll/start",
-      {},
-      this.bearerHeaders()
-    );
+    this.rejectIfWithheld("enrollMfa");
+    const res = await post(this.http(), "/api/v1/auth-service/mfa/enroll/start", {}, await this.bearerHeaders());
     return await this.unwrap(res, "MFA_ENROLL_FAILED");
   }
   async confirmMfa(code) {
-    const res = await post(
-      { apiUrl: this.hooks.apiUrl, publicKey: this.hooks.publicKey, debug: this.hooks.debug },
-      "/api/v1/auth-service/mfa/enroll/confirm",
-      { code },
-      this.bearerHeaders()
-    );
+    this.rejectIfWithheld("confirmMfa");
+    const res = await post(this.http(), "/api/v1/auth-service/mfa/enroll/confirm", { code }, await this.bearerHeaders());
     const data = await this.unwrap(res, "MFA_CONFIRM_FAILED");
     return Boolean(data.confirmed);
   }
   /**
-   * 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.
    */
   async disableMfa() {
-    const res = await post(
-      { apiUrl: this.hooks.apiUrl, publicKey: this.hooks.publicKey, debug: this.hooks.debug },
-      "/api/v1/auth-service/mfa/disable",
-      {},
-      this.bearerHeaders()
-    );
+    this.rejectIfWithheld("disableMfa");
+    const res = await post(this.http(), "/api/v1/auth-service/mfa/disable", {}, await this.bearerHeaders());
     await this.unwrap(res, "MFA_DISABLE_FAILED");
   }
-  // ============================================================
-  // DEVICE SESSIONS (Bearer-authenticated)
-  // ============================================================
   async listMySessions() {
-    const res = await getJson(
-      { apiUrl: this.hooks.apiUrl, publicKey: this.hooks.publicKey, debug: this.hooks.debug },
-      "/api/v1/auth-service/sessions/me",
-      this.bearerHeaders()
-    );
+    this.rejectIfWithheld("listMySessions");
+    const res = await getJson(this.http(), "/api/v1/auth-service/sessions/me", await this.bearerHeaders());
     if (!res || !res.ok) return [];
     const parsed = await res.json();
     return Array.isArray(parsed.data) ? parsed.data : [];
   }
-  /**
-   * 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). */
   async revokeSession(sessionId) {
-    const res = await del(
-      { apiUrl: this.hooks.apiUrl, publicKey: this.hooks.publicKey, debug: this.hooks.debug },
-      `/api/v1/auth-service/sessions/me/${encodeURIComponent(sessionId)}`,
-      this.bearerHeaders()
-    );
+    this.rejectIfWithheld("revokeSession");
+    const res = await del(this.http(), `/api/v1/auth-service/sessions/me/${encodeURIComponent(sessionId)}`, await this.bearerHeaders());
     await this.unwrap(res, "SESSION_REVOKE_FAILED");
   }
-  /** Revoke every session for the caller. Same reporting defect as `revokeSession`. */
+  /** Revoke every session for the caller. Inspects the response (s58.335). */
   async revokeAllSessions() {
-    const res = await del(
-      { apiUrl: this.hooks.apiUrl, publicKey: this.hooks.publicKey, debug: this.hooks.debug },
-      "/api/v1/auth-service/sessions/me",
-      this.bearerHeaders()
-    );
+    this.rejectIfWithheld("revokeAllSessions");
+    const res = await del(this.http(), "/api/v1/auth-service/sessions/me", await this.bearerHeaders());
     await this.unwrap(res, "SESSION_REVOKE_ALL_FAILED");
   }
+  // ============================================================
+  // DELETE (ADR-033 §3.3 row 28)
+  // ============================================================
   /**
    * 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.
+   * 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.
    *
-   * 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.
+   * 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).
    */
-  async deleteAccount() {
+  async deleteAccount(opts) {
+    this.rejectIfWithheld("deleteAccount");
     const token = await this.getAccessToken();
     if (!token) {
       throw new AuthError("NOT_SIGNED_IN", "Sign in before deleting your account");
     }
-    const res = await del(
-      { apiUrl: this.hooks.apiUrl, publicKey: this.hooks.publicKey, debug: this.hooks.debug },
-      "/api/v1/auth-service/me",
-      { Authorization: `Bearer ${token}` }
-    );
+    const res = await del(this.http(), "/api/v1/auth-service/me", { Authorization: `Bearer ${token}` });
     if (!res || !res.ok) {
       throw new Error(`deleteAccount failed${res ? ` (HTTP ${res.status})` : " (network error)"}`);
     }
@@ -1705,183 +2273,592 @@ var Auth = class {
           graceDays: parsed.data.graceDays ?? 0
         };
       }
-    } catch {
+    } catch {
+    }
+    await this.commitAsync({ kind: "clear", reason: "account_deleted", suppressHeldAutoRestore: true });
+    const discardFailed = [];
+    if (opts?.alsoDiscardHeldGuests) {
+      for (let i = 0; i < HELD_SLOT_KEYS.length; i++) {
+        const slot = this.held[i];
+        if (!slot) continue;
+        try {
+          await this.discardSlot(i);
+        } catch {
+          discardFailed.push(slot.userId);
+        }
+      }
+    }
+    return { ...out, heldGuests: this.heldCount(), discardFailed };
+  }
+  // ============================================================
+  // OIDC / SAML SSO (sign-in continuation)
+  // ============================================================
+  /**
+   * 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).
+   */
+  async startSso(returnTo) {
+    const res = await post(this.http(), "/api/v1/auth-service/sso/oidc/start", { returnTo });
+    if (!res || !res.ok) throw new AuthError("SSO_START_FAILED", `HTTP ${res?.status ?? "network"}`);
+    const parsed = await res.json();
+    if (!parsed.success || !parsed.data?.authorizationUrl) {
+      throw new AuthError("SSO_START_FAILED", "Missing authorizationUrl");
+    }
+    return { authorizationUrl: parsed.data.authorizationUrl };
+  }
+  /** Kick off a SAML 2.0 SSO flow. Mirrors `startSso`; `consumeSsoFragment` handles both fragments. */
+  async startSaml(returnTo) {
+    const res = await post(this.http(), "/api/v1/auth-service/sso/saml/start", { returnTo });
+    if (!res || !res.ok) throw new AuthError("SAML_START_FAILED", `HTTP ${res?.status ?? "network"}`);
+    const parsed = await res.json();
+    if (!parsed.success || !parsed.data?.authorizationUrl) {
+      throw new AuthError("SAML_START_FAILED", "Missing authorizationUrl");
+    }
+    return { authorizationUrl: parsed.data.authorizationUrl };
+  }
+  /**
+   * 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) {
+    return this.serialize(async () => {
+      this.rejectIfWithheld("consumeSsoFragment");
+      await this.awaitSettled();
+      const hashIdx = callbackUrl.indexOf("#");
+      const fragment = hashIdx >= 0 ? callbackUrl.slice(hashIdx + 1) : "";
+      const params = new URLSearchParams(fragment);
+      const err = params.get("sendora_oidc_error") ?? params.get("sendora_saml_error");
+      if (err) throw new AuthError("SSO_FAILED", decodeURIComponent(err));
+      const refresh = params.get("sendora_oidc_token") ?? params.get("sendora_saml_token");
+      if (!refresh) throw new AuthError("SSO_NO_TOKEN", "Callback URL has no SSO token");
+      const retiredAnonUserId = params.get("sendora_retired_anon");
+      const expect = this.snapshotIdentity();
+      this.attempt = { kind: "sign_in", expect };
+      try {
+        await this.awaitRefreshQuiet();
+        const res = await post(this.http(), REFRESH_PATH, { refreshToken: refresh });
+        if (!res || !res.ok) throw new AuthError("SSO_EXCHANGE_FAILED", `HTTP ${res?.status ?? "network"}`, { status: res?.status });
+        const parsed = await res.json();
+        const rotated = parsed.success ? readRotatedTokens(parsed.data) : null;
+        if (!rotated) {
+          throw new AuthError("SSO_EXCHANGE_FAILED", "Could not exchange OIDC token", { status: res.status });
+        }
+        const d = parsed.data;
+        const user = isAuthUserShape(d?.user) ? d.user : this.userFromClaims(rotated.accessToken);
+        const data = {
+          user,
+          tokens: { accessToken: rotated.accessToken, refreshToken: rotated.refreshToken, expiresIn: rotated.expiresIn, tokenType: "Bearer" },
+          ...retiredAnonUserId ? { retiredAnonUserId } : {}
+        };
+        await this.awaitRefreshQuiet();
+        this.installSignIn(data, expect);
+        return user;
+      } finally {
+        this.attempt = null;
+      }
+    });
+  }
+  /** Populate a user object from access-token claims when a response carries none (pre-B17 `/token/refresh`). */
+  userFromClaims(access) {
+    const claims = decodeJwtPayload(access);
+    return {
+      id: typeof claims?.sub === "string" ? claims.sub : "",
+      email: typeof claims?.email === "string" ? claims.email : null,
+      emailVerified: typeof claims?.email_verified === "boolean" ? claims.email_verified : true,
+      name: typeof claims?.name === "string" ? claims.name : null,
+      isAnonymous: claims?.is_anonymous === true,
+      ...claims && Object.prototype.hasOwnProperty.call(claims, "project") ? { project: typeof claims.project === "string" ? claims.project : null } : {}
+    };
+  }
+  /**
+   * 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.
+   */
+  async bearerHeaders() {
+    const accessToken = await this.getAccessToken();
+    if (!accessToken) {
+      throw new AuthError("NOT_SIGNED_IN", "Not signed in");
+    }
+    return { Authorization: `Bearer ${accessToken}` };
+  }
+  async unwrap(res, errCode) {
+    if (!res) throw new AuthError("NETWORK_ERROR", "Network request failed");
+    const parsed = await res.json().catch(() => ({}));
+    if (!res.ok || !parsed.success) {
+      throw new AuthError(parsed.error?.code ?? errCode, parsed.error?.message ?? `HTTP ${res.status}`, {
+        status: res.status,
+        retryAfterSeconds: readRetryAfterSeconds(parsed)
+      });
+    }
+    return parsed.data;
+  }
+  // ============================================================
+  // SIGN OUT (ADR-033 §3.3 row 27) — local-first, the one deliberate exception
+  // ============================================================
+  /**
+   * 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() {
+    return this.serialize(async () => {
+      if (this.withheld) {
+        this.commit({ kind: "discard_withheld" });
+        return;
+      }
+      await this.commitAsync({ kind: "clear", reason: "user" });
+    });
+  }
+  // ============================================================
+  // DEPRECATED, kept callable
+  // ============================================================
+  /**
+   * @deprecated Transfer every event + trait from an anonymous user to the
+   * currently-signed-in (target) user, then delete the anonymous row.
+   *
+   * 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`.
+   */
+  async merge(anonymousRefreshToken, targetRefreshToken) {
+    const i = this.held.findIndex((h) => h !== null && (h.refreshToken === anonymousRefreshToken || h.tokenAtHold === anonymousRefreshToken));
+    if (i !== -1 && targetRefreshToken === void 0) {
+      const claimed = await this.claimHeldGuest(this.held[i].userId);
+      return claimed.stats;
+    }
+    const target = targetRefreshToken ?? this.getRefreshToken();
+    if (!target) {
+      throw new AuthError(
+        "NO_TARGET_REFRESH",
+        "merge() needs a target refresh token. Call signIn() first or pass targetRefreshToken explicitly."
+      );
+    }
+    const merged = await this.postMerge(anonymousRefreshToken, target);
+    const user = this.user;
+    if (user && this.hooks.storage.get(REFRESH_KEY) === target) {
+      await this.awaitRefreshQuiet();
+      this.commit({
+        kind: "install",
+        reason: "claim",
+        record: { user, accessToken: merged.tokens.accessToken, refreshToken: merged.tokens.refreshToken, expiresIn: merged.tokens.expiresIn },
+        expect: this.snapshotIdentity(),
+        expectRefresh: target,
+        silent: true
+      });
+    }
+    return merged.stats;
+  }
+  /** `POST /merge` — bypasses `callAuth`'s `isAuthApiResponse` gate (`/merge` returns `{ ...stats, tokens, csrfToken }`, no `user`). */
+  async postMerge(anonymousRefreshToken, targetRefreshToken) {
+    const res = await post(this.http(), "/api/v1/auth-service/merge", { anonymousRefreshToken, targetRefreshToken });
+    if (!res) throw new AuthError("NETWORK_ERROR", "Network request failed");
+    let parsed;
+    try {
+      parsed = await res.json();
+    } catch {
+      throw new AuthError("PARSE_ERROR", `HTTP ${res.status}`, { status: res.status });
+    }
+    if (!res.ok || !parsed.success || !parsed.data) {
+      throw new AuthError(
+        parsed.error?.code ?? `HTTP_${res.status}`,
+        parsed.error?.message ?? `HTTP ${res.status}`,
+        { status: res.status, retryAfterSeconds: readRetryAfterSeconds(parsed) }
+      );
+    }
+    const tokens = readRotatedTokens({ tokens: parsed.data.tokens });
+    if (!tokens) throw new AuthError("MERGE_FAILED", "merge response carried no rotated token pair", { status: res.status });
+    const d = parsed.data;
+    return {
+      tokens,
+      stats: {
+        mergedUserId: d.mergedUserId ?? "",
+        deletedAnonymousId: d.deletedAnonymousId ?? "",
+        eventsReassigned: d.eventsReassigned ?? 0,
+        profilesReassigned: d.profilesReassigned ?? 0,
+        profilesDropped: d.profilesDropped ?? 0,
+        entitiesReassigned: d.entitiesReassigned ?? 0,
+        entitiesDropped: d.entitiesDropped ?? 0
+      }
+    };
+  }
+  // ============================================================
+  // INTERNALS — attempts, settling, refresh, cron
+  // ============================================================
+  http() {
+    return { apiUrl: this.hooks.apiUrl, publicKey: this.hooks.publicKey, debug: this.hooks.debug };
+  }
+  /** ADR-033 [2c]: in `withheld` every verb in REJECTED_IN_WITHHELD rejects with no network and no write. */
+  rejectIfWithheld(verb) {
+    if (this.withheld) {
+      throw withheldError(
+        "SESSION_WITHHELD",
+        `${verb}() is unavailable while the stored session is withheld (its project claim disagrees with init({expectedProjectId})). Call discardWithheld() or relaunch with the matching project.`
+      );
+    }
+  }
+  /** True in `anonymous` / `identified` — a live session a LINK can attach to. */
+  hasSession() {
+    const s = this.status();
+    return s === "anonymous" || s === "identified";
+  }
+  serialize(op) {
+    const guarded = async () => {
+      await this.readyPromise;
+      try {
+        return await op();
+      } catch (err) {
+        throw asAuthError(err);
+      }
+    };
+    const next = this.inflight.then(guarded, guarded);
+    this.inflight = next.catch(() => void 0);
+    return next;
+  }
+  /**
+   * 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.
+   */
+  async awaitSettled() {
+    await this.readyPromise;
+    while (!this.withheld && this.status() === "unknown") {
+      await this.refreshAccessToken();
+      if (this.withheld || this.status() !== "unknown") break;
+      const wait = Math.min(3e4, Math.max(100, this.refreshCooldownUntil - Date.now()));
+      await new Promise((r) => setTimeout(r, wait));
+    }
+    if (this.withheld) this.rejectIfWithheld("auth");
+  }
+  /** An identity-changing attempt awaits any in-flight refresh at start AND at commit (ADR-033 §3.3 scheduling rule 1). */
+  async awaitRefreshQuiet() {
+    while (this.refreshInflight) {
+      await this.refreshInflight.catch(() => void 0);
+    }
+  }
+  snapshotIdentity() {
+    if (!this.hooks.storage.get(REFRESH_KEY) || !this.user) return { sub: null, sid: null };
+    const claims = decodeJwtPayload(this.accessToken);
+    return { sub: this.user.id, sid: typeof claims?.sid === "string" ? claims.sid : null };
+  }
+  /** The identity CAS (INV-2): `sid` when both sides know it, else the `sub`; a signed-out side never matches a live one. */
+  identityMatches(expect) {
+    const cur = this.snapshotIdentity();
+    if (expect.sub !== cur.sub) return false;
+    if (expect.sid !== null && cur.sid !== null) return expect.sid === cur.sid;
+    return true;
+  }
+  /** The current session's JWT `project` claim (string | null), or undefined when unreadable. */
+  claimProject(accessToken) {
+    const claims = decodeJwtPayload(accessToken);
+    if (!claims || !Object.prototype.hasOwnProperty.call(claims, "project")) return void 0;
+    const p = claims.project;
+    return typeof p === "string" ? p : null;
+  }
+  /**
+   * 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`.
+   */
+  verdictFor(user, accessToken) {
+    const expected = this.hooks.expectedProjectId;
+    if (expected === void 0) return "match";
+    const v = projectVerdict(expected, accessToken);
+    if (v !== "unknown") return v;
+    if (user.project !== void 0) {
+      if (user.project === null) return "mismatch";
+      return user.project === expected ? "match" : "mismatch";
+    }
+    return "unknown";
+  }
+  heldCount() {
+    return this.held.reduce((n, h) => n + (h ? 1 : 0), 0);
+  }
+  heldSorted() {
+    return this.held.filter((h) => h !== null).sort((a, b) => b.heldAt - a.heldAt);
+  }
+  /** Slot indices eligible for auto-restore, newest first (ADR-033 §3.3 "eligible"). */
+  eligibleHeldSlots() {
+    const expected = this.hooks.expectedProjectId ?? this.hooks.projectId;
+    return this.held.map((h, i) => ({ h, i })).filter(({ h }) => h !== null && h.autoRestore !== false && !(expected !== void 0 && h.project !== null && h.project !== expected)).sort((a, b) => b.h.heldAt - a.h.heldAt).map(({ i }) => i);
+  }
+  freeSlotIndex() {
+    return this.held.findIndex((h) => h === null);
+  }
+  /** The `id` rule shared by claim / restore / discard: omit it ONLY when exactly one guest is held. */
+  resolveSlot(id) {
+    const present = this.held.map((h, i2) => h ? i2 : -1).filter((i2) => i2 !== -1);
+    if (id === void 0) {
+      if (present.length === 1) return present[0];
+      if (present.length === 0) throw new AuthError("NO_HELD_GUEST", "No guest is held on this device", { kind: "unknown" });
+      throw new AuthError(AMBIGUOUS_HELD_GUEST, `${present.length} guests are held on this device; pass the userId of the one you mean`, { kind: "unknown" });
+    }
+    const i = this.held.findIndex((h) => h?.userId === id);
+    if (i === -1) throw new AuthError("HELD_GUEST_NOT_FOUND", `No held guest with userId ${id}`, { kind: "unknown" });
+    return i;
+  }
+  // ── SIGN_IN row implementation ───────────────────────────────────────────
+  async doSignInDone(credential) {
+    const r = await this.doSignIn(credential);
+    if (r.kind === "mfa") {
+      throw new AuthError("MFA_REQUIRED", "Multi-factor authentication is required; call challengeMfa(mfaChallengeToken, code)", { kind: "invalid_credential" });
+    }
+    return r;
+  }
+  /**
+   * 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.
+   */
+  async doSignIn(credential) {
+    if (this.status() === "anonymous" && this.freeSlotIndex() === -1) throw new HeldGuestLimitError();
+    this.attempt = { kind: "sign_in", expect: this.snapshotIdentity() };
+    try {
+      await this.awaitRefreshQuiet();
+      const expect = this.snapshotIdentity();
+      this.attempt = { kind: "sign_in", expect };
+      const prev = this.user ? { userId: this.user.id, isAnonymous: this.user.isAnonymous } : null;
+      const { path, body } = signInWire(credential);
+      const res = await post(this.http(), path, body);
+      if (!res) throw new AuthError("NETWORK_ERROR", "Network request failed");
+      let parsed;
+      try {
+        parsed = await res.json();
+      } catch {
+        throw new AuthError("PARSE_ERROR", `HTTP ${res.status}`, { status: res.status });
+      }
+      if (!res.ok || !parsed.success || !parsed.data) {
+        if (parsed.error?.code === "CREDENTIAL_IN_USE") {
+          throw new CredentialInUseError(parsed.error.message, { ...readCollisionDetails(parsed), status: res.status });
+        }
+        throw new AuthError(
+          parsed.error?.code ?? `HTTP_${res.status}`,
+          parsed.error?.message ?? `HTTP ${res.status}`,
+          { status: res.status, retryAfterSeconds: readRetryAfterSeconds(parsed) }
+        );
+      }
+      const r = parsed.data;
+      if (r.mfaRequired === true && typeof r.mfaChallengeToken === "string") {
+        const u = r.user;
+        return { kind: "mfa", challengeToken: r.mfaChallengeToken, userId: typeof u?.id === "string" ? u.id : "" };
+      }
+      if (!isAuthApiResponse(parsed.data)) {
+        throw new AuthError(parsed.error?.code ?? "AUTH_ERROR", parsed.error?.message ?? "Sign-in failed");
+      }
+      const data = parsed.data;
+      await this.awaitRefreshQuiet();
+      const { held } = this.installSignIn(data, expect);
+      return {
+        kind: "done",
+        user: data.user,
+        previous: prev ? { ...prev, held } : null,
+        reactivated: data.reactivatedFromDeletion === true
+      };
+    } finally {
+      this.attempt = null;
     }
-    await this.wipeLocalIdentity("account_deleted");
-    return out;
   }
-  // ============================================================
-  // OIDC SSO
-  // ============================================================
-  /**
-   * 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.
-   */
-  async startSso(returnTo) {
-    const prevAnonRefreshToken = this.readPrevAnonRefreshToken();
-    const body = { returnTo };
-    if (prevAnonRefreshToken) body.prevAnonRefreshToken = prevAnonRefreshToken;
-    const res = await post(
-      { apiUrl: this.hooks.apiUrl, publicKey: this.hooks.publicKey, debug: this.hooks.debug },
-      "/api/v1/auth-service/sso/oidc/start",
-      body
-    );
-    if (!res || !res.ok) throw new AuthError("SSO_START_FAILED", `HTTP ${res?.status ?? "network"}`);
-    const parsed = await res.json();
-    if (!parsed.success || !parsed.data?.authorizationUrl) {
-      throw new AuthError("SSO_START_FAILED", "Missing authorizationUrl");
+  /** 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). */
+  installSignIn(data, expect) {
+    const outcome = this.commit({
+      kind: "install",
+      reason: "sign_in",
+      record: { user: data.user, accessToken: data.tokens.accessToken, refreshToken: data.tokens.refreshToken, expiresIn: data.tokens.expiresIn },
+      expect,
+      holdPrevious: true,
+      response: data
+    });
+    if (outcome.status === "project_mismatch") {
+      this.revokeFireAndForget(data.tokens.refreshToken);
+      throw withheldError("PROJECT_MISMATCH", "The signed-in session belongs to a different project than init({expectedProjectId}); nothing was installed");
     }
-    return { authorizationUrl: parsed.data.authorizationUrl };
+    if (outcome.status === "cas_mismatch" || outcome.status === "held_limit") {
+      this.revokeFireAndForget(data.tokens.refreshToken);
+      if (outcome.status === "held_limit") throw new HeldGuestLimitError();
+      throw new AuthError("ATTEMPT_SUPERSEDED", "The session changed while the sign-in was in flight; nothing was installed", { kind: "unknown" });
+    }
+    return { held: outcome.status === "applied" && outcome.held };
   }
+  // ── LINK row implementation ──────────────────────────────────────────────
   /**
-   * 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.
+   * 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.
    */
-  async startSaml(returnTo) {
-    const prevAnonRefreshToken = this.readPrevAnonRefreshToken();
-    const body = { returnTo };
-    if (prevAnonRefreshToken) body.prevAnonRefreshToken = prevAnonRefreshToken;
-    const res = await post(
-      { apiUrl: this.hooks.apiUrl, publicKey: this.hooks.publicKey, debug: this.hooks.debug },
-      "/api/v1/auth-service/sso/saml/start",
-      body
-    );
-    if (!res || !res.ok) throw new AuthError("SAML_START_FAILED", `HTTP ${res?.status ?? "network"}`);
-    const parsed = await res.json();
-    if (!parsed.success || !parsed.data?.authorizationUrl) {
-      throw new AuthError("SAML_START_FAILED", "Missing authorizationUrl");
+  async doLink(path, body, ctx) {
+    this.attempt = { kind: "link", expect: this.snapshotIdentity() };
+    try {
+      await this.awaitRefreshQuiet();
+      const expect = this.snapshotIdentity();
+      this.attempt = { kind: "link", expect };
+      const token = await this.getAccessToken();
+      if (!token) throw new AuthError("NOT_SIGNED_IN", "Sign in before linking a credential");
+      const res = await post(this.http(), path, body, { Authorization: `Bearer ${token}` });
+      if (!res) throw new AuthError("NETWORK_ERROR", "Network request failed");
+      let parsed;
+      try {
+        parsed = await res.json();
+      } catch {
+        throw new AuthError("PARSE_ERROR", `HTTP ${res.status}`, { status: res.status });
+      }
+      if (!res.ok || !parsed.success || !parsed.data) {
+        const code = parsed.error?.code ?? `HTTP_${res.status}`;
+        if (code === "CREDENTIAL_IN_USE") {
+          const details = readCollisionDetails(parsed);
+          return {
+            status: "credential_in_use",
+            provider: details.provider ?? ctx.label,
+            collision: details.collision ?? (path === LINK_EMAIL_PATH ? "email" : "identity"),
+            message: parsed.error?.message ?? "This credential is already linked to a different account",
+            httpStatus: res.status
+          };
+        }
+        if (code === "RECENT_AUTH_REQUIRED") {
+          return { status: "recent_auth_required", message: parsed.error?.message ?? "Re-authenticate before changing credentials" };
+        }
+        throw new AuthError(code, parsed.error?.message ?? "Failed to link credential", {
+          status: res.status,
+          retryAfterSeconds: readRetryAfterSeconds(parsed)
+        });
+      }
+      const d = parsed.data;
+      const alreadyLinked = d.alreadyLinked === true;
+      await this.awaitRefreshQuiet();
+      if (d.upgraded === true && isAuthApiResponse(d)) {
+        const outcome = this.commit({
+          kind: "install",
+          reason: "upgrade",
+          record: { user: d.user, accessToken: d.tokens.accessToken, refreshToken: d.tokens.refreshToken, expiresIn: d.tokens.expiresIn },
+          expect,
+          legacyEmit: ctx.legacyEmit,
+          response: d
+        });
+        if (outcome.status === "project_mismatch") {
+          this.revokeFireAndForget(d.tokens.refreshToken);
+          throw withheldError("PROJECT_MISMATCH", "The promoted session belongs to a different project than init({expectedProjectId}); nothing was installed");
+        }
+        if (outcome.status !== "applied") {
+          this.revokeFireAndForget(d.tokens.refreshToken);
+          throw new AuthError("ATTEMPT_SUPERSEDED", "The session changed while the link was in flight; nothing was installed", { kind: "unknown" });
+        }
+        return { status: "done", user: d.user, upgraded: true, alreadyLinked };
+      }
+      if (isAuthUserShape(d.user) && !alreadyLinked) {
+        const outcome = this.commit({ kind: "user", reason: "link", user: d.user, expect });
+        if (outcome.status !== "applied") {
+          throw new AuthError("ATTEMPT_SUPERSEDED", "The session changed while the link was in flight", { kind: "unknown" });
+        }
+        return { status: "done", user: d.user, upgraded: false, alreadyLinked: false };
+      }
+      const user = this.user ?? (isAuthUserShape(d.user) ? d.user : null);
+      if (!user) throw new AuthError("NOT_SIGNED_IN", "The session ended while the link was in flight");
+      return { status: "done", user, upgraded: false, alreadyLinked };
+    } finally {
+      this.attempt = null;
     }
-    return { authorizationUrl: parsed.data.authorizationUrl };
   }
+  // ── Held-token refresh (REFRESH_OK/DEAD routed to a slot, rows 22 + 25) ──
   /**
-   * 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.
+   * 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`).
    */
-  consumeSsoFragment(callbackUrl) {
-    return this.serialize(async () => {
-      const hashIdx = callbackUrl.indexOf("#");
-      const fragment = hashIdx >= 0 ? callbackUrl.slice(hashIdx + 1) : "";
-      const params = new URLSearchParams(fragment);
-      const err = params.get("sendora_oidc_error") ?? params.get("sendora_saml_error");
-      if (err) throw new AuthError("SSO_FAILED", decodeURIComponent(err));
-      const refresh = params.get("sendora_oidc_token") ?? params.get("sendora_saml_token");
-      if (!refresh) throw new AuthError("SSO_NO_TOKEN", "Callback URL has no SSO token");
-      const retiredAnonUserId = params.get("sendora_retired_anon");
-      const res = await post(
-        { apiUrl: this.hooks.apiUrl, publicKey: this.hooks.publicKey, debug: this.hooks.debug },
-        "/api/v1/auth-service/token/refresh",
-        { refreshToken: refresh }
-      );
-      if (!res || !res.ok) throw new AuthError("SSO_EXCHANGE_FAILED", `HTTP ${res?.status ?? "network"}`, { status: res?.status });
-      const parsed = await res.json();
-      const rotated = parsed.success ? readRotatedTokens(parsed.data) : null;
-      if (!rotated) {
-        throw new AuthError("SSO_EXCHANGE_FAILED", "Could not exchange OIDC token", { status: res.status });
-      }
-      const { accessToken: access, refreshToken: newRefresh, expiresIn } = rotated;
-      const claims = decodeJwtPayload(access);
-      const user = {
-        id: claims?.sub ?? "",
-        email: claims?.email ?? null,
-        emailVerified: claims?.email_verified ?? true,
-        name: claims?.name ?? null,
-        isAnonymous: false
-      };
-      if (this.user !== null) await this.wipeLocalIdentity("replaced");
-      this.persist({
-        user,
-        tokens: {
-          accessToken: access,
-          refreshToken: newRefresh,
-          expiresIn,
-          tokenType: "Bearer"
-        },
-        ...retiredAnonUserId ? { retiredAnonUserId } : {}
-      });
-      return user;
-    });
-  }
-  bearerHeaders() {
-    if (!this.accessToken) {
-      throw new AuthError("NOT_SIGNED_IN", "Not signed in");
-    }
-    return { Authorization: `Bearer ${this.accessToken}` };
-  }
-  async unwrap(res, errCode) {
+  async refreshHeld(i) {
+    const slot = this.held[i];
+    if (!slot) return { outcome: "dead" };
+    const sent = slot.refreshToken;
+    const res = await post(this.http(), REFRESH_PATH, { refreshToken: sent });
     if (!res) throw new AuthError("NETWORK_ERROR", "Network request failed");
-    const parsed = await res.json().catch(() => ({}));
+    let parsed;
+    try {
+      parsed = await res.json();
+    } catch {
+      throw new AuthError("PARSE_ERROR", `HTTP ${res.status}`, { status: res.status });
+    }
     if (!res.ok || !parsed.success) {
-      throw new AuthError(parsed.error?.code ?? errCode, parsed.error?.message ?? `HTTP ${res.status}`, {
-        status: res.status,
-        retryAfterSeconds: readRetryAfterSeconds(parsed)
-      });
+      const code = parsed.error?.code ?? `HTTP_${res.status}`;
+      if (isDeadRefreshError(code)) {
+        const endReason = readEndReason(parsed);
+        if (endReason !== void 0 && RELEASE_HELD_ON_END_REASONS.includes(endReason)) {
+          this.commit({ kind: "release", reason: "dead", slot: i, userId: slot.userId, endReason });
+          return { outcome: "dead" };
+        }
+        return { outcome: "kept" };
+      }
+      throw new AuthError(code, parsed.error?.message ?? `HTTP ${res.status}`, { status: res.status, retryAfterSeconds: readRetryAfterSeconds(parsed) });
     }
-    return parsed.data;
+    const rotated = readRotatedTokens(parsed.data);
+    if (!rotated) throw new AuthError("PARSE_ERROR", "refresh response carried no token pair", { status: res.status });
+    const d = parsed.data;
+    const user = isAuthUserShape(d?.user) ? d.user : { ...this.userFromClaims(rotated.accessToken), id: slot.userId, isAnonymous: true };
+    const persisted = this.commit({ kind: "slot_tokens", slot: i, sent, refreshToken: rotated.refreshToken });
+    if (persisted.status !== "applied") return { outcome: "kept" };
+    return {
+      outcome: "ok",
+      data: { user, tokens: { accessToken: rotated.accessToken, refreshToken: rotated.refreshToken, expiresIn: rotated.expiresIn, tokenType: "Bearer" } }
+    };
   }
-  /**
-   * 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.
-   */
-  signOut() {
-    return this.serialize(async () => {
-      const refresh = this.hooks.storage.get(REFRESH_KEY);
-      await this.wipeLocalIdentity("user");
-      if (refresh) {
-        void post(
-          { apiUrl: this.hooks.apiUrl, publicKey: this.hooks.publicKey, debug: this.hooks.debug },
-          "/api/v1/auth-service/token/revoke",
-          { refreshToken: refresh }
-        ).catch(() => void 0);
-      }
+  /** The RESTORE row's install half: ProjectGuard on the refresh response, install BEFORE releasing the slot. */
+  installRestored(i, data, expect) {
+    const slot = this.held[i];
+    const verdict = this.verdictFor(data.user, data.tokens.accessToken);
+    if (verdict === "mismatch") {
+      const actual = this.claimProject(data.tokens.accessToken) ?? data.user.project ?? null;
+      this.commit({ kind: "slot_project", slot: i, project: actual });
+      throw new HeldGuestProjectMismatch(slot.userId, this.hooks.expectedProjectId ?? this.hooks.projectId ?? "", actual);
+    }
+    const outcome = this.commit({
+      kind: "install",
+      reason: "restore",
+      record: { user: data.user, accessToken: data.tokens.accessToken, refreshToken: data.tokens.refreshToken, expiresIn: data.tokens.expiresIn },
+      expect,
+      holdPrevious: true,
+      response: data
     });
+    if (outcome.status === "held_limit") throw new HeldGuestLimitError();
+    if (outcome.status !== "applied") {
+      throw new AuthError("ATTEMPT_SUPERSEDED", "The session changed while the restore was in flight; nothing was installed", { kind: "unknown" });
+    }
+    this.commit({ kind: "release", reason: "restored", slot: i, userId: slot.userId });
+    return data.user;
   }
-  // --- internals ---
-  serialize(op) {
-    const guarded = async () => {
-      await this.readyPromise;
-      try {
-        return await op();
-      } catch (err) {
-        throw asAuthError(err);
-      }
-    };
-    const next = this.inflight.then(guarded, guarded);
-    this.inflight = next.catch(() => void 0);
-    return next;
-  }
+  // ── Current-token refresh (rows 20–26) ───────────────────────────────────
   /**
-   * 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.
+   * 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.
    *
-   * 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.
+   * 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).
    */
   async refreshAccessToken() {
     if (this.refreshInflight) return this.refreshInflight;
+    if (this.withheld) return null;
     const refreshSnapshot = this.hooks.storage.get(REFRESH_KEY);
     if (!refreshSnapshot) return null;
     this.refreshInflight = (async () => {
@@ -1903,27 +2880,64 @@ var Auth = class {
           }
         }
         sent = current ?? refreshSnapshot;
-        const data = await this.callAuth("/api/v1/auth-service/token/refresh", {
-          refreshToken: sent
-        });
-        if (!this.tokenStillCurrent(sent)) return null;
-        this.accessToken = data.tokens.accessToken;
-        this.accessExpiresAt = Date.now() + data.tokens.expiresIn * 1e3;
-        this.hooks.storage.set(TOKEN_KEY, data.tokens.accessToken);
-        this.hooks.storage.set(TOKEN_EXPIRES_KEY, String(this.accessExpiresAt));
-        this.hooks.storage.set(REFRESH_KEY, data.tokens.refreshToken);
-        if (this.user === null && isAuthApiResponse(data)) {
-          this.user = data.user;
-          this.hooks.storage.set(USER_KEY, JSON.stringify(data.user));
-          this.hooks.onIdentityChange(data.user.id);
-          this.emitAuthState({ event: "signed_in", user: data.user });
+        const res = await post(this.http(), REFRESH_PATH, { refreshToken: sent });
+        if (!res) throw new AuthError("NETWORK_ERROR", "Network request failed");
+        let parsed;
+        try {
+          parsed = await res.json();
+        } catch {
+          throw new AuthError("PARSE_ERROR", `HTTP ${res.status}`, { status: res.status });
+        }
+        if (!res.ok || !parsed.success) {
+          throw new AuthError(parsed.error?.code ?? `HTTP_${res.status}`, parsed.error?.message ?? `HTTP ${res.status}`, {
+            status: res.status,
+            retryAfterSeconds: readRetryAfterSeconds(parsed),
+            endReason: readEndReason(parsed)
+          });
+        }
+        const rotated = readRotatedTokens(parsed.data);
+        if (!rotated) throw new AuthError("PARSE_ERROR", "refresh response carried no token pair", { status: res.status });
+        const d = parsed.data;
+        const responseUser = isAuthUserShape(d?.user) ? d.user : null;
+        if (this.hooks.storage.get(REFRESH_KEY) === sent) {
+          const user = responseUser ?? this.user;
+          if (!user) {
+            this.commit({ kind: "tokens", sent, accessToken: rotated.accessToken, refreshToken: rotated.refreshToken, expiresIn: rotated.expiresIn });
+          } else {
+            const verdict = this.verdictFor(user, rotated.accessToken);
+            if (verdict === "mismatch") {
+              this.commit({ kind: "withhold", user, sent, accessToken: rotated.accessToken, refreshToken: rotated.refreshToken, expiresIn: rotated.expiresIn });
+              this.refreshFailureCount = 0;
+              this.refreshCooldownUntil = 0;
+              return null;
+            }
+            this.commit({
+              kind: "install",
+              reason: "refresh",
+              record: { user, accessToken: rotated.accessToken, refreshToken: rotated.refreshToken, expiresIn: rotated.expiresIn },
+              expectRefresh: sent
+            });
+          }
+        } else {
+          const i = this.held.findIndex((h) => h?.refreshToken === sent);
+          if (i !== -1) this.commit({ kind: "slot_tokens", slot: i, sent, refreshToken: rotated.refreshToken });
+          this.refreshFailureCount = 0;
+          this.refreshCooldownUntil = 0;
+          return null;
         }
         this.refreshFailureCount = 0;
         this.refreshCooldownUntil = 0;
-        return data.tokens.accessToken;
+        return rotated.accessToken;
       } catch (err) {
-        if (err instanceof AuthError && isDeadRefreshError(err.code) && this.tokenStillCurrent(sent)) {
-          await this.wipeLocalIdentity("session_expired").catch(() => void 0);
+        if (err instanceof AuthError && isDeadRefreshError(err.code)) {
+          if (this.hooks.storage.get(REFRESH_KEY) === sent) {
+            await this.commitAsync({ kind: "clear", reason: signedOutReasonFor(err.endReason), expectRefresh: sent });
+          } else {
+            const i = this.held.findIndex((h) => h?.refreshToken === sent);
+            if (i !== -1 && err.endReason !== void 0 && RELEASE_HELD_ON_END_REASONS.includes(err.endReason)) {
+              this.commit({ kind: "release", reason: "dead", slot: i, userId: this.held[i].userId, endReason: err.endReason });
+            }
+          }
           this.refreshFailureCount = 0;
           this.refreshCooldownUntil = 0;
           return null;
@@ -1938,16 +2952,7 @@ var Auth = class {
     })();
     return this.refreshInflight;
   }
-  /**
-   * 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.
-   */
+  /** Wave 62 — AppState resume hook: clear stuck backoff so a returning user gets an immediate attempt. */
   resetRefreshState() {
     this.refreshFailureCount = 0;
     this.refreshCooldownUntil = 0;
@@ -1958,9 +2963,11 @@ var Auth = class {
     const TICK_MS = 6e4;
     const JITTER_MS = 3e4;
     const tick = async () => {
-      if (!this.accessToken || !this.accessExpiresAt) return;
+      if (this.attempt || this.withheld) return;
+      if (!this.hooks.storage.get(REFRESH_KEY)) return;
       const now = Date.now();
-      if (!this.canServeCachedToken(now)) {
+      if (!this.user || !this.accessToken || !this.accessExpiresAt || !this.canServeCachedToken(now)) {
+        if (now < this.refreshCooldownUntil) return;
         await this.refreshAndReconcile(now);
         return;
       }
@@ -1998,82 +3005,34 @@ var Auth = class {
       this.proactiveRefreshAppStateUnsub = null;
     }
   }
-  /**
-   * 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() {
-    return this.hooks.storage.get(REFRESH_KEY) ?? 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.
-   */
-  async merge(anonymousRefreshToken, targetRefreshToken) {
-    const target = targetRefreshToken ?? this.getRefreshToken();
-    if (!target) {
-      throw new AuthError(
-        "NO_TARGET_REFRESH",
-        "merge() needs a target refresh token. Call signIn() first or pass targetRefreshToken explicitly."
-      );
-    }
-    const res = await post(
-      { apiUrl: this.hooks.apiUrl, publicKey: this.hooks.publicKey, debug: this.hooks.debug },
-      "/api/v1/auth-service/merge",
-      { anonymousRefreshToken, targetRefreshToken: target }
-    );
-    if (!res) throw new AuthError("NETWORK_ERROR", "Network request failed");
-    let parsed;
-    try {
-      parsed = await res.json();
-    } catch {
-      throw new AuthError("PARSE_ERROR", `HTTP ${res.status}`, { status: res.status });
-    }
-    if (!res.ok || !parsed.success || !parsed.data) {
-      throw new AuthError(
-        parsed.error?.code ?? `HTTP_${res.status}`,
-        parsed.error?.message ?? `HTTP ${res.status}`,
-        { status: res.status, retryAfterSeconds: readRetryAfterSeconds(parsed) }
-      );
+  revokeFireAndForget(refreshToken) {
+    void post(this.http(), REVOKE_PATH, { refreshToken }).catch(() => void 0);
+  }
+  /** B15: report a held guest, fire-and-forget; the pending flag is cleared only on a 2xx and retried on hydrate. */
+  reportHeldFireAndForget(userId, refreshToken) {
+    void post(this.http(), "/api/v1/auth-service/guest/held", { refreshToken }).then((res) => {
+      if (res && res.ok) this.commit({ kind: "held_report", userId, pending: false });
+    }).catch(() => void 0);
+  }
+  retryPendingHeldReports() {
+    for (const userId of Array.from(this.heldReportsPending)) {
+      const slot = this.held.find((h) => h?.userId === userId);
+      if (!slot) {
+        this.commit({ kind: "held_report", userId, pending: false });
+        continue;
+      }
+      this.reportHeldFireAndForget(userId, slot.refreshToken);
     }
-    const t = parsed.data.tokens;
-    if (t?.accessToken && t.refreshToken && typeof t.expiresIn === "number") {
-      this.accessToken = t.accessToken;
-      this.accessExpiresAt = Date.now() + t.expiresIn * 1e3;
-      this.hooks.storage.set(TOKEN_KEY, t.accessToken);
-      this.hooks.storage.set(TOKEN_EXPIRES_KEY, String(this.accessExpiresAt));
-      this.hooks.storage.set(REFRESH_KEY, t.refreshToken);
+  }
+  /** `Sendora.reset({includeHeldGuests:true})`: release every slot locally (NO server delete), via commit. */
+  releaseAllHeldGuests() {
+    for (let i = 0; i < HELD_SLOT_KEYS.length; i++) {
+      const slot = this.held[i];
+      if (slot) this.commit({ kind: "release", reason: "reset", slot: i, userId: slot.userId });
     }
-    return {
-      mergedUserId: parsed.data.mergedUserId ?? "",
-      deletedAnonymousId: parsed.data.deletedAnonymousId ?? "",
-      eventsReassigned: parsed.data.eventsReassigned ?? 0,
-      profilesReassigned: parsed.data.profilesReassigned ?? 0,
-      profilesDropped: parsed.data.profilesDropped ?? 0,
-      entitiesReassigned: parsed.data.entitiesReassigned ?? 0,
-      entitiesDropped: parsed.data.entitiesDropped ?? 0
-    };
   }
   async callAuth(path, body) {
-    const res = await post(
-      { apiUrl: this.hooks.apiUrl, publicKey: this.hooks.publicKey, debug: this.hooks.debug },
-      path,
-      body
-    );
+    const res = await post(this.http(), path, body);
     if (!res) {
       throw new AuthError("NETWORK_ERROR", "Network request failed");
     }
@@ -2092,57 +3051,143 @@ var Auth = class {
     }
     return parsed.data;
   }
-  persist(data) {
-    this.user = data.user;
-    this.accessToken = data.tokens.accessToken;
-    this.accessExpiresAt = Date.now() + data.tokens.expiresIn * 1e3;
-    this.hooks.storage.set(USER_KEY, JSON.stringify(data.user));
-    this.hooks.storage.set(TOKEN_KEY, data.tokens.accessToken);
-    this.hooks.storage.set(TOKEN_EXPIRES_KEY, String(this.accessExpiresAt));
-    this.hooks.storage.set(REFRESH_KEY, data.tokens.refreshToken);
-    this.hooks.onIdentityChange(data.user.id);
+  // ============================================================
+  // commit() — THE ONLY WRITER (ADR-033 §3.3, INV-1)
+  // ============================================================
+  //
+  // Every assignment of `this.user` / `this.accessToken` / `this.accessExpiresAt`
+  // / `this.held` / `this.withheld`, every write of an auth storage key, every
+  // cron start/stop and every `onAuthStateChanged` emission happens inside this
+  // method or the private helpers only it calls. Public methods build a `Tx`
+  // and hand it over; the CAS and the ProjectGuard are applied HERE, not at
+  // the call sites, so no call site can forget them.
+  commit(tx) {
+    switch (tx.kind) {
+      case "install":
+        return this.commitInstall(tx);
+      case "clear":
+        return this.commitClear(tx);
+      case "user":
+        return this.commitUser(tx);
+      case "release":
+        return this.commitRelease(tx);
+      case "withhold":
+        return this.commitWithhold(tx);
+      case "discard_withheld":
+        return this.commitDiscardWithheld();
+      case "tokens":
+        return this.commitTokens(tx);
+      case "slot_tokens":
+        return this.commitSlotTokens(tx);
+      case "slot_project":
+        return this.commitSlotProject(tx);
+      case "held_report":
+        return this.commitHeldReport(tx);
+      default:
+        return { status: "dropped" };
+    }
+  }
+  /** `commit()` for the clear path, awaiting the parent's `onAnonymousWipe` hook before resolving (the emission has already fired). */
+  async commitAsync(tx) {
+    const result = this.commit(tx);
+    if (this.pendingWipeHook) {
+      const p = this.pendingWipeHook;
+      this.pendingWipeHook = null;
+      await p.catch(() => void 0);
+    }
+    return result;
+  }
+  commitInstall(tx) {
+    const { record } = tx;
+    if (tx.expect && !this.identityMatches(tx.expect)) return { status: "cas_mismatch" };
+    if (tx.expectRefresh !== void 0 && this.hooks.storage.get(REFRESH_KEY) !== tx.expectRefresh) return { status: "cas_mismatch" };
+    if (tx.reason !== "hydrate") {
+      const verdict = this.verdictFor(record.user, record.accessToken);
+      if (verdict === "mismatch") return { status: "project_mismatch" };
+    }
+    const prevUser = this.user;
+    const prevRefresh = this.hooks.storage.get(REFRESH_KEY);
+    let held = false;
+    if (tx.reason === "hydrate") {
+      this.user = record.user;
+      this.accessToken = record.accessToken || null;
+      this.accessExpiresAt = this.accessToken ? tx.accessExpiresAt ?? 0 : 0;
+      if (tx.writeForward) this.writeSessionRecordOnly(record.user, this.accessToken, this.accessExpiresAt, record.refreshToken);
+      this.hooks.onIdentityChange(record.user.id);
+      this.startProactiveRefreshCron();
+      return { status: "applied", held: false };
+    }
+    if (tx.holdPrevious && prevUser && prevRefresh && prevUser.isAnonymous && prevUser.id !== record.user.id) {
+      const free = this.freeSlotIndex();
+      if (free === -1) return { status: "held_limit" };
+      const slot = {
+        v: 1,
+        userId: prevUser.id,
+        sid: this.snapshotIdentity().sid ?? "",
+        refreshToken: prevRefresh,
+        tokenAtHold: prevRefresh,
+        // Strictly newer than every held slot: two holds in the same millisecond would otherwise tie,
+        // leaving "newest" (getHeldGuests() order, the auto-restore pick) undefined. Web found it as a
+        // 1-in-4 flake; same fix in all four SDKs (s58.356).
+        heldAt: Math.max(Date.now(), ...this.held.filter((h) => h !== null).map((h) => h.heldAt + 1)),
+        project: this.claimProject(this.accessToken) ?? (typeof prevUser.project === "string" ? prevUser.project : null),
+        autoRestore: true
+      };
+      this.writeSlot(free, slot);
+      this.heldReportsPending.add(prevUser.id);
+      held = true;
+      this.emitAuthState({ event: "guest_held", userId: prevUser.id, count: this.heldCount(), user: prevUser });
+    } else if (prevUser && prevRefresh && !prevUser.isAnonymous && prevUser.id !== record.user.id && (tx.reason === "sign_in" || tx.reason === "mint" || tx.reason === "restore")) {
+      this.revokeFireAndForget(prevRefresh);
+    }
+    const userChanged = !prevUser || JSON.stringify(prevUser) !== JSON.stringify(record.user);
+    this.user = record.user;
+    this.accessToken = record.accessToken;
+    this.accessExpiresAt = Date.now() + record.expiresIn * 1e3;
+    this.writeSessionRecord(record.user, record.accessToken, this.accessExpiresAt, record.refreshToken);
+    this.hooks.onIdentityChange(record.user.id);
     this.startProactiveRefreshCron();
-    this.emitAuthState({ event: "signed_in", user: data.user });
-    if (data.retiredAnonUserId) {
-      this.fireDeviceTakeover(data.retiredAnonUserId, data.user.id);
-      this.emitAuthState({
-        event: "device_takeover",
-        user: data.user,
-        retiredAnonUserId: data.retiredAnonUserId
-      });
+    switch (tx.reason) {
+      case "mint":
+        this.emitAuthState({ event: "signed_in", user: record.user, cause: "mint" });
+        break;
+      case "sign_in":
+        this.emitAuthState({ event: "signed_in", user: record.user, cause: "sign_in" });
+        break;
+      case "restore":
+        this.emitAuthState({ event: "signed_in", user: record.user, cause: "restore" });
+        break;
+      case "upgrade":
+        if (tx.legacyEmit) this.emitAuthState({ event: "signed_in", user: record.user, cause: "link" });
+        else this.emitAuthState({ event: "user_updated", user: record.user, cause: "link" });
+        break;
+      case "claim":
+        if (!tx.silent) this.emitAuthState({ event: "user_updated", user: record.user, cause: "merge" });
+        break;
+      case "refresh":
+      case "recover":
+        if (!prevUser) this.emitAuthState({ event: "signed_in", user: record.user });
+        else if (userChanged) this.emitAuthState({ event: "user_updated", user: record.user, cause: "refresh" });
+        break;
+      default:
+        break;
     }
-    if (data.anonRetirement) this.lastAnonRetirement = data.anonRetirement;
-    if (data.reactivatedFromDeletion) {
-      this.fireDeletionCancelled(data.user.id);
-      this.emitAuthState({ event: "deletion_cancelled", user: data.user });
+    const data = tx.response;
+    if (data?.retiredAnonUserId) {
+      this.fireDeviceTakeover(data.retiredAnonUserId, record.user.id);
+      this.emitAuthState({ event: "device_takeover", user: record.user, retiredAnonUserId: data.retiredAnonUserId });
     }
+    if (data?.anonRetirement) this.lastAnonRetirement = data.anonRetirement;
+    if (data?.reactivatedFromDeletion) {
+      this.fireDeletionCancelled(record.user.id);
+      this.emitAuthState({ event: "deletion_cancelled", user: record.user });
+    }
+    if (held && prevUser) this.reportHeldFireAndForget(prevUser.id, prevRefresh);
+    return { status: "applied", held };
   }
-  /**
-   * 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.
-   */
-  /**
-   * 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.
-   */
-  tokenStillCurrent(sent) {
-    return this.hooks.storage.get(REFRESH_KEY) === sent;
-  }
-  async wipeLocalIdentity(reason = "replaced") {
+  commitClear(tx) {
+    if (tx.expectRefresh !== void 0 && this.hooks.storage.get(REFRESH_KEY) !== tx.expectRefresh) return { status: "dropped" };
+    const prevRefresh = this.hooks.storage.get(REFRESH_KEY);
     this.user = null;
     this.accessToken = null;
     this.accessExpiresAt = 0;
@@ -2150,21 +3195,216 @@ var Auth = class {
     this.lastTakeover = null;
     this.lastDeletionCancelled = null;
     this.lastAnonRetirement = null;
-    this.pendingAnonTakeover = null;
-    this.hooks.storage.remove(USER_KEY);
-    this.hooks.storage.remove(TOKEN_KEY);
-    this.hooks.storage.remove(TOKEN_EXPIRES_KEY);
-    this.hooks.storage.remove(REFRESH_KEY);
+    this.clearSessionKeys();
+    this.stopProactiveRefreshCron();
+    if (tx.suppressHeldAutoRestore) {
+      for (let i = 0; i < HELD_SLOT_KEYS.length; i++) {
+        const slot = this.held[i];
+        if (slot && slot.autoRestore) this.writeSlot(i, { ...slot, autoRestore: false });
+      }
+    }
+    const reason = tx.reason;
+    if (reason === "stale_blob" || reason === "replaced") return { status: "applied", held: false };
+    if (reason === "user" && prevRefresh) this.revokeFireAndForget(prevRefresh);
+    this.pendingWipeHook = this.wipeLocalIdentity(reason);
+    this.emitAuthState({ event: "signed_out", user: null, reason });
+    return { status: "applied", held: false };
+  }
+  /**
+   * 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.
+   */
+  wipeLocalIdentity(reason) {
+    return this.hooks.onAnonymousWipe(reason);
+  }
+  commitUser(tx) {
+    if (tx.expect && !this.identityMatches(tx.expect)) return { status: "cas_mismatch" };
+    const refresh = this.hooks.storage.get(REFRESH_KEY);
+    if (!refresh) return { status: "dropped" };
+    this.user = tx.user;
+    this.writeSessionRecord(tx.user, this.accessToken, this.accessExpiresAt, refresh);
+    this.hooks.onIdentityChange(tx.user.id);
+    this.emitAuthState({ event: "user_updated", user: tx.user, cause: tx.reason });
+    return { status: "applied", held: false };
+  }
+  commitRelease(tx) {
+    const slot = this.held[tx.slot];
+    if (!slot) return { status: "dropped" };
+    this.writeSlot(tx.slot, null);
+    if (this.heldReportsPending.delete(tx.userId)) this.persistPendingReports();
+    const change = tx.endReason ? { event: "guest_released", userId: tx.userId, reason: tx.reason, endReason: tx.endReason } : { event: "guest_released", userId: tx.userId, reason: tx.reason };
+    this.emitAuthState(change);
+    return { status: "applied", held: false };
+  }
+  /** Row 21 — a refresh of the CURRENT token answered with a mismatching claim: persist the rotation (token CAS) and withhold. */
+  commitWithhold(tx) {
+    if (this.hooks.storage.get(REFRESH_KEY) !== tx.sent) return { status: "dropped" };
+    const expiresAt = Date.now() + tx.expiresIn * 1e3;
+    this.writeTokens(tx.accessToken, expiresAt, tx.refreshToken);
+    this.enterWithheld(tx.user, tx.accessToken, tx.refreshToken, true);
+    return { status: "withheld" };
+  }
+  /** Enter `withheld`: in-memory only (ZERO storage writes), no cron, analytics quarantined; emits `session_withheld` only for an in-process transition. */
+  enterWithheld(user, accessToken, refreshToken, emit = false) {
+    const expected = this.hooks.expectedProjectId ?? "";
+    const actual = this.claimProject(accessToken) ?? (user.project === void 0 ? null : user.project);
+    this.user = null;
+    this.accessToken = null;
+    this.accessExpiresAt = 0;
+    this.withheld = { reason: "project_mismatch", expectedProjectId: expected, actualProjectId: actual, userId: user.id, isAnonymous: user.isAnonymous === true };
+    this.withheldRefresh = refreshToken;
     this.stopProactiveRefreshCron();
-    await this.hooks.onAnonymousWipe(reason);
-    if (reason !== "replaced") {
-      this.emitAuthState({ event: "signed_out", user: null, reason });
+    try {
+      this.hooks.onIdentityWithheld?.(this.withheld);
+    } catch (err) {
+      if (this.hooks.debug) console.warn("[Sendora] onIdentityWithheld hook threw", err);
+    }
+    if (emit) {
+      this.emitAuthState({ event: "session_withheld", reason: "project_mismatch", expectedProjectId: expected, actualProjectId: actual, userId: user.id });
+    }
+  }
+  /** Row 14 — `discardWithheld()` / `signOut()` in `withheld`: LOCAL ONLY, keeps held slots + queue + `user_id`. */
+  commitDiscardWithheld() {
+    if (!this.withheld) return { status: "dropped" };
+    const onDisk = this.hooks.storage.get(REFRESH_KEY);
+    if (this.withheldRefresh !== null && onDisk !== null && onDisk !== this.withheldRefresh) return { status: "dropped" };
+    const refresh = onDisk ?? this.withheldRefresh;
+    this.clearSessionKeys();
+    this.withheld = null;
+    this.withheldRefresh = null;
+    if (refresh) this.revokeFireAndForget(refresh);
+    this.emitAuthState({ event: "signed_out", user: null, reason: "user" });
+    return { status: "applied", held: false };
+  }
+  /** A rotated pair for the current session when no user is known to install (pre-B17 gap-fill). Token CAS. */
+  commitTokens(tx) {
+    if (this.hooks.storage.get(REFRESH_KEY) !== tx.sent) return { status: "dropped" };
+    const expiresAt = Date.now() + tx.expiresIn * 1e3;
+    this.writeTokens(tx.accessToken, expiresAt, tx.refreshToken);
+    this.accessToken = tx.accessToken;
+    this.accessExpiresAt = expiresAt;
+    return { status: "applied", held: false };
+  }
+  /** Row 22 — CAS PER SLOT: re-read the slot at write time; if it no longer holds `sent`, DROP. */
+  commitSlotTokens(tx) {
+    const onDisk = this.readSlot(tx.slot);
+    if (!onDisk || onDisk.refreshToken !== tx.sent) return { status: "dropped" };
+    this.writeSlot(tx.slot, { ...onDisk, refreshToken: tx.refreshToken });
+    return { status: "applied", held: false };
+  }
+  /** RESTORE row: a `null` slot project judged on the refresh response records the claim it saw. */
+  commitSlotProject(tx) {
+    const onDisk = this.readSlot(tx.slot);
+    if (!onDisk) return { status: "dropped" };
+    this.writeSlot(tx.slot, { ...onDisk, project: tx.project });
+    return { status: "applied", held: false };
+  }
+  commitHeldReport(tx) {
+    const before = this.heldReportsPending.size;
+    if (tx.pending) this.heldReportsPending.add(tx.userId);
+    else this.heldReportsPending.delete(tx.userId);
+    if (this.heldReportsPending.size !== before) this.persistPendingReports();
+    return { status: "applied", held: false };
+  }
+  // ── Storage write helpers (called ONLY from the commit handlers above) ──
+  /** Dual-write: the four frozen keys (downgrade-readable) + the `auth_session` record. */
+  writeSessionRecord(user, accessToken, accessExpiresAt, refreshToken) {
+    const st = this.hooks.storage;
+    st.set(USER_KEY, JSON.stringify(user));
+    if (accessToken) {
+      st.set(TOKEN_KEY, accessToken);
+      st.set(TOKEN_EXPIRES_KEY, String(accessExpiresAt));
+    } else {
+      st.remove(TOKEN_KEY);
+      st.remove(TOKEN_EXPIRES_KEY);
+    }
+    st.set(REFRESH_KEY, refreshToken);
+    const record = { v: 2, user, accessToken, accessExpiresAt, refreshToken };
+    if (this.heldReportsPending.size > 0) record.heldReportsPending = Array.from(this.heldReportsPending);
+    st.set(SESSION_KEY, JSON.stringify(record));
+  }
+  /** Hydrate's write-forward: ONLY the `auth_session` record (the frozen keys already hold the session untouched). */
+  writeSessionRecordOnly(user, accessToken, accessExpiresAt, refreshToken) {
+    const record = { v: 2, user, accessToken, accessExpiresAt, refreshToken };
+    if (this.heldReportsPending.size > 0) record.heldReportsPending = Array.from(this.heldReportsPending);
+    this.hooks.storage.set(SESSION_KEY, JSON.stringify(record));
+  }
+  /** The rotated pair only (the user is unchanged) — frozen keys + the record's token fields. */
+  writeTokens(accessToken, accessExpiresAt, refreshToken) {
+    const st = this.hooks.storage;
+    st.set(TOKEN_KEY, accessToken);
+    st.set(TOKEN_EXPIRES_KEY, String(accessExpiresAt));
+    st.set(REFRESH_KEY, refreshToken);
+    let record = { v: 2 };
+    const raw = st.get(SESSION_KEY);
+    if (raw) {
+      try {
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === "object" && parsed.v === 2) record = parsed;
+      } catch {
+      }
+    }
+    if (!record.user) {
+      const legacy = st.get(USER_KEY);
+      if (legacy) {
+        try {
+          const u = JSON.parse(legacy);
+          if (isAuthUserShape(u)) record.user = u;
+        } catch {
+        }
+      }
+    }
+    record.accessToken = accessToken;
+    record.accessExpiresAt = accessExpiresAt;
+    record.refreshToken = refreshToken;
+    if (this.heldReportsPending.size > 0) record.heldReportsPending = Array.from(this.heldReportsPending);
+    st.set(SESSION_KEY, JSON.stringify(record));
+  }
+  /** Clear EXACTLY the session keys (the four frozen + the record). Held slots, the queue and `user_id` are never touched here. */
+  clearSessionKeys() {
+    const st = this.hooks.storage;
+    st.remove(USER_KEY);
+    st.remove(TOKEN_KEY);
+    st.remove(TOKEN_EXPIRES_KEY);
+    st.remove(REFRESH_KEY);
+    this.persistPendingReports();
+  }
+  /** Keep the B15 pending-report flags on disk even with no session (a stub record); remove the record when nothing is pending. */
+  persistPendingReports() {
+    const st = this.hooks.storage;
+    if (this.hooks.storage.get(REFRESH_KEY) && this.user) {
+      this.writeSessionRecord(this.user, this.accessToken, this.accessExpiresAt, this.hooks.storage.get(REFRESH_KEY));
+      return;
+    }
+    if (this.heldReportsPending.size > 0) {
+      st.set(SESSION_KEY, JSON.stringify({ v: 2, heldReportsPending: Array.from(this.heldReportsPending) }));
+    } else {
+      st.remove(SESSION_KEY);
     }
   }
+  writeSlot(i, slot) {
+    const key = HELD_SLOT_KEYS[i];
+    this.held[i] = slot;
+    if (slot) this.hooks.storage.set(key, JSON.stringify(slot));
+    else this.hooks.storage.remove(key);
+  }
 };
+function signedOutReasonFor(endReason) {
+  switch (endReason) {
+    case "revoked":
+      return "revoked";
+    case "deleted":
+      return "deleted";
+    case "evicted":
+      return "evicted";
+    default:
+      return "session_expired";
+  }
+}
 function isDeadRefreshError(code) {
   if (!code) return false;
-  return code === "INVALID_REFRESH_TOKEN";
+  return DEAD_CODES.includes(code);
 }
 function readRotatedTokens(data) {
   if (!data || typeof data !== "object") return null;
@@ -2182,19 +3422,6 @@ function accessTokenExpIsFuture(token, nowMs) {
   if (typeof exp !== "number" || !Number.isFinite(exp)) return true;
   return nowMs < exp * 1e3;
 }
-function decodeJwtPayload(token) {
-  try {
-    const parts = token.split(".");
-    if (parts.length !== 3) return null;
-    const padded = parts[1].replace(/-/g, "+").replace(/_/g, "/");
-    const pad = (4 - padded.length % 4) % 4;
-    if (typeof atob !== "function") return null;
-    const json = atob(padded + "===".slice(0, pad));
-    return JSON.parse(json);
-  } catch {
-    return null;
-  }
-}
 
 // src/links.ts
 var import_react_native3 = require("react-native");
@@ -2924,11 +4151,15 @@ var EventQueue = class {
     }, ms);
   }
   /**
-   * Drain the queue FIFO. Removes an event only when the server ACCEPTED it (2xx)
-   * or PERMANENTLY refused it (a 4xx that a retry can't fix). Keeps it — and stops
-   * draining — on a transient failure (timeout throw, network null, 408/429/5xx),
-   * then arms a capped-exponential-backoff retry. The entire post lives inside the
-   * try/catch, so `NetworkTimeoutError` can never surface as an unhandled rejection.
+   * Drain the queue in order. Removes an event only when the server ACCEPTED it
+   * (2xx) or PERMANENTLY refused it (a 4xx that a retry can't fix). Keeps it —
+   * and stops draining — on a transient failure (timeout throw, network null,
+   * 408/429/5xx), then arms a capped-exponential-backoff retry. ⚠ Since 1.39.1 a
+   * transiently-failing HEAD is first rotated to the BACK, so one poison event
+   * cannot hold everything behind it; delivery order is therefore best-effort,
+   * not strict FIFO (identity travels in each event body, not by slot). The
+   * entire post lives inside the try/catch, so `NetworkTimeoutError` can never
+   * surface as an unhandled rejection.
    */
   async flush() {
     if (this.flushing || this.q.length === 0) return;
@@ -2990,14 +4221,20 @@ var ANON_KEY = "anon_id";
 var USER_ID_KEY = "user_id";
 var EVENT_QUEUE_KEY = "event_queue";
 var SCHEMA_VERSION_KEY = "schema_version";
-var SCHEMA_VERSION = "1";
-var AUTH_HYDRATE_KEYS = [
-  "auth_access_token",
-  "auth_access_expires",
-  "auth_refresh_token",
-  "auth_user"
-];
-var SECURE_KEYS = ["auth_refresh_token", "auth_access_token", "auth_user"];
+var SCHEMA_VERSION = "2";
+var SECURE_KEYS = AUTH_SECURE_KEYS;
+var ALL_SDK_KEYS = [ANON_KEY, USER_ID_KEY, SCHEMA_VERSION_KEY, EVENT_QUEUE_KEY, ...AUTH_HYDRATE_KEYS];
+var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function normalizeExpectedProjectId(expected, projectId) {
+  if (expected === void 0) return void 0;
+  if (typeof expected !== "string" || !UUID_RE.test(expected)) {
+    throw new Error(`[sendora] init: expectedProjectId must be a UUID (got ${JSON.stringify(expected)}).`);
+  }
+  if (projectId !== void 0 && projectId !== expected) {
+    throw new Error(`[sendora] init: expectedProjectId (${expected}) must equal projectId (${projectId}) when both are set.`);
+  }
+  return expected;
+}
 var PUBLIC_KEY_RE = /^pk_(prod|staging|dev|live|test)_[A-Za-z0-9]{16,}$/;
 var STORAGE_PREFIX_RE = /^[A-Za-z0-9_.-]{1,64}$/;
 function normalizeStoragePrefix(prefix) {
@@ -3136,6 +4373,8 @@ var SendoraSDK = class {
     this.sessionId = "";
     this.autoTrackCleanup = null;
     this.eventQueue = null;
+    /** ADR-033 [2c]: subscribers to `onIdentityWithheld`. */
+    this.withheldListeners = /* @__PURE__ */ new Set();
     // --- Engagement time (foreground-only, Wave 75) ---
     this.engEnabled = false;
     this.engScreen = null;
@@ -3183,6 +4422,7 @@ var SendoraSDK = class {
         `[sendoracloud] apiUrl override active: ${apiUrl} \u2014 confirm this is intentional. Tokens + events will be sent here.`
       );
     }
+    const expectedProjectId = normalizeExpectedProjectId(config.expectedProjectId, config.projectId);
     if (config.secureStorage || config.storagePrefix !== void 0) {
       const prefix = normalizeStoragePrefix(config.storagePrefix);
       this.storage = new Storage({
@@ -3191,16 +4431,7 @@ var SendoraSDK = class {
         prefix
       });
     }
-    await this.storage.hydrate([
-      ANON_KEY,
-      USER_ID_KEY,
-      SCHEMA_VERSION_KEY,
-      EVENT_QUEUE_KEY,
-      ...AUTH_HYDRATE_KEYS
-    ]);
-    if (!this.storage.get(SCHEMA_VERSION_KEY)) {
-      this.storage.set(SCHEMA_VERSION_KEY, SCHEMA_VERSION);
-    }
+    await this.storage.hydrate([...ALL_SDK_KEYS]);
     let anon = this.storage.get(ANON_KEY);
     if (!anon) {
       anon = uuid();
@@ -3226,6 +4457,22 @@ var SendoraSDK = class {
       apiUrl: this.config.apiUrl,
       publicKey: this.config.publicKey,
       debug: this.debug,
+      expectedProjectId,
+      projectId: this.config.projectId,
+      autoRestoreHeldGuest: config.autoRestoreHeldGuest !== false,
+      // ADR-033 [2c]: the stored session was refused by the project guard —
+      // quarantine analytics by nulling the IN-MEMORY user id only. The
+      // persisted `user_id` is untouched (a withheld hydrate writes nothing).
+      onIdentityWithheld: (info) => {
+        this.userId = null;
+        for (const cb of this.withheldListeners) {
+          try {
+            cb(info);
+          } catch (err) {
+            if (this.debug) console.warn("[sendoracloud] onIdentityWithheld listener threw", err);
+          }
+        }
+      },
       onIdentityChange: (userId) => {
         this.userId = userId;
         if (userId) this.storage.set(USER_ID_KEY, userId);
@@ -3242,6 +4489,9 @@ var SendoraSDK = class {
       }
     });
     this.auth.hydrate();
+    if (this.auth.status() !== "withheld" && this.storage.get(SCHEMA_VERSION_KEY) !== SCHEMA_VERSION) {
+      this.storage.set(SCHEMA_VERSION_KEY, SCHEMA_VERSION);
+    }
     this.links = new Links({
       apiUrl: this.config.apiUrl,
       publicKey: this.config.publicKey,
@@ -3982,23 +5232,44 @@ var SendoraSDK = class {
     if (!this._chatbotSessionId) this._chatbotSessionId = `chat_${uuid().replace(/-/g, "").slice(0, 24)}`;
     return this._chatbotSessionId;
   }
+  /**
+   * 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.
+   */
+  onIdentityWithheld(cb) {
+    this.withheldListeners.add(cb);
+    return () => {
+      this.withheldListeners.delete(cb);
+    };
+  }
   /**
    * 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.
+   * 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.
    *
-   * 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.
+   * ⚠ 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.
    */
-  async reset() {
+  async reset(opts) {
     await this.auth.signOut().catch(() => void 0);
     this.userId = null;
     this.sessionId = "";
     this.eventQueue?.clear();
-    await this.storage.clearAll();
+    if (opts?.includeHeldGuests) this.auth.releaseAllHeldGuests();
+    await this.storage.clearAll({ keys: ALL_SDK_KEYS, except: opts?.includeHeldGuests ? [] : HELD_SLOT_KEYS });
     this.storage.set(ANON_KEY, this.anonId);
   }
   /** Tear down auto-track listeners. Call in test harnesses. */
@@ -4058,15 +5329,21 @@ var SendoraCloud = new SendoraSDK();
 var index_default = SendoraCloud;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AMBIGUOUS_HELD_GUEST,
   AlreadyIdentifiedError,
   Auth,
   AuthError,
   CredentialInUseError,
   EmailAlreadyTakenError,
+  HELD_GUEST_SLOTS,
+  HeldGuestLimitError,
+  HeldGuestProjectMismatch,
   LinkError,
   Links,
   SendoraCloud,
   computeDeviceFingerprint,
+  decodeJwtPayload,
   extractShortcodeFromUrl,
-  getPlayInstallReferrer
+  getPlayInstallReferrer,
+  projectVerdict
 });