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

package/dist/esm/notifications/services/notification-badge.backend.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"notification-badge.backend.service.d.ts","sourceRoot":"","sources":["../../../../../src/notifications/services/notification-badge.backend.service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"notification-badge.backend.service.d.ts","sourceRoot":"","sources":["../../../../../src/notifications/services/notification-badge.backend.service.ts"],"names":[],"mappings":"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"}

package/dist/esm/notifications/services/notification-badge.backend.service.js

@@ -18,7 +18,7 @@ import { projectCaughtErrorLogFields } from '../../errors/utils/error-log-level-
 import { RepositoriesRegistryHandlerBackendService, } from '../../base-classes/services/repositories/repositories-registry-handler.backend.service.js';
 import { ResourcesRegistryBackendService } from '../../resources/services/resources-registry.backend.service.js';
 import { ExecutionContextCreatorBackendService } from '../../runtime/services/execution-context-creator.backend.service.js';
-import { ResourcePrimaryScope, NotificationBadgeOperation, NotificationBadgeSourceKind, CoreResourceType, CoreResourceOperation, CoreWebSocketEvent, } from '@wildo-ai/saas-models';
+import { ResourcePrimaryScope, NotificationBadgeOperation, NotificationBadgeSourceKind, CoreResourceType, CoreResourceOperation, buildNotificationBadgeReference, parseNotificationBadgeReference, CoreWebSocketEvent, } from '@wildo-ai/saas-models';
 import { WebSocketService } from '../../requests/service/websocket.service.js';
 /**
  * The derived-badge SOURCE count passes a fully explicit, self-scoped filter
@@ -29,6 +29,22 @@ import { WebSocketService } from '../../requests/service/websocket.service.js';
  * FK is injected/filtered correctly rather than bypassed.)
  */
 const EXPLICIT_SCOPE_REPO_OPTIONS = { excludeContextualFilter: true };
+/**
+ * How many times a RELATIVE badge write (increment / decrement) re-attempts its guarded statement
+ * before giving up and reporting the count it can observe.
+ *
+ * Two is what the mechanism needs and three is the margin. A first pass misses only when the badge
+ * row does not exist yet; the pass then materializes a ZERO row and the SECOND pass applies the
+ * delta to it. The only other way a pass can miss is the decrement's two-statement floor (see
+ * {@link NotificationBadgeBackendService.applyGuardedCountDelta}) losing a race in the window
+ * between its two statements — that is a genuine retry, and one spare pass is generous for a
+ * contention window measured in a single round trip.
+ *
+ * The loop terminates on its own budget rather than on a condition, because the exhaustion outcome
+ * is deliberately NOT a throw: a badge is a decoration, and failing a domain mutation because a
+ * counter could not be advanced would trade a cosmetic defect for a functional one.
+ */
+const RELATIVE_BADGE_WRITE_PASSES = 3;
 /**
  * NotificationBadgeBackendService
  *
@@ -91,10 +107,14 @@ let NotificationBadgeBackendService = class NotificationBadgeBackendService {
         });
     }
     /**
-     * Build a badge reference string
+     * Build a badge reference string.
+     *
+     * Delegates to the shared builder rather than re-templating the format: the browser reduces this
+     * exact string to a badge KEY on arrival, so the producer and the consumer must be reading one
+     * definition of where the parts are.
      */
     buildBadgeReference(scope, scopeId, identifier) {
-        return `${scope}:${scopeId}:${identifier}`;
+        return buildNotificationBadgeReference(scope, scopeId, identifier);
     }
     /**
      * Parse a badge reference string.
@@ -106,18 +126,7 @@ let NotificationBadgeBackendService = class NotificationBadgeBackendService {
      * to fail fast at parse time rather than later during dispatch.
      */
     parseBadgeReference(badgeReference) {
-        const parts = badgeReference.split(':');
-        if (parts.length !== 3)
-            return null;
-        const [scope, scopeId, identifier] = parts;
-        if (!this.isSupportedScope(scope)) {
-            return null;
-        }
-        return {
-            scope: scope,
-            scopeId,
-            identifier: identifier,
-        };
+        return parseNotificationBadgeReference(badgeReference);
     }
     /**
      * Get badge count for a specific identifier and scope
@@ -165,51 +174,73 @@ let NotificationBadgeBackendService = class NotificationBadgeBackendService {
         }
     }
     /**
-     * Execute a badge operation (increment, decrement, set, reset)
+     * Execute a badge operation (increment, decrement, set, reset).
+     *
+     * ## Two write shapes, because the vocabulary carries two kinds of change
+     *
+     * `SET` and `RESET` are ABSOLUTE: the value written does not depend on the value read, so a plain
+     * read-then-write is already correct — concurrent absolute writes are last-writer-wins, which is
+     * what "set it to N" means.
+     *
+     * `INCREMENT` and `DECREMENT` are RELATIVE, and that is where this method used to lose data. It
+     * read `count`, computed `count ± value` in JavaScript, and wrote the result back. Two operations
+     * committing concurrently both read the SAME previous value, so the second write overwrote the
+     * first and one increment vanished — with no error, no log, and a badge that is simply too low
+     * forever after (an EVENT_COUNTER badge is never re-derived; that is the whole distinction
+     * `NotificationBadgeSourceKind` draws, and it is why the drift is permanent here and self-healing
+     * on a DERIVED_QUERY badge).
+     *
+     * More checking cannot fix that — the two writers have nothing to collide on. So the relative arms
+     * now go through the adapter-neutral guarded mutation, where the STORE performs the arithmetic in
+     * one statement (`$inc` on MongoDB, `COALESCE(col, 0) + delta` on PostgreSQL) and the two writers
+     * collide on the row itself. See {@link applyRelativeCountChange}.
      */
     async executeBadgeOperation(executionContext, scope, scopeId, identifier, operation, value = 1) {
+        const resourceType = this.resolveResourceType(scope);
         const repository = this.resolveRepository(scope);
-        if (!repository) {
+        if (!resourceType || !repository) {
             throw this.errorBuilder.buildError('INTERNAL', executionContext, {
                 customMessageReference: 'NOTIFICATION_BADGES_REPOSITORY_NOT_FOUND',
                 context: { scope },
             });
         }
-        // Find existing badge
-        let badge = await this.findBadge(executionContext, scope, scopeId, identifier);
-        const previousCount = badge?.count ?? 0;
+        let previousCount;
         let newCount;
-        // Calculate new count based on operation
         switch (operation) {
             case NotificationBadgeOperation.INCREMENT:
-                newCount = previousCount + value;
-                break;
-            case NotificationBadgeOperation.DECREMENT:
-                newCount = Math.max(0, previousCount - value);
+            case NotificationBadgeOperation.DECREMENT: {
+                const delta = operation === NotificationBadgeOperation.INCREMENT ? value : -value;
+                ({ previousCount, newCount } = await this.applyRelativeCountChange(resourceType, scope, scopeId, identifier, delta));
                 break;
+            }
             case NotificationBadgeOperation.SET:
-                newCount = Math.max(0, value);
-                break;
-            case NotificationBadgeOperation.RESET:
-                newCount = 0;
+            case NotificationBadgeOperation.RESET: {
+                const absoluteCount = operation === NotificationBadgeOperation.SET ? Math.max(0, value) : 0;
+                ({ previousCount, newCount } = await this.writeAbsoluteCount(repository, scope, scopeId, identifier, absoluteCount));
                 break;
-            default:
+            }
+            default: {
+                /**
+                 * The vocabulary is closed, but the dispatcher reaches this method through
+                 * `badgeOp.operation as NotificationBadgeOperation` — an unchecked cast over an authored
+                 * string — so an unknown member can arrive at runtime.
+                 *
+                 * It now reads the count and writes NOTHING. The previous behaviour wrote `previousCount`
+                 * back over itself, which on an absent badge MATERIALIZED a zero row for an operation
+                 * nobody could name: a write performed because the switch had no other arm to fall into.
+                 * The event is still emitted below, so a client that asked for an unknown operation is
+                 * told the current value rather than left silent.
+                 */
+                previousCount = await this.getBadgeCount(executionContext, scope, scopeId, identifier);
                 newCount = previousCount;
-        }
-        // Update or create badge through a badge-resource-scoped EC (see
-        // buildBadgeExecutionContext) so context enrichment injects the scope FK
-        // (userId / organizationId) that the create DTO auto-excludes.
-        const badgeExecutionContext = await this.buildBadgeExecutionContext(scope, scopeId);
-        if (badge) {
-            await repository.update(badgeExecutionContext, badge._id, {
-                count: newCount,
-                updatedAt: new Date(),
-            });
-        }
-        else {
-            // Create new badge
-            const newBadge = this.buildNewBadge(scope, scopeId, identifier, newCount);
-            await repository.create(badgeExecutionContext, newBadge);
+                this.logger.warn('Unknown notification badge operation — reporting the current count without writing', {
+                    scope,
+                    scopeId,
+                    identifier,
+                    operation: String(operation),
+                });
+                break;
+            }
         }
         const badgeReference = this.buildBadgeReference(scope, scopeId, identifier);
         // Emit WebSocket event
@@ -226,6 +257,182 @@ let NotificationBadgeBackendService = class NotificationBadgeBackendService {
             newCount,
         };
     }
+    /**
+     * Apply a RELATIVE change (`+value` / `-value`) to a badge counter without ever reading it into
+     * JavaScript first.
+     *
+     * ## The shape, and why it is a loop rather than a straight line
+     *
+     * A guarded mutation only mutates a row that ALREADY EXISTS — it returns `null` when its filter
+     * matched nothing, and it cannot insert. A badge row, meanwhile, is materialized lazily on its
+     * first write. So the write is "apply the delta; if there was no row, materialize one at ZERO and
+     * apply the delta to that".
+     *
+     * **Materializing at ZERO rather than at the target is the load-bearing detail.** Creating the row
+     * already carrying `value` would mean two racing first-increments each insert a row holding `1`,
+     * and one of the two increments is lost exactly as before — the defect would simply have moved
+     * from the update to the insert. Creating at zero and then letting BOTH callers apply their own
+     * delta through the atomic statement keeps every increment: the store matches one row for both,
+     * and it ends at 2.
+     *
+     * ## The residual, stated rather than hidden
+     *
+     * Two racing materializations can still leave a DUPLICATE badge row, because nothing in the schema
+     * makes `(scopeId, identifier)` unique — `identifier` carries `.isSummaryField()` and no
+     * `.isUnique()`, so the store has no constraint to refuse the second insert with. That duplicate
+     * hazard is older than this method and is not what this change is about: it costs a stray row,
+     * whereas the read-modify-write cost a permanently wrong number. Closing it means a unique index,
+     * which is an engine resource change owing a migration in every PostgreSQL-backed surface
+     * (`.claude/rules/engine-resource-changes-owe-migrations.md`) and belongs with the badge-identity
+     * work, not here.
+     *
+     * @returns the count before and after, as observed from the row the store returned.
+     */
+    async applyRelativeCountChange(resourceType, scope, scopeId, identifier, delta) {
+        /**
+         * The identity of the ONE row this write may touch.
+         *
+         * Tenant scoping is preserved BY CONSTRUCTION rather than by the execution context: the guarded
+         * mutation is an infrastructure-tier door whose contract puts scope-aware filter construction on
+         * the caller, and the scope key (`userId` / `organizationId`) is right here in the filter, so
+         * the statement cannot reach another tenant's badge. That is the same posture the promotion
+         * redemption counter and the credit pool take.
+         */
+        const identityFilter = { ...this.buildScopeFilter(scope, scopeId), identifier };
+        for (let pass = 0; pass < RELATIVE_BADGE_WRITE_PASSES; pass += 1) {
+            const applied = await this.applyGuardedCountDelta(resourceType, identityFilter, delta);
+            if (applied) {
+                return applied;
+            }
+            /**
+             * Nothing matched. There are exactly two reasons, and they need opposite responses, so ask
+             * which one it is instead of assuming.
+             *
+             * - The badge row does not exist yet — materialize it and let the next pass apply the delta.
+             * - A DECREMENT lost the race between its two floor statements (see
+             *   {@link applyGuardedCountDelta}) — the row exists, and materializing would duplicate it.
+             *   Retry the pair instead.
+             *
+             * The read costs a round trip on a path taken once per badge lifetime (plus a genuinely rare
+             * contention window), which is why it is affordable here and would not be on the hot arm.
+             */
+            const existing = await this.findBadgeByIdentity(scope, scopeId, identifier);
+            if (!existing) {
+                await this.materializeZeroBadge(scope, scopeId, identifier);
+            }
+        }
+        /**
+         * Every pass lost its race. Report what the row currently holds and write nothing further: a
+         * badge is a decoration, and the caller is a domain mutation that has already committed, so
+         * throwing here would turn a cosmetic loss into a failed user action. The warning is what makes
+         * the loss visible — silence is what let the original read-modify-write defect live.
+         */
+        const current = await this.findBadgeByIdentity(scope, scopeId, identifier);
+        const currentCount = current?.count ?? 0;
+        this.logger.warn('Notification badge counter change was dropped after exhausting its atomic write passes', {
+            scope,
+            scopeId,
+            identifier,
+            delta,
+            currentCount,
+            passes: RELATIVE_BADGE_WRITE_PASSES,
+        });
+        return { previousCount: currentCount, newCount: currentCount };
+    }
+    /**
+     * ONE attempt at the atomic delta. Returns the before/after counts, or `null` when no row matched.
+     *
+     * ## The decrement floor lives in the FILTER, not in `Math.max`
+     *
+     * `Math.max(0, previousCount - value)` computes the floor from a value read moments earlier, which
+     * is the very read this change exists to remove. The floor is therefore expressed as a GUARD the
+     * store evaluates in the same statement as the write — `count: { $gte: magnitude }` — which is the
+     * idiom the promotion redemption counter uses for its `maxRedemptions` ceiling.
+     *
+     * That guard alone would REFUSE a decrement that cannot be taken in full, where the previous
+     * behaviour CLAMPED it to zero. Preserving the clamp needs a second statement, because neither
+     * adapter's neutral vocabulary can express "subtract, floored at zero" in one (there is no `$max`
+     * in `RepositoryGuardedMutation`, deliberately — an operator no adapter pair can honour identically
+     * does not get a name there). So a below-floor row is set to zero by a SECOND guarded statement,
+     * itself conditioned on the row still being below the floor. Each statement is atomic, and the
+     * pair is safe in every interleaving:
+     *
+     * - first matched → the count fell by exactly `magnitude`;
+     * - first missed, second matched → the count was below the floor at the moment of the write and is
+     *   now zero, which is what `Math.max(0, count - value)` meant for that count;
+     * - both missed → either no row, or a concurrent INCREMENT crossed the floor between the two
+     *   statements. The caller distinguishes those and retries rather than concluding.
+     *
+     * ## `updatedAt` is deliberately absent from the descriptor
+     *
+     * Both adapters bump it themselves — mongoose's `timestamps` hook on one, an explicit
+     * planned-column assignment inside `prepareGuardedUpdate` on the other. Passing it here would be a
+     * second authority for the same field, and the two would disagree the day either arm changes.
+     */
+    async applyGuardedCountDelta(resourceType, identityFilter, delta) {
+        if (delta >= 0) {
+            const incremented = await this.repositoriesRegistry.atomicGuardedMutation(resourceType, identityFilter, { increment: { count: delta } });
+            if (!incremented)
+                return null;
+            return { previousCount: incremented.count - delta, newCount: incremented.count };
+        }
+        const magnitude = -delta;
+        const decremented = await this.repositoriesRegistry.atomicGuardedMutation(resourceType, { ...identityFilter, count: { $gte: magnitude } }, { increment: { count: delta } });
+        if (decremented) {
+            return { previousCount: decremented.count + magnitude, newCount: decremented.count };
+        }
+        const clamped = await this.repositoriesRegistry.atomicGuardedMutation(resourceType, { ...identityFilter, count: { $lt: magnitude } }, { set: { count: 0 } });
+        if (!clamped)
+            return null;
+        /**
+         * `previousCount` is reported as the post-write zero rather than as an estimate. The row's
+         * pre-write count was somewhere in `[0, magnitude)` and the statement that overwrote it cannot
+         * report the value it replaced — a guarded mutation returns the row AFTER the write on both
+         * adapters. Nothing reads this field (it exists on `BadgeUpdateResult` and is consumed only by
+         * this service's own debug line), and an invented number would be worse than a floor.
+         */
+        return { previousCount: clamped.count, newCount: clamped.count };
+    }
+    /**
+     * Insert the badge row at ZERO so a subsequent atomic delta has something to mutate.
+     *
+     * Goes through the SERVICE tier (`repository.create` with the badge-scoped execution context)
+     * rather than a raw insert, so the row is schema-validated and gets its scope FK injected by
+     * context enrichment at birth — see {@link buildBadgeExecutionContext} for why the triggering
+     * operation's own context cannot serve here.
+     */
+    async materializeZeroBadge(scope, scopeId, identifier) {
+        const repository = this.resolveRepository(scope);
+        if (!repository)
+            return;
+        const badgeExecutionContext = await this.buildBadgeExecutionContext(scope, scopeId);
+        await repository.create(badgeExecutionContext, this.buildNewBadge(scope, scopeId, identifier, 0));
+    }
+    /**
+     * Write an ABSOLUTE count (`SET` / `RESET`).
+     *
+     * The read here is NOT a read-modify-write: the value written is fixed by the caller, so a
+     * concurrent absolute write can only replace it wholesale, which is what an absolute write means.
+     * The read decides update-versus-insert and supplies the reported `previousCount`.
+     */
+    async writeAbsoluteCount(repository, scope, scopeId, identifier, absoluteCount) {
+        const badge = await this.findBadgeByIdentity(scope, scopeId, identifier);
+        const previousCount = badge?.count ?? 0;
+        // Update or create badge through a badge-resource-scoped EC (see
+        // buildBadgeExecutionContext) so context enrichment injects the scope FK
+        // (userId / organizationId) that the create DTO auto-excludes.
+        const badgeExecutionContext = await this.buildBadgeExecutionContext(scope, scopeId);
+        if (badge) {
+            await repository.update(badgeExecutionContext, badge._id, {
+                count: absoluteCount,
+                updatedAt: new Date(),
+            });
+        }
+        else {
+            await repository.create(badgeExecutionContext, this.buildNewBadge(scope, scopeId, identifier, absoluteCount));
+        }
+        return { previousCount, newCount: absoluteCount };
+    }
     /**
      * Increment a badge count
      */
@@ -347,9 +554,24 @@ let NotificationBadgeBackendService = class NotificationBadgeBackendService {
     // Private Helper Methods
     // ================================
     /**
-     * Find a badge by scope, scopeId, and identifier
+     * Find a badge by scope, scopeId, and identifier.
+     *
+     * `executionContext` is the CALLER's context and is deliberately not used for the read: a badge
+     * read runs on its own badge-resource-scoped context, exactly as a badge write does, because the
+     * triggering operation's context carries the wrong scope (see {@link buildBadgeExecutionContext}).
+     * The parameter is kept so the private read reads like every other method on this service.
+     */
+    findBadge(executionContext, scope, scopeId, identifier) {
+        return this.findBadgeByIdentity(scope, scopeId, identifier);
+    }
+    /**
+     * The badge read itself, addressed only by identity.
+     *
+     * Split out of {@link findBadge} because the atomic write path has no caller execution context to
+     * pass — it is reconciling its own guarded statements, not serving a request — and inventing one
+     * to satisfy a parameter the read never consults would be ceremony.
      */
-    async findBadge(executionContext, scope, scopeId, identifier) {
+    async findBadgeByIdentity(scope, scopeId, identifier) {
         const repository = this.resolveRepository(scope);
         if (!repository) {
             return null;
@@ -377,24 +599,27 @@ let NotificationBadgeBackendService = class NotificationBadgeBackendService {
      * resilient (per existing behavior).
      */
     resolveRepository(scope) {
+        const resourceType = this.resolveResourceType(scope);
+        return resourceType ? this.repositoriesRegistry.getRepository(resourceType) : undefined;
+    }
+    /**
+     * Resolve the RESOURCE TYPE backing a badge scope — the same polymorphism dispatch
+     * {@link resolveRepository} performs, named separately because the atomic write path addresses the
+     * registry by resource type rather than by repository handle.
+     *
+     * One switch, two consumers: a second copy of this mapping is how a future third scope reaches one
+     * of them and not the other.
+     */
+    resolveResourceType(scope) {
         switch (scope) {
             case ResourcePrimaryScope.USER_SELF:
-                return this.repositoriesRegistry.getRepository(CoreResourceType.USER_NOTIFICATION_BADGES);
+                return CoreResourceType.USER_NOTIFICATION_BADGES;
             case ResourcePrimaryScope.ORGANIZATIONS:
-                return this.repositoriesRegistry.getRepository(CoreResourceType.ORGANIZATION_NOTIFICATION_BADGES);
+                return CoreResourceType.ORGANIZATION_NOTIFICATION_BADGES;
             default:
                 return undefined;
         }
     }
-    /**
-     * Whether a string scope value is one of the supported badge scopes.
-     * Used by `parseBadgeReference` to reject APPLICATION-scoped references
-     * at parse time (the variant was dropped in the polymorphism refactor).
-     */
-    isSupportedScope(scope) {
-        return scope === ResourcePrimaryScope.USER_SELF
-            || scope === ResourcePrimaryScope.ORGANIZATIONS;
-    }
     /**
      * Build filter for scope-specific queries.
      *