@bounded-sh/core 0.0.40 → 0.0.42

package/dist/index.js

@@ -2929,7 +2929,14 @@ async function revokeSession(refreshToken, issuer) {
         await axios.post(`${base}/session/revoke`, {
             refreshToken,
             appId: config.appId,
-        }, { headers: { 'Content-Type': 'application/json' }, timeout: 15000 });
+        }, {
+            headers: { 'Content-Type': 'application/json' },
+            timeout: 15000,
+            // Preserve the transport error for programmatic diagnostics while
+            // ensuring AxiosError.toJSON() cannot serialize the live token body
+            // into logs, telemetry, UI state, or crash reports.
+            redact: ['data'],
+        });
     }
     catch (err) {
         throw new SessionRevokeError(revokeFailureMessage(err), err);
@@ -4155,12 +4162,21 @@ class InsufficientBalanceError extends Error {
         this.deficitSol = deficitSol;
     }
 }
-// Cache for get responses
 const getCache = {};
-// Track in-flight requests to coalesce multiple identical requests
 const pendingRequests = {};
 // Default cache TTL (500ms = 0.5 seconds)
 const GET_CACHE_TTL = 500; // Adjust this value as needed (in milliseconds)
+function getReadCacheEntry(cacheKey, principalValue) {
+    var _a;
+    return (_a = getCache[cacheKey]) === null || _a === void 0 ? void 0 : _a.find(entry => entry.principalValue === principalValue);
+}
+function setReadCacheEntry(cacheKey, principalValue, data, expiresAt) {
+    var _a;
+    const bucket = (_a = getCache[cacheKey]) !== null && _a !== void 0 ? _a : [];
+    const reusableEntries = bucket.filter(entry => (entry.principalValue !== principalValue && entry.expiresAt >= Date.now()));
+    reusableEntries.push({ data, expiresAt, principalValue });
+    getCache[cacheKey] = reusableEntries;
+}
 // Last time we cleaned up the cache
 let lastCacheCleanup = Date.now();
 let uncacheableReadKeyCounter = 0;
