@wildo-ai/saas-frontend-lib 1.0.1 → 1.1.0

package/dist/esm/core/requests/websockets/WebSocketContext.js

@@ -4,7 +4,77 @@ import { io } from 'socket.io-client';
 import axios from 'axios';
 import { errorManagement } from '../../../core/errors/error-management.frontend.service.js';
 import { ResourceOperationRiskLevel, WildoHeaderKeys } from '@wildo-ai/saas-models';
-import { CoreWebSocketEvent, buildResourceRoomName, buildScopeRoomName, safeValidateWebSocketPayload, WebSocketEventSchemas, } from '@wildo-ai/saas-models';
+import { CoreWebSocketEvent, CoreWebSocketConnectionErrorCode, buildResourceRoomName, buildScopeRoomName, safeValidateWebSocketPayload, WebSocketEventSchemas, } from '@wildo-ai/saas-models';
+import { fullJitterBackoffMs } from '../../../core/requests/network-backoff.frontend.utils.js';
+import { getClientInstanceId } from '../../../core/requests/client-instance-id.frontend.service.js';
+import { envLoader } from '../../../core/runtime/env-variable-loader.frontend.service.js';
+import { LoggerFrontendService } from '../../../core/monitoring/logger.frontend.service.js';
+import { normalizeContextResourceIdentifiersForTransport } from '../../../core/resources/context-resource-identifiers.frontend.utils.js';
+import { decodeJwtPayload } from '../../../core/security/jwt.frontend.utils.js';
+/**
+ * Read the `exp` (expiry, epoch seconds) claim from a JWT access token.
+ * Returns `undefined` when the token is absent, malformed, or carries no
+ * numeric `exp` — callers treat that as "freshness unknown".
+ */
+function readAccessTokenExp(token) {
+    if (!token) {
+        return undefined;
+    }
+    try {
+        const { exp } = decodeJwtPayload(token);
+        return typeof exp === 'number' ? exp : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Choose the access token that expires LATER between the one already stored
+ * in the credential ref and an incoming one from a `connect()` config.
+ *
+ * `connect()` seeds the handshake credential ref from its config token. But
+ * `refreshAuth` can store a rotated (fresher) token into that same ref BEFORE
+ * `connect()` runs — e.g. the access token is refreshed mid-session-restore
+ * and only then does the WebSocket connect. Blindly overwriting with the
+ * config token would REGRESS the ref to the older, possibly-expired token and
+ * the handshake would be rejected with "Authentication failed". The primary
+ * fix lives at the caller (it now passes the freshest token), but this guard
+ * makes the invariant — "the ref never moves to an earlier-expiring token" —
+ * hold for ANY caller.
+ *
+ * The stored token is kept ONLY when it is PROVABLY fresher (both tokens
+ * decode to a numeric `exp` and the stored one is later). When freshness
+ * can't be compared, the incoming config token wins, since it is the caller's
+ * explicit connection intent (and may legitimately belong to a new session —
+ * a different user/org — whose token need not out-live the previous one).
+ */
+function pickFresherAccessToken(storedToken, incomingToken) {
+    // Only ever OVERRIDE the caller's intent when we can PROVE the stored token
+    // outlives the incoming one. In every other case (either token absent, or
+    // freshness not comparable) the incoming config token wins — preserving the
+    // original `token: config.token` seeding semantics exactly, including a
+    // deliberate token-less connect that must NOT resurrect a prior session's
+    // credential.
+    if (!storedToken || !incomingToken) {
+        return incomingToken;
+    }
+    const storedExp = readAccessTokenExp(storedToken);
+    const incomingExp = readAccessTokenExp(incomingToken);
+    if (storedExp !== undefined && incomingExp !== undefined && storedExp > incomingExp) {
+        return storedToken;
+    }
+    return incomingToken;
+}
+/**
+ * Ceiling on consecutive WS-initiated token renewals that mint a fresh token but
+ * still fail to yield a validated connection. Once hit, the WS layer stops
+ * requesting renewals until the server accepts a credential again (which resets
+ * the streak). Protects against a mint-succeeds-but-server-rejects loop — most
+ * acutely on the live `AUTH_REFRESH_FAILED` path, where the server's rejection is
+ * immediate (no reconnection backoff to space the retries out). Sized generously
+ * so ordinary clock-skew / one-off races self-heal well within it.
+ */
+const MAX_CONSECUTIVE_WS_AUTH_RENEWALS = 5;
 /**
  * WebSocket Context
  * Manages Socket.IO connections and real-time communication
@@ -18,6 +88,54 @@ export var WebSocketStatus;
     WebSocketStatus["ERROR"] = "error";
     WebSocketStatus["RECONNECTING"] = "reconnecting";
 })(WebSocketStatus || (WebSocketStatus = {}));
+function normalizeContextResourceIdentifiers(contextResourceIdentifiers) {
+    return normalizeContextResourceIdentifiersForTransport(contextResourceIdentifiers);
+}
+/**
+ * Order-independent content key for a normalized context-identifiers map. Two maps
+ * that produce the same key yield a byte-identical `resource:subscribe` payload on
+ * the server, so re-emitting for an already-claimed room is a server-side no-op.
+ * Used by `claimResourceRoom` to skip redundant re-subscriptions.
+ */
+function buildNormalizedContextKey(context) {
+    if (!context)
+        return '';
+    return Object.keys(context)
+        .sort()
+        .map((key) => `${key}=${context[key]}`)
+        .join('&');
+}
+/**
+ * Content-equality for the rendered subscribed-rooms list.
+ *
+ * `syncSubscribedRoomsFromClaims` rebuilds this array from the room-claims map on
+ * every claim/release — including idempotent re-claims that change nothing. Without
+ * this gate it would `setSubscribedRooms` a brand-new array reference each call,
+ * re-rendering every `useWebSocket()` consumer (`subscribedRooms` is a dependency of
+ * the context `value` memo) and, when the triggering claim originates from a
+ * render-phase RMM acquisition, helping sustain a paced re-render loop. Compares the
+ * stable scalar fields plus an order-independent context key per room; room order is
+ * the claims-map insertion order, which is stable across pure re-syncs.
+ */
+function areSubscribedRoomsEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++) {
+        const left = a[i];
+        const right = b[i];
+        if (left.roomName !== right.roomName
+            || left.resourceType !== right.resourceType
+            || left.resourceId !== right.resourceId
+            || left.scopeKey !== right.scopeKey
+            || left.scopeId !== right.scopeId
+            || buildNormalizedContextKey(left.contextResourceIdentifiers) !== buildNormalizedContextKey(right.contextResourceIdentifiers)) {
+            return false;
+        }
+    }
+    return true;
+}
 function roomMatchesOrganization(room, organizationId) {
     if (!organizationId) {
         return false;
@@ -27,12 +145,34 @@ function roomMatchesOrganization(room, organizationId) {
     }
     return Object.values(room.contextResourceIdentifiers).includes(organizationId);
 }
+function isPlainContextObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function normalizeSystemErrorDetails(details) {
+    if (details == null) {
+        return {};
+    }
+    if (isPlainContextObject(details)) {
+        return details;
+    }
+    return { errorDetails: details };
+}
 /**
  * WebSocket Context
  * Exported for use in separate hook file (Fast Refresh compatibility)
  * @internal - Use useWebSocket() hook instead of accessing this directly
  */
 export const WebSocketContext = createContext(undefined);
+/**
+ * Structured logger for WebSocket connectivity. Connection churn (reconnection
+ * attempts, transient drops) is reported HERE — once per outage — instead of
+ * through the global error/toast pipeline, so it lands in observability (the
+ * Pino→OTLP bridge) without spamming the user with a Sonner toast per attempt.
+ * The ambient connection state is surfaced by the status bar via
+ * `useWebSocket().status`; only a terminal give-up (`reconnect_failed`) or an
+ * actionable server signal (rate limit) still raises a user-facing notification.
+ */
+const wsConnectivityLogger = LoggerFrontendService.getLogger();
 export const WebSocketProvider = ({ children }) => {
     const [status, setStatus] = useState(WebSocketStatus.DISCONNECTED);
     const [connectionCount, setConnectionCount] = useState(0);
@@ -40,8 +180,50 @@ export const WebSocketProvider = ({ children }) => {
     const [subscribedRooms, setSubscribedRooms] = useState([]);
     const socketRef = useRef(null);
     const configRef = useRef(null);
+    /**
+     * Single source of truth for the credentials the Socket.IO handshake sends.
+     *
+     * The Socket.IO `auth` option is read through a callback (see
+     * `performActualConnect`) that pulls from this ref on EVERY connection AND
+     * reconnection attempt. That is what lets a token rotated mid-session (or
+     * while the socket is down) reach the next handshake — the access token is
+     * short-lived and expires routinely, so a value frozen at `io()` time goes
+     * stale and the server rejects the reconnect with "Authentication failed".
+     *
+     * `refreshAuth` updates this ref UNCONDITIONALLY (even when disconnected), so
+     * the freshest token is always what the next (re)connect presents. The live
+     * `AUTH_REFRESH` emit is an optimization on top, for the already-connected
+     * case, to avoid a reconnect round-trip.
+     */
+    const authStateRef = useRef({});
+    // The current session's auth-renewal request handler (from the connect config).
+    // Called when the handshake is rejected for an authentication reason so the
+    // auth layer can refresh the access token and revive this socket. Cleared on
+    // `disconnect()` so a torn-down session can never trigger a renewal.
+    const authErrorHandlerRef = useRef(null);
+    // Guards against firing a renewal request while a prior one is still settling.
+    // `connect_error` can fire repeatedly on a dead socket; the underlying
+    // `tokenRenewalHandler` already dedups in-flight refreshes, but this keeps the
+    // WS layer from queuing redundant calls between reconnection attempts.
+    const authRenewalInFlightRef = useRef(false);
+    // Loop breaker for the pathological case where renewal keeps SUCCEEDING (a
+    // fresh token is minted each time) yet the server still rejects it — a
+    // mint-vs-validate disagreement, not a transient outage. Counts consecutive
+    // renewals that produced a token but did NOT lead to a validated connection;
+    // reset to 0 whenever the server accepts the credential (`connect` or
+    // `SYSTEM_TOKEN_REFRESHED`). A transient/authoritative refresh FAILURE does not
+    // count (the auth layer already classifies it, and a long backend outage must
+    // still renew once the backend returns), so this never suppresses legitimate
+    // recovery. See `MAX_CONSECUTIVE_WS_AUTH_RENEWALS`.
+    const authRenewalStreakRef = useRef(0);
     const reconnectTimeoutRef = useRef(null);
     const reconnectAttemptsRef = useRef(0);
+    // Backoff counter for the connectivity SUPERVISOR's watchdog probes (see the
+    // supervisor effect near the bottom). Distinct from `reconnectAttemptsRef`,
+    // which tracks Socket.IO's own in-cycle reconnection attempts: this one paces
+    // the manual revival attempts that happen AFTER Socket.IO has given up. Reset
+    // to 0 on any successful (re)connect so the next outage starts probing quickly.
+    const revivalAttemptRef = useRef(0);
     const connectedAtRef = useRef(null);
     const roomClaimsRef = useRef(new Map());
     const eventListenersRef = useRef(new Map());
@@ -49,6 +231,11 @@ export const WebSocketProvider = ({ children }) => {
     const connectRequestIdRef = useRef(0);
     const connectKeyRef = useRef(null);
     const connectInFlightRef = useRef(false);
+    // Anti-noise: true once the CURRENT outage has been reported (structured log +
+    // status change). Guards against emitting one report per reconnection attempt —
+    // the whole point of not toasting connection churn. Reset on (re)connect so a
+    // later outage reports again.
+    const outageReportedRef = useRef(false);
     /**
      * Build room name from parameters
      */
@@ -62,14 +249,21 @@ export const WebSocketProvider = ({ children }) => {
         throw new Error('Must provide either resourceId or both scopeKey and scopeId');
     }, []);
     const syncSubscribedRoomsFromClaims = useCallback(() => {
-        setSubscribedRooms(Array.from(roomClaimsRef.current.values(), (room) => ({
+        const nextRooms = Array.from(roomClaimsRef.current.values(), (room) => ({
             roomName: room.roomName,
             resourceType: room.resourceType,
             resourceId: room.resourceId,
             scopeKey: room.scopeKey,
             scopeId: room.scopeId,
             contextResourceIdentifiers: room.contextResourceIdentifiers,
-        })));
+        }));
+        // Value-equality gate: only commit a new array when the room set actually
+        // changed by content. The claim/release paths call this on every acquisition
+        // (including idempotent re-claims), so an ungated `setSubscribedRooms` would
+        // mint a fresh array each time, churn the context `value` memo, and re-render
+        // every `useWebSocket()` consumer — and feed the render-phase RMM-acquisition
+        // re-render loop. Returning `prev` when unchanged lets React bail the update.
+        setSubscribedRooms((prev) => (areSubscribedRoomsEqual(prev, nextRooms) ? prev : nextRooms));
     }, []);
     const getSocketListener = useCallback((event, handler) => {
         const wrappers = eventListenerWrappersRef.current.get(event) ?? new Map();
@@ -155,8 +349,11 @@ export const WebSocketProvider = ({ children }) => {
                 });
                 return false;
             }
-            // Calculate delay with exponential backoff
-            const delay = Math.min(Math.pow(2, attempt) * BASE_DELAY_MS, MAX_DELAY_MS);
+            // Jittered exponential backoff (AWS "full jitter") — see
+            // network-backoff.frontend.utils. Deterministic backoff would have every
+            // client poll /health/ready in lockstep after a shared outage and then all
+            // reconnect on the same tick; jitter spreads that load.
+            const delay = fullJitterBackoffMs(attempt, BASE_DELAY_MS, MAX_DELAY_MS);
             console.warn(`WebSocket: API not ready (attempt ${attempt + 1}), retrying in ${delay}ms...`, {
                 healthUrl,
                 elapsedMs: elapsedTime,
@@ -165,6 +362,50 @@ export const WebSocketProvider = ({ children }) => {
             attempt++;
         }
     }, [wsUrlToHttpUrl]);
+    /**
+     * Ask the auth layer to renew the access token because the server rejected the
+     * credential this socket presented — either at the handshake (`connect_error`
+     * with `AUTHENTICATION_FAILED`) or during a live in-place refresh
+     * (`SYSTEM_ERROR` / `AUTH_REFRESH_FAILED`). Shared by both paths so their
+     * dedup + loop-protection behave identically.
+     *
+     * The WS layer never mints a token itself: `onAuthenticationError` runs
+     * `AuthSessionContext.tokenRenewalHandler`, which performs the resilient
+     * network refresh and, on success, seeds the fresh token back into this socket
+     * (`refreshAuth`) — reviving a dead handshake or re-emitting `AUTH_REFRESH` on a
+     * still-connected socket. This function only decides WHETHER to ask.
+     *
+     * Two guards:
+     * - `authRenewalInFlightRef` — one request at a time; the repeated
+     *   `connect_error`s of a dead socket (or a burst of `AUTH_REFRESH_FAILED`)
+     *   never queue redundant calls. Held for the FULL renewal promise.
+     * - `authRenewalStreakRef` / `MAX_CONSECUTIVE_WS_AUTH_RENEWALS` — stops a
+     *   mint-succeeds-but-server-still-rejects loop. Only SUCCESSFUL renewals that
+     *   didn't lead to a validated connection count; a validated credential
+     *   (`connect` / `SYSTEM_TOKEN_REFRESHED`) resets the streak, and a failed
+     *   refresh is decremented back out so a transient outage never trips the cap.
+     */
+    const requestAuthRenewal = useCallback((reason) => {
+        if (!authErrorHandlerRef.current || authRenewalInFlightRef.current) {
+            return;
+        }
+        if (authRenewalStreakRef.current >= MAX_CONSECUTIVE_WS_AUTH_RENEWALS) {
+            console.warn(`WebSocket: Suppressing token renewal (${reason}) — a freshly-minted token was rejected ${authRenewalStreakRef.current}× in a row; not looping the refresh endpoint`);
+            return;
+        }
+        console.log(`WebSocket: Requesting token renewal (${reason})`);
+        authRenewalInFlightRef.current = true;
+        authRenewalStreakRef.current += 1;
+        Promise.resolve(authErrorHandlerRef.current())
+            .catch(() => {
+            // Transient (backend unreachable / 5xx) or authoritative (logout) refresh
+            // failure — already classified/handled by the auth layer. It produced no
+            // fresh token, so it can't sustain a rejection loop: undo the streak
+            // increment so a later, genuinely-recoverable renewal is never blocked.
+            authRenewalStreakRef.current = Math.max(0, authRenewalStreakRef.current - 1);
+        })
+            .finally(() => { authRenewalInFlightRef.current = false; });
+    }, []);
     /**
      * Perform the Socket.IO connection
      */
@@ -174,15 +415,60 @@ export const WebSocketProvider = ({ children }) => {
         // - Include token in both auth object and extraHeaders as fallback
         // - Longer timeout for initial connection through ingress
         const socketOptions = {
-            auth: config.token ? {
-                token: config.token,
-                ...(config.consumableToken ? { consumableToken: config.consumableToken } : {}),
-            } : undefined,
+            // Dynamic auth callback — Socket.IO invokes this on every connection AND
+            // reconnection attempt, so each handshake reads the LATEST token from
+            // `authStateRef` rather than a value frozen at `io()` time. This is the
+            // fix for token-expiry reconnect failures: when the access token rotates
+            // mid-session (or while the socket is down), the next reconnect picks up
+            // the fresh token instead of replaying the stale one and getting rejected
+            // with "Authentication failed".
+            //
+            // The active-organization selector is validated server-side against the
+            // user's verified memberships before seeding initiatorIds.organizationId,
+            // so org-scoped resource subscriptions authorize correctly. A stale value
+            // is ignored server-side (never trusted), and ORGANIZATION_SWITCH keeps
+            // the server's active org in sync.
+            auth: (cb) => {
+                const { token, consumableToken, organizationId } = authStateRef.current;
+                // Client-install id rides the `auth` payload rather than `extraHeaders` for two reasons:
+                // `extraHeaders` is frozen for the manager's lifetime AND only applies to the polling
+                // transport in browsers, whereas this callback re-runs on every connect/reconnect — so a
+                // policy applied after the socket first connected is picked up on the next handshake, and a
+                // withdrawn policy stops being sent. Undefined (the opt-out default) omits the key entirely.
+                const clientInstanceId = getClientInstanceId();
+                cb({
+                    ...(token ? { token } : {}),
+                    ...(consumableToken ? { consumableToken } : {}),
+                    ...(organizationId ? { organizationId } : {}),
+                    ...(clientInstanceId ? { clientInstanceId } : {}),
+                    // Origin SURFACE, alongside the install id. A socket has no per-message headers, so both
+                    // origin signals ride the handshake or the backend cannot attribute socket-originated audit
+                    // rows the way it attributes HTTP ones. Sending only one of the pair was an asymmetry, not a
+                    // decision. Read from `envLoader` (not React context) for the same reason as the HTTP client:
+                    // this callback runs outside the provider tree.
+                    frontendServiceName: envLoader.loadEnvironmentConfig().frontendServiceName,
+                });
+            },
             // Start with polling, then upgrade to websocket (better for Traefik/proxies)
             transports: ['polling', 'websocket'],
             reconnection: config.autoReconnect ?? true,
-            reconnectionDelay: config.reconnectInterval ?? 5000,
-            reconnectionAttempts: config.maxReconnectAttempts ?? 5,
+            // Base retry delay. Socket.IO grows it exponentially toward
+            // `reconnectionDelayMax`; WITHOUT a max override Socket.IO caps growth at
+            // its own 5000ms default, so a 5000ms base yielded a FLAT ~5s curve with no
+            // growth. Base 1000 + max 30000 gives a real 1s→2s→4s→…→30s backoff.
+            reconnectionDelay: config.reconnectInterval ?? 1000,
+            reconnectionDelayMax: 30000,
+            // Socket.IO's built-in ± jitter applied to each delay (0.5 = ±50%). This
+            // de-correlates the reconnect wave of N clients after a shared outage —
+            // the same anti-thundering-herd goal as the HTTP layer's full-jitter policy
+            // (see network-backoff.frontend.utils). Do NOT drop it to 0.
+            randomizationFactor: 0.5,
+            // Generous AUTOMATIC budget before the connectivity supervisor
+            // (online / visibility / watchdog re-arm — see the supervisor effect) takes
+            // over. With the exponential curve this spans ~minutes of automatic retries;
+            // the supervisor then keeps the socket recoverable indefinitely, so a client
+            // is NEVER left permanently dead once this budget is exhausted.
+            reconnectionAttempts: config.maxReconnectAttempts ?? 15,
             // Longer timeout for Kubernetes ingress (Traefik may take time to upgrade)
             timeout: 30000,
             // Force new connection (don't reuse existing) - important for hot reload
@@ -190,23 +476,54 @@ export const WebSocketProvider = ({ children }) => {
             // Upgrade timeout for polling -> websocket upgrade
             upgradeTimeout: 10000,
         };
-        // Add headers as fallback (some proxies prefer headers over auth object)
-        if (config.token || config.consumableToken) {
+        // Header fallback for proxies that prefer headers over the auth object.
+        // NOTE: `extraHeaders` is static for the lifetime of the Socket.IO manager —
+        // it canNOT track a rotating token across reconnects. We therefore do NOT
+        // put the short-lived access token here (it would go stale and a reconnect
+        // would replay an expired Bearer header); the dynamic `auth.token` callback
+        // above is the authoritative, always-fresh credential and the server reads
+        // it first. Only the non-rotating consumable token is carried as a header.
+        if (config.consumableToken) {
             socketOptions.extraHeaders = {
-                ...(config.token ? { [WildoHeaderKeys.AUTHORIZATION]: `Bearer ${config.token}` } : {}),
-                ...(config.consumableToken ? { [WildoHeaderKeys.CONSUMABLE_TOKEN]: config.consumableToken } : {}),
+                [WildoHeaderKeys.CONSUMABLE_TOKEN]: config.consumableToken,
             };
         }
         const socket = io(config.url, socketOptions);
         socketRef.current = socket;
         attachRegisteredEventListeners(socket);
+        // Report a connectivity outage to observability exactly ONCE per outage
+        // (not once per reconnection attempt). Keeps the signal in logs/OTLP without
+        // the per-attempt Sonner-toast spam that this whole change removes. Message is
+        // reason-neutral because not every outage auto-reconnects (io server
+        // disconnect / terminal give-up do not).
+        const reportOutageOnce = (reason) => {
+            if (outageReportedRef.current)
+                return;
+            outageReportedRef.current = true;
+            wsConnectivityLogger.warn('WebSocket connectivity lost', {
+                source: 'websocket',
+                reason,
+            });
+        };
         socket.on('connect', () => {
             connectInFlightRef.current = false;
             setStatus(WebSocketStatus.CONNECTED);
             setConnectionCount(prev => prev + 1);
             setError(null);
             reconnectAttemptsRef.current = 0;
+            revivalAttemptRef.current = 0;
+            // A successful handshake means the current token is valid: re-arm the
+            // renewal guards so a LATER expiry (this socket lives for hours) can
+            // request a fresh renewal, and clear the minted-but-rejected streak.
+            authRenewalInFlightRef.current = false;
+            authRenewalStreakRef.current = 0;
             connectedAtRef.current = new Date();
+            // Recovery: if we had reported an outage, log the recovery once and re-arm
+            // the guard so a future outage reports again.
+            if (outageReportedRef.current) {
+                wsConnectivityLogger.info('WebSocket connectivity restored', { source: 'websocket' });
+                outageReportedRef.current = false;
+            }
             console.log('Socket.IO connected');
             for (const room of roomClaimsRef.current.values()) {
                 socket.emit(CoreWebSocketEvent.RESOURCE_SUBSCRIBE, {
@@ -222,17 +539,58 @@ export const WebSocketProvider = ({ children }) => {
             connectInFlightRef.current = false;
             setStatus(WebSocketStatus.DISCONNECTED);
             console.log('Socket.IO disconnected:', reason);
-            // Check if we should attempt reconnection
-            if (reason === 'io server disconnect') {
-                // Server initiated disconnect - notify user
-                const errorMessage = 'Server disconnected the connection';
+            // A disconnect is transient churn, NOT a user-facing error: Socket.IO will
+            // auto-reconnect (for transport drops), and the status bar
+            // (useWebSocket().status) already shows the DISCONNECTED/RECONNECTING state.
+            // Report the outage ONCE to observability instead of firing a Sonner toast
+            // per drop. If reconnection ultimately gives up, `reconnect_failed` sets the
+            // terminal ERROR the notifier surfaces.
+            //
+            // SKIP `io client disconnect` — that reason means WE called
+            // `socket.disconnect()` (logout / org teardown / the `disconnect()` method
+            // below). It is intentional, not an outage. Today `disconnect()` calls
+            // `removeAllListeners()` BEFORE `socket.disconnect()`, so this handler
+            // wouldn't fire on that path anyway — but this skip is defense-in-depth: it
+            // removes the load-bearing dependence on that ordering and also covers any
+            // other client-initiated disconnect that leaves listeners attached. All
+            // other reasons (transport close/error, ping timeout, io server disconnect)
+            // are genuine drops worth reporting.
+            if (reason !== 'io client disconnect') {
+                reportOutageOnce(reason);
+            }
+        });
+        socket.on(CoreWebSocketEvent.SYSTEM_TOKEN_REFRESHED, () => {
+            console.log('WebSocket: Server accepted refreshed socket auth token');
+            // The server validated the current credential: the streak of
+            // minted-but-rejected renewals is broken, so re-arm the loop breaker for a
+            // future expiry on this long-lived connection.
+            authRenewalStreakRef.current = 0;
+        });
+        socket.on(CoreWebSocketEvent.SYSTEM_ERROR, (payload) => {
+            if (payload?.code === 'AUTH_REFRESH_FAILED') {
+                // A live in-place `AUTH_REFRESH` emit was rejected — the token we believed
+                // fresh did not validate (clock skew, a sub-second expiry race, or the
+                // credential genuinely went stale on a long-lived connected socket while
+                // no HTTP traffic refreshed it). Re-emitting the SAME token would just
+                // fail again, so ask the auth layer for a genuinely fresh NETWORK token;
+                // on success `refreshAuth` re-emits `AUTH_REFRESH` with it. The shared
+                // loop breaker caps the mint-succeeds-but-server-still-rejects case (here
+                // the rejection is immediate, with no reconnection backoff to space it).
+                console.warn('WebSocket: Server rejected refreshed socket auth token', payload);
+                requestAuthRenewal('live refresh rejected');
+                return;
+            }
+            if (payload?.code === 'RATE_LIMIT_EXCEEDED') {
+                const errorMessage = payload.message || 'Too many real-time requests. Please slow down.';
+                const detailsContext = normalizeSystemErrorDetails(payload.details);
+                console.warn('WebSocket: Rate limit exceeded', payload);
                 setError(errorMessage);
-                errorManagement.handleError(new Error(`WebSocket server disconnected: ${reason}`), {
+                errorManagement.handleError(new Error(errorMessage), {
                     source: 'websocket',
                     riskLevel: ResourceOperationRiskLevel.MEDIUM,
                     additionalContext: {
-                        reason,
-                        wasConnected: true,
+                        ...detailsContext,
+                        errorCode: payload.code,
                     },
                 });
             }
@@ -241,16 +599,32 @@ export const WebSocketProvider = ({ children }) => {
             connectInFlightRef.current = false;
             console.error('Socket.IO connection error:', err.message);
             setError(err.message);
-            setStatus(WebSocketStatus.ERROR);
-            // Integrate with error management system
-            errorManagement.handleError(err, {
-                source: 'websocket',
-                riskLevel: ResourceOperationRiskLevel.MEDIUM,
-                additionalContext: {
-                    errorCode: err.code,
-                    errorType: err.type,
-                },
-            });
+            // AUTH-rejection self-heal. A handshake refused because the presented
+            // access token is expired/invalid carries `data.code ===
+            // AUTHENTICATION_FAILED` (see the backend auth middleware). Ask the auth
+            // layer to renew the token; on success its `refreshAuth` seeds the fresh
+            // token into `authStateRef` and revives this socket, so the NEXT
+            // reconnection attempt's dynamic-auth handshake succeeds — no HTTP traffic
+            // or window refocus required. The `errData.code` check is the stable
+            // contract; the message fallback keeps this working against a server that
+            // predates the structured code.
+            const errData = err.data;
+            const isAuthRejection = errData?.code === CoreWebSocketConnectionErrorCode.AUTHENTICATION_FAILED
+                || err.message === 'Authentication failed';
+            if (isAuthRejection) {
+                requestAuthRenewal('handshake rejected');
+            }
+            // A failed ATTEMPT while we are already in a reconnection cycle
+            // (`reconnectAttemptsRef > 0`) is expected churn — keep the status
+            // RECONNECTING so downstream consumers (status bar, ConnectionStatusNotifier)
+            // can distinguish "still trying" from a terminal give-up. Only an INITIAL
+            // connection failure (no reconnect cycle yet) is surfaced as ERROR; the
+            // terminal give-up is set by `reconnect_failed` below. This keeps ERROR a
+            // clean signal for "not connected AND not actively retrying".
+            setStatus(reconnectAttemptsRef.current > 0 ? WebSocketStatus.RECONNECTING : WebSocketStatus.ERROR);
+            // Report the outage once to observability (not once per attempt — that was
+            // the Sonner-toast spam this change removed). No per-attempt user toast.
+            reportOutageOnce(`connect_error:${err.type ?? err.message}`);
         });
         socket.io.on('reconnect_attempt', (attempt) => {
             reconnectAttemptsRef.current = attempt;
@@ -262,22 +636,26 @@ export const WebSocketProvider = ({ children }) => {
             setStatus(WebSocketStatus.CONNECTED);
             setError(null);
             reconnectAttemptsRef.current = 0;
+            revivalAttemptRef.current = 0;
         });
         socket.io.on('reconnect_failed', () => {
             console.error('Socket.IO reconnection failed');
             const errorMessage = 'Failed to reconnect after maximum attempts';
             setError(errorMessage);
+            // Terminal give-up → ERROR. This is the single source of the user-facing
+            // "connection lost" notification, owned by ConnectionStatusNotifier (which
+            // debounces the whole outage into ONE persistent, self-dismissing notice).
+            // We no longer fire errorManagement.handleError here — that produced a
+            // second, redundant toast on top of the notifier and the (former) per-attempt
+            // toasts. The outage was already reported once to observability via
+            // reportOutageOnce; log the terminal transition at that same tier.
             setStatus(WebSocketStatus.ERROR);
-            // Integrate with error management system
-            errorManagement.handleError(new Error(errorMessage), {
+            wsConnectivityLogger.warn('WebSocket reconnection gave up after maximum attempts', {
                 source: 'websocket',
-                riskLevel: ResourceOperationRiskLevel.HIGH,
-                additionalContext: {
-                    reconnectAttempts: reconnectAttemptsRef.current,
-                },
+                reconnectAttempts: reconnectAttemptsRef.current,
             });
         });
-    }, [attachRegisteredEventListeners]);
+    }, [attachRegisteredEventListeners, requestAuthRenewal]);
     /**
      * Perform readiness check and then connect to WebSocket
      */
@@ -326,6 +704,32 @@ export const WebSocketProvider = ({ children }) => {
         connectKeyRef.current = connectKey;
         connectInFlightRef.current = true;
         configRef.current = config;
+        // Register (or clear) this session's auth-renewal request handler. Stored in
+        // a ref rather than closed over so the long-lived `connect_error` listener
+        // always calls the CURRENT session's handler, and a reconnect that reuses the
+        // socket never invokes a stale one.
+        authErrorHandlerRef.current = config.onAuthenticationError ?? null;
+        // Seed the credential source of truth the handshake callback reads from.
+        // A `refreshAuth` that arrives between here and the actual `io()` call (the
+        // readiness-check window) will overwrite `token` in place, so the eventual
+        // handshake still presents the freshest token rather than this snapshot.
+        //
+        // Freshness guard: `refreshAuth` may have ALREADY stored a rotated token
+        // into `authStateRef` BEFORE this connect (e.g. the access token was
+        // refreshed during session restore, then the socket connects). Reseeding
+        // blindly from `config.token` would regress the ref to the older token and
+        // the handshake would be rejected. `pickFresherAccessToken` keeps the
+        // stored token only when it provably outlives the config token; otherwise
+        // the config token (the caller's explicit intent) wins.
+        const seededToken = pickFresherAccessToken(authStateRef.current.token, config.token);
+        if (seededToken !== config.token) {
+            console.log('WebSocket: Keeping already-stored fresher access token over the staler connect config token');
+        }
+        authStateRef.current = {
+            token: seededToken,
+            consumableToken: config.consumableToken,
+            organizationId: config.organizationId,
+        };
         setStatus(WebSocketStatus.CONNECTING);
         setError(null);
         // Perform readiness check then connect (async, fires and forgets)
@@ -343,11 +747,18 @@ export const WebSocketProvider = ({ children }) => {
         connectKeyRef.current = null;
         connectInFlightRef.current = false;
         reconnectAttemptsRef.current = 0;
+        // Re-arm the once-per-outage report guard: without this, a socket that had an
+        // outage (guard = true) then was torn down here and later revived for a NEW
+        // session would suppress that session's first outage report. Recovery via the
+        // `connect` handler also re-arms it, but an explicit disconnect may never
+        // reconnect on the same socket.
+        outageReportedRef.current = false;
         if (reconnectTimeoutRef.current) {
             clearTimeout(reconnectTimeoutRef.current);
             reconnectTimeoutRef.current = null;
         }
         if (socketRef.current) {
+            socketRef.current.removeAllListeners();
             socketRef.current.disconnect();
             socketRef.current = null;
         }
@@ -355,16 +766,167 @@ export const WebSocketProvider = ({ children }) => {
         roomClaimsRef.current.clear();
         setSubscribedRooms([]);
         connectedAtRef.current = null;
+        // Clear the stored credentials so a later, unrelated reconnect can never
+        // present a token from a session that was explicitly torn down (logout /
+        // org teardown). A fresh `connect()` reseeds `authStateRef`.
+        authStateRef.current = {};
+        // Drop the renewal handler + guards: a torn-down session must never trigger a
+        // token refresh. A fresh `connect()` re-registers the current session's.
+        authErrorHandlerRef.current = null;
+        authRenewalInFlightRef.current = false;
+        authRenewalStreakRef.current = 0;
     }, []);
     /**
      * Refresh authentication token
      */
     const refreshAuth = useCallback((token) => {
-        if (!socketRef.current?.connected) {
-            console.warn('Cannot refresh auth: not connected');
+        // ALWAYS persist the rotated token first, regardless of connection state.
+        // This is the credential the handshake callback presents on the next
+        // (re)connection, so even if the socket is currently down the fresh token
+        // is what the eventual reconnect will use. Skipping this on a disconnected
+        // socket (the old behavior) dropped the token on the floor and left
+        // auto-reconnect replaying the stale, now-expired one forever.
+        authStateRef.current = { ...authStateRef.current, token };
+        if (configRef.current) {
+            configRef.current = { ...configRef.current, token };
+        }
+        const socket = socketRef.current;
+        if (socket?.connected) {
+            // Live path: refresh in place without tearing down the connection.
+            console.log('WebSocket: Refreshing socket auth with renewed access token');
+            socket.emit(CoreWebSocketEvent.AUTH_REFRESH, { token });
             return;
         }
-        socketRef.current.emit(CoreWebSocketEvent.AUTH_REFRESH, { token });
+        // Disconnected. The fresh token is already stored for the next handshake.
+        // If a socket exists but is NOT actively trying to reconnect (its
+        // reconnection budget was exhausted, e.g. after repeated auth rejections on
+        // the stale token), kick a fresh connect so it actually retries — now with
+        // the renewed token. If it IS still reconnecting (`socket.active`), the next
+        // scheduled attempt will read the updated token automatically.
+        if (socket && !socket.active) {
+            console.log('WebSocket: Reviving idle socket to reconnect with renewed access token');
+            socket.connect();
+            return;
+        }
+        console.log('WebSocket: Stored renewed access token for next socket handshake');
+    }, []);
+    /**
+     * Revive a socket that is neither connected nor actively retrying.
+     *
+     * This is the resilience floor beneath Socket.IO's own reconnection budget.
+     * Socket.IO gives up PERMANENTLY once `reconnectionAttempts` is exhausted
+     * (`reconnect_failed` → ERROR); after that the socket sits dead forever unless
+     * something re-opens it. The browser's connectivity signals (the `online`
+     * event, a tab becoming visible again after mobile background suspension) and
+     * the watchdog poll all funnel through here to re-arm the manager with
+     * `socket.connect()` — the same revival `refreshAuth` already performs for its
+     * idle-socket case.
+     *
+     * No-ops (so it is safe to call liberally) when:
+     * - there is no active connection intent (`connectKeyRef` null — logged out or
+     *   intentionally disconnected), so a torn-down session is never resurrected;
+     * - the socket is already connected OR already mid-retry (`socket.active`), so
+     *   Socket.IO's in-progress reconnection cycle is never interrupted.
+     *
+     * Deliberately does NOT touch `status`: letting the socket's own lifecycle
+     * events drive it keeps the outage state steady (ERROR) across silent revival
+     * probes instead of flapping ERROR↔RECONNECTING on every failed attempt.
+     */
+    const attemptRevival = useCallback(() => {
+        if (!connectKeyRef.current) {
+            return;
+        }
+        const socket = socketRef.current;
+        if (!socket) {
+            // Intent remains but the socket was fully torn down — do a fresh connect.
+            if (configRef.current) {
+                connect(configRef.current);
+            }
+            return;
+        }
+        if (socket.connected || socket.active) {
+            return;
+        }
+        // Dead socket with a live intent: reset the in-cycle attempt counter so a
+        // subsequent failed probe reports as ERROR (not RECONNECTING), then re-open
+        // the manager that had given up.
+        reconnectAttemptsRef.current = 0;
+        console.log('WebSocket: Reviving dead socket after connectivity signal');
+        socket.connect();
+    }, [connect]);
+    // Hold the latest `attemptRevival` in a ref so the connectivity-supervisor
+    // effect can register its listeners ONCE (empty deps) without re-subscribing on
+    // every render as the callback identity changes.
+    const attemptRevivalRef = useRef(attemptRevival);
+    attemptRevivalRef.current = attemptRevival;
+    /**
+     * Connectivity supervisor — guarantees a client is never permanently dead.
+     *
+     * Three re-arm triggers, all routed through `attemptRevival` (which no-ops when
+     * the socket is healthy, already retrying, or there is no connection intent):
+     *
+     * 1. **`online` event** — the OS network interface returned (Wi-Fi reconnect,
+     *    laptop wake, VPN up). Instant revival, no wait.
+     * 2. **Page Visibility** — a backgrounded tab became visible again. Mobile
+     *    browsers freeze timers and drop sockets in the background, so the socket is
+     *    frequently dead on resume with no `online` event to announce it.
+     * 3. **Watchdog poll** — a jittered, self-scheduling timer. `navigator.onLine`
+     *    only reflects the LOCAL interface, so a backend restart / proxy hiccup that
+     *    outlives Socket.IO's automatic budget fires NO `online` event; the watchdog
+     *    is the backstop that still recovers it. Its backoff grows (full jitter,
+     *    capped) while the socket stays dead and resets on a real connect, so a
+     *    fleet of clients de-correlates instead of stampeding a recovering backend.
+     *
+     * Mount-once (empty deps); every callback/state is read through a ref so the
+     * listeners are never re-registered and the backoff counter survives renders.
+     */
+    useEffect(() => {
+        const handleOnline = () => attemptRevivalRef.current();
+        const handleVisibility = () => {
+            if (document.visibilityState === 'visible') {
+                attemptRevivalRef.current();
+            }
+        };
+        window.addEventListener('online', handleOnline);
+        document.addEventListener('visibilitychange', handleVisibility);
+        // Watchdog pacing. While healthy we poll lazily (just to notice a silent
+        // death); while dead we probe on a growing jittered backoff.
+        const WATCHDOG_HEALTHY_POLL_MS = 15000;
+        const WATCHDOG_BASE_MS = 2000;
+        const WATCHDOG_MAX_MS = 30000;
+        const WATCHDOG_MIN_GAP_MS = 500;
+        let watchdogTimer = null;
+        const scheduleWatchdog = (delay) => {
+            watchdogTimer = setTimeout(tick, delay);
+        };
+        function tick() {
+            const socket = socketRef.current;
+            // "Healthy" for the watchdog = connected, already retrying, OR no active
+            // connection intent (logged out / intentionally disconnected).
+            const healthy = !connectKeyRef.current || !!socket?.connected || !!socket?.active;
+            if (healthy) {
+                // Reset the backoff so the NEXT outage starts probing quickly again.
+                revivalAttemptRef.current = 0;
+                scheduleWatchdog(WATCHDOG_HEALTHY_POLL_MS);
+                return;
+            }
+            // Dead with a live intent → revive, then back off (jittered) before the
+            // next probe so N clients de-correlate on a recovering backend.
+            attemptRevivalRef.current();
+            const backoff = Math.max(WATCHDOG_MIN_GAP_MS, fullJitterBackoffMs(revivalAttemptRef.current, WATCHDOG_BASE_MS, WATCHDOG_MAX_MS));
+            revivalAttemptRef.current += 1;
+            scheduleWatchdog(backoff);
+        }
+        scheduleWatchdog(WATCHDOG_HEALTHY_POLL_MS);
+        return () => {
+            window.removeEventListener('online', handleOnline);
+            document.removeEventListener('visibilitychange', handleVisibility);
+            if (watchdogTimer) {
+                clearTimeout(watchdogTimer);
+            }
+        };
+        // Mount-only by design; all dependencies are accessed through refs.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
     }, []);
     /**
      * Listen to socket events directly
@@ -461,21 +1023,41 @@ export const WebSocketProvider = ({ children }) => {
      */
     const claimResourceRoom = useCallback(async (params) => {
         const roomName = buildRoomName(params);
+        const contextResourceIdentifiers = normalizeContextResourceIdentifiers(params.contextResourceIdentifiers);
         const existing = roomClaimsRef.current.get(roomName);
         if (existing) {
             const hadOwner = existing.ownerKeys.has(params.ownerKey);
             const previousOwnerContext = existing.ownerContexts.get(params.ownerKey);
             const previousSharedContext = existing.contextResourceIdentifiers;
+            // Idempotency guard: if this owner already holds the room and the room's
+            // wire context is byte-identical to what was last sent, the server already
+            // has this exact subscription. Re-emitting `resource:subscribe` would be a
+            // server-side no-op and only burns the per-socket subscribe rate-limit
+            // budget — this is the mechanism behind the Settings-surface flood, where an
+            // upstream effect re-claims every commit with an unchanged context. We
+            // compare against the *shared* room context (what was last put on the wire),
+            // so a genuine context change by this or any owner still re-emits.
+            const contextUnchanged = buildNormalizedContextKey(previousSharedContext) === buildNormalizedContextKey(contextResourceIdentifiers);
+            if (hadOwner && contextUnchanged && socketRef.current?.connected) {
+                // Owner already registered + wire context unchanged ⇒ the server already
+                // holds this exact subscription. Keep this owner's local context pointer
+                // fresh, but skip the redundant `resource:subscribe` emit. The shared
+                // context already equals the incoming one (that is what `contextUnchanged`
+                // asserts), and the room is already in the subscribed set, so no re-sync
+                // is needed.
+                existing.ownerContexts.set(params.ownerKey, contextResourceIdentifiers);
+                return { success: true, editingUsers: existing.editingUsers };
+            }
             existing.ownerKeys.add(params.ownerKey);
-            existing.ownerContexts.set(params.ownerKey, params.contextResourceIdentifiers);
-            existing.contextResourceIdentifiers = params.contextResourceIdentifiers;
+            existing.ownerContexts.set(params.ownerKey, contextResourceIdentifiers);
+            existing.contextResourceIdentifiers = contextResourceIdentifiers;
             if (socketRef.current?.connected) {
                 const refreshedSubscription = await requestResourceRoomSubscription({
                     resourceType: existing.resourceType,
                     resourceId: existing.resourceId,
                     scopeKey: existing.scopeKey,
                     scopeId: existing.scopeId,
-                    contextResourceIdentifiers: params.contextResourceIdentifiers,
+                    contextResourceIdentifiers,
                 });
                 if (refreshedSubscription.success) {
                     existing.editingUsers = refreshedSubscription.editingUsers;
@@ -506,14 +1088,17 @@ export const WebSocketProvider = ({ children }) => {
                 resourceId: params.resourceId,
                 scopeKey: params.scopeKey,
                 scopeId: params.scopeId,
-                contextResourceIdentifiers: params.contextResourceIdentifiers,
+                contextResourceIdentifiers,
                 ownerKeys: new Set([params.ownerKey]),
-                ownerContexts: new Map([[params.ownerKey, params.contextResourceIdentifiers]]),
+                ownerContexts: new Map([[params.ownerKey, contextResourceIdentifiers]]),
             });
             syncSubscribedRoomsFromClaims();
             return { success: false };
         }
-        const result = await requestResourceRoomSubscription(params);
+        const result = await requestResourceRoomSubscription({
+            ...params,
+            contextResourceIdentifiers,
+        });
         if (!result.success) {
             return result;
         }
@@ -523,9 +1108,9 @@ export const WebSocketProvider = ({ children }) => {
             resourceId: params.resourceId,
             scopeKey: params.scopeKey,
             scopeId: params.scopeId,
-            contextResourceIdentifiers: params.contextResourceIdentifiers,
+            contextResourceIdentifiers,
             ownerKeys: new Set([params.ownerKey]),
-            ownerContexts: new Map([[params.ownerKey, params.contextResourceIdentifiers]]),
+            ownerContexts: new Map([[params.ownerKey, contextResourceIdentifiers]]),
             editingUsers: result.editingUsers,
         });
         syncSubscribedRoomsFromClaims();
@@ -543,6 +1128,7 @@ export const WebSocketProvider = ({ children }) => {
      */
     const releaseResourceRoom = useCallback(async (params) => {
         const roomName = buildRoomName(params);
+        const contextResourceIdentifiers = normalizeContextResourceIdentifiers(params.contextResourceIdentifiers);
         const existing = roomClaimsRef.current.get(roomName);
         if (!existing) {
             return;
@@ -579,7 +1165,7 @@ export const WebSocketProvider = ({ children }) => {
             resourceId: params.resourceId,
             scopeKey: params.scopeKey,
             scopeId: params.scopeId,
-            contextResourceIdentifiers: params.contextResourceIdentifiers,
+            contextResourceIdentifiers,
         });
     }, [buildRoomName, syncSubscribedRoomsFromClaims]);
     const unsubscribeFromResource = useCallback(async (params) => {
@@ -629,7 +1215,7 @@ export const WebSocketProvider = ({ children }) => {
             socketRef.current.emit(CoreWebSocketEvent.RESOURCE_EDITING_START, {
                 resourceType: params.resourceType,
                 resourceId: params.resourceId,
-                contextResourceIdentifiers: params.contextResourceIdentifiers,
+                contextResourceIdentifiers: normalizeContextResourceIdentifiers(params.contextResourceIdentifiers),
                 timestamp: new Date(),
             });
             const handleResult = (response) => {
@@ -679,7 +1265,7 @@ export const WebSocketProvider = ({ children }) => {
             resourceId: params.resourceId,
             eventName: params.eventName,
             data: params.data,
-            contextResourceIdentifiers: params.contextResourceIdentifiers,
+            contextResourceIdentifiers: normalizeContextResourceIdentifiers(params.contextResourceIdentifiers),
             includeSelf: params.includeSelf,
             timestamp: new Date(),
         });
@@ -809,4 +1395,4 @@ export const WebSocketProvider = ({ children }) => {
     ]);
     return _jsx(WebSocketContext.Provider, { value: value, children: children });
 };
-//# sourceMappingURL=WebSocketContext.js.map
+//# sourceMappingURL=WebSocketContext.js.map