@wildo-ai/saas-backend-lib 1.0.1

package/src/requests/service/websocket.service.ts

@@ -0,0 +1,2844 @@
+import { injectable, inject, Container } from 'inversify';
+import { Server as HttpServer } from 'http';
+import { Server as SocketIOServer, Socket } from 'socket.io';
+import { createAdapter } from '@socket.io/redis-adapter';
+import { createClient } from 'redis';
+import { z } from 'zod';
+import { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';
+import { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';
+import { AppConfigurationService } from '~wildo-backend-lib/config/services/app-configuration.backend.service';
+import { RedisService } from '~wildo-backend-lib/databases/services/redis.service';
+import { ErrorBuilderBackendService } from '~wildo-backend-lib/errors/services/error-builder.backend.service';
+import {
+  ErrorCustomMessageReference,
+  ErrorType,
+  ExecutionContext_ExecutionType,
+  ResourcePrimaryScope,
+  CoreResourceOperation,
+  ARRAY_RESPONSE_OPERATIONS,
+  DataMode,
+  ResourceConfiguration_Operation,
+  OPERATION_VARIANT_KEY,
+  ResourcesConfigOperationsDtosBuilderUtils,
+  ResourceOperationsUtils,
+  WildoHeaderKeys,
+  ResourceOperationVariantType,
+  isWildoBackendError,
+} from '@wildo-ai/saas-models';
+import {
+  ExecutionContextCreatorBackendService,
+} from '~wildo-backend-lib/runtime/services/execution-context-creator.backend.service';
+import { AuthorizationsBackendService } from '~wildo-backend-lib/security/authorizations/services/authorizations.backend.service';
+import { ResourcesRegistryBackendService } from '~wildo-backend-lib/resources/services/resources-registry.backend.service';
+import { NotificationBadgeBackendService } from '~wildo-backend-lib/notifications/services/notification-badge.backend.service';
+import {
+  WS_ResourceSubscribePayload,
+  WS_ResourceEditingPayload,
+  WS_ResourceCustomEventPayload,
+  WS_ResourceUpdatedPayload,
+  WS_ResourceDeletedPayload,
+  WS_ResourceRoomStatePayload,
+  WS_ResourceSyncUpdatedPayload,
+  WS_ResourceUpdateNotificationPayload,
+  WS_ResourceSubscribePayloadSchema,
+  WS_ResourceEditingPayloadSchema,
+  WS_ResourceCustomEventPayloadSchema,
+  WS_UserNotificationPayload,
+  NotificationLevel,
+  NotificationDisplayTarget,
+  ResourceAction,
+  buildResourceRoomName,
+  buildScopeRoomName,
+  buildUserRoomName,
+  buildOrganizationRoomName,
+  buildOrganizationRoleRoomName,
+  buildAppRoleRoomName,
+  parseOrganizationRoomName,
+  WebSocketRoomPrefix,
+  CoreWebSocketEvent,
+  CORE_APP_ROLES,
+  WebSocketResourceDeliveryTarget,
+} from '@wildo-ai/saas-models';
+import { SocketAuthResult } from '~wildo-backend-lib/runtime/models/execution-context.backend.schemas';
+
+export interface WebSocketConfig {
+  cors: {
+    origin: string | string[];
+    credentials: boolean;
+  };
+  transports: ('websocket' | 'polling')[];
+  pingTimeout: number;
+  pingInterval: number;
+  maxHttpBufferSize: number;
+  allowEIO3: boolean;
+}
+
+type WebSocketResourceRoomEmitPayload =
+  | WS_ResourceUpdatedPayload
+  | WS_ResourceDeletedPayload
+  | WS_ResourceRoomStatePayload;
+
+function subscriptionMatchesOrganization(
+  subscription: SocketTrackedResourceSubscription,
+  organizationId: string,
+): boolean {
+  if (subscription.scopeId === organizationId) {
+    return true;
+  }
+
+  return Object.values(subscription.contextResourceIdentifiers ?? {}).includes(organizationId);
+}
+
+export interface WebSocketMessage {
+  type: string;
+  payload: any;
+  timestamp: Date;
+  userId?: string;
+  organizationId?: string;
+  targetUsers?: string[];
+  targetRoles?: string[];
+}
+
+export interface RoomInfo {
+  name: string;
+  organizationId: string;
+  type: 'organization' | 'user' | 'role' | 'custom' | 'resource';
+  members: Set<string>;
+  metadata?: Record<string, any>;
+}
+
+type SocketTrackedResourceSubscription = WS_ResourceSubscribePayload & {
+  roomName: string;
+};
+
+/**
+ * Rate limiting configuration (Redis-synchronized)
+ */
+export interface RateLimitConfig {
+  /** Maximum events per window */
+  maxEvents: number;
+  /** Window size in seconds */
+  windowSeconds: number;
+}
+
+/**
+ * Default rate limits per event type
+ */
+const DEFAULT_RATE_LIMITS: Record<string, RateLimitConfig> = {
+  // Resource subscription: 20 per 10 seconds (allow rapid page navigation)
+  [CoreWebSocketEvent.RESOURCE_SUBSCRIBE]: { maxEvents: 20, windowSeconds: 10 },
+  [CoreWebSocketEvent.RESOURCE_UNSUBSCRIBE]: { maxEvents: 20, windowSeconds: 10 },
+
+  // Editing events: 10 per minute (reasonable for form editing)
+  [CoreWebSocketEvent.RESOURCE_EDITING_START]: { maxEvents: 10, windowSeconds: 60 },
+  [CoreWebSocketEvent.RESOURCE_EDITING_END]: { maxEvents: 10, windowSeconds: 60 },
+
+  // Custom events: 30 per second (for real-time collaboration like cursor moves)
+  [CoreWebSocketEvent.RESOURCE_CUSTOM]: { maxEvents: 30, windowSeconds: 1 },
+
+  // Badge requests: 10 per second
+  [CoreWebSocketEvent.BADGE_GET]: { maxEvents: 10, windowSeconds: 1 },
+  [CoreWebSocketEvent.BADGE_GET_ALL]: { maxEvents: 5, windowSeconds: 1 },
+
+  // Auth/system events: 5 per minute
+  [CoreWebSocketEvent.AUTH_REFRESH]: { maxEvents: 5, windowSeconds: 60 },
+  [CoreWebSocketEvent.ORGANIZATION_SWITCH]: { maxEvents: 10, windowSeconds: 60 },
+
+  // Default for unlisted events: 100 per minute
+  'default': { maxEvents: 100, windowSeconds: 60 },
+};
+
+/**
+ * WebSocket Service
+ *
+ * Provides real-time communication for SaaS applications:
+ * - Multi-tenant socket management with identity-based rooms
+ * - Resource-centric rooms for collaboration (editing, locking, custom events)
+ * - Role-based message broadcasting
+ * - Redis adapter for horizontal scaling
+ * - JWT authentication reusing ExecutionContextCreatorBackendService
+ * - Authorization reusing AuthorizationsBackendService
+ */
+@injectable()
+export class WebSocketService {
+  private io: SocketIOServer | null = null;
+  private userSockets: Map<string, Set<string>> = new Map(); // userId -> socketIds
+  private rooms: Map<string, RoomInfo> = new Map();
+  private organizationSockets: Map<string, Set<string>> = new Map(); // orgId -> socketIds
+
+  // NEW: Track authenticated sockets and editing state
+  private authenticatedSockets: Map<string, SocketAuthResult> = new Map(); // socketId -> auth info
+  private resourceEditingState: Map<string, Set<string>> = new Map(); // resource room -> editing userIds
+  private resourceSubscriptionsBySocket: Map<string, Map<string, SocketTrackedResourceSubscription>> = new Map();
+
+  protected logDebug: (message: string, context?: Record<string, unknown>) => void;
+
+  constructor(
+    @inject(SAAS_SERVICE_TYPES.Logger) private logger: LoggerService,
+    @inject(SAAS_SERVICE_TYPES.AppConfigService) private configService: AppConfigurationService,
+    @inject(SAAS_SERVICE_TYPES.ErrorBuilderService) private errorBuilder: ErrorBuilderBackendService,
+    @inject(SAAS_SERVICE_TYPES.RedisService) private redisService: RedisService,
+    // Dependencies for factorized authentication/authorization
+    @inject(SAAS_SERVICE_TYPES.ExecutionContextCreatorBackendService) private executionContextCreator: ExecutionContextCreatorBackendService,
+    @inject(SAAS_SERVICE_TYPES.AuthorizationsService) private authorizationsService: AuthorizationsBackendService,
+    @inject(SAAS_SERVICE_TYPES.ResourceRegistryService) private resourcesRegistry: ResourcesRegistryBackendService,
+    // Container for lazy resolution of NotificationBadgeService to break circular dependency
+    @inject('Container') private container: Container,
+  ) {
+    this.logDebug = this.logger.debugByType('WebSocketService');
+    this.logger.setDebugTypeLogging('WebSocketService', false);
+  }
+
+  /**
+   * Lazy getter for NotificationBadgeService to break circular dependency
+   * NotificationBadgeService depends on WebSocketService, so we resolve it lazily
+   */
+  private getBadgeService(): NotificationBadgeBackendService {
+    return this.container.get<NotificationBadgeBackendService>(SAAS_SERVICE_TYPES.NotificationBadgeService);
+  }
+
+  private getSocketAuth(socket: Socket): SocketAuthResult {
+    return (socket as any).auth as SocketAuthResult;
+  }
+
+  private hasOrganizationAccess(auth: SocketAuthResult, organizationId: string): boolean {
+    if (auth.executionType === ExecutionContext_ExecutionType.PUBLIC_EXECUTION) {
+      return false;
+    }
+
+    return auth.initiatorRoles.some((roleInfo) =>
+      roleInfo.relatedPrimaryScope === ResourcePrimaryScope.ORGANIZATIONS
+      && roleInfo.relatedResourceId === organizationId,
+    );
+  }
+
+  private trackSocketResourceSubscription(
+    socketId: string,
+    subscription: SocketTrackedResourceSubscription,
+  ): void {
+    const subscriptions = this.resourceSubscriptionsBySocket.get(socketId) ?? new Map<string, SocketTrackedResourceSubscription>();
+    subscriptions.set(subscription.roomName, subscription);
+    this.resourceSubscriptionsBySocket.set(socketId, subscriptions);
+  }
+
+  private untrackSocketResourceSubscription(socketId: string, roomName: string): void {
+    const subscriptions = this.resourceSubscriptionsBySocket.get(socketId);
+    if (!subscriptions) {
+      return;
+    }
+
+    subscriptions.delete(roomName);
+    if (subscriptions.size === 0) {
+      this.resourceSubscriptionsBySocket.delete(socketId);
+    }
+  }
+
+  private async revokeTrackedResourceSubscription(params: {
+    socket: Socket;
+    auth: SocketAuthResult;
+    subscription: SocketTrackedResourceSubscription;
+    reason: 'auth_refresh' | 'organization_switch';
+  }): Promise<void> {
+    const { socket, auth, subscription, reason } = params;
+
+    await socket.leave(subscription.roomName);
+
+    if (subscription.resourceId && auth.initiatorIds?.userId) {
+      await this.trackEditingState(
+        subscription.resourceType,
+        subscription.resourceId,
+        auth.initiatorIds.userId,
+        'end',
+      );
+
+      this.io?.to(subscription.roomName).emit(CoreWebSocketEvent.RESOURCE_EDITING_END, {
+        resourceType: subscription.resourceType,
+        resourceId: subscription.resourceId,
+        initiatorUserId: auth.initiatorIds.userId,
+        reason,
+        timestamp: new Date(),
+      } satisfies WS_ResourceEditingPayload);
+    }
+
+    this.untrackSocketResourceSubscription(socket.id, subscription.roomName);
+  }
+
+  private async revalidateTrackedResourceSubscriptions(
+    socket: Socket,
+    auth: SocketAuthResult,
+  ): Promise<void> {
+    const subscriptions = Array.from(this.resourceSubscriptionsBySocket.get(socket.id)?.values() ?? []);
+    for (const subscription of subscriptions) {
+      try {
+        if (subscription.resourceId) {
+          await this.verifyResourceAccess(
+            socket,
+            auth,
+            subscription.resourceType,
+            subscription.resourceId,
+            subscription.contextResourceIdentifiers,
+          );
+        } else if (subscription.scopeKey && subscription.scopeId) {
+          await this.verifyScopeAccess(
+            auth,
+            subscription.scopeKey,
+            subscription.scopeId,
+            subscription.contextResourceIdentifiers,
+          );
+        } else {
+          throw new Error('Tracked resource subscription is missing routing identifiers');
+        }
+      } catch {
+        await this.revokeTrackedResourceSubscription({
+          socket,
+          auth,
+          subscription,
+          reason: 'auth_refresh',
+        });
+      }
+    }
+  }
+
+  /**
+   * Initialize WebSocket server
+   *
+   * For platform services that don't serve frontends (e.g., crontabs-batches-manager),
+   * WebSocket initialization is skipped since they only receive internal backend requests.
+   */
+  public async initialize(httpServer: HttpServer): Promise<void> {
+    const corsOrigins = this.getCorsOrigins();
+
+    // If no frontend URLs are configured, skip WebSocket initialization entirely
+    // This is expected for platform services that only receive backend-to-backend requests
+    // and don't need real-time WebSocket communication with browsers
+    if (corsOrigins.length === 0) {
+      this.logger.info('📝 No frontend URLs configured - skipping WebSocket initialization (platform/internal service mode)', {
+        availableEndpoints: Object.keys(this.configService.config?.runtime?.endPoints || {}),
+        note: 'This is expected for platform services that only receive backend-to-backend requests'
+      });
+
+      // Mark as "initialized" but in disabled mode - all public methods will safely no-op
+      this.io = null;
+      return;
+    }
+
+    const config: WebSocketConfig = {
+      cors: {
+        origin: corsOrigins,
+        credentials: true
+      },
+      transports: ['websocket', 'polling'],
+      pingTimeout: 60000,
+      pingInterval: 25000,
+      maxHttpBufferSize: 1e6,
+      allowEIO3: true
+    };
+
+    this.io = new SocketIOServer(httpServer, config);
+
+    // Setup Redis adapter for horizontal scaling
+    await this.setupRedisAdapter();
+
+    // Setup authentication middleware (FACTORIZED with HTTP)
+    this.setupAuthentication();
+
+    // Setup rate limiting middleware (Redis-synchronized across pods)
+    this.setupRateLimiting();
+
+    // Setup connection handling (identity-based rooms)
+    this.setupConnectionHandling();
+
+    this.logDebug('WebSocket service initialized', {
+      cors: config.cors.origin,
+      transports: config.transports
+    });
+  }
+
+  // =====================================================
+  // PUBLIC MESSAGING METHODS
+  // =====================================================
+
+  /**
+   * Send message to specific user (with cross-pod support via Redis adapter)
+   */
+  public async sendToUser(userId: string, message: WebSocketMessage): Promise<boolean> {
+    if (!this.io) {
+      this.logger.warn('WebSocket not initialized');
+      return false;
+    }
+
+    const roomName = buildUserRoomName(userId);
+    this.io.to(roomName).emit(message.type, {
+      ...message,
+      timestamp: new Date(),
+    });
+
+    this.logDebug('Message sent to user', {
+      userId: userId.substring(0, 8) + '...',
+      messageType: message.type,
+    });
+
+    return true;
+  }
+
+  /**
+   * Send a direct notification to a specific user.
+   *
+   * This is a convenience method for sending user notifications that are not
+   * tied to resource operations (e.g., "Your export is ready", "Payment received").
+   *
+   * @param userId - The user ID to notify
+   * @param notification - Notification configuration
+   * @param notification.type - Notification level (info, success, warning, error)
+   * @param notification.identifier - i18n identifier for message lookup
+   * @param notification.message - Direct message (fallback if identifier not found)
+   * @param notification.title - Optional notification title
+   * @param notification.data - Additional context data
+   * @param notification.displayTarget - Where to display (toast, center, or both)
+   * @param notification.organizationId - Organization context (optional)
+   *
+   * @example
+   * // Notify user about export completion
+   * await webSocketService.notifyUser(userId, {
+   *   type: NotificationLevel.SUCCESS,
+   *   identifier: 'export.completed',
+   *   data: { fileName: 'report.pdf', downloadUrl: '/files/123' },
+   * });
+   *
+   * @example
+   * // Notify user with direct message
+   * await webSocketService.notifyUser(userId, {
+   *   type: NotificationLevel.INFO,
+   *   message: 'Your session will expire in 5 minutes',
+   *   displayTarget: NotificationDisplayTarget.TOAST,
+   * });
+   */
+  public async notifyUser(
+    userId: string,
+    notification: {
+      type: NotificationLevel;
+      identifier?: string;
+      message?: string;
+      title?: string;
+      data?: Record<string, unknown>;
+      displayTarget?: NotificationDisplayTarget;
+      organizationId?: string;
+    }
+  ): Promise<boolean> {
+    const payload: WS_UserNotificationPayload = {
+      notificationLevel: notification.type,
+      identifier: notification.identifier,
+      message: notification.message,
+      title: notification.title,
+      data: notification.data,
+      displayTarget: notification.displayTarget ?? NotificationDisplayTarget.BOTH,
+      organizationId: notification.organizationId,
+      timestamp: new Date(),
+    };
+
+    const wsMessage: WebSocketMessage = {
+      type: CoreWebSocketEvent.USER_NOTIFICATION,
+      payload,
+      timestamp: new Date(),
+      userId,
+      organizationId: notification.organizationId,
+    };
+
+    return this.sendToUser(userId, wsMessage);
+  }
+
+  /**
+   * Send a direct notification to all users in an organization.
+   *
+   * @param organizationId - The organization ID
+   * @param notification - Notification configuration (same as notifyUser)
+   * @param excludeUsers - Optional list of user IDs to exclude
+   */
+  public async notifyOrganization(
+    organizationId: string,
+    notification: {
+      type: NotificationLevel;
+      identifier?: string;
+      message?: string;
+      title?: string;
+      data?: Record<string, unknown>;
+      displayTarget?: NotificationDisplayTarget;
+    },
+    excludeUsers?: string[]
+  ): Promise<number> {
+    const payload: WS_UserNotificationPayload = {
+      notificationLevel: notification.type,
+      identifier: notification.identifier,
+      message: notification.message,
+      title: notification.title,
+      data: notification.data,
+      displayTarget: notification.displayTarget ?? NotificationDisplayTarget.BOTH,
+      organizationId,
+      timestamp: new Date(),
+    };
+
+    const wsMessage: WebSocketMessage = {
+      type: CoreWebSocketEvent.USER_NOTIFICATION,
+      payload,
+      timestamp: new Date(),
+      organizationId,
+    };
+
+    return this.sendToOrganization(organizationId, wsMessage, excludeUsers);
+  }
+
+  /**
+   * Send message to organization (with cross-pod support via Redis adapter)
+   */
+  public async sendToOrganization(
+    organizationId: string,
+    message: WebSocketMessage,
+    excludeUsers?: string[]
+  ): Promise<number> {
+    const roomName = buildOrganizationRoomName(organizationId);
+    const messageWithTimestamp = {
+      ...message,
+      timestamp: new Date(),
+      organizationId
+    };
+
+    if (!this.io) {
+      this.logger.warn('WebSocket not initialized');
+      return 0;
+    }
+
+    if (excludeUsers && excludeUsers.length > 0) {
+      // For cross-pod compatibility with Redis adapter:
+      // 1. Send to the org room (reaches all pods)
+      // 2. Exclude users by emitting to their user rooms with a "skip" flag
+      //
+      // Alternative approach: Use Socket.IO's except() which works with Redis adapter
+      const excludeRooms = excludeUsers.map(userId => buildUserRoomName(userId));
+      let broadcast = this.io.to(roomName);
+      for (const excludeRoom of excludeRooms) {
+        broadcast = broadcast.except(excludeRoom);
+      }
+      broadcast.emit(message.type, messageWithTimestamp);
+
+      this.logDebug('Message sent to organization with exclusions', {
+        organizationId: organizationId.substring(0, 8) + '...',
+        messageType: message.type,
+        excludedUsers: excludeUsers.length,
+      });
+
+      // Return approximate count (exact count not available with except())
+      return 1;
+    } else {
+      this.io.to(roomName).emit(message.type, messageWithTimestamp);
+
+      this.logDebug('Message sent to organization', {
+        organizationId: organizationId.substring(0, 8) + '...',
+        messageType: message.type,
+      });
+
+      return 1;
+    }
+  }
+
+  /**
+   * Send message to users with specific role within an organization
+   */
+  public async sendToRole(
+    organizationId: string,
+    role: string,
+    message: WebSocketMessage
+  ): Promise<number> {
+    const roomName = buildOrganizationRoleRoomName(organizationId, role);
+    const messageWithTimestamp = {
+      ...message,
+      timestamp: new Date(),
+      organizationId
+    };
+
+    if (!this.io) {
+      this.logger.warn('WebSocket not initialized');
+      return 0;
+    }
+
+    const sentCount = (await this.io.in(roomName).fetchSockets()).length;
+    this.io.to(roomName).emit(message.type, messageWithTimestamp);
+
+    this.logDebug('Message sent to role', {
+      organizationId: organizationId.substring(0, 8) + '...',
+      role,
+      messageType: message.type,
+      sentCount
+    });
+
+    return sentCount;
+  }
+
+  /**
+   * Send message to users with application-level role (admin dashboard users).
+   *
+   * Application-level roles are not scoped to an organization - they are global
+   * admin roles like super admins, support staff, billing admins, etc.
+   *
+   * Users with app-level roles join app role rooms (via buildAppRoleRoomName) on connection.
+   *
+   * @param role - The application-level role (e.g., 'admin', 'super_admin', 'support')
+   * @param message - The WebSocket message to send
+   * @returns Number of sockets the message was sent to
+   *
+   * @example
+   * // Notify all application administrators
+   * await webSocketService.sendToAppRole(CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN, {
+   *   type: CoreWebSocketEvent.USER_NOTIFICATION,
+   *   payload: { notificationLevel: NotificationLevel.WARNING, message: 'New user signup requires review' },
+   *   timestamp: new Date(),
+   * });
+   */
+  public async sendToAppRole(
+    role: string,
+    message: WebSocketMessage
+  ): Promise<number> {
+    const roomName = buildAppRoleRoomName(role);
+    const messageWithTimestamp = {
+      ...message,
+      timestamp: new Date(),
+    };
+
+    if (!this.io) {
+      this.logger.warn('WebSocket not initialized');
+      return 0;
+    }
+
+    const sentCount = (await this.io.in(roomName).fetchSockets()).length;
+    this.io.to(roomName).emit(message.type, messageWithTimestamp);
+
+    this.logDebug('Message sent to app role', {
+      role,
+      messageType: message.type,
+      sentCount
+    });
+
+    return sentCount;
+  }
+
+  /**
+   * Send a direct notification to users with a specific application-level role.
+   *
+   * Convenience method for sending admin notifications.
+   *
+   * @param role - The application-level role
+   * @param notification - Notification configuration
+   *
+   * @example
+   * // Notify support staff about a new ticket
+   * await webSocketService.notifyAppRole(CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN, {
+   *   type: NotificationLevel.INFO,
+   *   identifier: 'support.new_ticket',
+   *   data: { ticketId: '123', subject: 'Help needed' },
+   * });
+   */
+  public async notifyAppRole(
+    role: string,
+    notification: {
+      type: NotificationLevel;
+      identifier?: string;
+      message?: string;
+      title?: string;
+      data?: Record<string, unknown>;
+      displayTarget?: NotificationDisplayTarget;
+    }
+  ): Promise<number> {
+    const payload: WS_UserNotificationPayload = {
+      notificationLevel: notification.type,
+      identifier: notification.identifier,
+      message: notification.message,
+      title: notification.title,
+      data: notification.data,
+      displayTarget: notification.displayTarget ?? NotificationDisplayTarget.BOTH,
+      timestamp: new Date(),
+    };
+
+    const wsMessage: WebSocketMessage = {
+      type: CoreWebSocketEvent.USER_NOTIFICATION,
+      payload,
+      timestamp: new Date(),
+    };
+
+    return this.sendToAppRole(role, wsMessage);
+  }
+
+  /**
+   * Broadcast message to all connected users
+   */
+  public async broadcast(message: WebSocketMessage): Promise<number> {
+    if (!this.io) {
+      this.logger.warn('WebSocket not initialized');
+      return 0;
+    }
+
+    const messageWithTimestamp = {
+      ...message,
+      timestamp: new Date()
+    };
+
+    const sockets = await this.io.fetchSockets();
+    this.io.emit(message.type, messageWithTimestamp);
+
+    this.logDebug('Message broadcasted', {
+      messageType: message.type,
+      connectedSockets: sockets.length
+    });
+
+    return sockets.length;
+  }
+
+  // =====================================================
+  // RESOURCE ROOM PUBLIC METHODS (for NotificationDispatcher)
+  // =====================================================
+
+  /**
+   * Extract DataMode from a websocket payload.
+   * Defaults to RAW for websocket messages when no explicit data mode is present.
+   */
+  private extractDataMode(payload?: { dataMode?: DataMode | 'raw' | 'summary' | 'context' | string }): DataMode {
+    return ResourceOperationsUtils.extractDataMode(payload, undefined, DataMode.RAW);
+  }
+
+  /**
+   * Select the appropriate response DTO based on DataMode.
+   * Similar to controller-resource.backend.service.ts
+   */
+  private selectResponseDto(
+    operation: ResourceConfiguration_Operation<any, any, any> | null,
+    dataMode?: DataMode
+  ): z.ZodTypeAny | undefined {
+    if (!operation) {
+      return undefined;
+    }
+    return ResourcesConfigOperationsDtosBuilderUtils.selectResponseDto(operation, dataMode) || undefined;
+  }
+
+  /**
+   * Validate and transform websocket resource data before sending it.
+   * Similar to controller-resource.backend.service.ts sendResponse() method.
+   *
+   * This method validates resource data against the appropriate DTO and transforms dates.
+   * It is used for sync-grade replay payloads and for custom websocket events that
+   * choose to carry resource-shaped data.
+   *
+   * @param resourceData - The resource data to validate (if present in payload)
+   * @param resourceType - Resource type
+   * @param operationIdentifier - Operation identifier (optional)
+   * @param dataMode - Data mode (defaults to RAW)
+   * @returns Validated and transformed resource data, or false when validation cannot proceed
+   */
+  private resolveOperationForWebSocketValidation(params: {
+    resourceType: string;
+    operationIdentifier?: string;
+    dataMode: DataMode;
+    validationTarget: 'canonical-read' | 'operation-response';
+  }) {
+    const desiredOperationIdentifier = params.validationTarget === 'canonical-read'
+      ? CoreResourceOperation.READ
+      : params.operationIdentifier ?? CoreResourceOperation.READ;
+
+    try {
+      const operationPath = this.resourcesRegistry.getOperationPathDefault(
+        params.resourceType,
+        desiredOperationIdentifier as CoreResourceOperation,
+      );
+      return this.resourcesRegistry.getOperationFromPath(operationPath);
+    } catch (error) {
+      this.logger.warn('WebSocket resource data validation lookup failed', {
+        resourceType: params.resourceType,
+        operationIdentifier: params.operationIdentifier,
+        desiredOperationIdentifier,
+        dataMode: params.dataMode,
+        validationTarget: params.validationTarget,
+        error: error instanceof Error ? error.message : 'Unknown',
+      });
+      return null;
+    }
+  }
+
+  private validateAndTransformResourceData(
+    resourceData: any,
+    resourceType: string,
+    operationIdentifier?: string,
+    dataMode: DataMode = DataMode.RAW,
+    validationTarget: 'canonical-read' | 'operation-response' = 'canonical-read',
+  ): { success: true; data: unknown } | { success: false } {
+    // If no resource data provided, signal the caller to emit metadata only.
+    if (!resourceData || typeof resourceData !== 'object') {
+      return { success: false };
+    }
+
+    const operation = this.resolveOperationForWebSocketValidation({
+      resourceType,
+      operationIdentifier,
+      dataMode,
+      validationTarget,
+    });
+    if (!operation) {
+      return { success: false };
+    }
+
+    // Select appropriate DTO based on DataMode
+    const selectedDto = this.selectResponseDto(operation, dataMode);
+
+    if (!selectedDto) {
+      return { success: false };
+    }
+
+    try {
+      // Transform dates from Date objects to ISO strings before validation
+      let transformedData = resourceData;
+      transformedData = ResourcesConfigOperationsDtosBuilderUtils.transformResponseDates(
+        resourceData,
+        selectedDto
+      );
+
+      // Validate response against the selected DTO as a runtime safety net
+      // Handle array responses (LIST, CREATE_MANY, etc.)
+      const effectiveOperation = operation.resourceOperationLike || operation.operationIdentifier;
+      const isArrayOperation = ARRAY_RESPONSE_OPERATIONS.includes(effectiveOperation as any);
+
+      if (isArrayOperation && Array.isArray(transformedData)) {
+        // For array operations, validate each item individually
+        return {
+          success: true,
+          data: transformedData.map(item => selectedDto.parse(item)),
+        };
+      } else {
+        // For single-item operations, validate directly
+        return {
+          success: true,
+          data: selectedDto.parse(transformedData),
+        };
+      }
+    } catch (error) {
+      this.logger.warn('WebSocket resource data validation failed', {
+        resourceType,
+        operationIdentifier,
+        dataMode,
+        error: error instanceof Error ? error.message : 'Unknown',
+        resourceDataKeys: typeof resourceData === 'object' ? Object.keys(resourceData) : 'not-object'
+      });
+      return { success: false };
+    }
+  }
+
+  private stripScopeNotificationReplayFields(
+    payload: WS_ResourceUpdateNotificationPayload,
+  ): WS_ResourceUpdateNotificationPayload {
+    const {
+      resourceData: _resourceData,
+      fieldMeta: _fieldMeta,
+      version: _version,
+      dataMode: _dataMode,
+      ...notificationPayload
+    } = payload;
+    return notificationPayload;
+  }
+
+  private validateAndTransformSyncReplayData(params: {
+    resourceData: unknown;
+    resourceType: string;
+    dataMode?: DataMode;
+  }): { success: true; data: unknown } | { success: false } {
+    const dataMode = params.dataMode ?? DataMode.RAW;
+
+    if (!params.resourceData || typeof params.resourceData !== 'object') {
+      this.logger.warn('WebSocket sync replay payload is missing resource data', {
+        resourceType: params.resourceType,
+        dataMode,
+      });
+      return { success: false };
+    }
+
+    const readOperation = this.resolveOperationForWebSocketValidation({
+      resourceType: params.resourceType,
+      dataMode,
+      validationTarget: 'canonical-read',
+    });
+    if (!readOperation) {
+      return { success: false };
+    }
+    const selectedDto = this.selectResponseDto(readOperation, dataMode);
+
+    if (!selectedDto) {
+      this.logger.warn('WebSocket sync replay payload missing canonical READ DTO', {
+        resourceType: params.resourceType,
+        dataMode,
+      });
+      return { success: false };
+    }
+
+    try {
+      const transformedData = ResourcesConfigOperationsDtosBuilderUtils.transformResponseDates(
+        params.resourceData,
+        selectedDto,
+      );
+      return {
+        success: true,
+        data: selectedDto.parse(transformedData),
+      };
+    } catch (error) {
+      this.logger.warn('WebSocket sync replay validation failed', {
+        resourceType: params.resourceType,
+        dataMode,
+        error: error instanceof Error ? error.message : 'Unknown',
+        resourceDataKeys: typeof params.resourceData === 'object' ? Object.keys(params.resourceData as Record<string, unknown>) : 'not-object',
+      });
+      return { success: false };
+    }
+  }
+
+  /**
+   * Emit to a specific resource room (path-independent)
+   * Called by NotificationDispatcherService after CRUD operations
+   *
+   * Resource-room sync payloads now validate replay-grade resource data when it
+   * is present in the payload.
+   *
+   * @param resourceType - Resource type
+   * @param resourceId - Resource ID
+   * @param event - WebSocket event name
+   * @param payload - Resource-room payload. Sync-grade update payloads carry authoritative
+   * `version` + `resourceData`; delete/state payloads intentionally do not.
+   *
+   * @example
+   * // Send notification-grade metadata only
+   * websocketService.emitToResourceRoom('users', 'userId123', CoreWebSocketEvent.RESOURCE_UPDATED, {
+   *   resourceType: 'users',
+   *   resourceId: 'userId123',
+   *   contextResourceIdentifiers: {},
+   *   action: ResourceAction.UPDATED,
+   *   operationIdentifier: CoreResourceOperation.UPDATE
+   * });
+   *
+   * @example
+   * // Send synchronization-grade replay data for RESOURCE_ROOM_SYNC
+   * websocketService.emitToResourceRoom('users', 'userId123', CoreWebSocketEvent.RESOURCE_UPDATED, {
+   *   resourceType: 'users',
+   *   resourceId: 'userId123',
+   *   contextResourceIdentifiers: {},
+   *   action: ResourceAction.UPDATED,
+   *   operationIdentifier: CoreResourceOperation.UPDATE,
+   *   resourceData: updatedUserObject, // Full resource object
+   *   dataMode: DataMode.RAW // or DataMode.SUMMARY, DataMode.CONTEXT
+   * });
+   */
+  public emitToResourceRoom(
+    resourceType: string,
+    resourceId: string,
+    event: string,
+    payload: WebSocketResourceRoomEmitPayload
+  ): boolean {
+    if (!this.io) {
+      this.logger.warn('WebSocket not initialized, cannot emit to resource room');
+      return false;
+    }
+
+    // Only sync-grade resource-room payloads are allowed to act like
+    // authoritative replay input for clients. Notification-grade room payloads
+    // still emit, but they do not go through the stricter canonical replay gate.
+    const shouldValidateSyncReplay = payload.deliveryTarget === WebSocketResourceDeliveryTarget.RESOURCE_ROOM_SYNC
+      && 'resourceData' in payload;
+    let payloadToEmit: WebSocketResourceRoomEmitPayload = payload;
+    let dataMode: DataMode = DataMode.RAW;
+
+    if (shouldValidateSyncReplay) {
+      dataMode = this.extractDataMode({ dataMode: payload.dataMode });
+      const validation = this.validateAndTransformSyncReplayData({
+        resourceData: payload.resourceData,
+        resourceType,
+        dataMode,
+      });
+      if (!validation.success) {
+        this.logDebug('Skipped resource-room emit: sync replay payload failed canonical validation', {
+          resourceType,
+          resourceId,
+          event,
+          deliveryTarget: payload.deliveryTarget,
+        });
+        return false;
+      }
+      payloadToEmit = {
+        ...payload,
+        resourceData: validation.data as Record<string, unknown>,
+      };
+    }
+
+    const roomName = buildResourceRoomName(resourceType, resourceId);
+    this.io.to(roomName).emit(event, payloadToEmit);
+
+    this.logDebug('Emitted to resource room', {
+      roomName,
+      event,
+      dataMode: shouldValidateSyncReplay ? dataMode : undefined,
+      hasResourceData: shouldValidateSyncReplay,
+      deliveryTarget: payload.deliveryTarget,
+    });
+    return true;
+  }
+
+  /**
+   * Helper method to send resource data via WebSocket with automatic validation.
+   *
+   * This is a convenience method that prepares a payload with resource data and sends it
+   * to a resource room. Use this when you want to send authoritative resource objects via
+   * WebSocket.
+   *
+   * @param resourceType - Resource type
+   * @param resourceId - Resource ID
+   * @param event - WebSocket event name (e.g., CoreWebSocketEvent.RESOURCE_UPDATED)
+   * @param action - Resource action (ResourceAction.CREATED, UPDATED, DELETED)
+   * @param resourceData - The resource data object to send (will be validated and transformed)
+   * @param options - Optional configuration
+   * @param options.operationIdentifier - Operation identifier (e.g., CoreResourceOperation.UPDATE)
+   * @param options.dataMode - Data mode (defaults to RAW)
+   * @param options.contextResourceIdentifiers - Context resource identifiers
+   * @param options.affectedIds - Array of affected resource IDs
+   * @param options.initiatorUserId - User ID of the initiator
+   *
+   * @example
+   * // Send updated user resource
+   * await websocketService.sendResourceData(
+   *   'users',
+   *   'userId123',
+   *   CoreWebSocketEvent.RESOURCE_UPDATED,
+   *   ResourceAction.UPDATED,
+   *   updatedUserObject,
+   *   {
+   *     operationIdentifier: CoreResourceOperation.UPDATE,
+   *     dataMode: DataMode.RAW,
+   *     contextResourceIdentifiers: {},
+   *     initiatorUserId: 'currentUserId'
+   *   }
+   * );
+   *
+   * @example
+   * // Send created resource with summary data
+   * await websocketService.sendResourceData(
+   *   'todos',
+   *   'todoId456',
+   *   CoreWebSocketEvent.RESOURCE_UPDATED,
+   *   ResourceAction.CREATED,
+   *   newTodoObject,
+   *   {
+   *     operationIdentifier: CoreResourceOperation.CREATE,
+   *     dataMode: DataMode.SUMMARY, // Use summary for list refreshes
+   *     contextResourceIdentifiers: { organizationId: 'org123' },
+   *     initiatorUserId: 'currentUserId'
+   *   }
+   * );
+   */
+  public sendResourceData(
+    resourceType: string,
+    resourceId: string,
+    event: string,
+    action: ResourceAction,
+    resourceData: any,
+    options: {
+      operationIdentifier?: string;
+      dataMode?: DataMode | string;
+      contextResourceIdentifiers?: Record<string, string>;
+      affectedIds?: string[];
+      initiatorUserId?: string;
+      version?: number;
+    } = {}
+  ): void {
+    const {
+      operationIdentifier,
+      dataMode = DataMode.RAW,
+      contextResourceIdentifiers = {},
+      affectedIds,
+      initiatorUserId,
+      version,
+    } = options;
+
+    // Convert DataMode enum to string for schema compatibility
+    const effectiveDataMode = typeof dataMode === 'string'
+      ? ResourceOperationsUtils.normalizeDataModeString(dataMode) || DataMode.RAW
+      : dataMode || DataMode.RAW;
+    const dataModeString = ResourceOperationsUtils.dataModeToString(effectiveDataMode);
+    const resolvedVersion = version ?? (
+      resourceData && typeof resourceData === 'object'
+        ? (resourceData as Record<string, unknown>)._version as number | undefined
+        : undefined
+    );
+
+    if (action !== ResourceAction.DELETED && resolvedVersion == null) {
+      this.logger.warn('sendResourceData skipped sync payload without authoritative version', {
+        resourceType,
+        resourceId,
+        event,
+        action,
+      });
+      return;
+    }
+
+    const payload: WS_ResourceSyncUpdatedPayload | WS_ResourceDeletedPayload = action === ResourceAction.DELETED
+      ? {
+          deliveryTarget: WebSocketResourceDeliveryTarget.RESOURCE_ROOM_SYNC,
+          resourceType,
+          resourceId,
+          contextResourceIdentifiers,
+          action: ResourceAction.DELETED,
+          operationIdentifier: operationIdentifier ?? CoreResourceOperation.DELETE,
+          affectedIds,
+          initiatorUserId,
+          timestamp: new Date(),
+        }
+      : {
+          deliveryTarget: WebSocketResourceDeliveryTarget.RESOURCE_ROOM_SYNC,
+          resourceType,
+          resourceId,
+          contextResourceIdentifiers,
+          action,
+          operationIdentifier: operationIdentifier ?? CoreResourceOperation.UPDATE,
+          resourceData,
+          dataMode: dataModeString,
+          affectedIds,
+          initiatorUserId,
+          timestamp: new Date(),
+          version: resolvedVersion,
+        };
+
+    this.emitToResourceRoom(resourceType, resourceId, event, payload);
+  }
+
+  /**
+   * Emit to scope rooms (collections) for list refresh
+   * Called by NotificationDispatcherService after CRUD operations
+   *
+   * Scope-room payloads validate resource-shaped data when it is present in the
+   * payload, while still treating these emissions as notification-grade rather
+   * than replay-grade sync.
+   *
+   * @param resourceType - Resource type
+   * @param scopes - Array of scope rooms to emit to
+   * @param event - WebSocket event name
+   * @param payload - Payload with optional resourceData and dataMode
+   *
+   * @example
+   * // Send notification-grade metadata for list refresh
+   * websocketService.emitToScopeRooms('users', [{ scopeKey: 'organization', scopeId: 'org123' }],
+   *   CoreWebSocketEvent.RESOURCE_UPDATED, { ... });
+   *
+   * @example
+   * // Send optional summary data for list refresh
+   * websocketService.emitToScopeRooms('users', [{ scopeKey: 'organization', scopeId: 'org123' }],
+   *   CoreWebSocketEvent.RESOURCE_UPDATED, {
+   *     ...metadata,
+   *     resourceData: updatedUserObject,
+   *     dataMode: DataMode.SUMMARY // Use SUMMARY for list refreshes
+   *   });
+   */
+  public emitToScopeRooms(
+    resourceType: string,
+    scopes: Array<{ scopeKey: string; scopeId: string }>,
+    event: string,
+    payload: WS_ResourceUpdateNotificationPayload
+  ): void {
+    if (!this.io) return;
+
+    // Extract DataMode and validate resource data if present
+    const dataMode = this.extractDataMode({ dataMode: payload.dataMode });
+    let validatedPayload = { ...payload };
+    const resourceData = payload.resourceData;
+
+    // Scope-room payloads stay notification-grade. If DTO shaping fails, strip
+    // replay-like fields rather than emitting non-canonical bodies; list
+    // invalidation is still useful even when authoritative replay truth is not.
+    if (resourceData) {
+      const validation = this.validateAndTransformResourceData(
+        resourceData,
+        resourceType,
+        undefined,
+        dataMode,
+        'canonical-read',
+      );
+
+      if (validation.success) {
+        validatedPayload = {
+          ...validatedPayload,
+          resourceData: validation.data,
+        };
+      } else {
+        validatedPayload = this.stripScopeNotificationReplayFields(validatedPayload);
+      }
+    }
+
+    for (const scope of scopes) {
+      const roomName = buildScopeRoomName(resourceType, scope.scopeKey, scope.scopeId);
+      this.io.to(roomName).emit(event, validatedPayload);
+    }
+
+    this.logDebug('Emitted to scope rooms', {
+      resourceType,
+      scopeCount: scopes.length,
+      event,
+      dataMode,
+      hasResourceData: !!resourceData,
+      deliveryTarget: payload.deliveryTarget,
+    });
+  }
+
+  /**
+   * Get all users currently editing a resource
+   */
+  public async getResourceEditingUsers(resourceType: string, resourceId: string): Promise<string[]> {
+    const prefix = this.redisService.getAppPrefix();
+    const key = `${prefix}editing:${resourceType}:${resourceId}`;
+    const redisClient = this.redisService.getClient();
+
+    if (!redisClient) {
+      return Array.from(this.resourceEditingState.get(key) || []);
+    }
+
+    try {
+      const editing = await redisClient.hGetAll(key);
+      return Object.keys(editing);
+    } catch {
+      return Array.from(this.resourceEditingState.get(key) || []);
+    }
+  }
+
+  // =====================================================
+  // ROOM MANAGEMENT
+  // =====================================================
+
+  /**
+   * Create custom room
+   */
+  public async createRoom(
+    roomName: string,
+    organizationId: string,
+    type: RoomInfo['type'] = 'custom',
+    metadata?: Record<string, any>
+  ): Promise<void> {
+    const room: RoomInfo = {
+      name: roomName,
+      organizationId,
+      type,
+      members: new Set(),
+      metadata
+    };
+
+    this.rooms.set(roomName, room);
+
+    this.logDebug('Room created', {
+      roomName,
+      organizationId: organizationId.substring(0, 8) + '...',
+      type,
+    });
+  }
+
+  /**
+   * Join user to room
+   */
+  public async joinRoom(userId: string, roomName: string): Promise<boolean> {
+    const socketIds = this.userSockets.get(userId);
+    const room = this.rooms.get(roomName);
+
+    if (!socketIds || !room || !this.io) {
+      return false;
+    }
+
+    room.members.add(userId);
+
+    for (const socketId of socketIds) {
+      const socket = this.io.sockets.sockets.get(socketId);
+      if (socket) {
+        await socket.join(roomName);
+      }
+    }
+
+    this.logDebug('User joined room', { userId: userId.substring(0, 8) + '...', roomName });
+    return true;
+  }
+
+  /**
+   * Remove user from room
+   */
+  public async leaveRoom(userId: string, roomName: string): Promise<boolean> {
+    const socketIds = this.userSockets.get(userId);
+    const room = this.rooms.get(roomName);
+
+    if (!socketIds || !room || !this.io) {
+      return false;
+    }
+
+    room.members.delete(userId);
+
+    for (const socketId of socketIds) {
+      const socket = this.io.sockets.sockets.get(socketId);
+      if (socket) {
+        await socket.leave(roomName);
+      }
+    }
+
+    this.logDebug('User left room', { userId: userId.substring(0, 8) + '...', roomName });
+    return true;
+  }
+
+  // =====================================================
+  // STATUS METHODS
+  // =====================================================
+
+  public getConnectedUsersCount(): number {
+    return this.authenticatedSockets.size;
+  }
+
+  public getOrganizationUsersCount(organizationId: string): number {
+    const socketIds = this.organizationSockets.get(organizationId);
+    return socketIds ? socketIds.size : 0;
+  }
+
+  public isUserConnected(userId: string): boolean {
+    const socketIds = this.userSockets.get(userId);
+    return socketIds ? socketIds.size > 0 : false;
+  }
+
+  public getRoomInfo(roomName: string): RoomInfo | undefined {
+    return this.rooms.get(roomName);
+  }
+
+  // =====================================================
+  // PRIVATE SETUP METHODS
+  // =====================================================
+
+  /**
+   * Get CORS origins from app-config runtime endpoints
+   */
+  private getCorsOrigins(): string[] {
+    // Config must be initialized - this is ensured by the initialization order:
+    // 1. AppsUpdaterConfigService fetches config from apps-manager
+    // 2. Standard AppConfigurationService is initialized with that config
+    // 3. HTTP server starts, which initializes WebSocket
+    // If config is not initialized here, it's a programming error - fail fast
+    if (!this.configService.isInitialized()) {
+      throw this.errorBuilder.buildError(
+        ErrorType.CONFIGURATION,
+        undefined,
+        {
+          customMessageReference: ErrorCustomMessageReference.APP_CONFIGURATION_NOT_INITIALIZED,
+          context: {
+            message: 'Application configuration not initialized : use config before using the service',
+            service: 'WebSocketService',
+            operation: 'getCorsOrigins'
+          }
+        }
+      );
+    }
+
+    const config = this.configService.config;
+    const frontendServices = Object.keys(config.frontendServices ?? {});
+
+    return frontendServices.map((frontendServiceName) => {
+      const url = config.runtime?.endPoints?.[frontendServiceName]?.publicUrl;
+      if (!url) {
+        throw new Error(
+          `Missing runtime.endPoints.${frontendServiceName}.publicUrl for declared frontend service "${frontendServiceName}". ` +
+          'WebSocket CORS cannot be derived from an incomplete runtime topology.',
+        );
+      }
+      return url;
+    });
+  }
+
+  /**
+   * Setup Redis adapter for horizontal scaling across Kubernetes pods
+   */
+  private async setupRedisAdapter(): Promise<void> {
+    try {
+      if (!this.io) {
+        throw new Error('Socket.IO server not initialized');
+      }
+
+      // Check if config is initialized before accessing
+      if (!this.configService.isInitialized()) {
+        this.logger.warn('App config not initialized, using memory adapter (single instance only)');
+        return;
+      }
+      const appConfig = this.configService.config;
+      const appSecrets = this.configService.secrets;
+
+      if (!appConfig.database.redis) {
+        this.logger.warn('Redis not configured, using memory adapter (single instance only)');
+        return;
+      }
+
+      const redisHost = appConfig.database.redis.host;
+      const redisPort = appConfig.database.redis.port || 6379;
+      const redisPassword = appSecrets?.database?.redis?.password;
+      const redisUsername = appSecrets?.database?.redis?.username;
+
+      if (!redisHost || redisHost.includes('localhost')) {
+        this.logger.warn('Redis not properly configured for production, using memory adapter (single instance only)');
+        return;
+      }
+
+      // Build Redis client options (same pattern as RedisService)
+      // Include username for ACL authentication (required when using app-specific credentials)
+      const redisOptions: Parameters<typeof createClient>[0] = {
+        socket: {
+          host: redisHost,
+          port: redisPort,
+          connectTimeout: 10000
+        },
+        username: redisUsername,
+        password: redisPassword,
+      };
+
+      const pubClient = createClient(redisOptions);
+      const subClient = pubClient.duplicate();
+
+      // CRITICAL: Attach error handlers BEFORE connect to prevent "missing 'error' handler" warnings
+      // These handlers prevent unhandled errors from crashing the process during Redis restarts
+      pubClient.on('error', (error) => {
+        this.logger.error('Socket.IO Redis pubClient error', {
+          error: error instanceof Error ? error.message : String(error)
+        });
+      });
+      subClient.on('error', (error) => {
+        this.logger.error('Socket.IO Redis subClient error', {
+          error: error instanceof Error ? error.message : String(error)
+        });
+      });
+
+      // Reconnection handlers for visibility
+      pubClient.on('reconnecting', () => {
+        this.logDebug('Socket.IO Redis pubClient reconnecting...');
+      });
+      subClient.on('reconnecting', () => {
+        this.logDebug('Socket.IO Redis subClient reconnecting...');
+      });
+
+      await Promise.all([
+        pubClient.connect(),
+        subClient.connect()
+      ]);
+
+      // SECURITY FIX: Use tenant-specific channel prefix for Socket.IO adapter
+      // This ensures each tenant's Socket.IO messages are isolated to their own channels
+      // ACL pattern &{username}#* will only allow access to channels with this prefix
+      const channelPrefix = redisUsername || 'default';
+      this.io.adapter(createAdapter(pubClient, subClient, { key: channelPrefix }));
+
+      this.logDebug('Socket.IO Redis adapter configured for horizontal scaling', {
+        redisHost,
+        redisPort,
+        channelPrefix,
+        scalingEnabled: true,
+        environment: process.env.APPLICATION_ENV || 'development'
+      });
+
+    } catch (error: unknown) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+      this.logger.error('Failed to setup Redis adapter, falling back to memory adapter', {
+        error: errorMessage,
+      });
+      this.logger.warn('Using memory adapter - horizontal scaling will not work across pods');
+    }
+  }
+
+  /**
+   * Setup authentication middleware
+   * FACTORIZED: Uses ExecutionContextCreatorBackendService for JWT validation
+   */
+  private setupAuthentication(): void {
+    if (!this.io) return;
+
+    this.io.use(async (socket, next) => {
+      try {
+        const token = socket.handshake.auth.token ||
+                      socket.handshake.headers.authorization?.replace('Bearer ', '');
+
+        let authResult: SocketAuthResult;
+
+        if (!token) {
+          // No token = public connection (allowed but limited)
+          authResult = this.executionContextCreator.getPublicSocketAuth();
+          this.logDebug('Public socket connection (no token)');
+        } else {
+          authResult = await this.executionContextCreator.authenticateSocketConnection(token);
+
+          // W7.3b: Capture consumable token from handshake auth or headers
+          const consumableToken = socket.handshake.auth?.consumableToken
+            || socket.handshake.headers?.[WildoHeaderKeys.CONSUMABLE_TOKEN];
+          if (consumableToken && typeof consumableToken === 'string') {
+            authResult.consumableTokenValue = consumableToken;
+          }
+
+          this.logDebug('Authenticated socket connection', {
+            executionType: authResult.executionType,
+            userId: authResult.initiatorIds?.userId?.substring(0, 8) + '...',
+            rolesCount: authResult.initiatorRoles.length,
+            hasConsumableToken: !!authResult.consumableTokenValue,
+          });
+        }
+
+        (socket as any).auth = authResult;
+        next();
+
+      } catch (error) {
+        this.logger.warn('WebSocket authentication failed', {
+          error: error instanceof Error ? error.message : 'Unknown error'
+        });
+        next(new Error('Authentication failed'));
+      }
+    });
+  }
+
+  /**
+   * Setup rate limiting middleware
+   * Uses Redis for cross-pod synchronization of rate limit counters
+   */
+  private setupRateLimiting(): void {
+    if (!this.io) return;
+
+    // Intercept all incoming events with rate limiting
+    this.io.use(async (socket, next) => {
+      // Override socket.on to wrap event handlers with rate limiting
+      const originalOn = socket.on.bind(socket);
+
+      (socket as any).on = (event: string, handler: (...args: any[]) => void) => {
+        // Skip internal Socket.IO events
+        if (event.startsWith('$') || ['connect', 'disconnect', 'error'].includes(event)) {
+          return originalOn(event, handler);
+        }
+
+        // Wrap handler with rate limiting check
+        return originalOn(event, async (...args: any[]) => {
+          const auth = (socket as any).auth as SocketAuthResult;
+          const identifier = auth.initiatorIds?.userId || socket.id;
+
+          const allowed = await this.checkRateLimit(identifier, event);
+          if (!allowed) {
+            // Rate limit exceeded - emit error and skip handler
+            socket.emit(CoreWebSocketEvent.SYSTEM_ERROR, {
+              code: 'RATE_LIMIT_EXCEEDED',
+              message: `Too many ${event} requests. Please slow down.`,
+              details: { event }
+            });
+            this.logDebug('Rate limit exceeded', {
+              identifier: identifier.substring(0, 8),
+              event
+            });
+            return;
+          }
+
+          // Call original handler
+          handler(...args);
+        });
+      };
+
+      next();
+    });
+  }
+
+  /**
+   * Check rate limit for an event using Redis
+   * Returns true if allowed, false if rate limited
+   *
+   * Uses sliding window algorithm with Redis INCR and EXPIRE
+   */
+  private async checkRateLimit(identifier: string, event: string): Promise<boolean> {
+    const config = DEFAULT_RATE_LIMITS[event] || DEFAULT_RATE_LIMITS['default'];
+    const redisClient = this.redisService.getClient();
+
+    // Fallback to in-memory if Redis unavailable (less accurate cross-pod)
+    if (!redisClient) {
+      return this.checkRateLimitInMemory(identifier, event, config);
+    }
+
+    try {
+      const prefix = this.redisService.getAppPrefix();
+      const key = `${prefix}ws:ratelimit:${identifier}:${event}`;
+      const windowKey = `${key}:${Math.floor(Date.now() / (config.windowSeconds * 1000))}`;
+
+      // Increment counter for current window
+      const count = await redisClient.incr(windowKey);
+
+      // Set expiry on first request in window
+      if (count === 1) {
+        await redisClient.expire(windowKey, config.windowSeconds + 1);
+      }
+
+      return count <= config.maxEvents;
+
+    } catch (error) {
+      // On Redis error, allow the request (fail open)
+      this.logger.warn('Rate limit check failed, allowing request', {
+        identifier: identifier.substring(0, 8),
+        event,
+        error: error instanceof Error ? error.message : 'Unknown',
+      });
+      return true;
+    }
+  }
+
+  /**
+   * In-memory rate limiting fallback (single pod only)
+   */
+  private inMemoryRateLimits: Map<string, { count: number; resetAt: number }> = new Map();
+
+  private checkRateLimitInMemory(
+    identifier: string,
+    event: string,
+    config: RateLimitConfig
+  ): boolean {
+    const key = `${identifier}:${event}`;
+    const now = Date.now();
+    const entry = this.inMemoryRateLimits.get(key);
+
+    if (!entry || now >= entry.resetAt) {
+      // Start new window
+      this.inMemoryRateLimits.set(key, {
+        count: 1,
+        resetAt: now + (config.windowSeconds * 1000),
+      });
+      return true;
+    }
+
+    if (entry.count >= config.maxEvents) {
+      return false;
+    }
+
+    entry.count++;
+    return true;
+  }
+
+  /**
+   * Setup connection handling
+   * Joins user to identity-based rooms based on their roles and IDs
+   * Sets up resource room handlers for collaboration
+   */
+  private setupConnectionHandling(): void {
+    if (!this.io) return;
+
+    this.io.on('connection', (socket: Socket) => {
+      const auth = (socket as any).auth as SocketAuthResult;
+
+      // Track authenticated socket
+      this.authenticatedSockets.set(socket.id, auth);
+
+      // === IDENTITY-BASED ROOM ASSIGNMENT ===
+
+      if (auth.executionType === ExecutionContext_ExecutionType.PUBLIC_EXECUTION) {
+        // Public users only join public room
+        socket.join(WebSocketRoomPrefix.PUBLIC);
+        this.logDebug('Public socket connected', { socketId: socket.id });
+
+        // Still setup disconnect handler
+        socket.on('disconnect', () => {
+          this.handleSocketDisconnection(socket.id, this.getSocketAuth(socket));
+        });
+        return;
+      }
+
+      // User: Join organization-based rooms from their roles
+      for (const roleInfo of auth.initiatorRoles) {
+        if (roleInfo.relatedPrimaryScope === ResourcePrimaryScope.ORGANIZATIONS && roleInfo.relatedResourceId) {
+          const orgId = roleInfo.relatedResourceId;
+
+          // Organization room (receives all org-wide notifications)
+          socket.join(buildOrganizationRoomName(orgId));
+
+          // Track organization sockets
+          if (!this.organizationSockets.has(orgId)) {
+            this.organizationSockets.set(orgId, new Set());
+          }
+          this.organizationSockets.get(orgId)!.add(socket.id);
+
+          // Role-specific rooms (for role-targeted notifications)
+          for (const role of roleInfo.roles || []) {
+            socket.join(buildOrganizationRoleRoomName(orgId, role));
+          }
+        }
+
+        if (roleInfo.relatedPrimaryScope === ResourcePrimaryScope.APPLICATION && roleInfo.relatedResourceId) {
+          // App-level role room (for app admins, super admins)
+          for (const role of roleInfo.roles || []) {
+            socket.join(buildAppRoleRoomName(role));
+          }
+        }
+      }
+
+      // User-specific room (for direct messages, personal notifications)
+      if (auth.initiatorIds?.userId) {
+        socket.join(buildUserRoomName(auth.initiatorIds.userId));
+
+        // Track user sockets for multi-tab support
+        if (!this.userSockets.has(auth.initiatorIds.userId)) {
+          this.userSockets.set(auth.initiatorIds.userId, new Set());
+        }
+        this.userSockets.get(auth.initiatorIds.userId)!.add(socket.id);
+      }
+
+      this.logDebug('Socket connected with identity rooms', {
+        socketId: socket.id,
+        executionType: auth.executionType,
+        userId: auth.initiatorIds?.userId?.substring(0, 8),
+        organizationRoles: auth.initiatorRoles.filter(r => r.relatedPrimaryScope === ResourcePrimaryScope.ORGANIZATIONS).length
+      });
+
+      // === RESOURCE ROOM HANDLERS (for collaboration) ===
+      this.setupResourceRoomHandlers(socket);
+
+      // === BADGE HANDLERS ===
+      this.setupBadgeHandlers(socket);
+
+      // === SYSTEM EVENT HANDLERS ===
+      this.setupSystemEventHandlers(socket);
+
+      // === DISCONNECTION HANDLING ===
+      socket.on('disconnect', () => {
+        this.handleSocketDisconnection(socket.id, this.getSocketAuth(socket));
+      });
+    });
+  }
+
+  /**
+   * Setup handlers for resource-centric rooms (collaboration, editing locks, custom events)
+   * These rooms are path-independent - same resource = same room regardless of access path
+   */
+  private setupResourceRoomHandlers(socket: Socket): void {
+
+    // === SUBSCRIBE TO RESOURCE ROOM ===
+    socket.on(CoreWebSocketEvent.RESOURCE_SUBSCRIBE, async (rawPayload: unknown) => {
+      // Runtime validation using Zod schema
+      const parseResult = WS_ResourceSubscribePayloadSchema.safeParse(rawPayload);
+      if (!parseResult.success) {
+        socket.emit(CoreWebSocketEvent.RESOURCE_SUBSCRIBED, {
+          roomName: '',
+          success: false,
+          error: `Invalid payload: ${parseResult.error.issues[0]?.message || 'validation failed'}`
+        });
+        return;
+      }
+
+      const payload = parseResult.data;
+      const { resourceType, resourceId, scopeKey, scopeId, contextResourceIdentifiers } = payload;
+
+      // Validate contextResourceIdentifiers has at least one entry
+      if (!contextResourceIdentifiers || Object.keys(contextResourceIdentifiers).length === 0) {
+        socket.emit(CoreWebSocketEvent.RESOURCE_SUBSCRIBED, {
+          roomName: '',
+          success: false,
+          error: 'contextResourceIdentifiers is required for authorization'
+        });
+        return;
+      }
+
+      try {
+        const auth = this.getSocketAuth(socket);
+        // Verify READ access using full context (organization, parent resources, etc.)
+        if (resourceId) {
+          await this.verifyResourceAccess(socket, auth, resourceType, resourceId, contextResourceIdentifiers);
+        } else if (scopeKey && scopeId) {
+          // For collection subscription, verify context access
+          await this.verifyScopeAccess(auth, scopeKey, scopeId, contextResourceIdentifiers);
+        } else {
+          throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
+            customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_VALIDATION_FAILED,
+            context: { operation: 'resourceSubscribe', message: 'Either resourceId or (scopeKey + scopeId) required' },
+          });
+        }
+
+        // Build room name
+        const roomName = resourceId
+          ? buildResourceRoomName(resourceType, resourceId)
+          : buildScopeRoomName(resourceType, scopeKey!, scopeId!);
+
+        socket.join(roomName);
+        this.trackSocketResourceSubscription(socket.id, {
+          ...payload,
+          roomName,
+        });
+
+        // Get current editing users for this resource (if subscribing to specific resource)
+        let editingUsers: string[] = [];
+        if (resourceId) {
+          editingUsers = await this.getResourceEditingUsers(resourceType, resourceId);
+        }
+
+        socket.emit(CoreWebSocketEvent.RESOURCE_SUBSCRIBED, {
+          roomName,
+          success: true,
+          editingUsers, // Include current editing users in subscription confirmation
+        });
+
+        this.logDebug('Socket subscribed to resource room', {
+          socketId: socket.id,
+          roomName,
+          userId: auth.initiatorIds?.userId?.substring(0, 8),
+          contextKeys: Object.keys(contextResourceIdentifiers),
+          editingUsersCount: editingUsers.length
+        });
+
+      } catch (error) {
+        const roomName = resourceId
+          ? buildResourceRoomName(resourceType, resourceId)
+          : buildScopeRoomName(resourceType, scopeKey || '', scopeId || '');
+        socket.emit(CoreWebSocketEvent.RESOURCE_SUBSCRIBED, {
+          roomName,
+          success: false,
+          error: error instanceof Error ? error.message : 'Access denied'
+        });
+      }
+    });
+
+    // === UNSUBSCRIBE FROM RESOURCE ROOM ===
+    socket.on(CoreWebSocketEvent.RESOURCE_UNSUBSCRIBE, (rawPayload: unknown) => {
+      // Runtime validation using Zod schema
+      const parseResult = WS_ResourceSubscribePayloadSchema.safeParse(rawPayload);
+      if (!parseResult.success) {
+        socket.emit(CoreWebSocketEvent.RESOURCE_UNSUBSCRIBED, {
+          roomName: '',
+          success: false,
+          error: `Invalid payload: ${parseResult.error.issues[0]?.message || 'validation failed'}`
+        });
+        return;
+      }
+
+      const payload = parseResult.data;
+      const { resourceType, resourceId, scopeKey, scopeId } = payload;
+
+      const roomName = resourceId
+        ? buildResourceRoomName(resourceType, resourceId)
+        : buildScopeRoomName(resourceType, scopeKey!, scopeId!);
+
+      socket.leave(roomName);
+      this.untrackSocketResourceSubscription(socket.id, roomName);
+      socket.emit(CoreWebSocketEvent.RESOURCE_UNSUBSCRIBED, { roomName, success: true });
+
+      this.logDebug('Socket unsubscribed from resource room', { socketId: socket.id, roomName });
+    });
+
+    // === START EDITING (LOCK) ===
+    socket.on(CoreWebSocketEvent.RESOURCE_EDITING_START, async (rawPayload: unknown) => {
+      // Runtime validation using Zod schema
+      const parseResult = WS_ResourceEditingPayloadSchema.safeParse(rawPayload);
+      if (!parseResult.success) {
+        socket.emit(CoreWebSocketEvent.RESOURCE_EDITING_ERROR, {
+          resourceType: '',
+          resourceId: '',
+          success: false,
+          error: `Invalid payload: ${parseResult.error.issues[0]?.message || 'validation failed'}`
+        });
+        return;
+      }
+
+      const payload = parseResult.data;
+      const { resourceType, resourceId, contextResourceIdentifiers } = payload;
+      const auth = this.getSocketAuth(socket);
+      const userId = auth.initiatorIds?.userId;
+
+      if (!userId) {
+        socket.emit(CoreWebSocketEvent.RESOURCE_EDITING_ERROR, {
+          resourceType,
+          resourceId,
+          success: false,
+          error: 'Authentication required for editing'
+        });
+        return;
+      }
+
+      // Validate contextResourceIdentifiers is provided
+      if (!contextResourceIdentifiers || Object.keys(contextResourceIdentifiers).length === 0) {
+        socket.emit(CoreWebSocketEvent.RESOURCE_EDITING_ERROR, {
+          resourceType,
+          resourceId,
+          success: false,
+          error: 'contextResourceIdentifiers is required for authorization'
+        });
+        return;
+      }
+
+      try {
+        // Verify user has WRITE access to edit this resource (using UPDATE operation)
+        await this.verifyResourceAccessForEdit(socket, auth, resourceType, resourceId, contextResourceIdentifiers);
+
+        const roomName = buildResourceRoomName(resourceType, resourceId);
+
+        // Track editing state in memory + Redis for cross-pod sync
+        await this.trackEditingState(resourceType, resourceId, userId, 'start');
+
+        // Broadcast to room (exclude sender) - don't include contextResourceIdentifiers in broadcast
+        const eventPayload: WS_ResourceEditingPayload = {
+          resourceType,
+          resourceId,
+          initiatorUserId: userId,
+          timestamp: new Date(),
+        };
+        socket.to(roomName).emit(CoreWebSocketEvent.RESOURCE_EDITING_START, eventPayload);
+
+        // Confirm to sender
+        socket.emit(CoreWebSocketEvent.RESOURCE_EDITING_STARTED, { resourceType, resourceId, success: true });
+
+        this.logDebug('User started editing resource', {
+          userId: userId.substring(0, 8),
+          resourceType,
+          resourceId: resourceId.substring(0, 8)
+        });
+
+      } catch (error) {
+        socket.emit(CoreWebSocketEvent.RESOURCE_EDITING_ERROR, {
+          resourceType,
+          resourceId,
+          success: false,
+          error: 'Access denied'
+        });
+      }
+    });
+
+    // === STOP EDITING (UNLOCK) ===
+    socket.on(CoreWebSocketEvent.RESOURCE_EDITING_END, async (rawPayload: unknown) => {
+      // Runtime validation using Zod schema
+      const parseResult = WS_ResourceEditingPayloadSchema.safeParse(rawPayload);
+      if (!parseResult.success) {
+        // Silent fail for editing end (not critical)
+        this.logDebug('Invalid editing end payload', {
+          error: parseResult.error.issues[0]?.message
+        });
+        return;
+      }
+
+      const payload = parseResult.data;
+      const { resourceType, resourceId } = payload;
+      const auth = this.getSocketAuth(socket);
+      const userId = auth.initiatorIds?.userId;
+
+      if (!userId) return;
+
+      const roomName = buildResourceRoomName(resourceType, resourceId);
+
+      // Clear editing state
+      await this.trackEditingState(resourceType, resourceId, userId, 'end');
+
+      // Broadcast to room (exclude sender)
+      const eventPayload: WS_ResourceEditingPayload = {
+        resourceType,
+        resourceId,
+        initiatorUserId: userId,
+        timestamp: new Date(),
+      };
+      socket.to(roomName).emit(CoreWebSocketEvent.RESOURCE_EDITING_END, eventPayload);
+
+      this.logDebug('User stopped editing resource', {
+        userId: userId.substring(0, 8),
+        resourceType,
+        resourceId: resourceId.substring(0, 8)
+      });
+    });
+
+    // === CUSTOM COLLABORATION EVENT ===
+    socket.on(CoreWebSocketEvent.RESOURCE_CUSTOM, async (rawPayload: unknown) => {
+      // Runtime validation using Zod schema
+      const parseResult = WS_ResourceCustomEventPayloadSchema.safeParse(rawPayload);
+      if (!parseResult.success) {
+        socket.emit(CoreWebSocketEvent.RESOURCE_CUSTOM_ERROR, {
+          eventName: '',
+          error: `Invalid payload: ${parseResult.error.issues[0]?.message || 'validation failed'}`
+        });
+        return;
+      }
+
+      const payload = parseResult.data;
+      const { resourceType, resourceId, eventName, data, includeSelf, contextResourceIdentifiers } = payload;
+      const auth = this.getSocketAuth(socket);
+      const userId = auth.initiatorIds?.userId;
+
+      // Validate contextResourceIdentifiers is provided
+      if (!contextResourceIdentifiers || Object.keys(contextResourceIdentifiers).length === 0) {
+        socket.emit(CoreWebSocketEvent.RESOURCE_CUSTOM_ERROR, { eventName, error: 'contextResourceIdentifiers is required' });
+        return;
+      }
+
+      try {
+        // Verify READ access (custom events require at least read access)
+        await this.verifyResourceAccess(socket, auth, resourceType, resourceId, contextResourceIdentifiers);
+
+        const roomName = buildResourceRoomName(resourceType, resourceId);
+
+        // Build outgoing event payload (don't include contextResourceIdentifiers in broadcast)
+        const eventPayload: WS_ResourceCustomEventPayload = {
+          resourceType,
+          resourceId,
+          eventName,
+          data,
+          initiatorUserId: userId,
+          timestamp: new Date(),
+          // Include resourceData and dataMode if present in the incoming payload
+          resourceData: payload.resourceData,
+          dataMode: payload.dataMode,
+        };
+
+        // Validate and transform resource data if present
+        if (payload.resourceData) {
+          const dataMode = this.extractDataMode(payload);
+          const validation = this.validateAndTransformResourceData(
+            payload.resourceData,
+            resourceType,
+            undefined, // Custom events don't have operationIdentifier
+            dataMode,
+            'canonical-read',
+          );
+          if (validation.success) {
+            eventPayload.resourceData = validation.data;
+          } else {
+            delete eventPayload.resourceData;
+            delete eventPayload.dataMode;
+          }
+        }
+
+        // Broadcast to room (include or exclude sender based on flag)
+        if (includeSelf) {
+          this.io!.to(roomName).emit(CoreWebSocketEvent.RESOURCE_CUSTOM, eventPayload);
+        } else {
+          socket.to(roomName).emit(CoreWebSocketEvent.RESOURCE_CUSTOM, eventPayload);
+        }
+
+      } catch (error) {
+        socket.emit(CoreWebSocketEvent.RESOURCE_CUSTOM_ERROR, { eventName, error: 'Access denied' });
+      }
+    });
+  }
+
+  /**
+   * Setup system event handlers (auth refresh, organization switch)
+   */
+  private setupSystemEventHandlers(socket: Socket): void {
+    // Token refresh handling
+    socket.on(CoreWebSocketEvent.AUTH_REFRESH, async (payload: { token: string }) => {
+      try {
+        const oldAuth = (socket as any).auth as SocketAuthResult;
+        const newAuth = await this.executionContextCreator.authenticateSocketConnection(payload.token);
+
+        // W7.3b: Carry forward consumable token across auth refreshes
+        if (oldAuth.consumableTokenValue) {
+          newAuth.consumableTokenValue = oldAuth.consumableTokenValue;
+        }
+
+        (socket as any).auth = newAuth;
+        this.authenticatedSockets.set(socket.id, newAuth);
+
+        // Re-assign identity rooms based on new auth
+        await this.reassignIdentityRooms(socket, oldAuth, newAuth);
+        await this.revalidateTrackedResourceSubscriptions(socket, newAuth);
+
+        socket.emit(CoreWebSocketEvent.SYSTEM_TOKEN_REFRESHED, { success: true });
+
+        this.logDebug('Socket auth refreshed and rooms reassigned', {
+          socketId: socket.id,
+          userId: newAuth.initiatorIds?.userId?.substring(0, 8),
+          newRolesCount: newAuth.initiatorRoles.length
+        });
+      } catch (error) {
+        socket.emit(CoreWebSocketEvent.SYSTEM_ERROR, {
+          code: 'AUTH_REFRESH_FAILED',
+          message: error instanceof Error ? error.message : 'Token refresh failed'
+        });
+      }
+    });
+
+    // Organization switch handling
+    socket.on(CoreWebSocketEvent.ORGANIZATION_SWITCH, async (payload: { organizationId: string; previousOrganizationId?: string }) => {
+      const auth = this.getSocketAuth(socket);
+
+      if (!this.hasOrganizationAccess(auth, payload.organizationId)) {
+        socket.emit(CoreWebSocketEvent.SYSTEM_ERROR, {
+          code: 'ORGANIZATION_SWITCH_FORBIDDEN',
+          message: 'Access denied to the requested organization',
+        });
+        return;
+      }
+
+      // Leave old organization rooms if specified
+      if (payload.previousOrganizationId) {
+        socket.leave(buildOrganizationRoomName(payload.previousOrganizationId));
+        this.organizationSockets.get(payload.previousOrganizationId)?.delete(socket.id);
+        if (this.organizationSockets.get(payload.previousOrganizationId)?.size === 0) {
+          this.organizationSockets.delete(payload.previousOrganizationId);
+        }
+        // Leave role rooms too
+        for (const roleInfo of auth.initiatorRoles) {
+          if (roleInfo.relatedPrimaryScope === ResourcePrimaryScope.ORGANIZATIONS &&
+              roleInfo.relatedResourceId === payload.previousOrganizationId) {
+            for (const role of roleInfo.roles || []) {
+              socket.leave(buildOrganizationRoleRoomName(payload.previousOrganizationId, role));
+            }
+          }
+        }
+
+        const trackedSubscriptions = Array.from(this.resourceSubscriptionsBySocket.get(socket.id)?.values() ?? []);
+        for (const subscription of trackedSubscriptions) {
+          if (!subscriptionMatchesOrganization(subscription, payload.previousOrganizationId)) {
+            continue;
+          }
+          await this.revokeTrackedResourceSubscription({
+            socket,
+            auth,
+            subscription,
+            reason: 'organization_switch',
+          });
+        }
+      }
+
+      // Join new organization rooms
+      socket.join(buildOrganizationRoomName(payload.organizationId));
+      if (!this.organizationSockets.has(payload.organizationId)) {
+        this.organizationSockets.set(payload.organizationId, new Set());
+      }
+      this.organizationSockets.get(payload.organizationId)!.add(socket.id);
+
+      // Find roles for the new organization and join role rooms
+      for (const roleInfo of auth.initiatorRoles) {
+        if (roleInfo.relatedPrimaryScope === ResourcePrimaryScope.ORGANIZATIONS &&
+            roleInfo.relatedResourceId === payload.organizationId) {
+          for (const role of roleInfo.roles || []) {
+            socket.join(buildOrganizationRoleRoomName(payload.organizationId, role));
+          }
+        }
+      }
+
+      this.logDebug('Organization switched', {
+        socketId: socket.id,
+        previousOrganizationId: payload.previousOrganizationId?.substring(0, 8),
+        newOrganizationId: payload.organizationId.substring(0, 8)
+      });
+    });
+  }
+
+  /**
+   * Reassign identity-based rooms when auth is refreshed
+   * Handles role changes, organization membership changes, etc.
+   */
+  private async reassignIdentityRooms(
+    socket: Socket,
+    oldAuth: SocketAuthResult,
+    newAuth: SocketAuthResult
+  ): Promise<void> {
+    // === LEAVE OLD ROOMS ===
+
+    // Leave old user room if user ID changed (unlikely but possible)
+    if (oldAuth.initiatorIds?.userId && oldAuth.initiatorIds.userId !== newAuth.initiatorIds?.userId) {
+      socket.leave(buildUserRoomName(oldAuth.initiatorIds.userId));
+      // Update user sockets tracking
+      this.userSockets.get(oldAuth.initiatorIds.userId)?.delete(socket.id);
+    }
+
+    // Build sets of old and new organization rooms for comparison
+    const oldOrgRooms = new Set<string>();
+    const oldRoleRooms = new Set<string>();
+    for (const roleInfo of oldAuth.initiatorRoles) {
+      if (roleInfo.relatedPrimaryScope === ResourcePrimaryScope.ORGANIZATIONS && roleInfo.relatedResourceId) {
+        oldOrgRooms.add(buildOrganizationRoomName(roleInfo.relatedResourceId));
+        for (const role of roleInfo.roles || []) {
+          oldRoleRooms.add(buildOrganizationRoleRoomName(roleInfo.relatedResourceId, role));
+        }
+      }
+      if (roleInfo.relatedPrimaryScope === ResourcePrimaryScope.APPLICATION) {
+        for (const role of roleInfo.roles || []) {
+          oldRoleRooms.add(buildAppRoleRoomName(role));
+        }
+      }
+    }
+
+    const newOrgRooms = new Set<string>();
+    const newRoleRooms = new Set<string>();
+    for (const roleInfo of newAuth.initiatorRoles) {
+      if (roleInfo.relatedPrimaryScope === ResourcePrimaryScope.ORGANIZATIONS && roleInfo.relatedResourceId) {
+        newOrgRooms.add(buildOrganizationRoomName(roleInfo.relatedResourceId));
+        for (const role of roleInfo.roles || []) {
+          newRoleRooms.add(buildOrganizationRoleRoomName(roleInfo.relatedResourceId, role));
+        }
+      }
+      if (roleInfo.relatedPrimaryScope === ResourcePrimaryScope.APPLICATION) {
+        for (const role of roleInfo.roles || []) {
+          newRoleRooms.add(buildAppRoleRoomName(role));
+        }
+      }
+    }
+
+    // Leave org rooms that are no longer in new auth
+    for (const room of oldOrgRooms) {
+      if (!newOrgRooms.has(room)) {
+        socket.leave(room);
+        // Update organization sockets tracking
+        const orgId = parseOrganizationRoomName(room);
+        if (orgId) {
+          this.organizationSockets.get(orgId)?.delete(socket.id);
+        }
+      }
+    }
+
+    // Leave role rooms that are no longer in new auth
+    for (const room of oldRoleRooms) {
+      if (!newRoleRooms.has(room)) {
+        socket.leave(room);
+      }
+    }
+
+    // Leave public room if was public but now authenticated
+    if (oldAuth.executionType === ExecutionContext_ExecutionType.PUBLIC_EXECUTION &&
+        newAuth.executionType !== ExecutionContext_ExecutionType.PUBLIC_EXECUTION) {
+      socket.leave(WebSocketRoomPrefix.PUBLIC);
+    }
+
+    // === JOIN NEW ROOMS ===
+
+    // Join new user room
+    if (newAuth.initiatorIds?.userId) {
+      socket.join(buildUserRoomName(newAuth.initiatorIds.userId));
+      if (!this.userSockets.has(newAuth.initiatorIds.userId)) {
+        this.userSockets.set(newAuth.initiatorIds.userId, new Set());
+      }
+      this.userSockets.get(newAuth.initiatorIds.userId)!.add(socket.id);
+    }
+
+    // Join new org rooms
+    for (const room of newOrgRooms) {
+      if (!oldOrgRooms.has(room)) {
+        socket.join(room);
+        const orgId = parseOrganizationRoomName(room);
+        if (orgId) {
+          if (!this.organizationSockets.has(orgId)) {
+            this.organizationSockets.set(orgId, new Set());
+          }
+          this.organizationSockets.get(orgId)!.add(socket.id);
+        }
+      }
+    }
+
+    // Join new role rooms
+    for (const room of newRoleRooms) {
+      if (!oldRoleRooms.has(room)) {
+        socket.join(room);
+      }
+    }
+
+    // Join public room if now public
+    if (newAuth.executionType === ExecutionContext_ExecutionType.PUBLIC_EXECUTION) {
+      socket.join(WebSocketRoomPrefix.PUBLIC);
+    }
+  }
+
+  /**
+   * Setup badge handlers (badge:get, badge:get-all)
+   * Enables frontend useBadge and useUserBadges hooks
+   */
+  private setupBadgeHandlers(socket: Socket): void {
+    // badge:get - Get single badge count
+    socket.on(CoreWebSocketEvent.BADGE_GET, async (
+      payload: { identifier: string; scope: string; scopeId: string },
+      callback?: (response: { count: number }) => void
+    ) => {
+      if (!callback) return;
+
+      try {
+        const auth = this.getSocketAuth(socket);
+        // Verify user has access to this scope
+        if (!this.verifyBadgeScopeAccess(auth, payload.scope as ResourcePrimaryScope, payload.scopeId)) {
+          callback({ count: 0 });
+          return;
+        }
+
+        // Build a minimal execution context for the badge service
+        const appReadOp = this.resourcesRegistry.getOperationFromPath(
+          this.resourcesRegistry.getOperationPathDefault('APPLICATION', CoreResourceOperation.READ)
+        );
+        if (!appReadOp) {
+          callback({ count: 0 });
+          return;
+        }
+
+        const executionContext = await this.executionContextCreator.buildContextFromSocketAuth(
+          auth,
+          appReadOp,
+          {}
+        );
+
+        const count = await this.getBadgeService().getBadgeCount(
+          executionContext,
+          payload.scope as ResourcePrimaryScope,
+          payload.scopeId,
+          payload.identifier as any
+        );
+
+        callback({ count });
+      } catch (error) {
+        this.logger.warn('Failed to get badge count', {
+          error: error instanceof Error ? error.message : 'Unknown error'
+        });
+        callback({ count: 0 });
+      }
+    });
+
+    // badge:get-all - Get all badges for a scope
+    socket.on(CoreWebSocketEvent.BADGE_GET_ALL, async (
+      payload: { scope: string; scopeId: string },
+      callback?: (response: Array<{ identifier: string; count: number }>) => void
+    ) => {
+      if (!callback) return;
+
+      try {
+        const auth = this.getSocketAuth(socket);
+        // Verify user has access to this scope
+        if (!this.verifyBadgeScopeAccess(auth, payload.scope as ResourcePrimaryScope, payload.scopeId)) {
+          callback([]);
+          return;
+        }
+
+        // Build a minimal execution context for the badge service
+        const appReadOp = this.resourcesRegistry.getOperationFromPath(
+          this.resourcesRegistry.getOperationPathDefault('APPLICATION', CoreResourceOperation.READ)
+        );
+        if (!appReadOp) {
+          callback([]);
+          return;
+        }
+
+        const executionContext = await this.executionContextCreator.buildContextFromSocketAuth(
+          auth,
+          appReadOp,
+          {}
+        );
+
+        const badges = await this.getBadgeService().getAllBadges(
+          executionContext,
+          payload.scope as ResourcePrimaryScope,
+          payload.scopeId
+        );
+
+        callback(badges);
+      } catch (error) {
+        this.logger.warn('Failed to get all badges', {
+          error: error instanceof Error ? error.message : 'Unknown error'
+        });
+        callback([]);
+      }
+    });
+  }
+
+  /**
+   * Verify user has access to a badge scope
+   */
+  private verifyBadgeScopeAccess(
+    auth: SocketAuthResult,
+    scope: ResourcePrimaryScope,
+    scopeId: string
+  ): boolean {
+    // Public users cannot access badges
+    if (auth.executionType === ExecutionContext_ExecutionType.PUBLIC_EXECUTION) {
+      return false;
+    }
+
+    switch (scope) {
+      case ResourcePrimaryScope.USER_SELF:
+        // User can only access their own badges
+        return auth.initiatorIds?.userId === scopeId;
+
+      case ResourcePrimaryScope.ORGANIZATIONS:
+        // User must be member of the organization
+        return auth.initiatorRoles.some(
+          r => r.relatedPrimaryScope === ResourcePrimaryScope.ORGANIZATIONS &&
+               r.relatedResourceId === scopeId
+        );
+
+      case ResourcePrimaryScope.APPLICATION:
+        // Application-level badges - check if user has any app roles
+        return auth.initiatorRoles.some(
+          r => r.relatedPrimaryScope === ResourcePrimaryScope.APPLICATION
+        );
+
+      default:
+        return false;
+    }
+  }
+
+  // =====================================================
+  // AUTHORIZATION HELPERS (FACTORIZED with HTTP)
+  // =====================================================
+
+  /**
+   * Verify user has READ access to a specific resource
+   *
+   * REUSES: AuthorizationsBackendService.authorizeInController()
+   * This is the EXACT same method used by HTTP controllers
+   */
+  private async verifyResourceAccess(
+    socket: Socket,
+    auth: SocketAuthResult,
+    resourceType: string,
+    resourceId: string,
+    contextResourceIdentifiers: Record<string, string>
+  ): Promise<void> {
+    if (auth.executionType === ExecutionContext_ExecutionType.PUBLIC_EXECUTION) {
+      throw this.errorBuilder.buildError(ErrorType.AUTHORIZATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.AUTHORIZATIONS_ACCESS_DENIED,
+        context: { resourceType, resourceId, message: 'Public connections cannot access resources' },
+      });
+    }
+
+    await this.authorizeSocketResourceAgainstAnyVariant(
+      auth,
+      resourceType,
+      resourceId,
+      contextResourceIdentifiers,
+      CoreResourceOperation.READ,
+    );
+  }
+
+  /**
+   * Verify user has WRITE access to edit a resource (for editing lock)
+   *
+   * REUSES: AuthorizationsBackendService.authorizeInController() with UPDATE operation
+   */
+  private async verifyResourceAccessForEdit(
+    socket: Socket,
+    auth: SocketAuthResult,
+    resourceType: string,
+    resourceId: string,
+    contextResourceIdentifiers: Record<string, string>
+  ): Promise<void> {
+    if (auth.executionType === ExecutionContext_ExecutionType.PUBLIC_EXECUTION) {
+      throw this.errorBuilder.buildError(ErrorType.AUTHORIZATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.AUTHORIZATIONS_ACCESS_DENIED,
+        context: { resourceType, resourceId, message: 'Public connections cannot edit resources' },
+      });
+    }
+
+    await this.authorizeSocketResourceAgainstAnyVariant(
+      auth,
+      resourceType,
+      resourceId,
+      contextResourceIdentifiers,
+      CoreResourceOperation.UPDATE,
+    );
+  }
+
+  /**
+   * Verify user has access to a scope (for collection subscriptions)
+   *
+   * REUSES: Role-based check for organization scope, or AuthorizationsBackendService for parent resources
+   */
+  private async verifyScopeAccess(
+    auth: SocketAuthResult,
+    scopeKey: string,
+    scopeId: string,
+    contextResourceIdentifiers: Record<string, string>
+  ): Promise<void> {
+    if (auth.executionType === ExecutionContext_ExecutionType.PUBLIC_EXECUTION) {
+      throw this.errorBuilder.buildError(ErrorType.AUTHORIZATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.AUTHORIZATIONS_ACCESS_DENIED,
+        context: { scopeKey, scopeId, message: 'Public connections cannot access scoped collections' },
+      });
+    }
+
+    const normalizedScopeKey = scopeKey.trim().toLowerCase();
+
+    // For organization scope, just check user has role in that org
+    if (normalizedScopeKey === 'org' || normalizedScopeKey === 'organization' || normalizedScopeKey === 'organizationid') {
+      const hasOrgAccess = auth.initiatorRoles.some(
+        r => r.relatedPrimaryScope === ResourcePrimaryScope.ORGANIZATIONS &&
+             r.relatedResourceId === scopeId
+      );
+      if (!hasOrgAccess) {
+        throw this.errorBuilder.buildError(ErrorType.AUTHORIZATION, undefined, {
+          customMessageReference: ErrorCustomMessageReference.AUTHORIZATIONS_ACCESS_DENIED,
+          context: { scopeId, scopeKey, message: 'No access to organization' },
+        });
+      }
+      return;
+    }
+
+    // For other scopes (e.g., todolist), verify READ access to the parent resource
+    const parentResourceType = this.mapScopeKeyToResourceType(scopeKey);
+    if (!parentResourceType) {
+      throw this.errorBuilder.buildError(ErrorType.AUTHORIZATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.AUTHORIZATIONS_ACCESS_DENIED,
+        context: { scopeId, scopeKey, message: 'Unknown or unmapped scope key' },
+      });
+    }
+
+    const scopeResourceId = contextResourceIdentifiers[`${scopeKey}Id`]
+      || contextResourceIdentifiers[`${normalizedScopeKey}Id`]
+      || contextResourceIdentifiers[scopeKey]
+      || contextResourceIdentifiers[normalizedScopeKey]
+      || scopeId;
+    await this.authorizeSocketResourceAgainstAnyVariant(
+      auth,
+      parentResourceType,
+      scopeResourceId,
+      contextResourceIdentifiers,
+      CoreResourceOperation.READ,
+      { scopeKey },
+    );
+  }
+
+  private getSocketAuthorizationCandidateOperations(
+    resourceType: string,
+    coreOperation: CoreResourceOperation.READ | CoreResourceOperation.UPDATE,
+  ): ResourceConfiguration_Operation<any, any, any>[] {
+    const registry = this.resourcesRegistry.getResourcesRegistry();
+    const resourceConfiguration = registry.resourceConfigurations[resourceType];
+
+    if (!resourceConfiguration) {
+      throw this.errorBuilder.buildError(ErrorType.NOT_FOUND, undefined, {
+        customMessageReference: ErrorCustomMessageReference.RESOURCES_REGISTRY_OPERATION_PATH_NOT_FOUND,
+        context: { resourceType, operation: coreOperation },
+      });
+    }
+
+    return resourceConfiguration.operations.filter((operation) => (
+      ResourceOperationsUtils.getCoreResourceOperationFromOperation(operation) === coreOperation
+      && !('isBulkOperation' in operation && operation.isBulkOperation === true)
+      && (
+        operation.variantType === ResourceOperationVariantType.API_CALL
+        || operation.variantType === ResourceOperationVariantType.API_CALL_WITH_CALLBACK
+      )
+      && 'initiatorInfos' in operation
+      && Array.isArray(operation.initiatorInfos)
+      && operation.initiatorInfos.length > 0
+    ));
+  }
+
+  private async authorizeSocketResourceAgainstAnyVariant(
+    auth: SocketAuthResult,
+    resourceType: string,
+    resourceId: string,
+    contextResourceIdentifiers: Record<string, string>,
+    coreOperation: CoreResourceOperation.READ | CoreResourceOperation.UPDATE,
+    extraContext?: Record<string, unknown>,
+  ): Promise<void> {
+    const candidateOperations = this.getSocketAuthorizationCandidateOperations(resourceType, coreOperation);
+    let lastAuthorizationError: unknown;
+
+    for (const operation of candidateOperations) {
+      try {
+        const executionContext = await this.executionContextCreator.buildContextFromSocketAuth(
+          auth,
+          operation,
+          contextResourceIdentifiers,
+        );
+
+        await this.authorizationsService.authorizeInController(resourceId, executionContext);
+
+        this.logDebug('Socket authorization succeeded with operation variant', {
+          resourceType,
+          resourceId,
+          coreOperation,
+          variantKey: operation.variantKey,
+          isOperationDefault: operation.isOperationDefault,
+          ...extraContext,
+        });
+        return;
+      } catch (error) {
+        if (isWildoBackendError(error) && error.type === ErrorType.AUTHORIZATION) {
+          lastAuthorizationError = error;
+          continue;
+        }
+
+        throw error;
+      }
+    }
+
+    if (lastAuthorizationError) {
+      throw lastAuthorizationError;
+    }
+
+    throw this.errorBuilder.buildError(ErrorType.NOT_FOUND, undefined, {
+      customMessageReference: ErrorCustomMessageReference.RESOURCES_REGISTRY_OPERATION_PATH_NOT_FOUND,
+      context: { resourceType, operation: coreOperation, ...extraContext },
+    });
+  }
+
+  /**
+   * Map scope key to parent resource type using the resources registry
+   *
+   * Scope keys follow the pattern: fieldIdentifier without 'Id' suffix
+   * E.g., 'todolist' → find resource with fieldIdentifier 'todolistId' → TODOLISTS
+   *
+   * Uses the registry's resource configurations to dynamically resolve
+   * without hardcoded mappings.
+   */
+  private mapScopeKeyToResourceType(scopeKey: string): string | null {
+    // Build the expected field identifier
+    const fieldIdentifierVariants = [
+      `${scopeKey}Id`,           // todolist → todolistId
+      `${scopeKey.toLowerCase()}Id`, // TodoList → todolistid (case insensitive)
+    ];
+
+    // Search through all resource configurations
+    const registry = this.resourcesRegistry.getResourcesRegistry();
+    const resourceTypes = Object.keys(registry.resourceConfigurations);
+
+    for (const resourceType of resourceTypes) {
+      const config = registry.resourceConfigurations[resourceType];
+      const configFieldId = config.resourceFieldIdentifier?.toLowerCase();
+
+      for (const variant of fieldIdentifierVariants) {
+        if (configFieldId === variant.toLowerCase()) {
+          return resourceType;
+        }
+      }
+    }
+
+    // Also check if scopeKey is itself a resource type (direct match)
+    if (registry.resourceConfigurations[scopeKey]) {
+      return scopeKey;
+    }
+
+    // Check for case-insensitive resource type match
+    const lowerScopeKey = scopeKey.toLowerCase();
+    for (const resourceType of resourceTypes) {
+      if (resourceType.toLowerCase() === lowerScopeKey) {
+        return resourceType;
+      }
+    }
+
+    this.logDebug('Could not map scope key to resource type', { scopeKey });
+    return null;
+  }
+
+  // =====================================================
+  // EDITING STATE TRACKING (Redis-backed for multi-pod)
+  // =====================================================
+
+  /**
+   * Track editing state in Redis for cross-pod synchronization
+   */
+  private async trackEditingState(
+    resourceType: string,
+    resourceId: string,
+    userId: string,
+    action: 'start' | 'end'
+  ): Promise<void> {
+    const prefix = this.redisService.getAppPrefix();
+    const key = `${prefix}editing:${resourceType}:${resourceId}`;
+    const redisClient = this.redisService.getClient();
+
+    if (!redisClient) {
+      // Fallback to in-memory if Redis unavailable
+      if (action === 'start') {
+        if (!this.resourceEditingState.has(key)) {
+          this.resourceEditingState.set(key, new Set());
+        }
+        this.resourceEditingState.get(key)!.add(userId);
+      } else {
+        this.resourceEditingState.get(key)?.delete(userId);
+      }
+      return;
+    }
+
+    try {
+      if (action === 'start') {
+        await redisClient.hSet(key, userId, new Date().toISOString());
+        await redisClient.expire(key, 3600); // 1 hour TTL (cleanup stale locks)
+      } else {
+        await redisClient.hDel(key, userId);
+      }
+    } catch (error) {
+      this.logger.warn('Failed to track editing state in Redis', {
+        error: error instanceof Error ? error.message : 'Unknown',
+        resourceType,
+        resourceId: resourceId.substring(0, 8)
+      });
+    }
+  }
+
+  /**
+   * Cleanup editing states when user disconnects
+   * Cleans both in-memory state AND Redis for immediate consistency across pods
+   *
+   * CROSS-POD SUPPORT: Uses Redis SCAN to find all editing keys across all pods
+   * where this user is editing, ensuring complete cleanup.
+   */
+  private async cleanupEditingStatesForUser(userId: string): Promise<void> {
+    if (!userId) return;
+
+    const redisClient = this.redisService.getClient();
+
+    // Cleanup in-memory state on this pod
+    for (const [key, users] of this.resourceEditingState.entries()) {
+      if (users.has(userId)) {
+        users.delete(userId);
+      }
+    }
+
+    // Cross-pod cleanup: SCAN Redis for all editing:* keys where this user is editing
+    if (redisClient) {
+      try {
+        await this.cleanupUserEditingStatesFromRedis(redisClient, userId);
+      } catch (error) {
+        this.logger.warn('Failed to cleanup Redis editing states on disconnect', {
+          userId: userId.substring(0, 8),
+          error: error instanceof Error ? error.message : 'Unknown',
+        });
+      }
+    }
+  }
+
+  /**
+   * SCAN Redis for all editing:* keys and remove the user from each
+   * Also broadcasts editing:end to affected resource rooms
+   *
+   * Key format: {appPrefix}editing:{resourceType}:{resourceId}
+   * Example: "wildo-ai-app_local:editing:users:user456"
+   */
+  private async cleanupUserEditingStatesFromRedis(
+    redisClient: ReturnType<typeof this.redisService.getClient>,
+    userId: string
+  ): Promise<void> {
+    if (!redisClient) return;
+
+    let cursor: string = '0';
+    const cleanedResources: Array<{ resourceType: string; resourceId: string }> = [];
+    const prefix = this.redisService.getAppPrefix();
+
+    // SCAN for all editing:* keys scoped to this application
+    do {
+      const result = await redisClient.scan(cursor, {
+        MATCH: `${prefix}editing:*`,
+        COUNT: 100, // Process in batches
+      });
+
+      cursor = result.cursor;
+      const keys = result.keys;
+
+      // Check each key for this user and remove if present
+      for (const key of keys) {
+        try {
+          // Check if user is in this hash
+          const exists = await redisClient.hExists(key, userId);
+          if (exists) {
+            // Remove user from this editing state
+            await redisClient.hDel(key, userId);
+
+            // Parse key to get resource info
+            // Key format: {prefix}editing:{resourceType}:{resourceId}
+            // Remove prefix first, then parse
+            const keyWithoutPrefix = prefix && key.startsWith(prefix)
+              ? key.slice(prefix.length)
+              : key;
+            const parts = keyWithoutPrefix.split(':');
+
+            // parts[0] = "editing", parts[1] = resourceType, parts[2] = resourceId
+            if (parts.length >= 3 && parts[0] === 'editing') {
+              cleanedResources.push({
+                resourceType: parts[1],
+                resourceId: parts[2],
+              });
+            }
+          }
+        } catch (error) {
+          this.logger.warn('Failed to check/delete editing state for key', {
+            key,
+            userId: userId.substring(0, 8),
+            error: error instanceof Error ? error.message : 'Unknown',
+          });
+        }
+      }
+    } while (cursor !== '0');
+
+    // Broadcast editing:end to all affected resource rooms
+    for (const resource of cleanedResources) {
+      const roomName = buildResourceRoomName(resource.resourceType, resource.resourceId);
+      this.io?.to(roomName).emit(CoreWebSocketEvent.RESOURCE_EDITING_END, {
+        resourceType: resource.resourceType,
+        resourceId: resource.resourceId,
+        initiatorUserId: userId,
+        reason: 'disconnect',
+        timestamp: new Date(),
+      });
+    }
+
+    if (cleanedResources.length > 0) {
+      this.logDebug('Cleaned up editing states for disconnected user', {
+        userId: userId.substring(0, 8),
+        cleanedCount: cleanedResources.length,
+      });
+    }
+  }
+
+  // =====================================================
+  // DISCONNECTION HANDLING
+  // =====================================================
+
+  /**
+   * Handle socket disconnection - cleanup state and notify rooms
+   */
+  private handleSocketDisconnection(socketId: string, auth: SocketAuthResult): void {
+    // Remove from authenticated sockets
+    this.authenticatedSockets.delete(socketId);
+    this.resourceSubscriptionsBySocket.delete(socketId);
+
+    const userId = auth.initiatorIds?.userId;
+
+    if (userId) {
+      // Remove from user sockets tracking
+      const userSocketIds = this.userSockets.get(userId);
+      if (userSocketIds) {
+        userSocketIds.delete(socketId);
+        if (userSocketIds.size === 0) {
+          this.userSockets.delete(userId);
+
+          // User completely disconnected - cleanup editing states
+          this.cleanupEditingStatesForUser(userId);
+        }
+      }
+    }
+
+    // Remove from organization sockets
+    for (const roleInfo of auth.initiatorRoles) {
+      if (roleInfo.relatedPrimaryScope === ResourcePrimaryScope.ORGANIZATIONS && roleInfo.relatedResourceId) {
+        const orgSocketIds = this.organizationSockets.get(roleInfo.relatedResourceId);
+        if (orgSocketIds) {
+          orgSocketIds.delete(socketId);
+          if (orgSocketIds.size === 0) {
+            this.organizationSockets.delete(roleInfo.relatedResourceId);
+          }
+        }
+      }
+    }
+
+    this.logDebug('Socket disconnected', {
+      socketId,
+      userId: userId?.substring(0, 8),
+      remainingConnections: this.authenticatedSockets.size
+    });
+  }
+
+  // =====================================================
+  // CLEANUP
+  // =====================================================
+
+  /**
+   * Cleanup resources
+   */
+  public async cleanup(): Promise<void> {
+    try {
+      if (this.io) {
+        this.io.close();
+        this.io = null;
+      }
+
+      this.authenticatedSockets.clear();
+      this.userSockets.clear();
+      this.organizationSockets.clear();
+      this.rooms.clear();
+      this.resourceEditingState.clear();
+      this.resourceSubscriptionsBySocket.clear();
+
+      this.logDebug('WebSocket service cleanup completed');
+
+    } catch (error: unknown) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+      this.logger.error('Error during WebSocket cleanup', { error: errorMessage });
+    }
+  }
+}