@wildo-ai/saas-backend-lib 1.0.1

package/src/notifications/services/notifications-dispatcher.backend.service.ts

@@ -0,0 +1,1696 @@
+import { inject, injectable } from 'inversify';
+import { ExecutionContext } from '~wildo-backend-lib/runtime/models/execution-context.backend.schemas';
+import {
+  ResourceConfiguration_Operation,
+  ResourcePrimaryScope,
+  CoreM2MNotificationChannel,
+  CoreUserNotificationChannel,
+  CoreUserNotificationTarget,
+  UserNotificationDefinition,
+  UserNotificationDefinition_FrontEndSuccessSchema,
+  M2MNotificationDefinition,
+  NotificationBadgeOperation,
+  CoreResourceOperation,
+  CoreWebSocketEvent,
+  WS_ResourceNotificationPayload,
+  WS_ResourceUpdatedPayload,
+  WS_ResourceDeletedPayload,
+  WS_ResourceSyncUpdatedPayload,
+  WS_ResourceUpdateNotificationPayload,
+  ResourceConfiguration_OperationVariant_CustomImplementation_FunctionParameters,
+  EmailTemplateType,
+  ResourceAction,
+  NotificationLevel,
+  CORE_APP_ROLES,
+  CORE_ORG_ROLES,
+  CoreResourceType,
+  OrganizationMemberStatus,
+  ResourcesConfigOperationsUrlsBuilderUtils,
+  ResourceOperationVariantType,
+  WebSocketResourceDeliveryTarget,
+} from '@wildo-ai/saas-models';
+import type { FieldMetaEntry, OrganizationMember } from '@wildo-ai/saas-models';
+import type { z } from 'zod';
+import { AvailableLanguage } from '@wildo-ai/presets-components-models';
+import { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';
+import { ErrorBuilderBackendService } from '~wildo-backend-lib/errors/services/error-builder.backend.service';
+import { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';
+import { WebSocketService, WebSocketMessage } from '~wildo-backend-lib/requests/service/websocket.service';
+import { NotificationBadgeBackendService } from './notification-badge.backend.service';
+import type { EmailBackendService } from '~wildo-backend-lib/notifications/email/services/email.backend.service';
+import type { QueueBackendService } from '~wildo-backend-lib/queue/queue.backend.service';
+import { AppConfigurationService } from '~wildo-backend-lib/config/services/app-configuration.backend.service';
+import { AuthControllerUtils } from '~wildo-backend-lib/security/authentications/services/utils/auth-controller.utils';
+import { RepositoriesRegistryHandlerBackendService } from '~wildo-backend-lib/base-classes/services/repositories/repositories-registry-handler.backend.service';
+import { ResourcesRegistryBackendService } from '~wildo-backend-lib/resources/services/resources-registry.backend.service';
+
+/**
+ * Notification Dispatcher Service
+ *
+ * Handles dispatching of all notification types based on resource operation configurations:
+ * - Notification badge operations (incrementing/decrementing/resetting badge counts)
+ * - User notifications (email, SMS, push, WebSocket, frontend success)
+ * - M2M (Machine-to-Machine) notifications (webhooks)
+ * - Resource room notifications (path-independent collaboration)
+ */
+/** Batch threshold for email sending - above this, use queue */
+const EMAIL_BATCH_THRESHOLD = 10;
+
+type CachedRoutePaths = { url: string; parameters: { fieldIdentifier: string; resourceType: string }[] }[];
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function normalizeResourceId(value: unknown): string | undefined {
+  if (typeof value === 'string' && value.length > 0) {
+    return value;
+  }
+
+  if (
+    typeof value === 'object'
+    && value !== null
+    && typeof (value as { toString?: () => string }).toString === 'function'
+  ) {
+    const normalized = value.toString();
+    if (normalized.length > 0 && normalized !== '[object Object]') {
+      return normalized;
+    }
+  }
+
+  return undefined;
+}
+
+function resolveResourceObjectForSync(
+  currentObject: unknown,
+  resourceId: string,
+  affectedIds: string[],
+): Record<string, unknown> | undefined {
+  if (Array.isArray(currentObject)) {
+    return currentObject.find((candidate): candidate is Record<string, unknown> => (
+      isPlainRecord(candidate) && normalizeResourceId(candidate._id ?? candidate.id) === resourceId
+    ));
+  }
+
+  if (!isPlainRecord(currentObject)) {
+    return undefined;
+  }
+
+  if (typeof currentObject._id === 'string' && currentObject._id !== resourceId) {
+    return undefined;
+  }
+
+  // A shared bulk result blob (e.g. { updatedIds: [...] }) is not authoritative
+  // per-resource replay truth for sync-grade room payloads.
+  if (affectedIds.length > 1 && typeof currentObject._id !== 'string') {
+    return undefined;
+  }
+
+  return currentObject;
+}
+
+function splitResourceObjectForWebSocket(resourceObject: Record<string, unknown>): {
+  cleanedResourceData: Record<string, unknown>;
+  fieldMeta?: Record<string, FieldMetaEntry>;
+  version?: number;
+} {
+  const { _field_meta, ...rest } = resourceObject;
+  return {
+    cleanedResourceData: rest,
+    fieldMeta: _field_meta as Record<string, FieldMetaEntry> | undefined,
+    version: resourceObject._version as number | undefined,
+  };
+}
+
+export function shouldOmitResourceUrlForOperation(
+  effectiveOperation: CoreResourceOperation | undefined,
+): boolean {
+  return effectiveOperation === CoreResourceOperation.DELETE
+    || effectiveOperation === CoreResourceOperation.DELETE_MANY;
+}
+
+export function buildResourceRoomSyncPayload(params: {
+  resourceType: string;
+  resourceId: string;
+  contextResourceIdentifiers: Record<string, string>;
+  action: ResourceAction;
+  affectedIds: string[];
+  operationIdentifier: string;
+  initiatorUserId?: string;
+  currentObject: unknown;
+  timestamp?: Date;
+}): WS_ResourceSyncUpdatedPayload | WS_ResourceDeletedPayload | null {
+  const timestamp = params.timestamp ?? new Date();
+
+  if (params.action === ResourceAction.DELETED) {
+    return {
+      deliveryTarget: WebSocketResourceDeliveryTarget.RESOURCE_ROOM_SYNC,
+      resourceType: params.resourceType,
+      resourceId: params.resourceId,
+      contextResourceIdentifiers: params.contextResourceIdentifiers,
+      action: ResourceAction.DELETED,
+      affectedIds: params.affectedIds,
+      operationIdentifier: params.operationIdentifier,
+      initiatorUserId: params.initiatorUserId,
+      timestamp,
+    };
+  }
+
+  const resourceObject = resolveResourceObjectForSync(
+    params.currentObject,
+    params.resourceId,
+    params.affectedIds,
+  );
+  if (!resourceObject) {
+    return null;
+  }
+
+  const {
+    cleanedResourceData,
+    fieldMeta,
+    version,
+  } = splitResourceObjectForWebSocket(resourceObject);
+
+  if (version == null) {
+    return null;
+  }
+
+  // Sync-grade resource-room events are the only websocket payloads allowed to
+  // carry authoritative replay data for a specific resource. If we cannot prove
+  // both the per-resource object body and its authoritative version, callers
+  // must fall back to a notification-grade stale hint instead.
+  return {
+    deliveryTarget: WebSocketResourceDeliveryTarget.RESOURCE_ROOM_SYNC,
+    resourceType: params.resourceType,
+    resourceId: params.resourceId,
+    contextResourceIdentifiers: params.contextResourceIdentifiers,
+    action: params.action,
+    affectedIds: params.affectedIds,
+    operationIdentifier: params.operationIdentifier,
+    initiatorUserId: params.initiatorUserId,
+    timestamp,
+    version,
+    resourceData: cleanedResourceData,
+    fieldMeta,
+  };
+}
+
+export function buildScopeRoomNotificationPayload(params: {
+  resourceType: string;
+  resourceId: string;
+  contextResourceIdentifiers: Record<string, string>;
+  action: ResourceAction;
+  affectedIds: string[];
+  operationIdentifier: string;
+  initiatorUserId?: string;
+  currentObject: unknown;
+  timestamp?: Date;
+}): WS_ResourceUpdateNotificationPayload {
+  const timestamp = params.timestamp ?? new Date();
+  // Scope rooms are collection/list invalidation surfaces. For multi-id writes
+  // they must not overstate single-resource replay truth, so replay-like fields
+  // are only included when the payload still represents one authoritative row.
+  const shouldIncludeReplayLikeFields = params.affectedIds.length <= 1;
+  const resourceObject = resolveResourceObjectForSync(
+    params.currentObject,
+    params.resourceId,
+    params.affectedIds,
+  );
+  const splitResourceObject = shouldIncludeReplayLikeFields && resourceObject
+    ? splitResourceObjectForWebSocket(resourceObject)
+    : null;
+
+  return {
+    deliveryTarget: WebSocketResourceDeliveryTarget.SCOPE_ROOM_NOTIFICATION,
+    resourceType: params.resourceType,
+    resourceId: params.resourceId,
+    contextResourceIdentifiers: params.contextResourceIdentifiers,
+    action: params.action,
+    affectedIds: params.affectedIds,
+    operationIdentifier: params.operationIdentifier,
+    initiatorUserId: params.initiatorUserId,
+    timestamp,
+    version: splitResourceObject?.version,
+    resourceData: splitResourceObject?.cleanedResourceData,
+    fieldMeta: splitResourceObject?.fieldMeta,
+  };
+}
+
+export function buildResourceRoomStaleHintPayload(params: {
+  resourceType: string;
+  resourceId: string;
+  contextResourceIdentifiers: Record<string, string>;
+  action: ResourceAction;
+  affectedIds: string[];
+  operationIdentifier: string;
+  initiatorUserId?: string;
+  timestamp?: Date;
+}): WS_ResourceUpdateNotificationPayload {
+  const timestamp = params.timestamp ?? new Date();
+  return {
+    deliveryTarget: WebSocketResourceDeliveryTarget.RESOURCE_ROOM_NOTIFICATION,
+    resourceType: params.resourceType,
+    resourceId: params.resourceId,
+    contextResourceIdentifiers: params.contextResourceIdentifiers,
+    action: params.action,
+    affectedIds: params.affectedIds,
+    operationIdentifier: params.operationIdentifier,
+    initiatorUserId: params.initiatorUserId,
+    timestamp,
+  };
+}
+
+@injectable()
+export class NotificationDispatcherService {
+
+  protected logDebug: (message: string, context?: Record<string, unknown>) => void;
+
+  private readRoutePathsCache = new Map<string, CachedRoutePaths | null>();
+
+  constructor(
+    @inject(SAAS_SERVICE_TYPES.Logger) private logger: LoggerService,
+    @inject(SAAS_SERVICE_TYPES.ErrorBuilderService) private errorBuilder: ErrorBuilderBackendService,
+    @inject(SAAS_SERVICE_TYPES.WebSocketService) private webSocketService: WebSocketService,
+    @inject(SAAS_SERVICE_TYPES.NotificationBadgeService) private badgeService: NotificationBadgeBackendService,
+    @inject(SAAS_SERVICE_TYPES.EmailService) private emailService: EmailBackendService,
+    @inject(SAAS_SERVICE_TYPES.QueueBackendService) private queueService: QueueBackendService,
+    @inject(SAAS_SERVICE_TYPES.AppConfigService) private appConfigService: AppConfigurationService,
+    @inject(SAAS_SERVICE_TYPES.RepositoriesRegistryHandlerService) private repositoriesRegistry: RepositoriesRegistryHandlerBackendService,
+    @inject(SAAS_SERVICE_TYPES.ResourceRegistryService) private resourcesRegistry: ResourcesRegistryBackendService,
+  ) {
+    this.logDebug = this.logger.debugByType('NotificationDispatcherService');
+    this.logger.setDebugTypeLogging('NotificationDispatcherService', false);
+  }
+
+  /**
+   * Dispatch notifications based on operation configuration
+   *
+   * @param executionContext - The execution context containing operation details and user information
+   * @param functionParameters - Parameters containing input data, current object, and context
+   */
+  async dispatchNotifications<
+    TResourceConfigOperation extends ResourceConfiguration_Operation<any, any, any>
+  >(
+    executionContext: ExecutionContext<TResourceConfigOperation>,
+    functionParameters: ResourceConfiguration_OperationVariant_CustomImplementation_FunctionParameters
+  ): Promise<void> {
+    const operation = executionContext.operation;
+
+    try {
+      const results = await Promise.allSettled([
+        this.dispatchConfiguredNotifications(executionContext, functionParameters),
+        this.dispatchResourceRoomNotifications(executionContext, functionParameters),
+      ]);
+
+      for (const result of results) {
+        if (result.status === 'rejected') {
+          this.logger.error('Error dispatching notifications', {
+            error: result.reason instanceof Error ? result.reason.message : 'Unknown error',
+            resourceType: operation.resourceIdentifier,
+            operationIdentifier: String(operation.operationIdentifier),
+          });
+        }
+      }
+    } catch (error) {
+      this.logger.error('Failed to dispatch notifications', {
+        error: error instanceof Error ? error.message : 'Unknown error',
+        resourceType: operation.resourceIdentifier,
+        operationIdentifier: String(operation.operationIdentifier),
+      });
+    }
+  }
+
+  async dispatchConfiguredNotifications<
+    TResourceConfigOperation extends ResourceConfiguration_Operation<any, any, any>
+  >(
+    executionContext: ExecutionContext<TResourceConfigOperation>,
+    functionParameters: ResourceConfiguration_OperationVariant_CustomImplementation_FunctionParameters
+  ): Promise<void> {
+    const operation = executionContext.operation;
+
+    try {
+      // Dispatch authored notification types in parallel. Resource-room
+      // synchronization can be invoked independently from this path when the
+      // caller only has post-write object truth and not a full computation context.
+      const results = await Promise.allSettled([
+        // 1. Notification badge operations
+        this.dispatchNotificationBadgeOperations(executionContext, functionParameters),
+
+        // 2. User notifications (email, SMS, push, WebSocket, frontend success)
+        this.dispatchUserNotifications(executionContext, functionParameters),
+
+        // 3. M2M notifications (webhooks)
+        this.dispatchM2MNotifications(executionContext, functionParameters),
+      ]);
+
+      for (const result of results) {
+        if (result.status === 'rejected') {
+          this.logger.error('Error dispatching notifications', {
+            error: result.reason instanceof Error ? result.reason.message : 'Unknown error',
+            resourceType: operation.resourceIdentifier,
+            operationIdentifier: String(operation.operationIdentifier),
+          });
+        }
+      }
+
+      this.logDebug('All notifications dispatched successfully', {
+        resourceType: operation.resourceIdentifier,
+        operationIdentifier: String(operation.operationIdentifier),
+        userNotificationCount: (operation.userNotifications || []).length,
+        badgeOperationsCount: (operation.notificationBadgeOperations || []).length,
+        m2mNotificationsCount: (operation.m2mNotifications || []).length,
+      });
+
+    } catch (error) {
+      // Log but don't throw - notifications should not break the main operation
+      this.logger.error('Error dispatching notifications', {
+        error: error instanceof Error ? error.message : 'Unknown error',
+        resourceType: operation.resourceIdentifier,
+        operationIdentifier: String(operation.operationIdentifier),
+      });
+    }
+  }
+
+  /**
+   * Dispatch notification badge operations
+   *
+   * @param executionContext - The execution context
+   * @param functionParameters - Function parameters with data context
+   * @private
+   */
+  private async dispatchNotificationBadgeOperations<
+    TResourceConfigOperation extends ResourceConfiguration_Operation<any, any, any>
+  >(
+    executionContext: ExecutionContext<TResourceConfigOperation>,
+    functionParameters: ResourceConfiguration_OperationVariant_CustomImplementation_FunctionParameters
+  ): Promise<void> {
+    const operation = executionContext.operation;
+    const badgeOperations = operation.notificationBadgeOperations || [];
+
+    if (badgeOperations.length === 0) {
+      return;
+    }
+
+    // Determine the scope and scopeId based on operation's primary scope
+    const { scope, scopeId } = this.determineBadgeScope(executionContext);
+    if (!scope || !scopeId) {
+      this.logDebug('Cannot determine badge scope, skipping badge operations', {
+        resourceType: operation.resourceIdentifier,
+        operationIdentifier: String(operation.operationIdentifier),
+      });
+      return;
+    }
+
+    // Execute each badge operation
+    for (const badgeOp of badgeOperations) {
+      try {
+        await this.badgeService.executeBadgeOperation(
+          executionContext,
+          scope,
+          scopeId,
+          badgeOp.identifier,
+          badgeOp.operation as NotificationBadgeOperation,
+          1 // Default value (can be extended to support custom values)
+        );
+
+        this.logDebug('Badge operation executed', {
+          identifier: badgeOp.identifier,
+          operation: badgeOp.operation,
+          scope,
+          scopeId,
+        });
+      } catch (error) {
+        this.logger.warn('Failed to execute badge operation', {
+          identifier: badgeOp.identifier,
+          operation: badgeOp.operation,
+          error: error instanceof Error ? error.message : 'Unknown error',
+        });
+      }
+    }
+  }
+
+  /**
+   * Determine the badge scope and scopeId from execution context
+   */
+  private determineBadgeScope<TResourceConfigOperation extends ResourceConfiguration_Operation<any, any, any>>(
+    executionContext: ExecutionContext<TResourceConfigOperation>
+  ): { scope: ResourcePrimaryScope | null; scopeId: string | null } {
+    const operation = executionContext.operation;
+    const primaryScope = operation.resourcePrimaryScope;
+    const initiatorIds = executionContext.initiatorIds;
+
+    switch (primaryScope) {
+      case ResourcePrimaryScope.USER_SELF:
+        return { scope: ResourcePrimaryScope.USER_SELF, scopeId: initiatorIds?.userId || null };
+
+      case ResourcePrimaryScope.ORGANIZATIONS:
+        return { scope: ResourcePrimaryScope.ORGANIZATIONS, scopeId: initiatorIds?.organizationId || null };
+
+      case ResourcePrimaryScope.APPLICATION:
+        return { scope: ResourcePrimaryScope.APPLICATION, scopeId: initiatorIds?.applicationId || null };
+
+      default:
+        // Fallback to organization if available, otherwise user
+        if (initiatorIds?.organizationId) {
+          return { scope: ResourcePrimaryScope.ORGANIZATIONS, scopeId: initiatorIds.organizationId };
+        }
+        if (initiatorIds?.userId) {
+          return { scope: ResourcePrimaryScope.USER_SELF, scopeId: initiatorIds.userId };
+        }
+        return { scope: null, scopeId: null };
+    }
+  }
+
+  /**
+   * Dispatch user notifications
+   *
+   * @param executionContext - The execution context
+   * @param functionParameters - Function parameters with data context
+   * @private
+   */
+  private async dispatchUserNotifications<
+    TResourceConfigOperation extends ResourceConfiguration_Operation<any, any, any>
+  >(
+    executionContext: ExecutionContext<TResourceConfigOperation>,
+    functionParameters: ResourceConfiguration_OperationVariant_CustomImplementation_FunctionParameters
+  ): Promise<void> {
+    const operation = executionContext.operation;
+    const userNotifications = operation.userNotifications || [];
+
+    if (userNotifications.length === 0) {
+      return;
+    }
+
+    for (const notification of userNotifications) {
+      try {
+        await this.dispatchSingleUserNotification(executionContext, functionParameters, notification);
+      } catch (error) {
+        this.logger.warn('Failed to dispatch user notification', {
+          identifier: notification.identifier,
+          channel: notification.channel,
+          target: notification.target,
+          error: error instanceof Error ? error.message : 'Unknown error',
+        });
+      }
+    }
+  }
+
+  /**
+   * Dispatch a single user notification based on its channel
+   */
+  private async dispatchSingleUserNotification<
+    TResourceConfigOperation extends ResourceConfiguration_Operation<any, any, any>
+  >(
+    executionContext: ExecutionContext<TResourceConfigOperation>,
+    functionParameters: ResourceConfiguration_OperationVariant_CustomImplementation_FunctionParameters,
+    notification: UserNotificationDefinition
+  ): Promise<void> {
+    const channel = notification.channel;
+
+    switch (channel) {
+      case CoreUserNotificationChannel.WEBSOCKET:
+        await this.dispatchWebSocketUserNotification(executionContext, functionParameters, notification);
+        break;
+
+      case CoreUserNotificationChannel.EMAIL:
+      case CoreUserNotificationChannel.SMS:
+      case CoreUserNotificationChannel.PUSH:
+        // Email/SMS/Push notifications require recipient userContext fetching
+        await this.dispatchEmailSmsPushUserNotification(executionContext, functionParameters, notification);
+        break;
+
+      case CoreUserNotificationChannel.FRONT_END_SUCCESS:
+        // Frontend success notifications are handled client-side
+        // We can optionally send them via WebSocket for SPAs
+        await this.dispatchWebSocketUserNotification(executionContext, functionParameters, notification);
+        break;
+
+      default:
+        this.logDebug('Unknown notification channel', {
+          channel,
+          identifier: notification.identifier,
+        });
+    }
+  }
+
+  /**
+   * Dispatch Email/SMS/Push user notifications
+   * These channels require recipient userContext fetching for template rendering
+   */
+  private async dispatchEmailSmsPushUserNotification<
+    TResourceConfigOperation extends ResourceConfiguration_Operation<any, any, any>
+  >(
+    executionContext: ExecutionContext<TResourceConfigOperation>,
+    functionParameters: ResourceConfiguration_OperationVariant_CustomImplementation_FunctionParameters,
+    notification: UserNotificationDefinition
+  ): Promise<void> {
+    const target = notification.target;
+    const channel = notification.channel;
+
+    // Get user IDs based on target
+    const userIds = await this.getUserIdsForTarget(executionContext, functionParameters, notification, target);
+
+    if (userIds.length === 0) {
+      this.logDebug('No user IDs found for notification', {
+        identifier: notification.identifier,
+        target,
+        channel,
+      });
+      return;
+    }
+
+    // Handle by channel type
+    switch (channel) {
+      case CoreUserNotificationChannel.EMAIL:
+        await this.dispatchEmailNotifications(executionContext, functionParameters, notification, userIds);
+        break;
+
+      case CoreUserNotificationChannel.SMS:
+      case CoreUserNotificationChannel.PUSH:
+        // SMS and Push not yet implemented
+        this.logDebug('SMS/Push notifications not yet implemented', {
+          identifier: notification.identifier,
+          channel,
+          userCount: userIds.length,
+        });
+        break;
+    }
+  }
+
+  /**
+   * Dispatch email notifications to a list of users.
+   * Uses direct sending for small lists, batch queue for larger lists.
+   */
+  private async dispatchEmailNotifications<
+    TResourceConfigOperation extends ResourceConfiguration_Operation<any, any, any>
+  >(
+    executionContext: ExecutionContext<TResourceConfigOperation>,
+    functionParameters: ResourceConfiguration_OperationVariant_CustomImplementation_FunctionParameters,
+    notification: UserNotificationDefinition,
+    userIds: string[]
+  ): Promise<void> {
+    const operation = executionContext.operation;
+
+    // Build template reference from executionContext.operation (guaranteed correct after doOperation corrections)
+    const targetKebab = (notification.target || notification.identifier).toLowerCase().replace(/_/g, '-');
+    const refParts = ['email', String(operation.resourceIdentifier), String(operation.operationIdentifier)];
+    if (operation.variantKey) refParts.push(String(operation.variantKey));
+    refParts.push(targetKebab);
+    let templateRef = refParts.join('.');
+    if (notification.customNotificationRef) {
+      templateRef += `_${notification.customNotificationRef}`;
+    }
+
+    // Determine locale (from config or default to 'en')
+    const locale = this.getDefaultLocale();
+
+    // Get app name and ID from config
+    const appConfig = this.appConfigService.config as Record<string, unknown>;
+    const appIdentity = appConfig.appIdentity as { appName?: string; displayName?: string } | undefined;
+    const applicationId = this.appConfigService.applicationId || 'unknown';
+    const appName = appIdentity?.displayName || appIdentity?.appName || 'Application';
+
+    // Resolve dashboard URL — scope/target-aware (admin targets → APP_ADMIN, else MAIN_APP)
+    const dashboardUrl = this.resolveDashboardUrlForNotification(
+      operation as unknown as ResourceConfiguration_Operation<any, any, any>, notification
+    );
+
+    // Fetch initiator name when user-initiated (for "X added you" style personalization)
+    const initiatorUserId = executionContext.initiatorIds?.userId;
+    const initiatorContext = initiatorUserId ? await this.fetchUserContext(initiatorUserId) : undefined;
+    const initiatorName = initiatorContext?.firstName ?? initiatorContext?.name ?? undefined;
+
+    // Resolve organization name from executionContext (org-scoped resources only)
+    const organizationName = await this.resolveOrganizationName(
+      operation as unknown as ResourceConfiguration_Operation<any, any, any>, executionContext
+    );
+
+    // Resolve direct resource URL (e.g. /organizations/:orgId/todos/:todoId → full link)
+    const resourceUrl = this.resolveResourceUrl(
+      operation as unknown as ResourceConfiguration_Operation<any, any, any>,
+      functionParameters.currentObject as Record<string, unknown> | undefined,
+      executionContext,
+      dashboardUrl
+    );
+
+    // Build base context from function parameters
+    const baseContext = {
+      currentObject: functionParameters.currentObject,
+      objectContext: {
+        primaryScopeContext: {
+          appName,
+          applicationId,
+          organizationName: organizationName ?? undefined,
+        },
+      },
+      additionalContext: {
+        operationType: String(operation.operationIdentifier),
+        resourceType: String(operation.resourceIdentifier),
+        dashboardUrl: dashboardUrl ?? undefined,
+        initiatorName: initiatorName ?? undefined,
+        resourceUrl: resourceUrl ?? undefined,
+      },
+    };
+
+    // For large recipient lists, use batch queue
+    if (userIds.length > EMAIL_BATCH_THRESHOLD) {
+      await this.enqueueEmailBatch(templateRef, locale, userIds, baseContext, notification);
+      return;
+    }
+
+    // Direct sending for smaller lists
+    for (const userId of userIds) {
+      try {
+        const recipientUserContext = await this.fetchUserContext(userId);
+
+        if (!recipientUserContext?.email) {
+          this.logger.warn('No email address for user, skipping notification', {
+            userId,
+            identifier: notification.identifier,
+          });
+          continue;
+        }
+
+        const recipientLocale = (recipientUserContext.preferredLanguage as AvailableLanguage) || locale;
+        const result = await this.emailService.send({
+          templateRef,
+          locale: recipientLocale,
+          type: EmailTemplateType.TRANSACTIONAL,
+          to: recipientUserContext.email,
+          context: {
+            ...baseContext,
+            userContext: {
+              userId,
+              email: recipientUserContext.email,
+              name: recipientUserContext.name,
+              firstName: recipientUserContext.firstName,
+            },
+          },
+        });
+
+        this.logDebug('Email notification sent', {
+          identifier: notification.identifier,
+          userId,
+          success: result.success,
+          messageId: result.messageId,
+        });
+      } catch (error) {
+        this.logger.warn('Failed to send email notification', {
+          userId,
+          identifier: notification.identifier,
+          error: error instanceof Error ? error.message : 'Unknown error',
+        });
+      }
+    }
+  }
+
+  /**
+   * Enqueue a batch of emails for asynchronous sending.
+   * Used for large recipient lists (above EMAIL_BATCH_THRESHOLD).
+   */
+  private async enqueueEmailBatch(
+    templateRef: string,
+    locale: AvailableLanguage,
+    userIds: string[],
+    baseContext: Record<string, unknown>,
+    notification: UserNotificationDefinition
+  ): Promise<void> {
+    // Fetch all user contexts first
+    const emailItems: Array<{
+      templateRef: string;
+      locale: string;
+      type: string;
+      to: string;
+      context: Record<string, unknown>;
+    }> = [];
+
+    for (const userId of userIds) {
+      try {
+        const recipientUserContext = await this.fetchUserContext(userId);
+
+        if (!recipientUserContext?.email) {
+          continue;
+        }
+
+        emailItems.push({
+          templateRef,
+          locale,
+          type: EmailTemplateType.TRANSACTIONAL,
+          to: recipientUserContext.email,
+          context: {
+            ...baseContext,
+            userContext: {
+              userId,
+              email: recipientUserContext.email,
+              name: recipientUserContext.name,
+              firstName: recipientUserContext.firstName,
+            },
+          },
+        });
+      } catch (error) {
+        this.logger.warn('Failed to fetch user context for batch', {
+          userId,
+          error: error instanceof Error ? error.message : 'Unknown error',
+        });
+      }
+    }
+
+    if (emailItems.length === 0) {
+      this.logDebug('No valid email recipients for batch', {
+        identifier: notification.identifier,
+      });
+      return;
+    }
+
+    // Enqueue the batch
+    const { jobId } = await this.queueService.enqueueCustomBatch(
+      'email.batch-send',
+      {
+        batchId: `${notification.identifier}-${Date.now()}`,
+        emails: emailItems,
+        retryOnFailure: true,
+        maxRetries: 3,
+      }
+    );
+
+    this.logDebug('Email batch enqueued', {
+      identifier: notification.identifier,
+      jobId,
+      emailCount: emailItems.length,
+    });
+  }
+
+  /**
+   * Get default locale from app config
+   */
+  private getDefaultLocale(): AvailableLanguage {
+    const langConfig = (this.appConfigService.config as any)?.appPreferences?.languages;
+    const defaultLang = langConfig?.defaultLanguage;
+    // Cast to AvailableLanguage, fallback to 'en' if not set
+    return (defaultLang as AvailableLanguage) ?? ('en' as AvailableLanguage);
+  }
+
+  /**
+   * Get user IDs for a notification target
+   * Handles both fixed targets and custom userIdsSelector
+   */
+  private async getUserIdsForTarget<
+    TResourceConfigOperation extends ResourceConfiguration_Operation<any, any, any>
+  >(
+    executionContext: ExecutionContext<TResourceConfigOperation>,
+    functionParameters: ResourceConfiguration_OperationVariant_CustomImplementation_FunctionParameters,
+    notification: UserNotificationDefinition,
+    target: string
+  ): Promise<string[]> {
+    // Custom user targeting via userIdsSelector
+    if (target === CoreUserNotificationTarget.USERS_CUSTOM && notification.userIdsSelector) {
+      // Ensure objectContext has the expected structure (parents/children)
+      const objectContext = functionParameters.objectContext || {};
+      const normalizedObjectContext = {
+        parents: (objectContext as any)?.parents || {},
+        children: (objectContext as any)?.children || {}
+      };
+
+      return notification.userIdsSelector({
+        currentObject: functionParameters.currentObject,
+        inputDto: functionParameters.inputDto,
+        objectContext: normalizedObjectContext,
+        initiatorIds: functionParameters.initiatorIds
+      });
+    }
+
+    // Fixed targets - extract from executionContext.initiatorIds
+    const initiatorIds = executionContext.initiatorIds;
+
+    switch (target) {
+      case CoreUserNotificationTarget.USER_SELF:
+        return initiatorIds?.userId ? [initiatorIds.userId] : [];
+
+      case CoreUserNotificationTarget.ORGANIZATION:
+      case CoreUserNotificationTarget.ORGANIZATION_USERS:
+        return this.getOrganizationRecipientUserIds(executionContext, initiatorIds?.organizationId);
+
+      case CoreUserNotificationTarget.ORGANIZATION_BILLING:
+      case CoreUserNotificationTarget.ORGANIZATION_USER_MANAGEMENT:
+      case CoreUserNotificationTarget.ORGANIZATION_ADMINISTRATIVE:
+      case CoreUserNotificationTarget.ORGANIZATION_SECURITY:
+        return this.getOrganizationRecipientUserIds(
+          executionContext,
+          initiatorIds?.organizationId,
+          this.mapOrganizationTargetToRoles(target as CoreUserNotificationTarget, notification),
+        );
+
+      default:
+        // Other targets (role-based, application-level) would also need user ID lookup
+        this.logDebug('Target requires user ID lookup', { target });
+        return [];
+    }
+  }
+
+  /**
+   * Fetch user context for a specific userId
+   * This is a placeholder - actual implementation would query the user repository
+   */
+  private async fetchUserContext(userId: string): Promise<any | undefined> {
+    try {
+      const userRepository = this.repositoriesRegistry.getRepository(CoreResourceType.USERS);
+      if (!userRepository) {
+        this.logDebug('No user repository available for fetchUserContext', { userId });
+        return undefined;
+      }
+      const user = await userRepository.read(
+        { operation: { resourceIdentifier: CoreResourceType.USERS, operationIdentifier: 'read' } } as any,
+        userId,
+        { excludeContextualFilter: true },
+      );
+      if (!user) return undefined;
+      return {
+        email: (user as any).email,
+        displayName: (user as any).displayName ?? (user as any).name ?? (user as any).email,
+        name: (user as any).displayName ?? (user as any).name,
+        firstName: (user as any).firstName,
+        preferredLanguage: (user as any).preferredLanguage ?? (user as any).language,
+        userId,
+      };
+    } catch {
+      this.logDebug('Failed to fetch user context', { userId });
+      return undefined;
+    }
+  }
+
+  private async getOrganizationRecipientUserIds(
+    executionContext: ExecutionContext<any>,
+    organizationId: string | undefined,
+    allowedRoles?: string[],
+  ): Promise<string[]> {
+    if (!organizationId) {
+      return [];
+    }
+
+    const organizationMembersRepository = this.repositoriesRegistry.getRepository(CoreResourceType.ORGANIZATION_MEMBERS);
+    if (!organizationMembersRepository) {
+      this.logDebug('No organization members repository available for notification targeting', {
+        organizationId,
+      });
+      return [];
+    }
+
+    const membershipSummaries = await organizationMembersRepository.list<OrganizationMember>(
+      executionContext as any,
+      {
+        organizationId,
+        status: OrganizationMemberStatus.ACTIVE,
+      },
+    );
+    const memberships = await Promise.all(
+      membershipSummaries.map(async (membership) => {
+        if (membership?.userId && Array.isArray(membership.roles)) {
+          return membership;
+        }
+        if (membership?._id) {
+          try {
+            return await organizationMembersRepository.read(
+              executionContext as any,
+              membership._id,
+            ) as OrganizationMember | null;
+          } catch {
+            return membership;
+          }
+        }
+        return membership;
+      }),
+    );
+
+    const allowedRoleSet = allowedRoles && allowedRoles.length > 0
+      ? new Set(allowedRoles)
+      : null;
+    const initiatorUserId = executionContext.initiatorIds?.userId;
+    const userIds = memberships
+      .filter((membership): membership is OrganizationMember => Boolean(membership))
+      .filter((membership) => membership.status === OrganizationMemberStatus.ACTIVE)
+      .filter((membership) => typeof membership.userId === 'string' && membership.userId.length > 0)
+      .filter((membership) => membership.userId !== initiatorUserId)
+      .filter((membership) => {
+        if (!allowedRoleSet) {
+          return true;
+        }
+        return membership.roles.some((role) => allowedRoleSet.has(role));
+      })
+      .map((membership) => membership.userId);
+
+    return Array.from(new Set(userIds));
+  }
+
+  /**
+   * Resolve the correct frontend app URL based on notification target.
+   * Uses the config-driven reverse lookup: notification target → user type (via defaultAppRoles) → app type.
+   * Admin-targeted notifications route to the app type that serves admin user types.
+   * All other notifications route to the default frontend app type.
+   */
+  private resolveDashboardUrlForNotification(
+    _operation: ResourceConfiguration_Operation<any, any, any>,
+    notification: UserNotificationDefinition
+  ): string | undefined {
+    const target = notification.target;
+    const config = this.appConfigService.config;
+
+    const isAdminTarget =
+      target === CoreUserNotificationTarget.APPLICATION_ADMINISTRATOR ||
+      target === CoreUserNotificationTarget.APPLICATION_BILLING ||
+      target === CoreUserNotificationTarget.APPLICATION_USER_MANAGEMENT ||
+      target === CoreUserNotificationTarget.APPLICATION_SECURITY ||
+      target === CoreUserNotificationTarget.APPLICATION_SUPPORT ||
+      target === CoreUserNotificationTarget.APPLICATION_OTHER ||
+      target === CoreUserNotificationTarget.APPLICATION_ADMIN_VIEWER;
+
+    let appType: string | null = null;
+
+    if (isAdminTarget) {
+      const adminUserType = Object.entries(config.userTypes)
+        .find(([, def]) => def.defaultAppRoles?.includes(CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN))?.[0];
+      appType = adminUserType
+        ? this.appConfigService.resolveFrontendServiceNameFromUserType(adminUserType)
+        : null;
+    }
+
+    if (!appType) {
+      appType = this.appConfigService.resolveDefaultFrontendServiceName();
+    }
+
+    if (!appType) return undefined;
+    return AuthControllerUtils.lookupFrontendPublicUrl(config, appType) ?? undefined;
+  }
+
+  /**
+   * Resolve organization name for email context.
+   * Only fetches for org-scoped resources (ORGANIZATIONS scope) using the org ID
+   * from executionContext. Returns undefined for USER_SELF, APPLICATION scopes.
+   */
+  private async resolveOrganizationName(
+    operation: ResourceConfiguration_Operation<any, any, any>,
+    executionContext: ExecutionContext<any>
+  ): Promise<string | undefined> {
+    if (operation.resourcePrimaryScope !== ResourcePrimaryScope.ORGANIZATIONS) {
+      return undefined;
+    }
+
+    const organizationId = executionContext.initiatorIds?.organizationId;
+    if (!organizationId) {
+      return undefined;
+    }
+
+    try {
+      const orgRepository = this.repositoriesRegistry.getRepository(CoreResourceType.ORGANIZATIONS);
+      if (!orgRepository) {
+        return undefined;
+      }
+      const org = await orgRepository.read(
+        { operation: { resourceIdentifier: CoreResourceType.ORGANIZATIONS, operationIdentifier: 'read' } } as any,
+        organizationId,
+        { excludeContextualFilter: true },
+      );
+      if (!org) return undefined;
+      return (org as any).displayName ?? (org as any).name ?? undefined;
+    } catch {
+      this.logDebug('Failed to resolve organization name', { organizationId });
+      return undefined;
+    }
+  }
+
+  /**
+   * Resolve a direct resource URL for the entity that triggered the notification.
+   * Builds the READ operation's frontend route and replaces `:param` placeholders
+   * with actual IDs from the currentObject and executionContext.
+   * Returns undefined for destructive operations (DELETE) or when resolution fails.
+   */
+  private resolveResourceUrl(
+    operation: ResourceConfiguration_Operation<any, any, any>,
+    currentObject: Record<string, unknown> | undefined,
+    executionContext: ExecutionContext<any>,
+    dashboardUrl: string | undefined
+  ): string | undefined {
+    if (!dashboardUrl || !currentObject) return undefined;
+
+    const effectiveOperation = this.resolveEffectiveCoreOperation(
+      operation.operationIdentifier,
+      operation.resourceOperationLike,
+    );
+    if (shouldOmitResourceUrlForOperation(effectiveOperation)) {
+      return undefined;
+    }
+
+    try {
+      const resourceType = String(operation.resourceIdentifier);
+      const routePaths = this.getReadRoutePaths(resourceType);
+      if (!routePaths) return undefined;
+
+      const resourceConfig = this.resourcesRegistry.tryGetResourceConfiguration(resourceType as any);
+
+      const idSources: Record<string, unknown> = {
+        ...(executionContext.initiatorIds ?? {}),
+        ...(currentObject as Record<string, unknown>),
+      };
+
+      const entityId = (currentObject as any).id ?? (currentObject as any)._id;
+      const selfFieldId = resourceConfig?.resourceFieldIdentifier;
+      if (selfFieldId && entityId) {
+        idSources[selfFieldId] = entityId;
+      }
+
+      const base = dashboardUrl.endsWith('/') ? dashboardUrl.slice(0, -1) : dashboardUrl;
+
+      for (const { url: routeTemplate, parameters } of routePaths) {
+        let resolved = routeTemplate;
+        let allResolved = true;
+        for (const param of parameters) {
+          const value = idSources[param.fieldIdentifier];
+          if (!value) { allResolved = false; break; }
+          resolved = resolved.replace(`:${param.fieldIdentifier}`, String(value));
+        }
+        if (allResolved && !resolved.includes(':')) {
+          return `${base}${resolved}`;
+        }
+      }
+
+      return undefined;
+    } catch {
+      this.logDebug('Failed to resolve resource URL', {
+        resourceIdentifier: String(operation.resourceIdentifier),
+      });
+      return undefined;
+    }
+  }
+
+  /**
+   * Get cached READ operation route paths for a resource type.
+   * Computed once per resource type since configs are immutable after initialization.
+   * Returns null (cached miss) when the resource has no routable READ operation.
+   */
+  private getReadRoutePaths(resourceType: string): CachedRoutePaths | null {
+    if (this.readRoutePathsCache.has(resourceType)) {
+      return this.readRoutePathsCache.get(resourceType)!;
+    }
+
+    const resourceConfig = this.resourcesRegistry.tryGetResourceConfiguration(resourceType as any);
+    if (!resourceConfig) {
+      this.readRoutePathsCache.set(resourceType, null);
+      return null;
+    }
+
+    const readOp = resourceConfig.operations.find(
+      (op: ResourceConfiguration_Operation<any, any, any>) =>
+        op.operationIdentifier === CoreResourceOperation.READ &&
+        (op.variantType === ResourceOperationVariantType.API_CALL ||
+         op.variantType === ResourceOperationVariantType.API_CALL_WITH_CALLBACK)
+    );
+    if (!readOp) {
+      this.readRoutePathsCache.set(resourceType, null);
+      return null;
+    }
+
+    const allFieldIds = this.resourcesRegistry.getAllResourceFieldIdentifiers();
+    const paths = ResourcesConfigOperationsUrlsBuilderUtils.buildOperationFrontendRoutePaths(
+      resourceConfig, readOp as any, allFieldIds
+    );
+
+    const result = paths.length > 0 ? paths : null;
+    this.readRoutePathsCache.set(resourceType, result);
+    return result;
+  }
+
+  /**
+   * Dispatch WebSocket-based user notification
+   * Routes to appropriate rooms based on target
+   */
+  private async dispatchWebSocketUserNotification<
+    TResourceConfigOperation extends ResourceConfiguration_Operation<any, any, any>
+  >(
+    executionContext: ExecutionContext<TResourceConfigOperation>,
+    functionParameters: ResourceConfiguration_OperationVariant_CustomImplementation_FunctionParameters,
+    notification: UserNotificationDefinition
+  ): Promise<void> {
+    const operation = executionContext.operation;
+    const target = notification.target;
+
+    // Build the notification payload
+    const payload: WS_ResourceNotificationPayload = {
+      resourceType: operation.resourceIdentifier,
+      operationIdentifier: String(operation.operationIdentifier),
+      isOperationDefault: operation.isOperationDefault,
+      isBulkOperation: 'isBulkOperation' in operation && operation.isBulkOperation === true,
+      action: this.mapOperationToAction(
+        operation.operationIdentifier,
+        operation.resourceOperationLike,
+      ),
+      // Pass configured notification level (if provided) - frontend will use this over action-based default
+      // UserNotificationLevel and NotificationLevel are identical enums - cast through unknown
+      notificationLevel: notification.level as unknown as NotificationLevel | undefined,
+      affectedIds: this.extractAffectedIds(functionParameters.currentObject),
+      contextResourceIdentifiers: this.convertContextResourceIdsToRecord(executionContext),
+      notificationIdentifier: notification.identifier,
+      initiatorUserId: executionContext.initiatorIds?.userId,
+      timestamp: new Date(),
+    };
+
+    // Copy FRONT_END_SUCCESS-specific display hints into the WS payload.
+    // The backend does NOT interpret these — it passes them through for the frontend.
+    if (notification.channel === CoreUserNotificationChannel.FRONT_END_SUCCESS) {
+      const feNotification = notification as z.infer<typeof UserNotificationDefinition_FrontEndSuccessSchema>;
+      if (feNotification.celebration || feNotification.nextStep) {
+        payload.frontendDisplayHints = {
+          celebration: feNotification.celebration,
+          nextStep: feNotification.nextStep,
+        };
+      }
+    }
+
+    const message: WebSocketMessage = {
+      type: CoreWebSocketEvent.RESOURCE_NOTIFICATION,
+      payload,
+      timestamp: new Date(),
+      userId: executionContext.initiatorIds?.userId,
+      organizationId: executionContext.initiatorIds?.organizationId,
+    };
+
+    // Route based on target
+    switch (target) {
+      case CoreUserNotificationTarget.USER_SELF:
+        if (executionContext.initiatorIds?.userId) {
+          await this.webSocketService.sendToUser(executionContext.initiatorIds.userId, message);
+        }
+        break;
+
+      case CoreUserNotificationTarget.ORGANIZATION:
+      case CoreUserNotificationTarget.ORGANIZATION_USERS:
+        if (executionContext.initiatorIds?.organizationId) {
+          await this.webSocketService.sendToOrganization(
+            executionContext.initiatorIds.organizationId,
+            message,
+            // Optionally exclude the initiator
+            executionContext.initiatorIds?.userId ? [executionContext.initiatorIds.userId] : undefined
+          );
+        }
+        break;
+
+      case CoreUserNotificationTarget.ORGANIZATION_BILLING:
+      case CoreUserNotificationTarget.ORGANIZATION_USER_MANAGEMENT:
+      case CoreUserNotificationTarget.ORGANIZATION_ADMINISTRATIVE:
+      case CoreUserNotificationTarget.ORGANIZATION_SECURITY:
+        // Send to specific role rooms within the organization
+        if (executionContext.initiatorIds?.organizationId && notification.userRoles) {
+          for (const role of notification.userRoles) {
+            await this.webSocketService.sendToRole(
+              executionContext.initiatorIds.organizationId,
+              role,
+              message
+            );
+          }
+        }
+        break;
+
+      case CoreUserNotificationTarget.APPLICATION_ADMINISTRATOR:
+      case CoreUserNotificationTarget.APPLICATION_BILLING:
+      case CoreUserNotificationTarget.APPLICATION_USER_MANAGEMENT:
+      case CoreUserNotificationTarget.APPLICATION_SECURITY:
+      case CoreUserNotificationTarget.APPLICATION_SUPPORT:
+      case CoreUserNotificationTarget.APPLICATION_OTHER:
+      case CoreUserNotificationTarget.APPLICATION_ADMIN_VIEWER:
+        // Application-level notifications go to admin dashboard users
+        // Map target to app-level role name for WebSocket room targeting
+        const appRoles = this.mapApplicationTargetToRoles(target, notification);
+        for (const appRole of appRoles) {
+          await this.webSocketService.sendToAppRole(appRole, message);
+        }
+        this.logDebug('Application-level notification sent', {
+          target,
+          identifier: notification.identifier,
+          roles: appRoles,
+        });
+        break;
+
+      case CoreUserNotificationTarget.USERS_CUSTOM:
+        // Custom user targeting via userIdsSelector
+        if (notification.userIdsSelector) {
+          // Ensure objectContext has the expected structure (parents/children)
+          const objectContext = functionParameters.objectContext || {};
+          const normalizedObjectContext = {
+            parents: (objectContext as any)?.parents || {},
+            children: (objectContext as any)?.children || {}
+          };
+
+          const userIds = notification.userIdsSelector({
+            currentObject: functionParameters.currentObject,
+            inputDto: functionParameters.inputDto,
+            objectContext: normalizedObjectContext,
+            initiatorIds: functionParameters.initiatorIds
+          });
+
+          // For WebSocket, we only need userIds (no need to fetch userContext)
+          for (const userId of userIds) {
+            await this.webSocketService.sendToUser(userId, message);
+          }
+        }
+        break;
+
+      case CoreUserNotificationTarget.INBOUND_CONTACT:
+        // Inbound contact notifications (e.g., contact form submissions)
+        // Route to support and admin roles by default
+        const inboundContactRoles = notification.userRoles?.length
+          ? notification.userRoles
+          : [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN];
+        for (const role of inboundContactRoles) {
+          await this.webSocketService.sendToAppRole(role, message);
+        }
+        this.logDebug('Inbound contact notification sent', {
+          identifier: notification.identifier,
+          roles: inboundContactRoles,
+        });
+        break;
+
+      default:
+        this.logDebug('Unknown notification target', {
+          target,
+          identifier: notification.identifier,
+        });
+    }
+  }
+
+  /**
+   * Dispatch M2M notifications (webhooks)
+   *
+   * @param executionContext - The execution context
+   * @param functionParameters - Function parameters with data context
+   * @private
+   */
+  private async dispatchM2MNotifications<
+    TResourceConfigOperation extends ResourceConfiguration_Operation<any, any, any>
+  >(
+    executionContext: ExecutionContext<TResourceConfigOperation>,
+    functionParameters: ResourceConfiguration_OperationVariant_CustomImplementation_FunctionParameters
+  ): Promise<void> {
+    const operation = executionContext.operation;
+    const m2mNotifications = operation.m2mNotifications || [];
+
+    if (m2mNotifications.length === 0) {
+      return;
+    }
+
+    for (const m2mNotification of m2mNotifications) {
+      const channel = m2mNotification.channel as CoreM2MNotificationChannel | string;
+      if (
+        channel === CoreM2MNotificationChannel.WEBHOOK_ORGANIZATION
+        || channel === CoreM2MNotificationChannel.WEBHOOK_APPLICATION
+      ) {
+        throw new Error(
+          `M2M notification channel '${channel}' is authored on ${String(operation.resourceIdentifier)}.${String(operation.operationIdentifier)} but no delivery implementation exists yet.`,
+        );
+      }
+
+      throw new Error(`M2M notification channel '${channel}' is not implemented.`);
+    }
+  }
+
+  /**
+   * Dispatch resource-room notifications (path-independent collaboration).
+   *
+   * This stays separately callable because some post-write orchestration paths
+   * only have authoritative object truth and initiator ids, not the full
+   * computation context required for authored notification delivery.
+   */
+  async dispatchResourceRoomNotifications<
+    TResourceConfigOperation extends ResourceConfiguration_Operation<any, any, any>
+  >(
+    executionContext: ExecutionContext<TResourceConfigOperation>,
+    functionParameters: ResourceConfiguration_OperationVariant_CustomImplementation_FunctionParameters
+  ): Promise<void> {
+    const operation = executionContext.operation;
+    const resourceType = operation.resourceIdentifier;
+    const currentObject = functionParameters.currentObject;
+
+    // Only dispatch for write operations
+    const operationIdentifier = operation.operationIdentifier;
+    if (!this.isWriteOperation(operationIdentifier, operation.resourceOperationLike)) {
+      return;
+    }
+
+    const affectedIds = this.extractAffectedIds(currentObject);
+    if (affectedIds.length === 0) {
+      return;
+    }
+
+    const action = this.mapOperationToAction(
+      operationIdentifier,
+      operation.resourceOperationLike,
+    );
+    const contextResourceIdentifiers = this.convertContextResourceIdsToRecord(executionContext);
+    const initiatorUserId = executionContext.initiatorIds?.userId;
+
+    const timestamp = new Date();
+    const operationIdentifierString = String(operationIdentifier);
+    const scopePayload = buildScopeRoomNotificationPayload({
+      resourceType,
+      resourceId: affectedIds[0],
+      contextResourceIdentifiers,
+      action,
+      affectedIds,
+      operationIdentifier: operationIdentifierString,
+      initiatorUserId,
+      currentObject,
+      timestamp,
+    });
+
+    // Emit to individual resource rooms
+    for (const resourceId of affectedIds) {
+      const resourcePayload = buildResourceRoomSyncPayload({
+        resourceType,
+        resourceId,
+        contextResourceIdentifiers,
+        action,
+        affectedIds,
+        operationIdentifier: operationIdentifierString,
+        initiatorUserId,
+        currentObject,
+        timestamp,
+      });
+
+      const resourceNotificationFallback = buildResourceRoomStaleHintPayload({
+        resourceType,
+        resourceId,
+        contextResourceIdentifiers,
+        action,
+        affectedIds,
+        operationIdentifier: operationIdentifierString,
+        initiatorUserId,
+        timestamp,
+      });
+
+      // Resource rooms get the strongest contract first: try authoritative sync
+      // replay for that exact id, and degrade to a notification-grade stale hint
+      // only when the backend cannot prove replay truth or the websocket layer
+      // rejects the replay payload during canonical validation.
+      if (!resourcePayload) {
+        this.logDebug('Skipped resource-room sync payload due to missing authoritative replay data', {
+          resourceType,
+          resourceId,
+          action,
+          affectedCount: affectedIds.length,
+        });
+        this.webSocketService.emitToResourceRoom(
+          resourceType,
+          resourceId,
+          CoreWebSocketEvent.RESOURCE_UPDATED,
+          resourceNotificationFallback,
+        );
+        continue;
+      }
+
+      const event = action === ResourceAction.DELETED
+        ? CoreWebSocketEvent.RESOURCE_DELETED
+        : CoreWebSocketEvent.RESOURCE_UPDATED;
+
+      const emitted = this.webSocketService.emitToResourceRoom(resourceType, resourceId, event, resourcePayload);
+      if (!emitted) {
+        this.logDebug('Skipped resource-room sync emit after canonical replay validation failure', {
+          resourceType,
+          resourceId,
+          action,
+          affectedCount: affectedIds.length,
+        });
+        this.webSocketService.emitToResourceRoom(
+          resourceType,
+          resourceId,
+          CoreWebSocketEvent.RESOURCE_UPDATED,
+          resourceNotificationFallback,
+        );
+      }
+    }
+
+    // Scope rooms are emitted separately from per-resource rooms because they
+    // serve list/cache refresh semantics rather than authoritative per-resource
+    // replay semantics.
+    const scopes = this.extractScopesFromContext(contextResourceIdentifiers, operation.resourcePrimaryScope);
+    if (scopes.length > 0) {
+      this.webSocketService.emitToScopeRooms(
+        resourceType,
+        scopes,
+        CoreWebSocketEvent.RESOURCE_UPDATED,
+        scopePayload,
+      );
+    }
+
+    this.logDebug('Resource room notifications dispatched', {
+      resourceType,
+      action,
+      affectedCount: affectedIds.length,
+      scopeCount: scopes.length,
+    });
+  }
+
+  // ================================
+  // Helper Methods
+  // ================================
+
+  /**
+   * Map APPLICATION_* notification targets to app-level role names for WebSocket targeting.
+   *
+   * These roles correspond to the `app:role:${role}` rooms that users join when they have
+   * application-level permissions (e.g., super admins, support staff).
+   *
+   * @param target - The CoreUserNotificationTarget
+   * @param notification - The notification definition (may contain userRoles override)
+   * @returns Array of role names to target
+   */
+  private mapApplicationTargetToRoles(
+    target: CoreUserNotificationTarget,
+    notification: UserNotificationDefinition
+  ): string[] {
+    // If userRoles is explicitly provided, use those
+    if (notification.userRoles && notification.userRoles.length > 0) {
+      return notification.userRoles;
+    }
+
+    // Map target to default app-level roles using CORE_APP_ROLES enum
+    // These should match the roles that users with app-level permissions have
+    switch (target) {
+      case CoreUserNotificationTarget.APPLICATION_ADMINISTRATOR:
+        return [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN];
+
+      case CoreUserNotificationTarget.APPLICATION_BILLING:
+        return [CORE_APP_ROLES.APP_ADMIN_BILLING_MANAGER, CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN];
+
+      case CoreUserNotificationTarget.APPLICATION_USER_MANAGEMENT:
+        return [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN];
+
+      case CoreUserNotificationTarget.APPLICATION_SECURITY:
+        return [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN];
+
+      case CoreUserNotificationTarget.APPLICATION_SUPPORT:
+        return [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN];
+
+      case CoreUserNotificationTarget.APPLICATION_ADMIN_VIEWER:
+        return [CORE_APP_ROLES.APP_ADMIN_VIEWER, CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN];
+
+      case CoreUserNotificationTarget.APPLICATION_OTHER:
+      default:
+        // Default to admin roles for generic application notifications
+        return [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN];
+    }
+  }
+
+  private mapOrganizationTargetToRoles(
+    target: CoreUserNotificationTarget,
+    notification: UserNotificationDefinition,
+  ): string[] {
+    if (notification.userRoles && notification.userRoles.length > 0) {
+      return notification.userRoles;
+    }
+
+    switch (target) {
+      case CoreUserNotificationTarget.ORGANIZATION_BILLING:
+      case CoreUserNotificationTarget.ORGANIZATION_USER_MANAGEMENT:
+      case CoreUserNotificationTarget.ORGANIZATION_ADMINISTRATIVE:
+      case CoreUserNotificationTarget.ORGANIZATION_SECURITY:
+        return [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN];
+      case CoreUserNotificationTarget.ORGANIZATION:
+      case CoreUserNotificationTarget.ORGANIZATION_USERS:
+      default:
+        return [];
+    }
+  }
+
+  /**
+   * Map operation identifier to action type
+   */
+  private mapOperationToAction(
+    operationIdentifier: any,
+    resourceOperationLike?: CoreResourceOperation,
+  ): ResourceAction {
+    const effectiveOperation = this.resolveEffectiveCoreOperation(operationIdentifier, resourceOperationLike);
+
+    switch (effectiveOperation) {
+      case CoreResourceOperation.CREATE:
+      case CoreResourceOperation.CREATE_MANY:
+        return ResourceAction.CREATED;
+      case CoreResourceOperation.DELETE:
+      case CoreResourceOperation.DELETE_MANY:
+        return ResourceAction.DELETED;
+      case CoreResourceOperation.UPDATE:
+      case CoreResourceOperation.UPDATE_MANY:
+      default:
+        return ResourceAction.UPDATED;
+    }
+  }
+
+  /**
+   * Check if operation is a write operation (CREATE, UPDATE, DELETE)
+   */
+  private isWriteOperation(
+    operationIdentifier: any,
+    resourceOperationLike?: CoreResourceOperation,
+  ): boolean {
+    const effectiveOperation = this.resolveEffectiveCoreOperation(operationIdentifier, resourceOperationLike);
+    return (
+      effectiveOperation === CoreResourceOperation.CREATE ||
+      effectiveOperation === CoreResourceOperation.CREATE_MANY ||
+      effectiveOperation === CoreResourceOperation.UPDATE ||
+      effectiveOperation === CoreResourceOperation.UPDATE_MANY ||
+      effectiveOperation === CoreResourceOperation.DELETE ||
+      effectiveOperation === CoreResourceOperation.DELETE_MANY
+    );
+  }
+
+  private resolveEffectiveCoreOperation(
+    operationIdentifier: any,
+    resourceOperationLike?: CoreResourceOperation,
+  ): CoreResourceOperation | undefined {
+    if (resourceOperationLike) {
+      return resourceOperationLike;
+    }
+
+    const candidate = String(operationIdentifier) as CoreResourceOperation;
+    return Object.values(CoreResourceOperation).includes(candidate)
+      ? candidate
+      : undefined;
+  }
+
+  /**
+   * Extract affected IDs from the current object (result)
+   */
+  private extractAffectedIds(currentObject: any): string[] {
+    if (!currentObject) {
+      return [];
+    }
+
+    // Handle array of objects (bulk operations)
+    if (Array.isArray(currentObject)) {
+      return currentObject
+        .flatMap((item) => {
+          if (typeof item === 'string' && item.length > 0) {
+            return [item];
+          }
+
+          if (item && (item._id || item.id)) {
+            return [String(item._id || item.id)];
+          }
+
+          return [];
+        });
+    }
+
+    // Handle single object
+    if (currentObject._id || currentObject.id) {
+      return [String(currentObject._id || currentObject.id)];
+    }
+
+    // Handle delete responses
+    if (currentObject.deletedIds) {
+      return currentObject.deletedIds.map((id: any) => String(id));
+    }
+    if (currentObject.deletedId) {
+      return [String(currentObject.deletedId)];
+    }
+
+    // Handle update responses
+    if (currentObject.updatedIds) {
+      return currentObject.updatedIds.map((id: any) => String(id));
+    }
+
+    return [];
+  }
+
+  /**
+   * Convert ExecutionContext context resource IDs Map to Record<string, string>
+   * Handles string, string[], and undefined values appropriately
+   */
+  private convertContextResourceIdsToRecord<
+    TResourceConfigOperation extends ResourceConfiguration_Operation<any, any, any>
+  >(
+    executionContext: ExecutionContext<TResourceConfigOperation>
+  ): Record<string, string> {
+    const contextResourceIds = executionContext.getContextResourceIds();
+    const result: Record<string, string> = {};
+
+    for (const [key, value] of contextResourceIds.entries()) {
+      if (value === undefined) {
+        continue;
+      }
+
+      // Handle string or string[] - for arrays, take first element (same as getContextResourceId)
+      const stringValue = Array.isArray(value) ? value[0] : value;
+      if (stringValue !== undefined) {
+        result[key] = stringValue;
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Extract scopes from context resource identifiers for scope room notifications
+   */
+  private extractScopesFromContext(
+    contextResourceIdentifiers: Record<string, string>,
+    primaryScope: ResourcePrimaryScope
+  ): Array<{ scopeKey: string; scopeId: string }> {
+    const scopes: Array<{ scopeKey: string; scopeId: string }> = [];
+    const seenScopes = new Set<string>();
+    const pushScope = (scopeKey: string, scopeId: string | undefined): void => {
+      if (!scopeId) {
+        return;
+      }
+      const dedupeKey = `${scopeKey}:${scopeId}`;
+      if (seenScopes.has(dedupeKey)) {
+        return;
+      }
+      seenScopes.add(dedupeKey);
+      scopes.push({ scopeKey, scopeId });
+    };
+
+    if (primaryScope === ResourcePrimaryScope.APPLICATION && contextResourceIdentifiers.applicationId) {
+      pushScope('app', contextResourceIdentifiers.applicationId);
+    }
+
+    if (primaryScope === ResourcePrimaryScope.USER_SELF && contextResourceIdentifiers.userId) {
+      pushScope('user', contextResourceIdentifiers.userId);
+    }
+
+    // Add organization scope if present
+    if (contextResourceIdentifiers.organizationId) {
+      pushScope('org', contextResourceIdentifiers.organizationId);
+    }
+
+    // Add other parent resource scopes
+    for (const [key, value] of Object.entries(contextResourceIdentifiers)) {
+      // Skip organizationId (already handled) and the resource's own ID
+      if (key === 'organizationId' || key.endsWith('Id') && !key.includes('Parent')) {
+        // Add parent resource scopes (e.g., todoListId -> todolist scope)
+        const scopeKey = key.replace(/Id$/, '').toLowerCase();
+        if (scopeKey !== 'organization' && value) {
+          pushScope(scopeKey, value);
+        }
+      }
+    }
+
+    return scopes;
+  }
+}