@@ -4291,32 +4307,34 @@ async function getReadPrincipalKey(overrides) {
     // makeApiRequest applies overrides.headers AFTER its computed auth header, so
     // caller-supplied Authorization is the real request auth when present.
     if (hasAuthHeader(overrides === null || overrides === void 0 ? void 0 : overrides.headers)) {
-        const principal = principalFromAuthValue(authValueFromHeaders(overrides === null || overrides === void 0 ? void 0 : overrides.headers));
+        const authValue = authValueFromHeaders(overrides === null || overrides === void 0 ? void 0 : overrides.headers);
+        const principal = principalFromAuthValue(authValue);
         return principal
-            ? { key: `${appId}:${principal}`, cacheable: true }
-            : { key: uncacheableReadKey(appId, 'h'), cacheable: false };
+            ? { key: `${appId}:${principal}`, cacheable: true, principalValue: authValue }
+            : { key: uncacheableReadKey(appId, 'h'), cacheable: false, principalValue: null };
     }
     // Per-request auth-header override (wallet client). Key by the exact opaque
     // header it produces, not decoded claims or the unverified _walletAddress hint.
     if (overrides === null || overrides === void 0 ? void 0 : overrides._getAuthHeaders) {
         try {
             const headers = await overrides._getAuthHeaders();
-            const principal = principalFromAuthValue(authValueFromHeaders(headers));
+            const authValue = authValueFromHeaders(headers);
+            const principal = principalFromAuthValue(authValue);
             return principal
-                ? { key: `${appId}:o${principal}`, cacheable: true }
-                : { key: uncacheableReadKey(appId, 'o'), cacheable: false };
+                ? { key: `${appId}:o${principal}`, cacheable: true, principalValue: authValue }
+                : { key: uncacheableReadKey(appId, 'o'), cacheable: false, principalValue: null };
         }
         catch (_a) {
             // If we can't resolve the override identity, do not read/write cache.
-            return { key: uncacheableReadKey(appId, 'o'), cacheable: false };
+            return { key: uncacheableReadKey(appId, 'o'), cacheable: false, principalValue: null };
         }
     }
     // Ambient session principal.
     const idToken = await getIdToken(config.isServer);
     const principal = principalFromIdToken$1(idToken);
     return principal
-        ? { key: `${appId}:${principal}`, cacheable: true }
-        : { key: uncacheableReadKey(appId, 'a'), cacheable: false };
+        ? { key: `${appId}:${principal}`, cacheable: true, principalValue: idToken !== null && idToken !== void 0 ? idToken : null }
+        : { key: uncacheableReadKey(appId, 'a'), cacheable: false, principalValue: null };
 }
 /**
  * Validates that a field name is a safe identifier (alphanumeric, underscores, dots for nested paths).
@@ -4597,6 +4615,7 @@ async function search(path, query, opts = {}) {
     return response.data;
 }
 async function get(path, opts = {}) {
+    var _a, _b;
     try {
         let normalizedPath = path.startsWith("/") ? path.slice(1) : path;
         // Remove last '*' if it exists in the path
@@ -4607,7 +4626,8 @@ async function get(path, opts = {}) {
             throw new Error("Invalid path provided.");
         }
         // Create cache key combining path, prompt, filter, sort, includeSubPaths,
-        // shape, limit, cursor — and (H1) the caller's appId + principal fingerprint,
+        // shape, limit, cursor — and (H1) the caller's appId + compact principal
+        // bucket. Exact opaque credential equality is checked inside that bucket,
         // so a private read cached for one user is never served to another in a
         // shared process / SSR worker / browser login-switch. The cache is opt-in
         // and disabled for no-auth reads, which get an uncacheable unique key.
@@ -4622,20 +4642,25 @@ async function get(path, opts = {}) {
         const cacheEnabled = opts.cache === true && !opts.bypassCache && principalKey.cacheable;
         const now = Date.now();
         // Check for valid cache entry when the caller explicitly opted in.
-        if (cacheEnabled && getCache[cacheKey] && now < getCache[cacheKey].expiresAt) {
-            return getCache[cacheKey].data;
+        const cachedEntry = getReadCacheEntry(cacheKey, principalKey.principalValue);
+        if (cacheEnabled &&
+            cachedEntry &&
+            now < cachedEntry.expiresAt) {
+            return cachedEntry.data;
         }
         // If we're bypassing cache, we should still coalesce identical requests
         // but need a different key to avoid interfering with regular requests
         const requestKey = opts.bypassCache ? `bypass:${cacheKey}` : cacheKey;
-        // Check if there's already an in-flight request for this key
-        // Fix for TS error - use hasOwnProperty to explicitly check if key exists
-        if (Object.prototype.hasOwnProperty.call(pendingRequests, requestKey)) {
-            // Return the existing promise to coalesce requests
-            return pendingRequests[requestKey];
+        // The compact principal hash is only an index bucket. Coalesce only when
+        // the exact opaque credential also matches, so collisions stay isolated.
+        const existingPending = (_a = pendingRequests[requestKey]) === null || _a === void 0 ? void 0 : _a.find(entry => entry.principalValue === principalKey.principalValue);
+        if (existingPending) {
+            return existingPending.promise;
         }
         // Create a new request promise and store it
-        const requestPromise = (async () => {
+        let requestPromise;
+        requestPromise = (async () => {
+            var _a;
             try {
                 const pathIsDocument = normalizedPath.split("/").length % 2 === 0;
                 // Cache miss or bypass - proceed with HTTP API request
@@ -4666,10 +4691,7 @@ async function get(path, opts = {}) {
                 const responseData = normalizeReadResult(response.data, pathIsDocument);
                 // Cache the response only when explicitly requested and principal-bound.
                 if (cacheEnabled) {
-                    getCache[cacheKey] = {
-                        data: responseData,
-                        expiresAt: now + GET_CACHE_TTL
-                    };
+                    setReadCacheEntry(cacheKey, principalKey.principalValue, responseData, now + GET_CACHE_TTL);
                     // Periodically clean up expired cache entries (every 5 seconds)
                     if (now - lastCacheCleanup > 5000) {
                         cleanupExpiredCache();
@@ -4680,12 +4702,21 @@ async function get(path, opts = {}) {
                 return responseData;
             }
             finally {
-                // Remove this request from pendingRequests regardless of success/failure
-                delete pendingRequests[requestKey];
+                // Remove only this exact request. A colliding principal can legitimately
+                // have another request in the same compact-hash bucket.
+                const bucket = pendingRequests[requestKey];
+                const index = (_a = bucket === null || bucket === void 0 ? void 0 : bucket.findIndex(entry => entry.promise === requestPromise)) !== null && _a !== void 0 ? _a : -1;
+                if (index >= 0)
+                    bucket.splice(index, 1);
+                if ((bucket === null || bucket === void 0 ? void 0 : bucket.length) === 0)
+                    delete pendingRequests[requestKey];
             }
         })();
-        // Store the promise so other calls can join it
-        pendingRequests[requestKey] = requestPromise;
+        // Store the promise so only callers with the exact same credential join it.
+        ((_b = pendingRequests[requestKey]) !== null && _b !== void 0 ? _b : (pendingRequests[requestKey] = [])).push({
+            principalValue: principalKey.principalValue,
+            promise: requestPromise,
+        });
         // Return the promise
         return requestPromise;
     }
@@ -4697,9 +4728,12 @@ async function get(path, opts = {}) {
 function cleanupExpiredCache() {
     const now = Date.now();
     Object.keys(getCache).forEach(key => {
-        if (getCache[key] && getCache[key].expiresAt < now) {
+        var _a, _b;
+        const activeEntries = (_b = (_a = getCache[key]) === null || _a === void 0 ? void 0 : _a.filter(entry => entry.expiresAt >= now)) !== null && _b !== void 0 ? _b : [];
+        if (activeEntries.length > 0)
+            getCache[key] = activeEntries;
+        else
             delete getCache[key];
-        }
     });
     lastCacheCleanup = now;
 }
@@ -4961,8 +4995,11 @@ async function getMany(paths, opts = {}) {
     for (let i = 0; i < normalizedPaths.length; i++) {
         const normalizedPath = normalizedPaths[i];
         const cacheKey = `${principalKey.key}|${normalizedPath}:`;
-        if (cacheEnabled && getCache[cacheKey] && now < getCache[cacheKey].expiresAt) {
-            results[i] = { path: normalizedPath, data: getCache[cacheKey].data };
+        const cachedEntry = getReadCacheEntry(cacheKey, principalKey.principalValue);
+        if (cacheEnabled &&
+            cachedEntry &&
+            now < cachedEntry.expiresAt) {
+            results[i] = { path: normalizedPath, data: cachedEntry.data };
         }
         else {
             uncachedIndices.push(i);
@@ -4999,10 +5036,7 @@ async function getMany(paths, opts = {}) {
                     results[originalIndex] = normalizedResult;
                     if (!normalizedResult.error && cacheEnabled) {
                         const cacheKey = `${principalKey.key}|${normalizedPath}:`;
-                        getCache[cacheKey] = {
-                            data: normalizedResult.data,
-                            expiresAt: now + GET_CACHE_TTL
-                        };
+                        setReadCacheEntry(cacheKey, principalKey.principalValue, normalizedResult.data, now + GET_CACHE_TTL);
                     }
                 }
                 else {
@@ -5032,10 +5066,27 @@ async function getMany(paths, opts = {}) {
     return results;
 }
 async function runQuery(absolutePath, queryName, queryArgs, opts) {
-    const result = await runQueryMany([{ absolutePath, queryName, queryArgs }], opts);
-    return result[0];
+    var _a;
+    const rows = await runQueryManyRows([{ absolutePath, queryName, queryArgs }], opts);
+    const row = rows[0];
+    // The worker disambiguates a computed null from a failed/undeclared query
+    // with a per-row `error` string — surface it instead of returning undefined.
+    if ((row === null || row === void 0 ? void 0 : row.error) != null) {
+        const err = new Error(String(row.error));
+        err.isQueryError = true;
+        err.queryName = queryName;
+        err.path = absolutePath;
+        throw err;
+    }
+    return (_a = row === null || row === void 0 ? void 0 : row.result) !== null && _a !== void 0 ? _a : null;
 }
 async function runQueryMany(many, opts) {
+    // Batch shape stays an array of result values (errored rows map to null) so
+    // existing callers keep working; use runQuery for per-row error surfacing.
+    const rows = await runQueryManyRows(many, opts);
+    return rows.map((row) => { var _a; return (_a = row === null || row === void 0 ? void 0 : row.result) !== null && _a !== void 0 ? _a : null; });
+}
+async function runQueryManyRows(many, opts) {
     var _a, _b, _c, _d;
     try {
         let queries = [];
@@ -5057,7 +5108,7 @@ async function runQueryMany(many, opts) {
         if (!Array.isArray(rows)) {
             throw new Error(`queries endpoint returned an unexpected response shape (status ${response.status})`);
         }
-        return rows.map((result) => result.result);
+        return rows;
     }
     catch (error) {
         throw error;
@@ -5095,6 +5146,11 @@ async function runExpressionMany(many) {
             if (queryResult.trace) {
                 result.trace = queryResult.trace;
             }
+            // Pass through the server's per-row failure so callers can distinguish
+            // a computed null from a failed row.
+            if (queryResult.error != null) {
+                result.error = String(queryResult.error);
+            }
             return result;
         });
     }
@@ -5547,10 +5603,37 @@ var operations = /*#__PURE__*/Object.freeze({
 // ============ Global State ============
 // One connection per routing target (appId, or appId#room#<collection>/<roomId>)
 const connections = new Map();
+// Coalesce concurrent first-use/auth-preflight calls for the same routing target.
+// React commonly mounts several subscriptions in one render; without this map,
+// every call can pass the empty `connections` check, await auth, and create an
+// orphan ReconnectingWebSocket before the first call publishes its connection.
+// Keyed by the identity-bucket lease key (see connectionLeaseKey) so two distinct
+// wallet tokens never share one in-flight socket even under a compact-hash collision.
+const connectionFlights = new Map();
+// A subscriber holds a routing-target lease from connection acquisition until
+// its callback/subscription is registered. The last old-route unsubscribe must
+// not close a connection already captured by a new route awaiting auth. Keyed by
+// the same identity-bucket lease key as connectionFlights.
+const connectionAcquisitions = new Map();
+// Compact identity hashes remain useful bounded-size indexes, but collisions
+// share a bucket instead of sharing authority. Each exact bearer keeps its own
+// cache entry so collision isolation does not evict another principal's cache.
 const responseCache = new Map();
 const CACHE_TTL = 5 * 60 * 1000; // 5 minutes
 const TOKEN_REFRESH_BUFFER = 10 * 60 * 1000; // Refresh token 10 minutes before expiry
 const TOKEN_CHECK_INTERVAL = 5 * 60 * 1000; // Check token freshness every 5 minutes
+function getResponseCacheEntry(cacheKey, identityToken) {
+    var _a;
+    return (_a = responseCache.get(cacheKey)) === null || _a === void 0 ? void 0 : _a.find(entry => entry.identityToken === identityToken);
+}
+function setResponseCacheEntry(cacheKey, identityToken, data) {
+    var _a;
+    const now = Date.now();
+    const bucket = (_a = responseCache.get(cacheKey)) !== null && _a !== void 0 ? _a : [];
+    const reusableEntries = bucket.filter(entry => (entry.identityToken !== identityToken && now - entry.timestamp < CACHE_TTL));
+    reusableEntries.push({ data, timestamp: now, identityToken });
+    responseCache.set(cacheKey, reusableEntries);
+}
 // ============ WebSocket Config ============
 const BASE_MIN_RECONNECT_DELAY_MS = 1000;
 const MIN_RECONNECT_DELAY_JITTER_MS = 1000;
@@ -5558,6 +5641,10 @@ const MAX_RECONNECT_DELAY_MS = 300000;
 const RECONNECT_DELAY_GROW_FACTOR = 1.8;
 const MIN_BROWSER_RECONNECT_INTERVAL_MS = 5000;
 const WS_AUTH_EXPIRED_CODE = 'auth_expired';
+// React runs old-route effect cleanup before new-route effects. Keep an
+// otherwise-idle socket for one short handoff window so the new route can
+// cancel teardown and reuse it; genuinely idle sockets still close promptly.
+const IDLE_CONNECTION_CLOSE_GRACE_MS = 1000;
 const WS_CONFIG = {
     // Keep retrying indefinitely so long outages recover without page refresh.
     maxRetries: Infinity,
@@ -5588,12 +5675,12 @@ function hashForKey(value) {
 }
 /**
  * SECURITY (H1): Response-cache keys must be scoped to the caller's identity, not
- * just the path/filter/shape. The `identity` prefix (`<appId>:<principal>`) keeps
- * a private subscription snapshot cached for one user from being delivered to a
- * different user who subscribes with the same options (shared process / SSR worker
- * / browser login-switch; this cache has a 5-minute TTL). Callers must opt in
- * before entries are read or written; no-auth subscriptions never populate an
- * implicit anonymous cache bucket.
+ * just the path/filter/shape. The compact `identity` prefix selects a bucket;
+ * exact opaque bearer equality is required inside it before reuse. Together they
+ * keep a private snapshot from being delivered to a different user with the same
+ * options (shared process / SSR worker / browser login-switch; this cache has a
+ * 5-minute TTL). Callers must opt in before entries are read or written; no-auth
+ * subscriptions never populate an implicit anonymous cache bucket.
  */
 function getCacheKey(path, prompt, shape, limit, cursor, filter, identity) {
     const normalizedPath = path.startsWith('/') ? path.slice(1) : path;
@@ -5631,16 +5718,16 @@ function livePrincipalFromIdToken(idToken) {
 }
 function authSnapshotFromToken(idToken) {
     return {
-        tokenFingerprint: principalFromIdToken(idToken),
+        tokenValue: idToken !== null && idToken !== void 0 ? idToken : null,
         principal: livePrincipalFromIdToken(idToken),
     };
 }
 function connectionMatchesAuthToken(connection, idToken) {
     const current = authSnapshotFromToken(idToken);
-    if (!current.tokenFingerprint) {
-        return connection.authTokenFingerprint === null && connection.authPrincipal === null;
+    if (!current.tokenValue) {
+        return connection.authTokenValue === null && connection.authPrincipal === null;
     }
-    if (connection.authTokenFingerprint && connection.authTokenFingerprint === current.tokenFingerprint) {
+    if (connection.authTokenValue && connection.authTokenValue === current.tokenValue) {
         return true;
     }
     return !!connection.authPrincipal && !!current.principal && connection.authPrincipal === current.principal;
@@ -5649,7 +5736,7 @@ async function canSendAuthenticatedLiveIntent(connection, isServer) {
     const currentToken = await getIdToken(isServer);
     if (!currentToken)
         return false;
-    if (!connection.authTokenFingerprint && !connection.authPrincipal)
+    if (!connection.authTokenValue && !connection.authPrincipal)
         return false;
     return connectionMatchesAuthToken(connection, currentToken);
 }
@@ -5662,19 +5749,19 @@ async function getSubscriptionIdentity(effectiveAppId, isServer, overrides) {
             const bearer = bearerFromAuthHeaders(await overrides._getAuthHeaders());
             const principal = principalFromIdToken(bearer);
             return principal
-                ? { key: `${effectiveAppId}:o${principal}`, cacheable: true }
-                : { key: `${effectiveAppId}:oanon`, cacheable: false };
+                ? { key: `${effectiveAppId}:o${principal}`, cacheable: true, token: bearer }
+                : { key: `${effectiveAppId}:oanon`, cacheable: false, token: null };
         }
         catch (_a) {
             // Couldn't resolve the override identity — do not use response cache.
-            return { key: `${effectiveAppId}:o-uncacheable-${safeBtoa(String(connectionEpoch++))}`, cacheable: false };
+            return { key: `${effectiveAppId}:o-uncacheable-${safeBtoa(String(connectionEpoch++))}`, cacheable: false, token: null };
         }
     }
     const idToken = await getIdToken(isServer);
     const principal = principalFromIdToken(idToken);
     return principal
-        ? { key: `${effectiveAppId}:${principal}`, cacheable: true }
-        : { key: `${effectiveAppId}:anon`, cacheable: false };
+        ? { key: `${effectiveAppId}:${principal}`, cacheable: true, token: idToken !== null && idToken !== void 0 ? idToken : null }
+        : { key: `${effectiveAppId}:anon`, cacheable: false, token: null };
 }
 /** Extract the bare bearer token from a `{ Authorization: 'Bearer <jwt>' }` map. */
 function bearerFromAuthHeaders(headers) {
@@ -5730,7 +5817,7 @@ function failConnectionAuth(connection, error) {
     connection.authFailure = error;
     connection.pendingAuthToken = null;
     connection.pendingAuthSnapshot = null;
-    connection.authTokenFingerprint = null;
+    connection.authTokenValue = null;
     connection.authPrincipal = null;
     connection.isConnecting = false;
     connection.isConnected = false;
@@ -5741,6 +5828,7 @@ function failConnectionAuth(connection, error) {
     connection.pendingSubscriptions.clear();
     for (const subscription of connection.subscriptions.values()) {
         notifyErrorCallbacks(subscription, error);
+        rejectSubscriptionRefresh(subscription, error);
     }
 }
 function scheduleTokenRefresh(connection, isServer) {
@@ -5933,7 +6021,136 @@ function replaySubscriptions(connection) {
         sendSubscribe(connection, sub);
     }
 }
-async function getOrCreateConnection(appId, isServer, routePath, authTokenProvider, principalKey) {
+/**
+ * Derive the stable identity-bucket lease key used to coalesce (singleflight)
+ * and refcount (acquisition / idle-close) connection use. Ambient app/room
+ * 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.
+ */
+function connectionLeaseKey(appId, routePath, principalKey, principalToken) {
+    const roomKey = roomKeyFromRoutePath(routePath);
+    const base = roomKey ? `${appId}#room#${roomKey}` : appId;
+    if (!principalKey)
+        return base;
+    const bucket = `${base}#id#${principalKey}`;
+    return principalToken ? `${bucket}#tok#${principalToken}` : bucket;
+}
+function cancelIdleConnectionClose(connection) {
+    if (!connection.idleCloseTimer)
+        return;
+    clearTimeout(connection.idleCloseTimer);
+    connection.idleCloseTimer = null;
+}
+function closeConnectionNow(connection) {
+    if (connections.get(connection.key) !== connection)
+        return;
+    if (!connection.ws)
+        return;
+    cancelIdleConnectionClose(connection);
+    if (connection.tokenRefreshTimer) {
+        clearInterval(connection.tokenRefreshTimer);
+        connection.tokenRefreshTimer = null;
+    }
+    const ws = connection.ws;
+    connection.ws = null;
+    connection.isConnecting = false;
+    connection.isConnected = false;
+    connection.isAuthenticating = false;
+    const closeError = new Error('WebSocket connection closed');
+    for (const subscription of connection.subscriptions.values()) {
+        rejectSubscriptionRefresh(subscription, closeError);
+    }
+    connections.delete(connection.key);
+    try {
+        ws.close();
+    }
+    catch ( /* already closing */_a) { /* already closing */ }
+}
+function scheduleConnectionCloseIfIdle(connection) {
+    var _a;
+    if (connections.get(connection.key) !== connection)
+        return;
+    if (connection.subscriptions.size > 0)
+        return;
+    if (((_a = connectionAcquisitions.get(connection.acquisitionKey)) !== null && _a !== void 0 ? _a : 0) > 0)
+        return;
+    if (!connection.ws || connection.idleCloseTimer)
+        return;
+    connection.idleCloseTimer = setTimeout(() => {
+        var _a;
+        connection.idleCloseTimer = null;
+        if (connection.subscriptions.size > 0)
+            return;
+        if (((_a = connectionAcquisitions.get(connection.acquisitionKey)) !== null && _a !== void 0 ? _a : 0) > 0)
+            return;
+        closeConnectionNow(connection);
+    }, IDLE_CONNECTION_CLOSE_GRACE_MS);
+}
+/**
+ * Acquire a connection under a routing-target lease. The lease is refcounted on
+ * the identity-bucket key and held across the caller's auth preflight so a
+ * concurrent old-route teardown cannot close a socket a new route is about to
+ * reuse. The lease is released once the caller has registered its
+ * subscription/callback.
+ */
+async function acquireConnection(appId, isServer, routePath, authTokenProvider, principalKey, principalToken) {
+    var _a;
+    const leaseKey = connectionLeaseKey(appId, routePath, principalKey, principalToken);
+    connectionAcquisitions.set(leaseKey, ((_a = connectionAcquisitions.get(leaseKey)) !== null && _a !== void 0 ? _a : 0) + 1);
+    let released = false;
+    let releaseTimer = null;
+    const release = (connection) => {
+        var _a;
+        if (released)
+            return;
+        released = true;
+        if (releaseTimer) {
+            clearTimeout(releaseTimer);
+            releaseTimer = null;
+        }
+        const remaining = ((_a = connectionAcquisitions.get(leaseKey)) !== null && _a !== void 0 ? _a : 1) - 1;
+        if (remaining > 0)
+            connectionAcquisitions.set(leaseKey, remaining);
+        else
+            connectionAcquisitions.delete(leaseKey);
+        if (connection)
+            scheduleConnectionCloseIfIdle(connection);
+    };
+    try {
+        const connection = await getOrCreateConnection(appId, isServer, routePath, authTokenProvider, principalKey, principalToken);
+        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
+        // before subscribeV2 reaches its explicit release path.
+        releaseTimer = setTimeout(releaseConnection, 0);
+        return { connection, release: releaseConnection };
+    }
+    catch (error) {
+        release();
+        throw error;
+    }
+}
+async function getOrCreateConnection(appId, isServer, routePath, authTokenProvider, principalKey, principalToken) {
+    // 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);
+    const activeFlight = connectionFlights.get(leaseKey);
+    if (activeFlight)
+        return activeFlight;
+    const flight = getOrCreateConnectionOnce(appId, isServer, routePath, authTokenProvider, principalKey, principalToken, leaseKey);
+    connectionFlights.set(leaseKey, flight);
+    try {
+        return await flight;
+    }
+    finally {
+        if (connectionFlights.get(leaseKey) === flight) {
+            connectionFlights.delete(leaseKey);
+        }
+    }
+}
+async function getOrCreateConnectionOnce(appId, isServer, routePath, authTokenProvider, principalKey, principalToken, leaseKey) {
     attachBrowserReconnectHooksOnce();
     // A per-room subscription gets its OWN connection routed to the room DO; all
     // other subscriptions share the app-level connection (project DO). The worker
@@ -5944,9 +6161,38 @@ async function getOrCreateConnection(appId, isServer, routePath, authTokenProvid
     // keyed by the wallet identity, so its WS authenticates as that wallet and
     // never shares a connection (or token) with any top-level server caller.
     const base = roomKey ? `${appId}#room#${roomKey}` : appId;
-    const connKey = principalKey ? `${base}#id#${principalKey}` : base;
-    let connection = connections.get(connKey);
+    const identityBucketKey = principalKey
+        ? `${base}#id#${principalKey}`
+        : base;
+    let connKey = identityBucketKey;
+    let connection;
+    if (principalKey && principalToken) {
+        // The 31-bit hash selects a small bucket only. Exact token equality is
+        // authoritative, and a rare collision gets an independent map slot.
+        for (const [candidateKey, candidate] of connections) {
+            if ((candidateKey === identityBucketKey || candidateKey.startsWith(`${identityBucketKey}#collision#`)) &&
+                candidate.connectionIdentityToken === principalToken) {
+                connKey = candidateKey;
+                connection = candidate;
+                break;
+            }
+        }
+        if (!connection && connections.has(connKey)) {
+            let collisionIndex = 1;
+            while (connections.has(`${identityBucketKey}#collision#${collisionIndex}`))
+                collisionIndex += 1;
+            connKey = `${identityBucketKey}#collision#${collisionIndex}`;
+        }
+    }
+    else {
+        connection = connections.get(connKey);
+    }
     if (connection && connection.ws) {
+        // We may reuse this connection; cancel any pending idle-close so it is
+        // not torn down during the auth preflight below. The held acquisition
+        // lease also guards this window, but cancelling here avoids a needless
+        // grace-timer round-trip on the common reuse path.
+        cancelIdleConnectionClose(connection);
         if (connection.authFailure) {
             throw connection.authFailure;
         }
@@ -5962,19 +6208,7 @@ async function getOrCreateConnection(appId, isServer, routePath, authTokenProvid
         if (connection.isConnected &&
             !connection.isAuthenticating &&
             !connectionMatchesAuthToken(connection, currentAuthToken)) {
-            if (connection.tokenRefreshTimer) {
-                clearInterval(connection.tokenRefreshTimer);
-                connection.tokenRefreshTimer = null;
-            }
-            try {
-                connection.ws.close();
-            }
-            catch (_a) {
-                // Already closing.
-            }
-            connection.ws = null;
-            connection.isConnected = false;
-            connections.delete(connection.key);
+            closeConnectionNow(connection);
         }
         else {
             connection.authFailure = null;
@@ -5995,13 +6229,16 @@ async function getOrCreateConnection(appId, isServer, routePath, authTokenProvid
         isAuthenticating: false,
         appId,
         key: connKey,
+        acquisitionKey: leaseKey,
         routePath: roomKey ? routePath : undefined,
         authTokenProvider,
+        connectionIdentityToken: principalToken !== null && principalToken !== void 0 ? principalToken : null,
         pendingAuthToken: null,
         pendingAuthSnapshot: null,
-        authTokenFingerprint: null,
+        authTokenValue: null,
         authPrincipal: null,
         tokenRefreshTimer: null,
+        idleCloseTimer: null,
         consecutiveAuthFailures: 0,
         authFailure: null,
     };
@@ -6078,7 +6315,7 @@ async function getOrCreateConnection(appId, isServer, routePath, authTokenProvid
         }
         else {
             connection.isAuthenticating = false;
-            connection.authTokenFingerprint = null;
+            connection.authTokenValue = null;
             connection.authPrincipal = null;
             replaySubscriptions(connection);
         }
@@ -6096,10 +6333,14 @@ async function getOrCreateConnection(appId, isServer, routePath, authTokenProvid
     // Handle errors
     ws.addEventListener('error', (event) => {
         console.error('[WS v2] WebSocket error:', event);
+        const wsError = new Error('WebSocket error');
         for (const [, pending] of connection.pendingSubscriptions) {
-            pending.reject(new Error('WebSocket error'));
+            pending.reject(wsError);
         }
         connection.pendingSubscriptions.clear();
+        for (const subscription of connection.subscriptions.values()) {
+            rejectSubscriptionRefresh(subscription, wsError);
+        }
     });
     // Handle close
     ws.addEventListener('close', () => {
@@ -6123,7 +6364,7 @@ function handleServerMessage(connection, message) {
     switch (message.type) {
         case 'authenticated': {
             connection.isAuthenticating = false;
-            connection.authTokenFingerprint = (_b = (_a = connection.pendingAuthSnapshot) === null || _a === void 0 ? void 0 : _a.tokenFingerprint) !== null && _b !== void 0 ? _b : null;
+            connection.authTokenValue = (_b = (_a = connection.pendingAuthSnapshot) === null || _a === void 0 ? void 0 : _a.tokenValue) !== null && _b !== void 0 ? _b : null;
             connection.authPrincipal = (_d = (_c = connection.pendingAuthSnapshot) === null || _c === void 0 ? void 0 : _c.principal) !== null && _d !== void 0 ? _d : null;
             replaySubscriptions(connection);
             break;
@@ -6131,15 +6372,49 @@ function handleServerMessage(connection, message) {
         case 'subscribed': {
             const subscription = connection.subscriptions.get(message.subscriptionId);
             if (subscription) {
+                const refresh = subscription.refresh;
                 // A data update can race ahead of subscribed during reconnect.
                 // If we already received data for this subscription, treat subscribed
                 // as an ack only and avoid regressing to an older snapshot.
-                if (subscription.lastData === undefined) {
+                if (refresh) {
+                    const hadBaseline = subscription.lastData !== undefined;
+                    if (subscription.dataRevision === refresh.dataRevisionAtStart) {
+                        if (subscription.cache) {
+                            const cacheKey = getCacheKey(subscription.path, subscription.prompt, subscription.shape, subscription.limit, subscription.cursor, subscription.filter, subscription.identity);
+                            setResponseCacheEntry(cacheKey, subscription.identityToken, message.data);
+                        }
+                        subscription.lastData = message.data;
+                        subscription.dataRevision += 1;
+                        if (hadBaseline) {
+                            const callbacks = Array.from(refresh.callbacks)
+                                .filter((callback) => subscription.callbacks.includes(callback));
+                            notifyCallbackOptions(callbacks, message.data);
+                        }
+                        else {
+                            // The refresh joined an original registration or a
+                            // reconnect replay before its first baseline arrived.
+                            // Every active callback needs that initial snapshot.
+                            notifyCallbacks(subscription, message.data);
+                        }
+                    }
+                    else if (refresh.callbacks.size > 0 && subscription.lastData !== undefined) {
+                        // A newer authorized data frame arrived after this refresh
+                        // began. Do not regress lastData to the older subscribed
+                        // snapshot; use that newer frame for callbacks that joined
+                        // after it was broadcast.
+                        const callbacks = Array.from(refresh.callbacks)
+                            .filter((callback) => subscription.callbacks.includes(callback));
+                        notifyCallbackOptions(callbacks, subscription.lastData);
+                    }
+                    resolveSubscriptionRefresh(subscription);
+                }
+                else if (subscription.lastData === undefined) {
                     if (subscription.cache) {
                         const cacheKey = getCacheKey(subscription.path, subscription.prompt, subscription.shape, subscription.limit, subscription.cursor, subscription.filter, subscription.identity);
-                        responseCache.set(cacheKey, { data: message.data, timestamp: Date.now() });
+                        setResponseCacheEntry(cacheKey, subscription.identityToken, message.data);
                     }
                     subscription.lastData = message.data;
+                    subscription.dataRevision += 1;
                     notifyCallbacks(subscription, message.data);
                 }
             }
@@ -6166,12 +6441,20 @@ function handleServerMessage(connection, message) {
                 // Update cache
                 if (subscription.cache) {
                     const cacheKey = getCacheKey(subscription.path, subscription.prompt, subscription.shape, subscription.limit, subscription.cursor, subscription.filter, subscription.identity);
-                    responseCache.set(cacheKey, { data: message.data, timestamp: Date.now() });
+                    setResponseCacheEntry(cacheKey, subscription.identityToken, message.data);
                 }
                 // Store last data
                 subscription.lastData = message.data;
+                subscription.dataRevision += 1;
                 // Notify callbacks
                 notifyCallbacks(subscription, message.data);
+                // A data frame is itself a full, freshly authorized snapshot.
+                // It satisfies every joined callback even if the duplicate
+                // subscribed ACK was lost; resolving here prevents a false
+                // refresh timeout ten seconds after the UI already rendered.
+                if (subscription.refresh) {
+                    resolveSubscriptionRefresh(subscription);
+                }
             }
             break;
         }
@@ -6258,6 +6541,7 @@ function handleServerMessage(connection, message) {
                 const subscription = connection.subscriptions.get(message.subscriptionId);
                 if (subscription) {
                     notifyErrorCallbacks(subscription, wsError);
+                    rejectSubscriptionRefresh(subscription, wsError);
                 }
             }
             break;
@@ -6294,13 +6578,10 @@ function addIdsToSubscriptionData(data) {
         return data.map(withSubscriptionId);
     return withSubscriptionId(data);
 }
-function notifyCallbacks(subscription, data) {
+function notifyCallbackOptions(callbacks, data) {
     var _a;
     // Attach the bare `id` (leaf doc key) to every delivered row (Bug 1).
     const decorated = addIdsToSubscriptionData(data);
-    // Snapshot the callbacks array so that unsubscriptions during
-    // notification don't cause callbacks to be skipped.
-    const callbacks = subscription.callbacks.slice();
     for (const callback of callbacks) {
         try {
             (_a = callback.onData) === null || _a === void 0 ? void 0 : _a.call(callback, decorated);
@@ -6310,23 +6591,33 @@ function notifyCallbacks(subscription, data) {
         }
     }
 }
+function notifyCallbacks(subscription, data) {
+    // Snapshot the callbacks array so that unsubscriptions during
+    // notification don't cause callbacks to be skipped.
+    notifyCallbackOptions(subscription.callbacks.slice(), data);
+}
+function notifyErrorCallback(callback, error) {
+    let delivered = false;
+    try {
+        const onError = callback.onError;
+        if (!onError)
+            return false;
+        onError(error);
+        delivered = true;
+    }
+    catch (callbackError) {
+        console.error('[WS v2] Error in subscription error callback:', callbackError);
+    }
+    return delivered;
+}
 function notifyErrorCallbacks(subscription, error) {
     let delivered = false;
     const callbacks = subscription.callbacks.slice();
     for (const callback of callbacks) {
-        if (!callback.onError)
-            continue;
-        delivered = true;
-        try {
-            callback.onError(error);
-        }
-        catch (callbackError) {
-            console.error('[WS v2] Error in subscription error callback:', callbackError);
-        }
+        delivered = notifyErrorCallback(callback, error) || delivered;
     }
-    if (delivered) {
+    if (delivered)
         error.__boundedDeliveredToOnError = true;
-    }
     return delivered;
 }
 // WebSocket readyState constants
@@ -6357,6 +6648,71 @@ function sendSubscribe(connection, subscription) {
         console.error('[WS v2] Error sending subscribe message:', error);
     }
 }
+function resolveSubscriptionRefresh(subscription) {
+    const refresh = subscription.refresh;
+    if (!refresh)
+        return;
+    subscription.refresh = null;
+    if (refresh.timer)
+        clearTimeout(refresh.timer);
+    refresh.callbacks.clear();
+    refresh.resolve();
+}
+function rejectSubscriptionRefresh(subscription, error) {
+    const refresh = subscription.refresh;
+    if (!refresh)
+        return;
+    subscription.refresh = null;
+    if (refresh.timer)
+        clearTimeout(refresh.timer);
+    refresh.callbacks.clear();
+    refresh.reject(error);
+}
+/**
+ * A callback joining an already-registered non-cache subscription cannot be
+ * seeded from `lastData`: that snapshot may predate the callback's auth
+ * preflight. Re-send the same subscription id so the server re-runs read auth
+ * and returns a fresh baseline, without allocating another websocket or
+ * replacing the logical client subscription.
+ */
+function requestFreshSubscriptionSnapshot(connection, subscription, callback) {
+    let refresh = subscription.refresh;
+    if (!refresh) {
+        let resolve;
+        let reject;
+        const promise = new Promise((resolvePromise, rejectPromise) => {
+            resolve = resolvePromise;
+            reject = rejectPromise;
+        });
+        refresh = {
+            promise,
+            resolve,
+            reject,
+            timer: null,
+            callbacks: new Set(),
+            dataRevisionAtStart: subscription.dataRevision,
+        };
+        subscription.refresh = refresh;
+        refresh.timer = setTimeout(() => {
+            if (subscription.refresh !== refresh)
+                return;
+            rejectSubscriptionRefresh(subscription, new Error('Subscription timeout'));
+        }, 10000);
+    }
+    // Register before sendSubscribe: test/browser transports may synchronously
+    // dispatch the subscribed response from send().
+    refresh.callbacks.add(callback);
+    // Every newly joined callback gets an idempotent same-id resend when the
+    // authenticated socket is ready. Do not suppress this because an initial
+    // confirmation or an earlier refresh is pending: that pending frame may
+    // have been lost or displaced, and sharing it is exactly how an entire
+    // route remount can inherit one doomed timeout. When connecting or
+    // authenticating, replaySubscriptions will send after auth completes.
+    if (connection.isConnected && !connection.isAuthenticating) {
+        sendSubscribe(connection, subscription);
+    }
+    return refresh.promise;
+}
 function sendUnsubscribe(connection, subscriptionId) {
     if (!connection.ws || connection.ws.readyState !== WS_READY_STATE_OPEN) {
         return;
@@ -6405,16 +6761,27 @@ async function subscribeV2(path, subscriptionOptions, roomRoutePath) {
         : undefined;
     const identityInfo = await getSubscriptionIdentity(effectiveAppId, config.isServer, overrides);
     const identity = identityInfo.key;
+    const identityToken = identityInfo.token;
     const responseCacheEnabled = subscriptionOptions.cache === true && identityInfo.cacheable;
+    // Preserve the existing compact connection-key shape, but use the exact
+    // token as a secondary in-memory equality check within that hash bucket.
     const principalKey = authTokenProvider ? identity : undefined;
+    const principalToken = authTokenProvider
+        ? (identityToken !== null && identityToken !== void 0 ? identityToken : identity)
+        : undefined;
     const cacheKey = responseCacheEnabled
         ? getCacheKey(normalizedPath, subscriptionOptions.prompt, subscriptionOptions.shape, subscriptionOptions.limit, subscriptionOptions.cursor, subscriptionOptions.filter, identity)
         : null;
-    // Get or create connection for this routing target (room-scoped when a
-    // room route is supplied by the live helper, else the app-level connection).
+    // 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.
     let connection;
+    let releaseConnection;
     try {
-        connection = await getOrCreateConnection(effectiveAppId, config.isServer, roomRoutePath, authTokenProvider, principalKey);
+        const acquisition = await acquireConnection(effectiveAppId, config.isServer, roomRoutePath, authTokenProvider, principalKey, principalToken);
+        connection = acquisition.connection;
+        releaseConnection = acquisition.release;
     }
     catch (error) {
         const err = error instanceof Error ? error : new Error(String(error));
@@ -6424,73 +6791,130 @@ async function subscribeV2(path, subscriptionOptions, roomRoutePath) {
         }
         throw err;
     }
-    // Deliver cached data immediately if available, but only after connection
-    // auth preflight has succeeded. An expired authenticated session must receive
-    // an auth error, not a stale private snapshot followed by a failed connect.
-    const cachedEntry = cacheKey ? responseCache.get(cacheKey) : undefined;
-    if (cachedEntry && Date.now() - cachedEntry.timestamp < CACHE_TTL && subscriptionOptions.onData) {
-        setTimeout(() => {
-            var _a;
-            (_a = subscriptionOptions.onData) === null || _a === void 0 ? void 0 : _a.call(subscriptionOptions, addIdsToSubscriptionData(cachedEntry.data));
-        }, 0);
-    }
+    const cachedEntry = cacheKey ? getResponseCacheEntry(cacheKey, identityToken) : undefined;
     // Check if we already have a subscription for this path+prompt+shape+limit+cursor+filter+sort
-    const shapeKey = subscriptionOptions.shape ? JSON.stringify(subscriptionOptions.shape) : '';
-    const filterKey = subscriptionOptions.filter ? JSON.stringify(subscriptionOptions.filter) : '';
-    const sortKey = subscriptionOptions.sort ? JSON.stringify(subscriptionOptions.sort) : '';
     let existingSubscription;
-    for (const sub of connection.subscriptions.values()) {
-        const subShapeKey = sub.shape ? JSON.stringify(sub.shape) : '';
-        const subFilterKey = sub.filter ? JSON.stringify(sub.filter) : '';
-        const subSortKey = sub.sort ? JSON.stringify(sub.sort) : '';
-        // H1: also require the same principal identity — 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.path === normalizedPath && sub.prompt === subscriptionOptions.prompt && subShapeKey === shapeKey && subFilterKey === filterKey && subSortKey === sortKey && sub.includeSubPaths === ((_a = subscriptionOptions.includeSubPaths) !== null && _a !== void 0 ? _a : false) && sub.limit === subscriptionOptions.limit && sub.cursor === subscriptionOptions.cursor) {
-            existingSubscription = sub;
-            break;
+    try {
+        const shapeKey = subscriptionOptions.shape ? JSON.stringify(subscriptionOptions.shape) : '';
+        const filterKey = subscriptionOptions.filter ? JSON.stringify(subscriptionOptions.filter) : '';
+        const sortKey = subscriptionOptions.sort ? JSON.stringify(subscriptionOptions.sort) : '';
+        for (const sub of connection.subscriptions.values()) {
+            const subShapeKey = sub.shape ? JSON.stringify(sub.shape) : '';
+            const subFilterKey = sub.filter ? JSON.stringify(sub.filter) : '';
+            const subSortKey = sub.sort ? JSON.stringify(sub.sort) : '';
+            // 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 && subShapeKey === shapeKey && subFilterKey === filterKey && subSortKey === sortKey && sub.includeSubPaths === ((_a = subscriptionOptions.includeSubPaths) !== null && _a !== void 0 ? _a : false) && sub.limit === subscriptionOptions.limit && sub.cursor === subscriptionOptions.cursor) {
+                existingSubscription = sub;
+                break;
+            }
         }
     }
+    catch (error) {
+        releaseConnection();
+        throw error;
+    }
     if (existingSubscription) {
+        let replayData = undefined;
+        let replayOnData;
+        if (responseCacheEnabled) {
+            // Read callback getters before mutating the shared subscription. If
+            // a caller supplied a throwing getter, the acquisition fail-safe can
+            // release cleanly without leaving a ghost callback behind.
+            replayOnData = subscriptionOptions.onData;
+            replayData = existingSubscription.lastData !== undefined
+                ? existingSubscription.lastData
+                : cachedEntry && Date.now() - cachedEntry.timestamp < CACHE_TTL
+                    ? cachedEntry.data
+                    : undefined;
+        }
         if (responseCacheEnabled) {
             existingSubscription.cache = true;
         }
         // Add callback to existing subscription
         existingSubscription.callbacks.push(subscriptionOptions);
-        // Deliver last known data immediately only for explicit, principal-bound
-        // cache opt-in. Otherwise joining an existing subscription can replay a
-        // stale private snapshot without a fresh server auth result.
-        if (responseCacheEnabled &&
-            existingSubscription.cache &&
-            existingSubscription.lastData !== undefined &&
-            subscriptionOptions.onData) {
-            setTimeout(() => {
-                var _a;
-                (_a = subscriptionOptions.onData) === null || _a === void 0 ? void 0 : _a.call(subscriptionOptions, addIdsToSubscriptionData(existingSubscription.lastData));
-            }, 0);
+        let refreshPromise = null;
+        if (responseCacheEnabled) {
+            // Explicit, principal-bound cache opt-in may replay exactly one
+            // snapshot. Prefer the active subscription's lastData, falling back
+            // to the short-lived response cache while a reconnect is in flight.
+            if (replayData !== undefined && replayOnData) {
+                setTimeout(() => {
+                    replayOnData === null || replayOnData === void 0 ? void 0 : replayOnData(addIdsToSubscriptionData(replayData));
+                }, 0);
+            }
+        }
+        else {
+            // Default (non-cache) subscriptions require a fresh authorized
+            // baseline for every newly joined callback. Reuse the same logical
+            // subscription id and socket, but make the server re-run the read.
+            refreshPromise = requestFreshSubscriptionSnapshot(connection, existingSubscription, subscriptionOptions);
+        }
+        releaseConnection();
+        if (refreshPromise) {
+            try {
+                await refreshPromise;
+            }
+            catch (error) {
+                const err = error instanceof Error ? error : new Error(String(error));
+                let deliveredLocally = false;
+                if (!err.__boundedDeliveredToOnError) {
+                    deliveredLocally = notifyErrorCallback(subscriptionOptions, err);
+                }
+                if (!subscriptionOptions.onError) {
+                    await removeCallbackFromSubscription(connection, existingSubscription.subscriptionId, subscriptionOptions);
+                    throw err;
+                }
+                if (!err.__boundedDeliveredToOnError && !deliveredLocally) {
+                    console.warn('[WS v2] Subscription refresh failed, keeping for reconnect recovery:', error);
+                }
+            }
         }
         return async () => {
             await removeCallbackFromSubscription(connection, existingSubscription.subscriptionId, subscriptionOptions);
         };
     }
+    // Deliver cached data immediately for a new logical subscription, but only
+    // after connection auth preflight has succeeded. An expired authenticated
+    // session must receive an auth error, not a stale private snapshot followed
+    // by a failed connect.
+    if (cachedEntry && Date.now() - cachedEntry.timestamp < CACHE_TTL && subscriptionOptions.onData) {
+        setTimeout(() => {
+            var _a;
+            (_a = subscriptionOptions.onData) === null || _a === void 0 ? void 0 : _a.call(subscriptionOptions, addIdsToSubscriptionData(cachedEntry.data));
+        }, 0);
+    }
     // Create new subscription
     const subscriptionId = generateSubscriptionId();
-    const subscription = {
-        subscriptionId,
-        path: normalizedPath,
-        filter: subscriptionOptions.filter,
-        sort: subscriptionOptions.sort,
-        prompt: subscriptionOptions.prompt,
-        shape: subscriptionOptions.shape,
-        limit: subscriptionOptions.limit,
-        cursor: subscriptionOptions.cursor,
-        includeSubPaths: (_b = subscriptionOptions.includeSubPaths) !== null && _b !== void 0 ? _b : false,
-        callbacks: [subscriptionOptions],
-        lastData: undefined,
-        cache: responseCacheEnabled,
-        identity,
-    };
-    connection.subscriptions.set(subscriptionId, subscription);
+    let subscription;
+    try {
+        subscription = {
+            subscriptionId,
+            path: normalizedPath,
+            filter: subscriptionOptions.filter,
+            sort: subscriptionOptions.sort,
+            prompt: subscriptionOptions.prompt,
+            shape: subscriptionOptions.shape,
+            limit: subscriptionOptions.limit,
+            cursor: subscriptionOptions.cursor,
+            includeSubPaths: (_b = subscriptionOptions.includeSubPaths) !== null && _b !== void 0 ? _b : false,
+            callbacks: [subscriptionOptions],
+            lastData: undefined,
+            dataRevision: 0,
+            refresh: null,
+            cache: responseCacheEnabled,
+            identity,
+            identityToken,
+        };
+        connection.subscriptions.set(subscriptionId, subscription);
+    }
+    catch (error) {
+        releaseConnection();
+        throw error;
+    }
+    releaseConnection();
     // Send subscribe message if connected
     if (connection.isConnected && !connection.isAuthenticating) {
         // Create a promise to wait for subscription confirmation
@@ -6510,15 +6934,23 @@ async function subscribeV2(path, subscriptionOptions, roomRoutePath) {
         }
         catch (error) {
             const err = error instanceof Error ? error : new Error(String(error));
+            let deliveredLocally = false;
             if (!err.__boundedDeliveredToOnError) {
-                notifyErrorCallbacks(subscription, err);
+                // A local confirmation timeout belongs to the caller that
+                // originated it. Joined callbacks may already have a viable
+                // same-id refresh and must not be poisoned by that old attempt.
+                deliveredLocally = notifyErrorCallback(subscriptionOptions, err);
             }
             if (!subscriptionOptions.onError) {
                 connection.pendingSubscriptions.delete(subscriptionId);
-                connection.subscriptions.delete(subscriptionId);
+                // This registration may have acquired joined callbacks while
+                // its confirmation was pending. Remove only the originating
+                // callback; deleting the whole logical subscription would
+                // orphan those remounted consumers and their refresh flight.
+                await removeCallbackFromSubscription(connection, subscriptionId, subscriptionOptions);
                 throw err;
             }
-            if (!err.__boundedDeliveredToOnError) {
+            if (!err.__boundedDeliveredToOnError && !deliveredLocally) {
                 console.warn('[WS v2] Subscription confirmation failed, keeping for reconnect recovery:', error);
             }
         }
@@ -6529,12 +6961,14 @@ async function subscribeV2(path, subscriptionOptions, roomRoutePath) {
     };
 }
 async function removeCallbackFromSubscription(connection, subscriptionId, callback) {
+    var _a;
     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);
     // If there are still callbacks, don't unsubscribe
     if (subscription.callbacks.length > 0) {
         return;
@@ -6556,17 +6990,9 @@ async function removeCallbackFromSubscription(connection, subscriptionId, callba
         sendUnsubscribe(connection, subscriptionId);
         await unsubscribePromise;
     }
-    // If no more subscriptions, close connection
-    if (connection.subscriptions.size === 0 && connection.ws) {
-        // Clear token refresh timer
-        if (connection.tokenRefreshTimer) {
-            clearInterval(connection.tokenRefreshTimer);
-            connection.tokenRefreshTimer = null;
-        }
-        connection.ws.close();
-        connection.ws = null;
-        connections.delete(connection.key);
-    }
+    // If no more subscriptions, let the connection close after a short idle
+    // grace so an immediately-following route remount can reclaim the socket.
+    scheduleConnectionCloseIfIdle(connection);
 }
 /**
  * Close all v2 subscriptions.
@@ -6574,6 +7000,11 @@ async function removeCallbackFromSubscription(connection, subscriptionId, callba
 async function closeAllSubscriptionsV2() {
     const closePromises = [];
     for (const [appId, connection] of connections) {
+        cancelIdleConnectionClose(connection);
+        const closeError = new Error('Subscriptions closed');
+        for (const subscription of connection.subscriptions.values()) {
+            rejectSubscriptionRefresh(subscription, closeError);
+        }
         if (connection.tokenRefreshTimer) {
             clearInterval(connection.tokenRefreshTimer);
             connection.tokenRefreshTimer = null;
@@ -6582,15 +7013,18 @@ async function closeAllSubscriptionsV2() {
             const ws = connection.ws;
             connection.ws = null;
             connection.isConnected = false;
-            closePromises.push(new Promise((resolve) => {
-                ws.addEventListener('close', () => {
-                    resolve();
-                });
-                ws.close();
-            }));
+            if (ws.readyState !== WS_READY_STATE_CLOSED) {
+                closePromises.push(new Promise((resolve) => {
+                    ws.addEventListener('close', () => {
+                        resolve();
+                    });
+                    ws.close();
+                }));
+            }
         }
         connections.delete(appId);
     }
+    connectionAcquisitions.clear();
     await Promise.all(closePromises);
 }
 /**
@@ -6623,10 +7057,12 @@ function getCachedDataV2(path, prompt) {
     // opt-in. Resolve the caller's identity from an active cache-enabled
     // subscription for this path. No matching sub → null (safe).
     let identity;
+    let identityToken;
     outer: for (const connection of connections.values()) {
         for (const sub of connection.subscriptions.values()) {
             if (sub.cache && sub.path === normalizedPath && sub.prompt === prompt) {
                 identity = sub.identity;
+                identityToken = sub.identityToken;
                 break outer;
             }
         }
@@ -6635,7 +7071,7 @@ function getCachedDataV2(path, prompt) {
         return null;
     }
     const cacheKey = getCacheKey(path, prompt, undefined, undefined, undefined, undefined, identity);
-    const cachedEntry = responseCache.get(cacheKey);
+    const cachedEntry = getResponseCacheEntry(cacheKey, identityToken !== null && identityToken !== void 0 ? identityToken : null);
     if (cachedEntry && Date.now() - cachedEntry.timestamp < CACHE_TTL) {
         return cachedEntry.data;
     }
@@ -6697,10 +7133,15 @@ async function doReconnectWithNewAuth() {
         if (!connection.ws) {
             continue;
         }
+        cancelIdleConnectionClose(connection);
+        const reconnectError = new Error('Connection reconnecting due to auth change');
         for (const [, pending] of connection.pendingSubscriptions) {
-            pending.reject(new Error('Connection reconnecting due to auth change'));
+            pending.reject(reconnectError);
         }
         connection.pendingSubscriptions.clear();
+        for (const subscription of connection.subscriptions.values()) {
+            rejectSubscriptionRefresh(subscription, reconnectError);
+        }
         for (const [, pending] of connection.pendingUnsubscriptions) {
             pending.resolve();
         }
@@ -6760,10 +7201,10 @@ async function wsIntent(appId, roomRoutePath, intent, isServer) {
     const currentToken = await getIdToken(isServer).catch(() => null);
     if (!currentToken) {
         // Mid-refresh: the socket principal still governs server-side.
-        if (!connection.authTokenFingerprint && !connection.authPrincipal)
+        if (!connection.authTokenValue && !connection.authPrincipal)
             return false;
     }
-    else if (!connection.authTokenFingerprint && !connection.authPrincipal) {
+    else if (!connection.authTokenValue && !connection.authPrincipal) {
         // Anonymous socket + authenticated user: do not attribute this user's
         // input to the anon principal. Reauth the socket; caller may fall back.
         void maybeReauthRoomConnection(connection);
@@ -6783,7 +7224,7 @@ async function wsIntent(appId, roomRoutePath, intent, isServer) {
     }
 }
 // Debounced background reauth: when the client's current token no longer
-// matches the connection's auth fingerprint (token rotation), refresh the
+// matches the connection's authenticated identity (token rotation), refresh the
 // socket auth ONCE rather than degrading every subsequent send.
 const reauthInFlight = new WeakSet();
 async function maybeReauthRoomConnection(connection, isServer) {