@bounded-sh/core 0.0.100-performance.1 → 0.0.101

package/dist/{index-B8PpRj6x.js → index-BEGeDFQI.js}

@@ -4190,7 +4190,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 Promise.resolve().then(function () { return require('./solana-message-w2FxOkFA.js'); });
+        const { genSolanaMessage } = await Promise.resolve().then(function () { return require('./solana-message-CJTnYiJu.js'); });
         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);
@@ -5282,6 +5282,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,
@@ -5302,6 +5333,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++) {
@@ -5321,7 +5372,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}`;
@@ -5650,18 +5705,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;
@@ -5725,9 +5838,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;
@@ -5749,7 +5862,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
@@ -5762,15 +5875,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;
@@ -5781,7 +5973,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;
@@ -5795,8 +5987,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;
@@ -5871,6 +6066,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,
@@ -6171,6 +6369,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') }`
@@ -6179,6 +6387,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)
@@ -6354,6 +6567,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)
@@ -6447,6 +6677,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)
@@ -6542,7 +6862,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.
@@ -6581,16 +6901,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));
@@ -6601,34 +6957,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;
@@ -6711,8 +7039,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,
@@ -6721,6 +7050,7 @@ async function subscribeV2(path, subscriptionOptions, roomRoutePath) {
             identity,
             identityToken,
             specKey,
+            rehomeAttempts: 0,
         };
         connection.subscriptions.set(subscriptionId, subscription);
     }
@@ -6794,15 +7124,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;
@@ -6968,7 +7304,7 @@ async function doReconnectWithNewAuth() {
         console.warn('[WS v2] Failed to clear HTTP read cache on auth change:', error);
     }
     try {
-        const { reconnectRealtimeStoreWithNewAuth } = await Promise.resolve().then(function () { return require('./realtime-store-D7mJ7rTj.js'); });
+        const { reconnectRealtimeStoreWithNewAuth } = await Promise.resolve().then(function () { return require('./realtime-store-DrtEj-bE.js'); });
         await reconnectRealtimeStoreWithNewAuth();
     }
     catch (error) {
@@ -7043,8 +7379,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)) {
@@ -7094,9 +7432,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
@@ -7126,6 +7463,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;
     }
@@ -7163,9 +7503,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))) {
@@ -8419,7 +8758,7 @@ async function setMany(many, options) {
                         'Nothing was signed or submitted.');
                 }
                 const solanaChain = workerChain;
-                const { handlePreBuiltTransaction, buildExpectedWriteIntent } = await Promise.resolve().then(function () { return require('./solana-operations-DJQDYdrk.js'); });
+                const { handlePreBuiltTransaction, buildExpectedWriteIntent } = await Promise.resolve().then(function () { return require('./solana-operations-CU0YbiMu.js'); });
                 // 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
@@ -8783,7 +9122,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;
@@ -8990,7 +9329,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;
@@ -9108,72 +9447,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 : {});
@@ -9181,6 +9543,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)),
@@ -9190,11 +9553,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'); },
@@ -9202,6 +9573,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).
  *
@@ -9904,7 +10533,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 Promise.resolve().then(function () { return require('./solana-message-w2FxOkFA.js'); });
+    const implementation = await Promise.resolve().then(function () { return require('./solana-message-CJTnYiJu.js'); });
     return implementation.genSolanaMessage(address, nonce);
 }
 
@@ -10455,6 +11084,7 @@ function defineLiveModule(mod) {
 
 exports.AUTH_CHANGED_CODE = AUTH_CHANGED_CODE;
 exports.AUTH_EXPIRED_CODE = AUTH_EXPIRED_CODE;
+exports.AppTokenExchangeError = AppTokenExchangeError;
 exports.BoundedDeclineError = BoundedDeclineError;
 exports.DECLINE_EVENT_NAME = DECLINE_EVENT_NAME;
 exports.DEFAULT_QUERY_POLL_INTERVAL_MS = DEFAULT_QUERY_POLL_INTERVAL_MS;
@@ -10477,10 +11107,12 @@ exports.browserSignInDomain = browserSignInDomain;
 exports.bufferExports = bufferExports;
 exports.canonicalizeArgs = canonicalizeArgs;
 exports.canonicalizeResult = canonicalizeResult;
+exports.clearAppTokenCache = clearAppTokenCache;
 exports.clearCache = clearCache;
 exports.closeAllQuerySubscriptions = closeAllQuerySubscriptions;
 exports.closeAllSubscriptions = closeAllSubscriptions;
 exports.count = count;
+exports.createAppTokenAuthHeaders = createAppTokenAuthHeaders;
 exports.createClient = createClient;
 exports.createSessionWithSignature = createSessionWithSignature;
 exports.createSolanaSignInMessageText = createSolanaSignInMessageText;
@@ -10491,6 +11123,7 @@ exports.deriveUserIdentityFromIdToken = deriveUserIdentityFromIdToken;
 exports.dispatchDeclineEvent = dispatchDeclineEvent;
 exports.dispatchRateLimitEvent = dispatchRateLimitEvent;
 exports.docId = docId;
+exports.exchangeAppToken = exchangeAppToken;
 exports.functions = functions;
 exports.genAuthNonce = genAuthNonce;
 exports.genSiweMessage = genSiweMessage;
@@ -10547,4 +11180,4 @@ exports.toMillis = toMillis;
 exports.toSeconds = toSeconds;
 exports.waitForSetResult = waitForSetResult;
 exports.withEffects = withEffects;
-//# sourceMappingURL=index-B8PpRj6x.js.map
+//# sourceMappingURL=index-BEGeDFQI.js.map