@bounded-sh/core 0.0.100 → 0.0.102

package/dist/{index-DW5yMQwV.mjs → index-CMT0saxy.mjs}

@@ -4188,7 +4188,7 @@ class ServerSessionManager {
         const sessionConfig = (_a = this.sessionConfig) !== null && _a !== void 0 ? _a : undefined;
         /* fetch nonce from auth API (bound to the snapshotted app+issuer) */
         const nonce = await genAuthNonce(sessionConfig);
-        const { genSolanaMessage } = await import('./solana-message-BGkYFU3C.mjs');
+        const { genSolanaMessage } = await import('./solana-message-C_717vAx.mjs');
         const message = await genSolanaMessage(address, nonce, sessionConfig === null || sessionConfig === void 0 ? void 0 : sessionConfig.appId);
         /* sign the message */
         const sigBytes = nacl.sign.detached(new TextEncoder().encode(message), kp.secretKey);
@@ -5280,6 +5280,37 @@ const MIN_BROWSER_RECONNECT_INTERVAL_MS = 5000;
 // cancel teardown and reuse it; genuinely idle sockets still close promptly.
 const IDLE_CONNECTION_CLOSE_GRACE_MS = 5000;
 const SUBSCRIPTION_CONFIRM_TIMEOUT_MS = 10000;
+/**
+ * Live subscriptions the SDK puts on ONE socket before opening another.
+ *
+ * The realtime worker refuses the 51st distinct subscribe on a connection with
+ * `{ code: 'subscription_limit', status: 429 }` - see
+ * `packages/cdk/cloudflare/realtime-worker/src/subscriptions.ts`
+ * (`attachment.subscriptions.length >= 50`). The cap is structural there: every
+ * subscription spec has to fit the 16KB Durable Object hibernation attachment,
+ * and each write fans out across the whole set of one socket.
+ *
+ * 45 leaves deliberate headroom under that 50: two concurrent subscribeV2 calls
+ * can both see room and overshoot by a frame or two, and another tab may already
+ * hold subscriptions on the same DO. A refusal that happens anyway is treated as
+ * backpressure, not a failure (see rehomeRefusedSubscription).
+ */
+const SHARD_CAP = 45;
+/**
+ * Sockets one routing target (app, room, or wallet identity) may hold. Past this
+ * a subscribe fails loudly with `subscription_limit` instead of opening
+ * connections without end - 8 * 45 = 360 concurrent live subscriptions per
+ * target, far beyond any legitimate UI.
+ */
+const MAX_SHARDS_PER_KEY = 8;
+/** Re-homes one logical subscription may attempt before its refusal surfaces. */
+const MAX_REHOME_ATTEMPTS = MAX_SHARDS_PER_KEY;
+const SUBSCRIPTION_LIMIT_CODE = 'subscription_limit';
+// Mirror of the server's `clampSubscriptionLimit` (realtime-worker
+// src/subscriptions.ts): an omitted or non-numeric limit becomes the default, a
+// value above the ceiling is clamped down, and a zero/negative limit is rejected.
+const SUBSCRIPTION_DEFAULT_LIMIT = 100;
+const SUBSCRIPTION_MAX_LIMIT = 1000;
 const WS_CONFIG = {
     // Keep retrying indefinitely so long outages recover without page refresh.
     maxRetries: Infinity,
@@ -5300,6 +5331,26 @@ let reconnectInProgress = null;
 function generateSubscriptionId() {
     return `sub_${Date.now()}_${Math.random().toString(36).substring(2, 11)}`;
 }
+/**
+ * Apply the server's own subscription-limit clamp so the client identifies a
+ * subscription by the value the server will actually key it on.
+ *
+ * The worker de-dups a connection's subscriptions on the CLAMPED limit and
+ * REPLACES a colliding entry (sending `unsubscribed` for the displaced id), so
+ * `limit: undefined` and `limit: 100` are one server subscription. Matching on
+ * the raw option made the SDK register two, and the second silently retired the
+ * first stream. `null` mirrors the server's rejection of a zero/negative limit.
+ * Authority: `clampSubscriptionLimit` in realtime-worker src/subscriptions.ts.
+ */
+function normalizeSubscriptionLimit(raw) {
+    if (raw === undefined || raw === null)
+        return SUBSCRIPTION_DEFAULT_LIMIT;
+    if (typeof raw !== 'number' || !Number.isFinite(raw))
+        return SUBSCRIPTION_DEFAULT_LIMIT;
+    if (raw <= 0)
+        return null;
+    return raw > SUBSCRIPTION_MAX_LIMIT ? SUBSCRIPTION_MAX_LIMIT : Math.floor(raw);
+}
 function hashForKey$1(value) {
     let h = 5381;
     for (let i = 0; i < value.length; i++) {
@@ -5319,7 +5370,11 @@ function hashForKey$1(value) {
 function getCacheKey(path, prompt, shape, limit, cursor, filter, identity) {
     const normalizedPath = path.startsWith('/') ? path.slice(1) : path;
     const shapeKey = shape && Object.keys(shape).length > 0 ? JSON.stringify(shape) : '';
-    const limitKey = limit !== undefined ? `:l${limit}` : '';
+    // Normalized, for the same reason the de-dup scan is: two options that clamp
+    // to one server subscription must share one cache entry, or a joined callback
+    // cannot read the snapshot its own subscription just wrote.
+    const normalizedLimit = normalizeSubscriptionLimit(limit);
+    const limitKey = `:l${normalizedLimit === null ? 'rejected' : normalizedLimit}`;
     const cursorKey = cursor ? `:c${hashForKey$1(cursor)}` : '';
     const filterKey = filter && Object.keys(filter).length > 0 ? `:f${hashForKey$1(JSON.stringify(filter))}` : '';
     return `${identity}|${normalizedPath}:${prompt || 'default'}:${shapeKey}${limitKey}${cursorKey}${filterKey}`;
@@ -5648,18 +5703,76 @@ function replaySubscriptions(connection) {
  * connections key by their routing target; wallet-scoped connections pin the
  * exact bearer so two distinct tokens never share a flight or a lease, even
  * when their compact `#id#<principalKey>` hashes collide.
+ *
+ * `shardIndex` selects which socket of that target's pool this is. Shard 0 adds
+ * nothing, so every key an unsharded client produces is unchanged.
  */
-function connectionLeaseKey(appId, routePath, principalKey, principalToken, anonymous) {
+function connectionLeaseKey(appId, routePath, principalKey, principalToken, anonymous, shardIndex = 0) {
     const roomKey = roomKeyFromRoutePath(routePath);
     // A read-only scoped instance is anonymous and must never share a socket with
     // the authenticated global path even when it targets the same appId.
     const appKey = anonymous ? `${appId}#ro` : appId;
-    const base = roomKey ? `${appKey}#room#${roomKey}` : appKey;
+    const base = routingBaseKey(roomKey ? `${appKey}#room#${roomKey}` : appKey, shardIndex);
     if (!principalKey)
         return base;
     const bucket = `${base}#id#${principalKey}`;
     return principalToken ? `${bucket}#tok#${principalToken}` : bucket;
 }
+/**
+ * Apply a shard suffix to the ROUTING part of a connection key, ahead of any
+ * `#id#`/`#tok#` identity bucket. Keeping the suffix here means the room/app
+ * prefix a caller already knows (`<appId>#room#<collection>/<roomId>`) is still
+ * the shard-0 key, so existing single-socket lookups keep working verbatim.
+ */
+function routingBaseKey(base, shardIndex) {
+    return shardIndex > 0 ? `${base}#s${shardIndex}` : base;
+}
+/** The live connection holding a given lease key, across identity collisions. */
+function connectionForLeaseKey(leaseKey) {
+    for (const connection of connections.values()) {
+        if (connection.acquisitionKey === leaseKey)
+            return connection;
+    }
+    return undefined;
+}
+/**
+ * The connection that currently owns a subscription id.
+ *
+ * A subscriber's unsubscribe closure captures the connection it registered on,
+ * but a `subscription_limit` re-home can move the subscription to another shard
+ * afterwards. Re-resolving by id means an unsubscribe still reaches the socket
+ * that actually holds it instead of silently no-oping and leaking the
+ * subscription. Ids are minted locally and globally unique, so an id identifies
+ * exactly one subscription across every connection.
+ */
+function connectionHoldingSubscription(subscriptionId) {
+    for (const connection of connections.values()) {
+        if (connection.subscriptions.has(subscriptionId))
+            return connection;
+    }
+    return undefined;
+}
+/**
+ * Walk a routing target's shard pool, shard 0 first, and return the first
+ * connection the caller accepts. Callers that used to read a single
+ * `connections.get(<base>)` need this because shard 0 closes when it drains
+ * while a later shard is still carrying subscriptions - a bare lookup would
+ * then report "no socket" for an app that has several.
+ */
+function findShardConnection(baseKey, accept) {
+    for (let shardIndex = 0; shardIndex < MAX_SHARDS_PER_KEY; shardIndex++) {
+        const connection = connections.get(routingBaseKey(baseKey, shardIndex));
+        if (connection && accept(connection))
+            return connection;
+    }
+    return undefined;
+}
+/** An OPEN socket that is not mid-auth: safe to send an authorized frame on. */
+function isWarmConnection(connection) {
+    return !!connection.ws
+        && connection.ws.readyState === WS_READY_STATE_OPEN
+        && !connection.isAuthenticating;
+}
 function cancelIdleConnectionClose(connection) {
     if (!connection.idleCloseTimer)
         return;
@@ -5723,9 +5836,9 @@ function scheduleConnectionCloseIfIdle(connection) {
  * reuse. The lease is released once the caller has registered its
  * subscription/callback.
  */
-async function acquireConnection(appId, isServer, routePath, authTokenProvider, principalKey, principalToken, source) {
+async function acquireConnection(appId, isServer, routePath, authTokenProvider, principalKey, principalToken, source, shardIndex = 0) {
     var _a;
-    const leaseKey = connectionLeaseKey(appId, routePath, principalKey, principalToken, source === null || source === void 0 ? void 0 : source.anonymous);
+    const leaseKey = connectionLeaseKey(appId, routePath, principalKey, principalToken, source === null || source === void 0 ? void 0 : source.anonymous, shardIndex);
     connectionAcquisitions.set(leaseKey, ((_a = connectionAcquisitions.get(leaseKey)) !== null && _a !== void 0 ? _a : 0) + 1);
     let released = false;
     let releaseTimer = null;
@@ -5747,7 +5860,7 @@ async function acquireConnection(appId, isServer, routePath, authTokenProvider,
             scheduleConnectionCloseIfIdle(connection);
     };
     try {
-        const connection = await getOrCreateConnection(appId, isServer, routePath, authTokenProvider, principalKey, principalToken, source);
+        const connection = await getOrCreateConnection(appId, isServer, routePath, authTokenProvider, principalKey, principalToken, source, shardIndex);
         const releaseConnection = () => release(connection);
         // Registration is synchronous after the caller's await. This fail-safe
         // releases on the next task even if an option getter/callback throws
@@ -5760,15 +5873,94 @@ async function acquireConnection(appId, isServer, routePath, authTokenProvider,
         throw error;
     }
 }
-async function getOrCreateConnection(appId, isServer, routePath, authTokenProvider, principalKey, principalToken, source) {
+function shardTargetFromConnection(connection) {
+    var _a;
+    return {
+        appId: connection.appId,
+        isServer: connection.isServer,
+        routePath: connection.routePath,
+        authTokenProvider: connection.authTokenProvider,
+        principalKey: connection.principalKey,
+        principalToken: (_a = connection.connectionIdentityToken) !== null && _a !== void 0 ? _a : undefined,
+        source: connection.source,
+    };
+}
+function shardLeaseKeyFor(target, shardIndex) {
+    var _a;
+    return connectionLeaseKey(target.appId, target.routePath, target.principalKey, target.principalToken, (_a = target.source) === null || _a === void 0 ? void 0 : _a.anonymous, shardIndex);
+}
+function subscriptionLimitExhaustedError(target) {
+    const error = new Error(`${SUBSCRIPTION_LIMIT_CODE}: this client already holds the maximum ${MAX_SHARDS_PER_KEY * SHARD_CAP} live subscriptions for ${target.appId}`);
+    error.code = SUBSCRIPTION_LIMIT_CODE;
+    error.status = 429;
+    return error;
+}
+/**
+ * Choose the shard that should carry a subscription.
+ *
+ * The de-dup scan spans EVERY shard of the target before any placement decision:
+ * a second subscriber with identical specs must ref-count onto the existing
+ * subscription wherever it lives, never open a duplicate on another socket.
+ * Failing that, the lowest-index shard with room wins, so a client that drops
+ * back under one socket's worth of subscriptions collapses onto shard 0 again.
+ */
+function planSubscriptionShard(target, matches) {
+    let firstShardWithRoom = -1;
+    for (let shardIndex = 0; shardIndex < MAX_SHARDS_PER_KEY; shardIndex++) {
+        const connection = connectionForLeaseKey(shardLeaseKeyFor(target, shardIndex));
+        if (!connection) {
+            if (firstShardWithRoom < 0)
+                firstShardWithRoom = shardIndex;
+            continue;
+        }
+        for (const subscription of connection.subscriptions.values()) {
+            if (matches(subscription))
+                return { shardIndex, existing: subscription };
+        }
+        if (firstShardWithRoom < 0 && connection.subscriptions.size < connection.capacityCeiling) {
+            firstShardWithRoom = shardIndex;
+        }
+    }
+    return { shardIndex: firstShardWithRoom < 0 ? MAX_SHARDS_PER_KEY : firstShardWithRoom };
+}
+/**
+ * Acquire the connection that will carry a subscription, opening another shard
+ * when the current ones are at SHARD_CAP.
+ *
+ * Placement is re-decided after every acquisition because the auth preflight is
+ * an await: concurrently mounting subscribers can fill the shard this call
+ * planned for, and the subscription it planned to join can be gone. Both cases
+ * re-plan rather than overshoot, bounded by the shard ceiling.
+ */
+async function acquireSubscriptionShard(target, matches) {
+    for (let attempt = 0; attempt <= MAX_SHARDS_PER_KEY; attempt++) {
+        const placement = planSubscriptionShard(target, matches);
+        if (placement.shardIndex >= MAX_SHARDS_PER_KEY)
+            throw subscriptionLimitExhaustedError(target);
+        const acquisition = await acquireConnection(target.appId, target.isServer, target.routePath, target.authTokenProvider, target.principalKey, target.principalToken, target.source, placement.shardIndex);
+        const { connection } = acquisition;
+        const existing = placement.existing;
+        if (existing) {
+            if (connection.subscriptions.get(existing.subscriptionId) === existing) {
+                return { acquisition, existing };
+            }
+        }
+        else if (connection.subscriptions.size < connection.capacityCeiling) {
+            return { acquisition };
+        }
+        acquisition.release();
+    }
+    throw subscriptionLimitExhaustedError(target);
+}
+async function getOrCreateConnection(appId, isServer, routePath, authTokenProvider, principalKey, principalToken, source, shardIndex = 0) {
     // Singleflight: concurrent first-use of the same routing target shares one
     // in-flight connection rather than each creating an orphan socket. Keyed by
     // the identity-bucket lease key so distinct wallet tokens never coalesce.
-    const leaseKey = connectionLeaseKey(appId, routePath, principalKey, principalToken, source === null || source === void 0 ? void 0 : source.anonymous);
+    const leaseKey = connectionLeaseKey(appId, routePath, principalKey, principalToken, source === null || source === void 0 ? void 0 : source.anonymous, shardIndex);
     const activeFlight = connectionFlights.get(leaseKey);
     if (activeFlight)
         return activeFlight;
-    const flight = getOrCreateConnectionOnce(appId, isServer, routePath, authTokenProvider, principalKey, principalToken, leaseKey, source);
+    const flight = getOrCreateConnectionOnce(appId, isServer, routePath, authTokenProvider, principalKey, principalToken, leaseKey, source, shardIndex);
     connectionFlights.set(leaseKey, flight);
     try {
         return await flight;
@@ -5779,7 +5971,7 @@ async function getOrCreateConnection(appId, isServer, routePath, authTokenProvid
         }
     }
 }
-async function getOrCreateConnectionOnce(appId, isServer, routePath, authTokenProvider, principalKey, principalToken, leaseKey, source) {
+async function getOrCreateConnectionOnce(appId, isServer, routePath, authTokenProvider, principalKey, principalToken, leaseKey, source, shardIndex = 0) {
     var _a, _b;
     attachBrowserReconnectHooksOnce();
     const anonymous = (source === null || source === void 0 ? void 0 : source.anonymous) === true;
@@ -5793,8 +5985,11 @@ async function getOrCreateConnectionOnce(appId, isServer, routePath, authTokenPr
     // never shares a connection (or token) with any top-level server caller. A
     // read-only scoped (anonymous) instance is likewise isolated by an `#ro`
     // marker so it never shares the authenticated global socket on the same appId.
+    // Shard N>0 of the same routing target is a SEPARATE socket to the SAME
+    // Durable Object: the server's cap is per websocket attachment, so an extra
+    // connection buys an extra budget without changing where anything routes.
     const appKey = anonymous ? `${appId}#ro` : appId;
-    const base = roomKey ? `${appKey}#room#${roomKey}` : appKey;
+    const base = routingBaseKey(roomKey ? `${appKey}#room#${roomKey}` : appKey, shardIndex);
     const identityBucketKey = principalKey
         ? `${base}#id#${principalKey}`
         : base;
@@ -5869,6 +6064,9 @@ async function getOrCreateConnectionOnce(appId, isServer, routePath, authTokenPr
         appId,
         key: connKey,
         acquisitionKey: leaseKey,
+        shardIndex,
+        principalKey,
+        capacityCeiling: SHARD_CAP,
         routePath: roomKey ? routePath : undefined,
         authTokenProvider,
         connectionIdentityToken: principalToken !== null && principalToken !== void 0 ? principalToken : null,
@@ -6169,6 +6367,16 @@ function handleServerMessage(connection, message) {
             if (connection.isAuthenticating && connection.pendingAuthToken && !connection.authTokenProvider && !connection.anonymous) {
                 void recoverFromServerAuthRejection(connection);
             }
+            // `subscription_limit` is backpressure on THIS socket, not a verdict
+            // on the read: the DO refuses a subscribe once its hibernation
+            // attachment is full. Move the subscription to another shard instead
+            // of failing the caller. The client shards below the server's cap, so
+            // this is the residual case - another tab on the same DO, a race, or
+            // a server enforcing a lower cap.
+            if (message.code === SUBSCRIPTION_LIMIT_CODE && message.subscriptionId
+                && rehomeRefusedSubscription(connection, message.subscriptionId, message)) {
+                break;
+            }
             // Build an Error that ALSO carries the stable `code` as a structured
             // field (not just string-interpolated into the message) so callers can
             // branch on it — e.g. `catch (e) { if (e.code === 'invariant_violation') }`
@@ -6177,6 +6385,11 @@ function handleServerMessage(connection, message) {
             const buildWsError = () => {
                 const err = new Error(`${message.code}: ${message.message}`);
                 err.code = message.code;
+                // The server's HTTP-equivalent status, so a caller can tell 429
+                // backpressure from a 413 oversize frame from a 403 policy
+                // denial without pattern-matching the code string.
+                if (typeof message.status === 'number')
+                    err.status = message.status;
                 if (message.requestId)
                     err.requestId = message.requestId;
                 if (message.subscriptionId)
@@ -6352,6 +6565,23 @@ function rejectPendingSubscriptionConfirmation(connection, subscriptionId, error
     pending.reject(error);
     return true;
 }
+/**
+ * Take a confirmation record off a connection WITHOUT settling it, so it can be
+ * re-armed on another socket. A `subscription_limit` refusal has not failed the
+ * caller's subscribe - the subscription is still being placed - so rejecting the
+ * promise here would turn backpressure into an error the app has to handle.
+ */
+function detachPendingSubscriptionConfirmation(connection, subscriptionId) {
+    const pending = connection.pendingSubscriptions.get(subscriptionId);
+    if (!pending)
+        return null;
+    connection.pendingSubscriptions.delete(subscriptionId);
+    if (pending.timer) {
+        clearTimeout(pending.timer);
+        pending.timer = null;
+    }
+    return pending;
+}
 function armSubscriptionConfirmationTimeout(connection, subscription, pending) {
     pending.timer = setTimeout(() => {
         if (connection.pendingSubscriptions.get(subscription.subscriptionId) !== pending)
@@ -6445,6 +6675,96 @@ function registerDetachedReplayConfirmation(connection, subscription) {
         }
     });
 }
+function subscriptionLimitError(message) {
+    const error = new Error(`${message.code}: ${message.message}`);
+    error.code = message.code;
+    error.status = typeof message.status === 'number' ? message.status : 429;
+    if (message.subscriptionId)
+        error.subscriptionId = message.subscriptionId;
+    return error;
+}
+/**
+ * Handle a server `subscription_limit` refusal as backpressure: unregister the
+ * subscription from the socket that refused it and place it on another shard.
+ *
+ * Unregistering is what makes the refusal non-permanent. A refused subscription
+ * that stayed in `connection.subscriptions` was re-sent by replaySubscriptions()
+ * on every reconnect, to be refused again forever.
+ *
+ * Returns true when this refusal has been taken over and must not also be
+ * reported to the subscription's callbacks.
+ */
+function rehomeRefusedSubscription(connection, subscriptionId, message) {
+    const subscription = connection.subscriptions.get(subscriptionId);
+    if (!subscription)
+        return false;
+    connection.subscriptions.delete(subscriptionId);
+    // Believe the server over SHARD_CAP: whatever this socket still holds is the
+    // most it demonstrably accepts. The planner stops offering it until it drains.
+    connection.capacityCeiling = Math.min(connection.capacityCeiling, connection.subscriptions.size);
+    const pending = detachPendingSubscriptionConfirmation(connection, subscriptionId);
+    subscription.rehomeAttempts += 1;
+    if (subscription.rehomeAttempts > MAX_REHOME_ATTEMPTS) {
+        // Every shard refused it. This is the one case where the cap reaches the
+        // app, and it arrives as a real error with `code` and `status`.
+        const error = subscriptionLimitError(message);
+        notifyErrorCallbacks(subscription, error);
+        rejectSubscriptionRefresh(subscription, error);
+        pending === null || pending === void 0 ? void 0 : pending.reject(error);
+        scheduleConnectionCloseIfIdle(connection);
+        return true;
+    }
+    void moveSubscriptionToAnotherShard(connection, subscription, pending, message);
+    scheduleConnectionCloseIfIdle(connection);
+    return true;
+}
+async function moveSubscriptionToAnotherShard(refusedConnection, subscription, pending, message) {
+    const target = shardTargetFromConnection(refusedConnection);
+    let acquisition;
+    try {
+        // Never join an existing subscription here: this id is the thing being
+        // placed, and its de-dup identity was already settled when it was created.
+        ({ acquisition } = await acquireSubscriptionShard(target, () => false));
+    }
+    catch (error) {
+        const failure = error instanceof Error ? error : subscriptionLimitError(message);
+        notifyErrorCallbacks(subscription, failure);
+        rejectSubscriptionRefresh(subscription, failure);
+        pending === null || pending === void 0 ? void 0 : pending.reject(failure);
+        return;
+    }
+    const connection = acquisition.connection;
+    try {
+        if (subscription.callbacks.length === 0) {
+            // Every consumer unsubscribed while the re-home was in flight.
+            pending === null || pending === void 0 ? void 0 : pending.reject(new Error('Subscription unsubscribed'));
+            return;
+        }
+        // The new socket owes this subscription a fresh snapshot, exactly as a
+        // reconnect replay does, so callbacks are not left holding stale data.
+        subscription.lastData = undefined;
+        connection.subscriptions.set(subscription.subscriptionId, subscription);
+        if (pending) {
+            pending.retrySent = false;
+            connection.pendingSubscriptions.set(subscription.subscriptionId, pending);
+        }
+        else {
+            registerDetachedReplayConfirmation(connection, subscription);
+        }
+        if (isWarmConnection(connection)) {
+            sendSubscribeWithConfirmation(connection, subscription);
+        }
+        else if (pending) {
+            // Cold or authenticating: replaySubscriptions() sends it and re-arms
+            // the per-socket window once the socket authenticates. Bound the wait
+            // until then, the same way an original cold registration does.
+            armSubscriptionConfirmationTimeout(connection, subscription, pending);
+        }
+    }
+    finally {
+        acquisition.release();
+    }
+}
 function resolveSubscriptionRefresh(subscription) {
     const refresh = subscription.refresh;
     if (!refresh)
@@ -6540,7 +6860,7 @@ function sendUnsubscribe(connection, subscriptionId) {
  *   the subscription onto, since a WS connection routes to a single DO.
  */
 async function subscribeV2(path, subscriptionOptions, roomRoutePath) {
-    var _a, _b, _c, _d, _e, _f;
+    var _a, _b, _c, _d, _e;
     const overrides = subscriptionOptions._overrides;
     // A scoped createClient() instance passes its own resolved config; the
     // default path reads the module-global init() config.
@@ -6579,16 +6899,52 @@ async function subscribeV2(path, subscriptionOptions, roomRoutePath) {
     const cacheKey = responseCacheEnabled
         ? getCacheKey(normalizedPath, subscriptionOptions.prompt, subscriptionOptions.shape, subscriptionOptions.limit, subscriptionOptions.cursor, subscriptionOptions.filter, identity)
         : null;
+    // Stringify THIS call's specs once; existing subscriptions carry their
+    // precomputed specKey, so the shared-subscription scan is a string compare per
+    // entry (previously each new subscribe re-stringified every existing
+    // subscription's shape/filter/sort - O(N²) with many live hooks). Resolved
+    // before acquisition because shard placement needs the de-dup predicate.
+    const specKey = JSON.stringify([
+        (_b = subscriptionOptions.shape) !== null && _b !== void 0 ? _b : null,
+        (_c = subscriptionOptions.filter) !== null && _c !== void 0 ? _c : null,
+        (_d = subscriptionOptions.sort) !== null && _d !== void 0 ? _d : null,
+    ]);
+    const normalizedLimit = normalizeSubscriptionLimit(subscriptionOptions.limit);
+    const includeSubPaths = (_e = subscriptionOptions.includeSubPaths) !== null && _e !== void 0 ? _e : false;
+    // H1: the scan also requires the same principal identity (compact hash AND
+    // exact token) - a different logged-in user must not piggy-back on (and
+    // inherit lastData from) another user's existing subscription, even with
+    // identical path/prompt/shape/filter/sort.
+    const matchesThisSubscription = (sub) => (sub.identity === identity
+        && sub.identityToken === identityToken
+        && sub.path === normalizedPath
+        && sub.prompt === subscriptionOptions.prompt
+        && sub.specKey === specKey
+        && sub.includeSubPaths === includeSubPaths
+        && sub.normalizedLimit === normalizedLimit
+        && sub.cursor === subscriptionOptions.cursor);
     // Acquire a connection for this routing target (room-scoped when a room route
-    // is supplied by the live helper, else the app-level connection). The lease is
-    // held across auth preflight and released once this call registers below, so a
-    // concurrent old-route teardown cannot close a socket we are about to reuse.
+    // is supplied by the live helper, else the app-level connection), on the shard
+    // that either already holds this exact subscription or still has room under
+    // the server's per-socket cap. The lease is held across auth preflight and
+    // released once this call registers below, so a concurrent old-route teardown
+    // cannot close a socket we are about to reuse.
     let connection;
     let releaseConnection;
+    let existingSubscription;
     try {
-        const acquisition = await acquireConnection(effectiveAppId, config.isServer, roomRoutePath, authTokenProvider, principalKey, principalToken, source);
+        const { acquisition, existing } = await acquireSubscriptionShard({
+            appId: effectiveAppId,
+            isServer: config.isServer,
+            routePath: roomRoutePath,
+            authTokenProvider,
+            principalKey,
+            principalToken,
+            source,
+        }, matchesThisSubscription);
         connection = acquisition.connection;
         releaseConnection = acquisition.release;
+        existingSubscription = existing;
     }
     catch (error) {
         const err = error instanceof Error ? error : new Error(String(error));
@@ -6599,34 +6955,6 @@ async function subscribeV2(path, subscriptionOptions, roomRoutePath) {
         throw err;
     }
     const cachedEntry = cacheKey ? getResponseCacheEntry(cacheKey, identityToken) : undefined;
-    // Check if we already have a subscription for this path+prompt+shape+limit+cursor+filter+sort
-    let existingSubscription;
-    let specKey = '';
-    try {
-        // Stringify THIS call's specs once; existing subscriptions carry their
-        // precomputed specKey, so the scan is a string compare per entry
-        // (previously each new subscribe re-stringified every existing
-        // subscription's shape/filter/sort — O(N²) with many live hooks).
-        specKey = JSON.stringify([
-            (_b = subscriptionOptions.shape) !== null && _b !== void 0 ? _b : null,
-            (_c = subscriptionOptions.filter) !== null && _c !== void 0 ? _c : null,
-            (_d = subscriptionOptions.sort) !== null && _d !== void 0 ? _d : null,
-        ]);
-        for (const sub of connection.subscriptions.values()) {
-            // H1: also require the same principal identity (compact hash AND exact
-            // token) — a different logged-in user must not piggy-back on (and
-            // inherit lastData from) another user's existing subscription, even
-            // with identical path/prompt/shape/filter/sort.
-            if (sub.identity === identity && sub.identityToken === identityToken && sub.path === normalizedPath && sub.prompt === subscriptionOptions.prompt && sub.specKey === specKey && sub.includeSubPaths === ((_e = subscriptionOptions.includeSubPaths) !== null && _e !== void 0 ? _e : false) && sub.limit === subscriptionOptions.limit && sub.cursor === subscriptionOptions.cursor) {
-                existingSubscription = sub;
-                break;
-            }
-        }
-    }
-    catch (error) {
-        releaseConnection();
-        throw error;
-    }
     if (existingSubscription) {
         let replayData = undefined;
         let replayOnData;
@@ -6709,8 +7037,9 @@ async function subscribeV2(path, subscriptionOptions, roomRoutePath) {
             prompt: subscriptionOptions.prompt,
             shape: subscriptionOptions.shape,
             limit: subscriptionOptions.limit,
+            normalizedLimit,
             cursor: subscriptionOptions.cursor,
-            includeSubPaths: (_f = subscriptionOptions.includeSubPaths) !== null && _f !== void 0 ? _f : false,
+            includeSubPaths,
             callbacks: [subscriptionOptions],
             lastData: undefined,
             dataRevision: 0,
@@ -6719,6 +7048,7 @@ async function subscribeV2(path, subscriptionOptions, roomRoutePath) {
             identity,
             identityToken,
             specKey,
+            rehomeAttempts: 0,
         };
         connection.subscriptions.set(subscriptionId, subscription);
     }
@@ -6792,15 +7122,21 @@ async function subscribeV2(path, subscriptionOptions, roomRoutePath) {
         await removeCallbackFromSubscription(connection, subscriptionId, subscriptionOptions);
     };
 }
-async function removeCallbackFromSubscription(connection, subscriptionId, callback) {
-    var _a;
+async function removeCallbackFromSubscription(registeredOn, subscriptionId, callback) {
+    var _a, _b;
+    // A `subscription_limit` re-home can have moved this subscription to another
+    // shard since the caller captured its connection, so resolve the current
+    // owner rather than no-oping (which would leak the subscription forever).
+    const connection = registeredOn.subscriptions.has(subscriptionId)
+        ? registeredOn
+        : (_a = connectionHoldingSubscription(subscriptionId)) !== null && _a !== void 0 ? _a : registeredOn;
     const subscription = connection.subscriptions.get(subscriptionId);
     if (!subscription) {
         return;
     }
     // Remove this callback
     subscription.callbacks = subscription.callbacks.filter(cb => cb !== callback);
-    (_a = subscription.refresh) === null || _a === void 0 ? void 0 : _a.callbacks.delete(callback);
+    (_b = subscription.refresh) === null || _b === void 0 ? void 0 : _b.callbacks.delete(callback);
     // If there are still callbacks, don't unsubscribe
     if (subscription.callbacks.length > 0) {
         return;
@@ -6966,7 +7302,7 @@ async function doReconnectWithNewAuth() {
         console.warn('[WS v2] Failed to clear HTTP read cache on auth change:', error);
     }
     try {
-        const { reconnectRealtimeStoreWithNewAuth } = await import('./realtime-store-CeDT7vJF.mjs');
+        const { reconnectRealtimeStoreWithNewAuth } = await import('./realtime-store-DqAAqfo9.mjs');
         await reconnectRealtimeStoreWithNewAuth();
     }
     catch (error) {
@@ -7041,8 +7377,10 @@ const WS_RUNQUERY_MAX_FRAME_BYTES = 60000;
  */
 async function runNamedQueriesOverSocket(appId, queries, isServer) {
     var _a;
-    const connection = connections.get(appId);
-    if (!connection || !connection.ws || connection.ws.readyState !== WS_READY_STATE_OPEN || connection.isAuthenticating) {
+    // Any warm shard of this app's pool will do: a query is not bound to the
+    // socket a subscription happens to live on.
+    const connection = findShardConnection(appId, isWarmConnection);
+    if (!connection) {
         return null; // no warm socket -> HTTP (never open one just for queries)
     }
     if (!((_a = connection.capabilities) === null || _a === void 0 ? void 0 : _a.runQuery)) {
@@ -7092,9 +7430,8 @@ async function runNamedQueriesOverSocket(appId, queries, isServer) {
  */
 async function wsIntent(appId, roomRoutePath, intent, isServer) {
     const roomKey = roomKeyFromRoutePath(roomRoutePath);
-    const connKey = roomKey ? `${appId}#room#${roomKey}` : appId;
-    const connection = connections.get(connKey);
-    if (!connection || !connection.ws || connection.ws.readyState !== WS_READY_STATE_OPEN || connection.isAuthenticating) {
+    const connection = findShardConnection(roomKey ? `${appId}#room#${roomKey}` : appId, isWarmConnection);
+    if (!connection) {
         return false;
     }
     // Identity-aware send gate. The server attributes intents to the
@@ -7124,6 +7461,9 @@ async function wsIntent(appId, roomRoutePath, intent, isServer) {
         return false;
     }
     try {
+        // The identity gate above awaits, so the socket is re-read here; a
+        // teardown in that window throws and is reported as not-sent, exactly as
+        // wsIntentReliable does.
         connection.ws.send(JSON.stringify({ type: 'intent', intent }));
         return true;
     }
@@ -7161,9 +7501,8 @@ async function maybeReauthRoomConnection(connection, isServer) {
  */
 async function wsIntentReliable(appId, roomRoutePath, intent, isServer) {
     const roomKey = roomKeyFromRoutePath(roomRoutePath);
-    const connKey = roomKey ? `${appId}#room#${roomKey}` : appId;
-    const connection = connections.get(connKey);
-    if (!connection || !connection.ws || connection.ws.readyState !== WS_READY_STATE_OPEN || connection.isAuthenticating) {
+    const connection = findShardConnection(roomKey ? `${appId}#room#${roomKey}` : appId, isWarmConnection);
+    if (!connection) {
         return undefined;
     }
     if (!(await canSendAuthenticatedLiveIntent(connection, isServer))) {
@@ -8417,7 +8756,7 @@ async function setMany(many, options) {
                         'Nothing was signed or submitted.');
                 }
                 const solanaChain = workerChain;
-                const { handlePreBuiltTransaction, buildExpectedWriteIntent } = await import('./solana-operations-CHgW7Pue.mjs');
+                const { handlePreBuiltTransaction, buildExpectedWriteIntent } = await import('./solana-operations-DGNA2nGZ.mjs');
                 // OA-0001: derive the expected intent from OUR OWN request (the one
                 // ground truth a tampered builder response cannot change) so the
                 // validator can reject any transaction whose operation semantics
@@ -8781,7 +9120,7 @@ async function getTransactionJson(rpc, signature, commitment = 'confirmed') {
 }
 
 const DEFAULT_TIMEOUT_MS = 60000;
-const DEFAULT_MAX_ATTEMPTS = 20;
+const DEFAULT_MAX_ATTEMPTS$1 = 20;
 const DEFAULT_POLL_INTERVAL_MS = 3000;
 /** Mirror read after a late confirmation. No settle delay: the tx already landed. */
 const RECONCILE_MIRROR_SETTLE_MS = 0;
@@ -8988,7 +9327,7 @@ async function waitForSetResult(receipt, options) {
         return reconcileSetResult(receipt, options);
     }
     const timeoutMs = (_a = options === null || options === void 0 ? void 0 : options.timeoutMs) !== null && _a !== void 0 ? _a : DEFAULT_TIMEOUT_MS;
-    const maxAttempts = (_b = options === null || options === void 0 ? void 0 : options.maxAttempts) !== null && _b !== void 0 ? _b : DEFAULT_MAX_ATTEMPTS;
+    const maxAttempts = (_b = options === null || options === void 0 ? void 0 : options.maxAttempts) !== null && _b !== void 0 ? _b : DEFAULT_MAX_ATTEMPTS$1;
     const pollIntervalMs = (_c = options === null || options === void 0 ? void 0 : options.pollIntervalMs) !== null && _c !== void 0 ? _c : DEFAULT_POLL_INTERVAL_MS;
     const startedAt = Date.now();
     let current = receipt;
@@ -9106,72 +9445,95 @@ async function reconnectWithNewAuth() {
     return reconnectWithNewAuthV2();
 }
 
-/**
- * Scoped multi-app client factory.
- *
- * `createClient()` returns an isolated, READ-ONLY client bound to one Bounded
- * app, independent of the module-global `init()` client. It exists so a single
- * frontend can hold its normal authenticated client for its own app AND a
- * read-only client for a SECOND Bounded app (e.g. a shared steward/runtime app),
- * with live subscriptions on both and zero interference between them.
- *
- * Each instance carries its OWN fully-resolved config (endpoints + appId) and
- * routes through the SAME shared transport/subscription implementation as the
- * global path - it never forks that code. Isolation comes from threading the
- * instance config (and a read-only marker) through the existing per-request /
- * per-subscription override channel, plus the websocket layer already keying
- * connections by appId.
- *
- * ## v1 scope: read-only, unauthenticated
- *
- * A scoped instance is UNAUTHENTICATED. It sends no auth, never reads or
- * refreshes the global session, and connects to its app's realtime endpoint
- * anonymously. It is therefore only useful against collections a Bounded app
- * exposes with a public read rule (`read: true`) - private/per-user reads will
- * be denied by the target app's policy, exactly as an anonymous caller would be.
- *
- * Writes and any auth-requiring surface are NOT supported on a scoped instance
- * and throw a clear error. Per-instance authentication is a planned follow-up.
- */
-/** Error thrown when an unsupported (write / auth-requiring) call is made on a
- *  read-only scoped client. */
+var __rest$1 = (undefined && undefined.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+/** Error thrown when an unsupported (write) call is made on a scoped client.
+ *  Reads may be authenticated per instance; writes still are not supported. */
 class ScopedClientReadOnlyError extends Error {
     constructor(operation) {
-        super(`createClient() instances are read-only in v1: "${operation}" is not supported. ` +
-            `Use the global init() client for authenticated writes, or read only public ` +
-            `(read: true) collections on this scoped instance.`);
+        super(`createClient() instances are read-only: "${operation}" is not supported. ` +
+            `Use the global init() client for authenticated writes, or read public ` +
+            `(read: true) collections - and, with getAuthHeaders, this credential's own ` +
+            `readable collections - on this scoped instance.`);
         this.name = 'ScopedClientReadOnlyError';
     }
 }
 /**
- * Create a read-only client scoped to a single Bounded app.
+ * Create a read-only client scoped to a single Bounded app, anonymous by default
+ * and authenticated when given `getAuthHeaders`.
  *
  * @example
  * ```ts
  * // Global client stays the venue's own authenticated app:
  * await init({ appId: VENUE_APP, network: 'bounded-production', authMethod: 'email' });
  *
- * // A second, read-only client for the steward runtime app:
+ * // A second, anonymous client for the steward runtime app's public collections:
  * const steward = createClient({ appId: STEWARD_APP, network: 'bounded-production' });
  * const state = await steward.get('runtime/current');
  * const stop = await steward.subscribe('runtime/current', (d) => render(d));
+ *
+ * // The same second app, read AS THE SIGNED-IN HUMAN: the venue session is
+ * // exchanged for a token pinned to the child app (see createAppTokenAuthHeaders).
+ * const mine = createClient({
+ *   appId: ROOT_APP,
+ *   network: 'bounded-production',
+ *   getAuthHeaders: createAppTokenAuthHeaders({
+ *     authApiUrl: HUMAN_AUTH_URL,
+ *     appId: ROOT_APP,
+ *     parentToken: () => getIdToken(),
+ *   }),
+ * });
+ * const stopChat = await mine.subscribe(`conversations/${id}/m`, (d) => render(d));
  * ```
  */
 function createClient(config) {
     if (!config || !config.appId) {
         throw new Error('createClient requires an appId.');
     }
+    // The credential source is an instance concern, not a ClientConfig field: keep
+    // it out of the resolved config so it can never leak through getConfig() or the
+    // `_config` override channel.
+    const { getAuthHeaders } = config, clientFields = __rest$1(config, ["getAuthHeaders"]);
     // Resolve from the PRISTINE defaults (never the mutated global) so a scoped
     // instance is fully independent of any prior init(). Same precedence as init:
     // defaults < network preset < explicit fields.
-    const resolved = resolveClientConfig(DEFAULT_CLIENT_CONFIG, config);
+    const resolved = resolveClientConfig(DEFAULT_CLIENT_CONFIG, clientFields);
+    // Normalize the provider once. Downstream (api.ts, operations.ts,
+    // subscription-v2.ts) consumes the same `_getAuthHeaders` shape a server wallet
+    // client uses, so a null/undefined return becomes "no headers" here rather than
+    // becoming a special case in three transports.
+    const authHeaders = getAuthHeaders
+        ? async () => { var _a; return (_a = (await getAuthHeaders())) !== null && _a !== void 0 ? _a : {}; }
+        : undefined;
+    /** True when the provider currently yields an Authorization header. */
+    const hasCredential = async () => {
+        if (!authHeaders)
+            return false;
+        const headers = await authHeaders();
+        return Object.keys(headers).some((name) => name.toLowerCase() === 'authorization');
+    };
     // The override channel that carries this instance's identity through the
     // shared transport and subscription code. `_config` retargets endpoints +
-    // appId; `_readOnly` omits auth and blocks ambient-session/global-cache reads.
-    const instanceOverrides = () => ({ _config: resolved, _readOnly: true });
+    // appId. Then either `_getAuthHeaders` (this instance's credential is the SOLE
+    // auth source - never the ambient session, and never a managed-credential 401
+    // recovery that could sign another principal out) or `_readOnly` (omit auth and
+    // block ambient-session/global-cache reads).
+    const instanceOverrides = () => authHeaders
+        ? { _config: resolved, _getAuthHeaders: authHeaders }
+        : { _config: resolved, _readOnly: true };
     // Merge caller-supplied opts with the instance overrides. The instance
-    // `_config`/`_readOnly` are applied LAST so app code can never override the
-    // routing/identity of a scoped call (but may still pass e.g. an AbortSignal).
+    // `_config` plus its `_getAuthHeaders`/`_readOnly` are applied LAST so app code
+    // can never override the routing/identity of a scoped call (but may still pass
+    // e.g. an AbortSignal).
     const withOverrides = (opts) => {
         var _a;
         const base = (opts !== null && opts !== void 0 ? opts : {});
@@ -9179,6 +9541,7 @@ function createClient(config) {
     };
     return {
         appId: resolved.appId,
+        authenticated: !!authHeaders,
         getConfig: () => (Object.assign({}, resolved)),
         get: (path, opts) => get(path, withOverrides(opts)),
         getMany: (paths, opts) => getMany(paths, withOverrides(opts)),
@@ -9188,11 +9551,19 @@ function createClient(config) {
         aggregate: (path, operation, opts) => aggregate(path, operation, withOverrides(opts)),
         runQuery: (absolutePath, queryName, queryArgs, opts) => runQuery(absolutePath, queryName, queryArgs, withOverrides(opts)),
         runQueryMany: (many, opts) => runQueryMany(many, withOverrides(opts)),
-        subscribe: (path, options) => {
-            var _a;
+        subscribe: async (path, options) => {
+            var _a, _b;
             const opts = typeof options === 'function' ? { onData: options } : Object.assign({}, options);
-            // Force this instance's scoped, read-only routing onto the subscription.
-            opts._overrides = Object.assign(Object.assign({}, ((_a = opts._overrides) !== null && _a !== void 0 ? _a : {})), { _config: resolved, _readOnly: true });
+            // Force this instance's scoped routing onto the subscription. An
+            // authenticated instance threads its credential provider, which gives the
+            // subscription its own connection keyed by that exact credential; with no
+            // credential right now it subscribes anonymously (the `#ro` socket) instead
+            // of failing, so a signed-out page still gets public data. This is resolved
+            // per subscribe, so the socket a subscription lands on always matches the
+            // credential it was authorized with - including after a shard re-home,
+            // which rebuilds the same routing + auth arguments from the connection.
+            opts._overrides = (await hasCredential())
+                ? Object.assign(Object.assign({}, ((_a = opts._overrides) !== null && _a !== void 0 ? _a : {})), { _config: resolved, _getAuthHeaders: authHeaders }) : Object.assign(Object.assign({}, ((_b = opts._overrides) !== null && _b !== void 0 ? _b : {})), { _config: resolved, _readOnly: true });
             return subscribe(path, opts);
         },
         set: () => { throw new ScopedClientReadOnlyError('set'); },
@@ -9200,6 +9571,264 @@ function createClient(config) {
     };
 }
 
+/**
+ * Second-app tokens: exchange a signed-in app's id token for one pinned to a
+ * DIFFERENT Bounded app the platform records as its child.
+ *
+ * WHY. A browser signed in to app A holds an id token pinned to A
+ * (`custom:appId`), and the realtime data plane refuses it for app B
+ * (`app_mismatch`). When B is a child app of A - an OpenApps agent root under its
+ * venue - the Bounded Auth issuer will mint a short-lived, B-pinned token for the
+ * SAME human at `POST {authApiUrl}/app-token/exchange`. The issuer, not this
+ * helper, decides whether the relationship holds; it reads it from the platform's
+ * own records and refuses anything else. `custom:userId` of the minted token is
+ * the presenting token's own, so B sees the same principal A does.
+ *
+ * WHAT THIS ADDS over a bare POST, all of it in memory and per process:
+ *   - a cache keyed by (exact parent credential, child appId), so one exchange
+ *     serves every read and socket for that pair;
+ *   - refresh shortly BEFORE expiry, driven by use rather than a timer, so no
+ *     interval keeps a process alive and no request ever carries a token that
+ *     expires in flight;
+ *   - single-flight, so N components mounting at once make ONE exchange;
+ *   - BOUNDED retry with backoff and a recorded give-up. A 429 stops the schedule
+ *     immediately rather than feeding it, and so does any other definitive
+ *     refusal. There is no unbounded retry loop anywhere in this module;
+ *   - invalidation on sign-out and identity change: the cache key IS the exact
+ *     parent credential (hashed), so a new session cannot read the old session's
+ *     entry, and `clearAppTokenCache()` drops entries outright.
+ *
+ * The parent token is treated as OPAQUE credential material for keying: it is
+ * hashed, never decoded for identity, and never logged.
+ */
+/** Thrown when an exchange stops trying. `giveUp` carries the recorded reason. */
+class AppTokenExchangeError extends Error {
+    constructor(giveUp) {
+        super(`app token exchange for ${giveUp.appId} gave up after ${giveUp.attempts} attempt(s): ${giveUp.reason}`);
+        this.name = 'AppTokenExchangeError';
+        this.giveUp = giveUp;
+    }
+}
+/** Re-exchange once the remaining life drops under this. */
+const REFRESH_SKEW_MS = 60000;
+/** Floor for a response that reports no usable expiry of its own. */
+const FALLBACK_LIFETIME_MS = 5 * 60000;
+const DEFAULT_MAX_ATTEMPTS = 3;
+const MAX_ATTEMPTS_CEILING = 5;
+const FIRST_RETRY_DELAY_MS = 300;
+const MAX_RETRY_DELAY_MS = 2000;
+const cache = new Map();
+const inFlight = new Map();
+/** Opaque, stable key material for a credential we must never decode or log. */
+function fingerprint(value) {
+    let hash = 5381;
+    for (let index = 0; index < value.length; index++) {
+        hash = ((hash << 5) + hash + value.charCodeAt(index)) >>> 0;
+    }
+    return hash.toString(16);
+}
+function cacheKey(appId, parentToken) {
+    return `${appId}:${fingerprint(parentToken)}`;
+}
+function usable(entry, nowMs) {
+    return !!entry && entry.expiresAtMs - REFRESH_SKEW_MS > nowMs;
+}
+/** Cache entries above which a lookup also drops the expired ones. */
+const PRUNE_THRESHOLD = 32;
+/**
+ * Drop expired entries so a long-lived process (SSR, React Native) that sees a
+ * new parent credential every rotation does not grow this map forever. Keyed by
+ * the exact credential, entries are otherwise only replaced by a same-key refresh.
+ */
+function pruneExpired(nowMs) {
+    if (cache.size <= PRUNE_THRESHOLD)
+        return;
+    for (const [key, entry] of Array.from(cache.entries())) {
+        if (entry.expiresAtMs <= nowMs)
+            cache.delete(key);
+    }
+}
+function exchangeUrl(authApiUrl) {
+    return `${authApiUrl.replace(/\/+$/, '')}/app-token/exchange`;
+}
+/**
+ * When the minted token stops being usable: the issuer's own `expiresAt`, else
+ * the token's `exp`, else a short floor for a token that carries neither.
+ *
+ * Returns null when both stated expiries are already in the PAST. Caching a dead
+ * credential under an invented lifetime would make every request fail for that
+ * long, so an expired mint is a give-up instead.
+ */
+function expiryFromResponse(body, token, nowMs) {
+    const reported = Number(body.expiresAt);
+    if (Number.isFinite(reported))
+        return reported > nowMs ? reported : null;
+    try {
+        const payload = JSON.parse(decodeBase64Url(token.split('.')[1]));
+        const exp = Number(payload.exp);
+        if (Number.isFinite(exp))
+            return exp * 1000 > nowMs ? exp * 1000 : null;
+    }
+    catch (_a) {
+        /* an opaque token is fine; fall through to the floor */
+    }
+    return nowMs + FALLBACK_LIFETIME_MS;
+}
+/** 5xx and transport faults are worth one more try; nothing else is. */
+function retriable(status) {
+    return status === null || (status >= 500 && status !== 501);
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function recordGiveUp(options, giveUp) {
+    var _a;
+    const report = (_a = options.onGiveUp) !== null && _a !== void 0 ? _a : ((info) => console.warn('[bounded] app token exchange gave up', info));
+    try {
+        report(giveUp);
+    }
+    catch (_b) {
+        /* a reporting fault must not replace the exchange failure */
+    }
+    return new AppTokenExchangeError(giveUp);
+}
+async function performExchange(options) {
+    var _a, _b;
+    const attemptCeiling = Math.max(1, Math.min(MAX_ATTEMPTS_CEILING, (_a = options.maxAttempts) !== null && _a !== void 0 ? _a : DEFAULT_MAX_ATTEMPTS));
+    const doFetch = (_b = options.fetchImpl) !== null && _b !== void 0 ? _b : fetch;
+    let retryDelay = FIRST_RETRY_DELAY_MS;
+    let lastStatus = null;
+    let lastReason = 'unknown';
+    for (let attempt = 1; attempt <= attemptCeiling; attempt++) {
+        let status = null;
+        let reason = 'transport_failed';
+        try {
+            const response = await doFetch(exchangeUrl(options.authApiUrl), {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ idToken: options.parentToken, appId: options.appId }),
+            });
+            status = response.status;
+            const body = await response.json().catch(() => ({}));
+            if (response.ok) {
+                const token = typeof body.idToken === 'string' ? body.idToken : '';
+                if (!token) {
+                    throw recordGiveUp(options, { appId: options.appId, status, reason: 'no_token_in_response', attempts: attempt });
+                }
+                const nowMs = Date.now();
+                const expiresAtMs = expiryFromResponse(body, token, nowMs);
+                if (expiresAtMs === null) {
+                    throw recordGiveUp(options, { appId: options.appId, status, reason: 'expired_token_in_response', attempts: attempt });
+                }
+                return { token, expiresAtMs, appId: options.appId };
+            }
+            reason = typeof body.error === 'string' && body.error ? body.error : `http_${status}`;
+        }
+        catch (error) {
+            // A give-up raised above is already final.
+            if (error instanceof AppTokenExchangeError)
+                throw error;
+            status = null;
+            reason = 'transport_failed';
+        }
+        lastStatus = status;
+        lastReason = reason;
+        // A 429 is the issuer telling us to stop. It stops the schedule; it never
+        // feeds it. Every other definitive refusal stops too.
+        if (!retriable(status) || attempt === attemptCeiling) {
+            throw recordGiveUp(options, { appId: options.appId, status, reason, attempts: attempt });
+        }
+        await delay(retryDelay);
+        retryDelay = Math.min(MAX_RETRY_DELAY_MS, retryDelay * 2);
+    }
+    // Unreachable: the loop always returns or throws.
+    throw recordGiveUp(options, { appId: options.appId, status: lastStatus, reason: lastReason, attempts: attemptCeiling });
+}
+/**
+ * Get a child-app id token for the human the parent token belongs to, from cache
+ * when one is still comfortably fresh and otherwise by exchanging once.
+ *
+ * Concurrent callers for the same (parent credential, appId) share one exchange.
+ * On give-up this rejects with {@link AppTokenExchangeError} and caches nothing.
+ */
+async function exchangeAppToken(options) {
+    if (!(options === null || options === void 0 ? void 0 : options.authApiUrl))
+        throw new Error('exchangeAppToken requires an authApiUrl.');
+    if (!(options === null || options === void 0 ? void 0 : options.appId))
+        throw new Error('exchangeAppToken requires an appId.');
+    if (!(options === null || options === void 0 ? void 0 : options.parentToken))
+        throw new Error('exchangeAppToken requires a parentToken.');
+    const key = cacheKey(options.appId, options.parentToken);
+    pruneExpired(Date.now());
+    const cached = cache.get(key);
+    if (usable(cached, Date.now()))
+        return cached;
+    // Past the refresh skew the entry is no longer served; drop it so a failed
+    // refresh can never fall back to a token that is about to expire mid-request.
+    if (cached)
+        cache.delete(key);
+    const active = inFlight.get(key);
+    if (active)
+        return active;
+    const flight = performExchange(options).then((token) => {
+        cache.set(key, token);
+        return token;
+    }).finally(() => {
+        if (inFlight.get(key) === flight)
+            inFlight.delete(key);
+    });
+    inFlight.set(key, flight);
+    return flight;
+}
+/**
+ * Drop cached child-app tokens. Call this on sign-out; an identity change needs
+ * no call, because the cache key is the exact parent credential.
+ *
+ * With no argument every entry goes. `appId` narrows to one child app, and
+ * `parentToken` narrows to one session's entries.
+ */
+function clearAppTokenCache(scope) {
+    if (!scope || (!scope.appId && !scope.parentToken)) {
+        cache.clear();
+        inFlight.clear();
+        return;
+    }
+    if (scope.appId && scope.parentToken) {
+        const key = cacheKey(scope.appId, scope.parentToken);
+        cache.delete(key);
+        inFlight.delete(key);
+        return;
+    }
+    const prefix = scope.appId ? `${scope.appId}:` : null;
+    const suffix = scope.parentToken ? `:${fingerprint(scope.parentToken)}` : null;
+    for (const key of Array.from(cache.keys())) {
+        if ((prefix && key.startsWith(prefix)) || (suffix && key.endsWith(suffix)))
+            cache.delete(key);
+    }
+    for (const key of Array.from(inFlight.keys())) {
+        if ((prefix && key.startsWith(prefix)) || (suffix && key.endsWith(suffix)))
+            inFlight.delete(key);
+    }
+}
+/**
+ * Build the `getAuthHeaders` a scoped `createClient({ appId, getAuthHeaders })`
+ * instance authenticates with, backed by {@link exchangeAppToken}.
+ *
+ * Signed out (`parentToken()` yields nothing) returns NO headers, which leaves
+ * the scoped instance anonymous - the public read lane - instead of failing. A
+ * give-up on the exchange itself rejects, so a broken exchange surfaces as an
+ * error rather than as silently unauthenticated reads.
+ */
+function createAppTokenAuthHeaders(options) {
+    return async () => {
+        const parentToken = await options.parentToken();
+        if (!parentToken)
+            return {};
+        const minted = await exchangeAppToken(Object.assign(Object.assign({}, options), { parentToken }));
+        return { Authorization: `Bearer ${minted.token}` };
+    };
+}
+
 /**
  * Live named-query subscriptions (subscribeQuery) - HTTP client poller (v1).
  *
@@ -9902,7 +10531,7 @@ function toMillis(seconds) {
 
 /** SIWS message creation is async already, so its onchain module can be lazy. */
 async function genSolanaMessage(address, nonce) {
-    const implementation = await import('./solana-message-BGkYFU3C.mjs');
+    const implementation = await import('./solana-message-C_717vAx.mjs');
     return implementation.genSolanaMessage(address, nonce);
 }
 
@@ -10451,5 +11080,5 @@ function defineLiveModule(mod) {
     return mod;
 }
 
-export { getIdToken as $, subscribe as A, closeAllSubscriptions as B, clearCache as C, getCachedData as D, reconnectWithNewAuth as E, createClient as F, ScopedClientReadOnlyError as G, subscribeQuery as H, InsufficientBalanceError as I, closeAllQuerySubscriptions as J, canonicalizeArgs as K, canonicalizeResult as L, DEFAULT_QUERY_POLL_INTERVAL_MS as M, MIN_QUERY_POLL_INTERVAL_MS as N, BoundedDeclineError as O, deriveDecline as P, dispatchDeclineEvent as Q, DECLINE_EVENT_NAME as R, SOLANA_MAX_SUPPORTED_TRANSACTION_VERSION as S, dispatchRateLimitEvent as T, RATE_LIMIT_EVENT_NAME as U, hasActiveConnection as V, increment as W, serverTimestamp as X, now as Y, toSeconds as Z, toMillis as _, getTransactionJson as a, deriveUserIdentityFromIdToken as a0, getSessionGeneration as a1, WebSessionManager as a2, ReactNativeSessionManager as a3, getActiveSessionManager as a4, onSessionCleared as a5, SessionEnvironmentError as a6, UNSUPPORTED_ENVIRONMENT_CODE as a7, AUTH_CHANGED_CODE as a8, AUTH_EXPIRED_CODE as a9, withEffects as aA, isEffectResult as aB, defineLiveModule as aC, EFFECT_INTENT_ADDRESS as aD, isAuthExpiredError as aa, getFreshAuthToken as ab, ServerSessionManager as ac, createSessionWithSignature as ad, refreshSession as ae, revokeSession as af, signSessionCreateMessage as ag, genAuthNonce as ah, genSolanaMessage as ai, createSolanaSignInRequest as aj, createSolanaSignInMessageText as ak, genSolanaSignInRequest as al, genSolanaSignInMessage as am, browserSignInDomain as an, SOLANA_SIGN_IN_STATEMENT as ao, genSiweMessage as ap, normalizeEvmAddress as aq, toLowerEvmAddress as ar, functions as as, invoke as at, FunctionInvokeError as au, live as av, intent as aw, status as ax, subscribeView as ay, LiveIntentError as az, bufferExports as b, getWebhookKeysUrl as c, getConfiguredAppId as d, get as e, getMany as f, getConfig as g, docId as h, init as i, setMany as j, setFile as k, getFiles as l, search as m, runQueryMany as n, runExpression as o, runExpressionMany as p, queryAggregate as q, runQuery as r, set as s, signMessage as t, signTransaction as u, signAndSubmitTransaction as v, count as w, aggregate as x, reconcileSetResult as y, waitForSetResult as z };
-//# sourceMappingURL=index-DW5yMQwV.mjs.map
+export { serverTimestamp as $, subscribe as A, closeAllSubscriptions as B, clearCache as C, getCachedData as D, reconnectWithNewAuth as E, createClient as F, ScopedClientReadOnlyError as G, exchangeAppToken as H, InsufficientBalanceError as I, clearAppTokenCache as J, createAppTokenAuthHeaders as K, AppTokenExchangeError as L, subscribeQuery as M, closeAllQuerySubscriptions as N, canonicalizeArgs as O, canonicalizeResult as P, DEFAULT_QUERY_POLL_INTERVAL_MS as Q, MIN_QUERY_POLL_INTERVAL_MS as R, SOLANA_MAX_SUPPORTED_TRANSACTION_VERSION as S, BoundedDeclineError as T, deriveDecline as U, dispatchDeclineEvent as V, DECLINE_EVENT_NAME as W, dispatchRateLimitEvent as X, RATE_LIMIT_EVENT_NAME as Y, hasActiveConnection as Z, increment as _, getTransactionJson as a, now as a0, toSeconds as a1, toMillis as a2, getIdToken as a3, deriveUserIdentityFromIdToken as a4, getSessionGeneration as a5, WebSessionManager as a6, ReactNativeSessionManager as a7, getActiveSessionManager as a8, onSessionCleared as a9, intent as aA, status as aB, subscribeView as aC, LiveIntentError as aD, withEffects as aE, isEffectResult as aF, defineLiveModule as aG, EFFECT_INTENT_ADDRESS as aH, SessionEnvironmentError as aa, UNSUPPORTED_ENVIRONMENT_CODE as ab, AUTH_CHANGED_CODE as ac, AUTH_EXPIRED_CODE as ad, isAuthExpiredError as ae, getFreshAuthToken as af, ServerSessionManager as ag, createSessionWithSignature as ah, refreshSession as ai, revokeSession as aj, signSessionCreateMessage as ak, genAuthNonce as al, genSolanaMessage as am, createSolanaSignInRequest as an, createSolanaSignInMessageText as ao, genSolanaSignInRequest as ap, genSolanaSignInMessage as aq, browserSignInDomain as ar, SOLANA_SIGN_IN_STATEMENT as as, genSiweMessage as at, normalizeEvmAddress as au, toLowerEvmAddress as av, functions as aw, invoke as ax, FunctionInvokeError as ay, live as az, bufferExports as b, getWebhookKeysUrl as c, getConfiguredAppId as d, get as e, getMany as f, getConfig as g, docId as h, init as i, setMany as j, setFile as k, getFiles as l, search as m, runQueryMany as n, runExpression as o, runExpressionMany as p, queryAggregate as q, runQuery as r, set as s, signMessage as t, signTransaction as u, signAndSubmitTransaction as v, count as w, aggregate as x, reconcileSetResult as y, waitForSetResult as z };
+//# sourceMappingURL=index-CMT0saxy.mjs.map