@wildo-ai/saas-backend-lib 1.1.1 → 1.1.3

package/dist/esm/notifications/services/notifications-dispatcher.backend.service.js

@@ -10,9 +10,10 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
+var NotificationDispatcherService_1;
 import { inject, injectable, optional } from 'inversify';
 import { createHash, randomUUID } from 'node:crypto';
-import { ResourcePrimaryScope, CoreM2MNotificationChannel, CoreUserNotificationChannel, CoreUserNotificationTarget, NotificationBadgeSourceKind, CoreResourceOperation, CoreWebSocketEvent, EmailTemplateType, ResourceAction, CORE_APP_ROLES, CORE_ORG_ROLES, CoreResourceType, OrganizationMemberStatus, ResourcesConfigOperationsUrlsBuilderUtils, ResourcesConfig_OperationPathUtils, ResourceOperationVariantType, WebSocketResourceDeliveryTarget, ErrorType, ErrorCustomMessageReference, } from '@wildo-ai/saas-models';
+import { ResourcePrimaryScope, deriveResourceScopeRoomQualifiers, CoreM2MNotificationChannel, CoreUserNotificationChannel, CoreUserNotificationTarget, userNotificationTargetIsSuppressibleByRecipientPreference, NotificationBadgeSourceKind, buildNotificationBadgeDefinitionIndex, CoreResourceOperation, CoreWebSocketEvent, EmailTemplateType, ResourceAction, CORE_APP_ROLES, CORE_ORG_ROLES, CoreResourceType, OrganizationMemberStatus, UserStatus, ResourcesConfigOperationsUrlsBuilderUtils, ResourcesConfig_OperationPathUtils, ResourceOperationVariantType, WebSocketResourceDeliveryTarget, ErrorType, ErrorCustomMessageReference, } from '@wildo-ai/saas-models';
 import { BrandAssetComposition, BrandAssetPurpose } from '@wildo-ai/saas-models';
 import { AvailableLanguage } from '@wildo-ai/presets-components-models';
 import { SAAS_SERVICE_TYPES } from '../../inject/models/service-types.js';
@@ -247,6 +248,7 @@ export function buildResourceRoomStaleHintPayload(params) {
     };
 }
 let NotificationDispatcherService = class NotificationDispatcherService {
+    static { NotificationDispatcherService_1 = this; }
     logger;
     errorBuilder;
     webSocketService;
@@ -362,30 +364,60 @@ let NotificationDispatcherService = class NotificationDispatcherService {
         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
+        const definitionsByKey = buildNotificationBadgeDefinitionIndex(this.resourcesRegistry.getResourcesRegistry().notificationBadgeDefinitions ?? []);
         for (const badgeOp of badgeOperations) {
+            /**
+             * The DEFINITION decides the badge, including its SCOPE.
+             *
+             * This used to take the scope from `determineBadgeScope(executionContext)` — the operation's
+             * own `resourcePrimaryScope`, with an initiator-shaped fallback — and pass the authored
+             * identifier straight through with no lookup at all. Two things followed. An operation on a
+             * user-scoped resource wrote a USER counter even when the definition it named lived at
+             * organization scope, so the row it created belonged to no definition. And an identifier that
+             * matched no definition wrote a counter nothing could ever render, reported nowhere.
+             *
+             * Resolving the ref first fixes both at once: the scope is read off the definition, and an
+             * unresolvable ref cannot reach the write. Only the scopeId — WHOSE badge — remains a runtime
+             * question, and it is answered from the initiator at the definition's own scope.
+             */
+            const definition = definitionsByKey.get(badgeOp.badgeRef);
+            if (!definition) {
+                /**
+                 * Unreachable on an application that started: `validateNotificationBadgeDeclarations`
+                 * refuses this at configuration time. Kept as defence in depth for a host that assembles a
+                 * registry by another route, and loud because a silent skip here is the original defect.
+                 */
+                this.logger.warn('Badge operation names no registered badge definition — skipping', {
+                    badgeRef: badgeOp.badgeRef,
+                    operation: badgeOp.operation,
+                    resourceType: operation.resourceIdentifier,
+                    operationIdentifier: String(operation.operationIdentifier),
+                });
+                continue;
+            }
+            const scopeId = this.resolveBadgeScopeId(executionContext, definition.scope);
+            if (!scopeId) {
+                this.logDebug('No scope id for the badge definition\'s scope, skipping badge operation', {
+                    badgeRef: badgeOp.badgeRef,
+                    scope: definition.scope,
+                    resourceType: operation.resourceIdentifier,
+                    operationIdentifier: String(operation.operationIdentifier),
+                });
+                continue;
+            }
             try {
-                await this.badgeService.executeBadgeOperation(executionContext, scope, scopeId, badgeOp.identifier, badgeOp.operation, 1 // Default value (can be extended to support custom values)
+                await this.badgeService.executeBadgeOperation(executionContext, definition.scope, scopeId, definition.identifier, badgeOp.operation, 1 // Default value (can be extended to support custom values)
                 );
                 this.logDebug('Badge operation executed', {
-                    identifier: badgeOp.identifier,
+                    badgeRef: badgeOp.badgeRef,
                     operation: badgeOp.operation,
-                    scope,
+                    scope: definition.scope,
                     scopeId,
                 });
             }
             catch (error) {
                 this.logger.warn('Failed to execute badge operation', {
-                    identifier: badgeOp.identifier,
+                    badgeRef: badgeOp.badgeRef,
                     operation: badgeOp.operation,
                     ...projectCaughtErrorLogFields(error),
                 });
@@ -465,44 +497,33 @@ let NotificationDispatcherService = class NotificationDispatcherService {
         }
     }
     /**
-     * Determine the badge scope and scopeId from execution context.
+     * Resolve WHOSE badge this is — the scopeId — for a scope the DEFINITION already fixed.
+     *
+     * ## Why this no longer decides the scope
      *
-     * Only USER_SELF and ORGANIZATIONS are supported badge scopes after the
-     * polymorphism refactor (`.cursor/plans/notification-badges-polymorphism-refactor.md`):
-     * the APPLICATION variant was dropped (no canonical badges declared at app
-     * scope and no resource type backs it anymore). An operation whose
-     * `resourcePrimaryScope` is APPLICATION (or any other unsupported value)
-     * yields `{ scope: null, scopeId: null }` so the caller logs and skips
-     * cleanly — never silently dispatches into the badge service where
-     * `resolveRepository(APPLICATION)` would throw.
+     * Its predecessor (`determineBadgeScope`) answered both halves from the execution context: it
+     * read `operation.resourcePrimaryScope`, mapped `USER_SELF` → `initiatorIds.userId` and
+     * `ORGANIZATIONS` → `initiatorIds.organizationId`, and for anything else — `APPLICATION`,
+     * `ANONYMOUS`, or an unscoped operation — guessed, preferring the organization when the request
+     * happened to carry one and falling back to the user. That guess decided which COLLECTION a
+     * counter was written to, from a property of the operation that has nothing to say about which
+     * badge the author meant. An operation on a user-scoped resource could only ever move a
+     * user-scoped counter, whatever badge its `badgeRef` named.
      *
-     * The fallback (org-then-user from `initiatorIds`) is retained for the
-     * `undefined` / unscoped operation case so badge effects on operations that
-     * happen to share an org/user context still fire.
+     * The definition names the scope, so only the id is left, and the id is genuinely a runtime fact:
+     * which user, which organization. `null` means the request carries no identity at that scope
+     * (an anonymous or purely application-scoped call reaching an org-scoped badge), which is a skip
+     * rather than an error — no principal's count could have changed.
      */
-    determineBadgeScope(executionContext) {
-        const operation = executionContext.operation;
-        const primaryScope = operation.resourcePrimaryScope;
+    resolveBadgeScopeId(executionContext, scope) {
         const initiatorIds = executionContext.initiatorIds;
-        switch (primaryScope) {
+        switch (scope) {
             case ResourcePrimaryScope.USER_SELF:
-                return { scope: ResourcePrimaryScope.USER_SELF, scopeId: initiatorIds?.userId || null };
+                return initiatorIds?.userId || null;
             case ResourcePrimaryScope.ORGANIZATIONS:
-                return { scope: ResourcePrimaryScope.ORGANIZATIONS, scopeId: initiatorIds?.organizationId || null };
-            // APPLICATION (and ANONYMOUS) intentionally fall through to the
-            // unscoped-fallback branch below: see JSDoc above.
+                return initiatorIds?.organizationId || null;
             default:
-                // Fallback to organization if available, otherwise user.
-                // Note: APPLICATION-scoped operations land here too — they take the
-                // org/user path if those identifiers are available, otherwise the
-                // dispatcher logs "Cannot determine badge scope, skipping".
-                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 };
+                return null;
         }
     }
     /**
@@ -520,20 +541,27 @@ let NotificationDispatcherService = class NotificationDispatcherService {
         }
         const emailResults = [];
         for (const notification of userNotifications) {
-            // Config-declared side-effect gate: skip a notification whose `condition` evaluates falsy
-            // against the post-operation context. Evaluated here — before channel resolution and the
-            // email-by-address path — so it gates every channel uniformly. Canonical use: the org-member
-            // invite email fires only for INVITED rows, never for an ACTIVE direct-add (founder / SSO-JIT /
-            // SCIM), whose denormalized `userEmail` is the member's OWN address. Absent = always dispatch.
-            if (notification.condition && !notification.condition(functionParameters)) {
-                this.logDebug('Skipping user notification: condition not met', {
-                    identifier: notification.identifier,
-                    channel: notification.channel,
-                    target: notification.target,
-                });
-                continue;
-            }
             try {
+                // Config-declared side-effect gate: skip a notification whose `condition` evaluates falsy
+                // against the post-operation context. Evaluated before channel resolution and the
+                // email-by-address path, so it gates every channel uniformly. Canonical use: the org-member
+                // invite email fires only for INVITED rows, never for an ACTIVE direct-add (founder /
+                // SSO-JIT / SCIM), whose denormalized `userEmail` is the member's OWN address. Absent =
+                // always dispatch.
+                //
+                // It sits INSIDE the try deliberately. The predicate is application-authored code running
+                // in the dispatcher's loop, so one that throws is a single notification's failure and not
+                // the operation's. Evaluated outside, one bad predicate ended the loop and silently dropped
+                // every notification declared after it, which is exactly what the catch below exists to
+                // prevent.
+                if (notification.condition && !notification.condition(functionParameters)) {
+                    this.logDebug('Skipping user notification: condition not met', {
+                        identifier: notification.identifier,
+                        channel: notification.channel,
+                        target: notification.target,
+                    });
+                    continue;
+                }
                 const notificationEmailResults = await this.dispatchSingleUserNotification(executionContext, functionParameters, notification, emailSubmissionSourceId);
                 emailResults.push(...notificationEmailResults);
             }
@@ -582,6 +610,13 @@ let NotificationDispatcherService = class NotificationDispatcherService {
     async dispatchEmailSmsPushUserNotification(executionContext, functionParameters, notification, emailSubmissionSourceId) {
         const target = notification.target;
         const channel = notification.channel;
+        /*
+         * The recipient channel switches (#409) do NOT apply on the email-by-address path below. The
+         * address comes from a field on the operation's own object and identifies no user, so there is
+         * no preferences row to consult — the canonical case is an invitation sent to somebody who does
+         * not have an account yet. Suppression is a property of a KNOWN recipient, and this path has
+         * none by construction.
+         */
         // Email-by-address: when an EMAIL notification declares `recipientEmailField`, the
         // recipient is a raw address read from the current object — a party who is NOT a
         // platform user (an organization-invitation invitee, an inbound lead). There is no
@@ -592,6 +627,38 @@ let NotificationDispatcherService = class NotificationDispatcherService {
         if (recipientEmailField) {
             return this.dispatchEmailToRecipientAddress(executionContext, functionParameters, notification, recipientEmailField, emailSubmissionSourceId);
         }
+        /*
+         * Organization notification ROUTING (#410, decided 2026-09-08).
+         *
+         * A tenant's `organizationNotifications` record carries four category addresses and four
+         * category switches. It is seeded by apps-manager at provisioning, rendered and edited through
+         * the organizations preset, audited — and until now read by NOTHING: organization-targeted
+         * notifications resolved to member user ids by role and went to each member's own address, so a
+         * tenant that filled the settings screen in changed nothing at all.
+         *
+         * The category is DERIVED from the notification's target, not declared. The target vocabulary
+         * and the record's categories line up one-for-one — `ORGANIZATION_BILLING` ↔ `billing`,
+         * `ORGANIZATION_SECURITY` ↔ `security`, and so on — so a second authoring surface would only be
+         * a place for the two to disagree.
+         *
+         * A configured address REPLACES the member fan-out rather than adding to it. A tenant that
+         * routes security mail to a SOC address is saying where that mail goes, not asking for a copy;
+         * sending both would make the setting an amplifier instead of a router.
+         */
+        const organizationRouting = channel === CoreUserNotificationChannel.EMAIL
+            ? await this.resolveOrganizationNotificationRouting(executionContext, notification, target)
+            : undefined;
+        if (organizationRouting?.suppressed) {
+            this.logDebug('Skipping organization notification: the tenant switched this category off', {
+                identifier: notification.identifier,
+                target,
+                category: organizationRouting.category,
+            });
+            return [];
+        }
+        if (organizationRouting?.address) {
+            return this.dispatchEmailToOrganizationAddress(executionContext, functionParameters, notification, organizationRouting.address, organizationRouting.category, emailSubmissionSourceId);
+        }
         // Get user IDs based on target
         const userIds = await this.getUserIdsForTarget(executionContext, functionParameters, notification, target);
         if (userIds.length === 0) {
@@ -715,6 +782,14 @@ let NotificationDispatcherService = class NotificationDispatcherService {
                     });
                     continue;
                 }
+                if (!this.recipientAcceptsNotificationChannel(notification, recipientUserContext)) {
+                    this.logDebug('Skipping user notification: recipient switched this channel off', {
+                        userId,
+                        identifier: notification.identifier,
+                        channel: notification.channel,
+                    });
+                    continue;
+                }
                 const recipientLocale = this.resolveRecipientLocale(recipientUserContext, locale);
                 const result = await this.emailService.send({
                     ...(emailSubmissionSourceId && {
@@ -766,6 +841,116 @@ let NotificationDispatcherService = class NotificationDispatcherService {
      * token-bearing emails still carry their `acceptUrl`. Best-effort: a missing address
      * or a send failure is logged and swallowed, never thrown into the operation pipeline.
      */
+    /**
+     * Which of the tenant's four notification categories an organization-targeted notification
+     * belongs to, or `undefined` when the target names no category.
+     *
+     * DERIVED from the target rather than declared per notification (#410). The two vocabularies were
+     * built to line up and a mapping table is the only place they can drift; the entries that are
+     * absent are absent for a reason:
+     *
+     *   - `ORGANIZATION_USERS` fans out to every member BY DESIGN. Routing it to one address would
+     *     change who the message is for, not merely where it lands.
+     *   - `ORGANIZATION` is the tenant itself with no category, so it falls to `defaultEmailAddress`
+     *     below without belonging to a switch.
+     */
+    static ORGANIZATION_NOTIFICATION_CATEGORY_BY_TARGET = Object.freeze({
+        [CoreUserNotificationTarget.ORGANIZATION_BILLING]: 'billing',
+        [CoreUserNotificationTarget.ORGANIZATION_SECURITY]: 'security',
+        [CoreUserNotificationTarget.ORGANIZATION_ADMINISTRATIVE]: 'administrative',
+        [CoreUserNotificationTarget.ORGANIZATION_USER_MANAGEMENT]: 'usersManagement',
+    });
+    /**
+     * Resolve where an organization-targeted email should go, and whether it should go at all.
+     *
+     * Returns `undefined` for a target this record does not govern, so the caller falls through to
+     * the ordinary member fan-out. Reading the record is best-effort: a tenant with no
+     * `organizationNotifications` row, or a read that fails, must fall through to the behaviour that
+     * existed before this feature rather than silently dropping the notification.
+     */
+    async resolveOrganizationNotificationRouting(executionContext, notification, target) {
+        const category = NotificationDispatcherService_1.ORGANIZATION_NOTIFICATION_CATEGORY_BY_TARGET[target];
+        const isTenantWide = target === CoreUserNotificationTarget.ORGANIZATION;
+        if (!category && !isTenantWide)
+            return undefined;
+        const organizationId = executionContext?.initiatorIds?.organizationId;
+        if (!organizationId)
+            return undefined;
+        let settings;
+        try {
+            const repository = this.repositoriesRegistry.getRepository(CoreResourceType.ORGANIZATION_NOTIFICATIONS);
+            if (!repository)
+                return undefined;
+            const record = await repository.read({ operation: { resourceIdentifier: CoreResourceType.ORGANIZATION_NOTIFICATIONS, operationIdentifier: 'read' } }, { organizationId }, { excludeContextualFilter: true });
+            settings = record?.emailNotifications;
+        }
+        catch {
+            this.logDebug('Failed to read organization notification settings; falling back to member fan-out', {
+                identifier: notification.identifier,
+                organizationId,
+            });
+            return undefined;
+        }
+        if (!settings)
+            return undefined;
+        // The switch is a suppression and applies whether or not an address is configured: a tenant
+        // that turns billing notifications off means it for the members too, not only for the address.
+        if (category && settings[category] === false) {
+            return { suppressed: true, category };
+        }
+        const categoryAddress = category
+            ? settings[`${category}Address`]
+            : undefined;
+        const address = (typeof categoryAddress === 'string' && categoryAddress.trim())
+            || (typeof settings.defaultEmailAddress === 'string' && settings.defaultEmailAddress.trim())
+            || undefined;
+        return { address: address || undefined, suppressed: false, category };
+    }
+    /**
+     * Send one organization-routed email to the tenant's configured address (#410).
+     *
+     * Deliberately NOT reusing `dispatchEmailToRecipientAddress`: that path exists for an address
+     * read off the operation's own object — an invitee who has no account — and its logging and its
+     * `userId: ''` sentinel both say so. This recipient is a tenant's own routing address, a
+     * different thing with a different reason for having no user, and collapsing them would make the
+     * logs unable to answer which kind of send happened.
+     */
+    async dispatchEmailToOrganizationAddress(executionContext, functionParameters, notification, recipientEmail, category, emailSubmissionSourceId) {
+        const { templateRef, locale, baseContext } = await this.buildEmailNotificationContext(executionContext, functionParameters, notification);
+        try {
+            const result = await this.emailService.send({
+                ...(emailSubmissionSourceId && {
+                    submissionId: deriveEmailNotificationSubmissionId(emailSubmissionSourceId, notification.identifier, templateRef, { email: recipientEmail }),
+                }),
+                templateRef,
+                locale,
+                type: EmailTemplateType.TRANSACTIONAL,
+                to: recipientEmail,
+                context: {
+                    ...baseContext,
+                    // A routing address belongs to the TENANT, not to a person: `userId: ''` is the same
+                    // "no platform user" sentinel the by-address path uses, for a different reason.
+                    userContext: { userId: '', email: recipientEmail },
+                },
+            });
+            this.logDebug('Organization-routed notification sent', {
+                identifier: notification.identifier,
+                category,
+                success: result.success,
+                submissionId: result.submissionId,
+                outcome: result.outcome,
+            });
+            return [result];
+        }
+        catch (error) {
+            this.logger.warn('Failed to send organization-routed notification', {
+                identifier: notification.identifier,
+                category,
+                ...projectCaughtErrorLogFields(error),
+            });
+            return [];
+        }
+    }
     async dispatchEmailToRecipientAddress(executionContext, functionParameters, notification, recipientEmailField, emailSubmissionSourceId) {
         const operation = executionContext.operation;
         const currentObject = functionParameters.currentObject;
@@ -832,6 +1017,17 @@ let NotificationDispatcherService = class NotificationDispatcherService {
                 if (!recipientUserContext?.email) {
                     continue;
                 }
+                // Same gate as the direct loop above. Both exist because the dispatcher splits on list size,
+                // and a suppression applied to only one of them would depend on how many recipients an
+                // operation happened to have.
+                if (!this.recipientAcceptsNotificationChannel(notification, recipientUserContext)) {
+                    this.logDebug('Skipping user notification in batch: recipient switched this channel off', {
+                        userId,
+                        identifier: notification.identifier,
+                        channel: notification.channel,
+                    });
+                    continue;
+                }
                 emailItems.push({
                     submissionId: emailSubmissionSourceId
                         ? deriveEmailNotificationSubmissionId(emailSubmissionSourceId, notification.identifier, templateRef, { userId })
@@ -960,12 +1156,112 @@ let NotificationDispatcherService = class NotificationDispatcherService {
             case CoreUserNotificationTarget.ORGANIZATION_ADMINISTRATIVE:
             case CoreUserNotificationTarget.ORGANIZATION_SECURITY:
                 return this.getOrganizationRecipientUserIds(executionContext, initiatorIds?.organizationId, this.mapOrganizationTargetToRoles(target, notification));
+            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:
+                /*
+                 * Resolved since #507. Seventeen shipped engine notifications target APPLICATION_ADMINISTRATOR
+                 * on the EMAIL channel — application API-key lifecycle, OAuth-client lifecycle and user events —
+                 * and every one of them used to fall into `default:`, resolve nobody, and send nothing. None
+                 * declares `recipientEmailField`, so none escaped through the by-address path.
+                 *
+                 * It went unnoticed because the WEBSOCKET branch for these same targets always worked
+                 * (`mapApplicationTargetToRoles` + `sendToAppRole`), so an administrator watching a dashboard
+                 * saw the events live and the feature appeared to work. Only the email half was dead.
+                 */
+                return this.getApplicationRecipientUserIds(executionContext, this.mapApplicationTargetToRoles(target, notification));
+            case CoreUserNotificationTarget.INBOUND_CONTACT:
+                /*
+                 * Resolves NO user, deliberately and not by omission. An inbound contact is a person who is not
+                 * a user of this application — the notification reaches them through `recipientEmailField`, the
+                 * by-address path, which never calls this method. Returning `[]` here is the correct answer and
+                 * is stated as its own case so it is not mistaken for the defect above.
+                 */
+                return [];
             default:
-                // Other targets (role-based, application-level) would also need user ID lookup
-                this.logDebug('Target requires user ID lookup', { target });
+                /*
+                 * Every member of the vocabulary now has an explicit answer, so reaching here means a target was
+                 * ADDED and nobody decided what it resolves to.
+                 *
+                 * This is a WARN and not a debug line, which is the second half of #507's fix. The defect above
+                 * survived because a `default:` arm silently returned no recipients for seven enum members while
+                 * logging at debug — a channel `AbstractControllerBackendService` disables — so the dispatcher
+                 * reported success and delivered nothing. A target the dispatcher cannot serve has to say so
+                 * where somebody reads it.
+                 */
+                this.logger.warn('Notification target resolves no recipients: the dispatcher has no rule for it', {
+                    target,
+                    identifier: notification.identifier,
+                    channel: notification.channel,
+                });
                 return [];
         }
     }
+    /**
+     * The users an APPLICATION-level notification is addressed to: holders of the target's app roles.
+     *
+     * The app-level counterpart of {@link getOrganizationRecipientUserIds}, and it mirrors that method
+     * deliberately — same sub-call context, same initiator exclusion, same "no repository means no
+     * recipients" posture — so the two halves of one feature cannot drift into behaving differently.
+     *
+     * ## Tenancy: there is no tenant to cross
+     *
+     * These recipients are application-level administrators rather than members of the tenant whose row
+     * triggered the event, so the question "does this leak one tenant's data to another" has to be
+     * answered rather than assumed. It is answered by the population: all 17 notifications sit on
+     * APPLICATION-scoped resources (`users`, application API keys, application OAuth clients), and
+     * `resolveOrganizationName` — the only place a tenant's name enters an email context — returns
+     * `undefined` unless the operation's `resourcePrimaryScope` is `ORGANIZATIONS`. So no tenant name
+     * reaches these bodies, by construction rather than by care.
+     *
+     * That is a property of the CURRENT population, not a guarantee about future ones. An
+     * ORGANIZATIONS-scoped operation that adds an `APPLICATION_*` notification would put a tenant's data
+     * in front of a non-member, and this is the comment that should stop it.
+     *
+     * ## Why the query filters rather than listing everyone
+     *
+     * `appRoles` is `.isDBIndexed()`, and the same `$in` shape is what the super-administrator floor uses
+     * to count administrators. The organization path can afford to filter roles in memory because its
+     * population is one tenant's roster; the application population is every user of the application.
+     */
+    async getApplicationRecipientUserIds(executionContext, appRoles) {
+        if (appRoles.length === 0) {
+            return [];
+        }
+        const usersRepository = this.repositoriesRegistry.getRepository(CoreResourceType.USERS);
+        if (!usersRepository) {
+            // WARN rather than debug: this is the shape that hid #507 for the life of the target.
+            this.logger.warn('No users repository available for application-level notification targeting', {
+                appRoles,
+            });
+            return [];
+        }
+        // Same reasoning as the organization roster read: this runs during dispatch for a notification
+        // attached to ANY resource operation, so the caller's context is keyed to that resource and its
+        // contextual filter is fail-closed on a field USERS does not model.
+        const recipientReadContext = this.executionContextCreator
+            ? await this.executionContextCreator.createForSubCall(executionContext, CoreResourceType.USERS, CoreResourceOperation.LIST)
+            : executionContext;
+        const candidates = await usersRepository.list(recipientReadContext, {
+            appRoles: { $in: [...appRoles] },
+            // ACTIVE only. A suspended or pending administrator is not someone to notify, and the
+            // retention hide at the repository chokepoint already keeps erased-but-retained rows out —
+            // which matters here because `appRoles` is `.isAuditEvidence()` and survives the scrub, so a
+            // retained row would otherwise still match a role filter.
+            status: UserStatus.ACTIVE,
+        });
+        const initiatorUserId = executionContext.initiatorIds?.userId;
+        return Array.from(new Set((Array.isArray(candidates) ? candidates : [])
+            .map((candidate) => candidate?._id)
+            .filter((userId) => typeof userId === 'string' && userId.length > 0)
+            // Mirrors the organization path: the administrator who rotated the key does not need an email
+            // telling them they rotated it.
+            .filter((userId) => userId !== initiatorUserId)));
+    }
     /**
      * Resolve the per-recipient context consumed by every greeting surface (email
      * subject/body, the `initiatorName` personalization, batch/direct sends).
@@ -987,6 +1283,50 @@ let NotificationDispatcherService = class NotificationDispatcherService {
      * as `displayName`; `firstName` is the informal variant with the same email
      * floor.
      */
+    /**
+     * Whether this notification may be sent to THIS recipient on THIS channel, given the recipient's
+     * own channel switches (#409).
+     *
+     * Until 2026-09-08 `UserPreferences.notifications` was stored, editable on the self-preferences
+     * screen, classified as personal data, subject-exported and reset on erasure — and read by
+     * nothing. A person who turned email off still received email.
+     *
+     * ONE predicate rather than a check at each of the three send loops, because that is the shape
+     * this repository's own rule asks for: an invariant applied at some of its call sites is the
+     * defect it keeps recording. The loops call this; nothing else decides.
+     *
+     * Three ways a message is delivered regardless, each for a different reason:
+     *   - the target is ROLE-addressed (see `userNotificationTargetIsSuppressibleByRecipientPreference`)
+     *     — the recipient did not choose to receive it as a person;
+     *   - the notification declares `alwaysDeliver` — a security notice a compromised account's owner
+     *     must still receive;
+     *   - the channel has no switch, or the recipient has no preferences row at all. A missing record
+     *     must never read as "everything off": preferences are created lazily, so a user who has never
+     *     opened the settings screen would otherwise silently stop receiving everything.
+     */
+    recipientAcceptsNotificationChannel(notification, recipientUserContext) {
+        if (notification.alwaysDeliver === true)
+            return true;
+        if (!userNotificationTargetIsSuppressibleByRecipientPreference(notification.target))
+            return true;
+        const preferences = recipientUserContext?.notificationChannelPreferences;
+        if (!preferences)
+            return true;
+        switch (notification.channel) {
+            case CoreUserNotificationChannel.EMAIL:
+                return preferences.email !== false;
+            case CoreUserNotificationChannel.SMS:
+                return preferences.sms !== false;
+            case CoreUserNotificationChannel.PUSH:
+                return preferences.push !== false;
+            default:
+                // WEBSOCKET and FRONT_END_SUCCESS carry no switch of their own. The `inApp` preference
+                // governs the notification CENTRE, which is a frontend surface — `NotificationContext`
+                // honours it there, because suppressing the socket frame would also suppress the live
+                // UI updates that ride the same channel.
+                return true;
+        }
+    }
     async fetchUserContext(userId) {
         try {
             const userRepository = this.repositoriesRegistry.getRepository(CoreResourceType.USERS);
@@ -1023,6 +1363,10 @@ let NotificationDispatcherService = class NotificationDispatcherService {
                 name: displayName,
                 firstName,
                 preferredLanguage,
+                // The recipient's own channel switches (#409). Costs NOTHING extra: the preferences record
+                // is already read above for the locale, and only its language fields were being consumed —
+                // which is precisely why a user who turned email off kept receiving email.
+                notificationChannelPreferences: preferences?.notifications,
                 userId,
             };
         }
@@ -1628,15 +1972,27 @@ let NotificationDispatcherService = class NotificationDispatcherService {
         }
     }
     mapOrganizationTargetToRoles(target, notification) {
-        if (notification.userRoles && notification.userRoles.length > 0) {
-            return notification.userRoles;
-        }
+        /*
+         * The override is consulted ONLY for a target that reads it (#495).
+         *
+         * This short-circuit used to run FIRST, before the switch — so `userRoles` on `ORGANIZATION` or
+         * `ORGANIZATION_USERS` narrowed the recipients resolved here, while the websocket branch for those
+         * same two targets calls `sendToOrganization` and never reads it. One declaration, two behaviours,
+         * decided by which channel the notification happened to use, with no diagnostic either way.
+         *
+         * Those two targets mean EVERYONE in the tenant by definition, so the empty list below is the
+         * answer on both channels and the override has no business changing it. `userNotificationTargetReadsUserRoles`
+         * is the same predicate the schema refuses on, so a declaration that reaches here can only be one
+         * the vocabulary admits.
+         */
         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];
+                return notification.userRoles && notification.userRoles.length > 0
+                    ? notification.userRoles
+                    : [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN];
             case CoreUserNotificationTarget.ORGANIZATION:
             case CoreUserNotificationTarget.ORGANIZATION_USERS:
             default:
@@ -1751,45 +2107,20 @@ let NotificationDispatcherService = class NotificationDispatcherService {
     /**
      * Extract scopes from context resource identifiers for scope room notifications
      */
+    /**
+     * Which scope rooms this mutation's rows belong to.
+     *
+     * Delegates to `deriveResourceScopeRoomQualifiers` in `@wildo-ai/saas-models`, which is where the
+     * rule now lives so that a CLIENT caching a read can subscribe to exactly the rooms this emits
+     * into. Two copies of this rule would agree only until one side gained a case, and the failure
+     * would be silent — a client subscribed to the wrong room does not error, it simply never hears
+     * that its cache is stale.
+     */
     extractScopesFromContext(contextResourceIdentifiers, primaryScope) {
-        const scopes = [];
-        const seenScopes = new Set();
-        const pushScope = (scopeKey, scopeId) => {
-            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;
+        return deriveResourceScopeRoomQualifiers(contextResourceIdentifiers, primaryScope);
     }
 };
-NotificationDispatcherService = __decorate([
+NotificationDispatcherService = NotificationDispatcherService_1 = __decorate([
     injectable(),
     __param(0, inject(SAAS_SERVICE_TYPES.Logger)),
     __param(1, inject(SAAS_SERVICE_TYPES.ErrorBuilderService)),