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

package/dist/esm/runtime/services/health-readiness-contributor.backend.interface.d.ts

@@ -1,9 +1,60 @@
+/**
+ * The health of ONE readiness dependency, as a process's own contributor reports it.
+ *
+ * `connecting` is deliberately distinct from `unhealthy`: it maps to a `degraded` overall status,
+ * which is still a READY outcome. A dependency that is coming up must not evict the process from
+ * its load balancer.
+ */
 export interface ReadinessDependencyHealth {
     status: 'healthy' | 'unhealthy' | 'connecting';
     latency?: number;
+    /**
+     * Why it is unhealthy, for the OPERATOR — this reaches the WARN log stream and nothing else.
+     * `/health/ready` is typically unauthenticated, so error text (which routinely carries hostnames,
+     * ports and credential paths) is deliberately never put on the response (#498).
+     */
     error?: string;
     details?: Record<string, unknown>;
 }
+/**
+ * A process's own readiness dependency, contributed to `/health/ready`.
+ *
+ * ## The seam, and how a process opens it
+ *
+ * `HealthControllerBackendService` checks four components: MongoDB (only when this runtime has
+ * one), the application configuration, the configured file storage, and — through this interface —
+ * ONE dependency the engine cannot know about. Redis is the canonical example of why the seam
+ * exists rather than a fifth hard-coded check: backend and companion startup both allow an
+ * in-memory fallback, so Redis must not be a universal gate; a process that genuinely CANNOT serve
+ * without it says so here instead.
+ *
+ * A process opens the seam from its own container, which already extends the engine's — this is
+ * exactly how `platform-module-registry` binds its `StorageCredentialResolver`:
+ *
+ * ```ts
+ * c.bind(SAAS_SERVICE_TYPES.HealthReadinessContributorService)
+ *   .to(MyProcessReadinessContributor)
+ *   .inSingletonScope();
+ * ```
+ *
+ * The injection point is `@optional()`, so a process that binds nothing keeps the previous
+ * behaviour exactly: the component reports healthy and never appears in `failing`.
+ *
+ * ## `getComponentName` is a PUBLISHED name, not a log label
+ *
+ * Since #498 it keys this component in the readiness response's `components` map and is the string
+ * that appears in `failing`. So it is what an operator reads on a 503, and what an e2e lane asserts
+ * on. Name the DEPENDENCY (`redis`, `searchIndex`, `licenceServer`), not the check.
+ *
+ * ## `checkReadiness` is called on EVERY probe
+ *
+ * Roughly every two seconds, per process. It is bounded at 5 s by the controller — a check that
+ * never settles is reported as unhealthy rather than hanging the probe — but it must be cheap:
+ * a ping, a cached connection state, a pool statistic. Never a query that does work.
+ *
+ * Throwing is a supported outcome and is reported as unhealthy with the thrown message; the
+ * contributor does not need its own try/catch.
+ */
 export interface HealthReadinessContributorBackendService {
     getComponentName(): string;
     checkReadiness(): Promise<ReadinessDependencyHealth>;

package/dist/esm/runtime/services/health-readiness-contributor.backend.interface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"health-readiness-contributor.backend.interface.d.ts","sourceRoot":"","sources":["../../../../../src/runtime/services/health-readiness-contributor.backend.interface.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,YAAY,CAAC;IAC/C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,wCAAwC;IACvD,gBAAgB,IAAI,MAAM,CAAC;IAC3B,cAAc,IAAI,OAAO,CAAC,yBAAyB,CAAC,CAAC;CACtD"}
+{"version":3,"file":"health-readiness-contributor.backend.interface.d.ts","sourceRoot":"","sources":["../../../../../src/runtime/services/health-readiness-contributor.backend.interface.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,YAAY,CAAC;IAC/C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,MAAM,WAAW,wCAAwC;IACvD,gBAAgB,IAAI,MAAM,CAAC;IAC3B,cAAc,IAAI,OAAO,CAAC,yBAAyB,CAAC,CAAC;CACtD"}

package/dist/esm/runtime/services/health-readiness-contributor.backend.interface.js.map

@@ -1 +1 @@
-{"version":3,"file":"health-readiness-contributor.backend.interface.js","sourceRoot":"","sources":["../../../../../src/runtime/services/health-readiness-contributor.backend.interface.ts"],"names":[],"mappings":"","sourcesContent":["export interface ReadinessDependencyHealth {\n  status: 'healthy' | 'unhealthy' | 'connecting';\n  latency?: number;\n  error?: string;\n  details?: Record<string, unknown>;\n}\n\nexport interface HealthReadinessContributorBackendService {\n  getComponentName(): string;\n  checkReadiness(): Promise<ReadinessDependencyHealth>;\n}\n"]}
+{"version":3,"file":"health-readiness-contributor.backend.interface.js","sourceRoot":"","sources":["../../../../../src/runtime/services/health-readiness-contributor.backend.interface.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * The health of ONE readiness dependency, as a process's own contributor reports it.\n *\n * `connecting` is deliberately distinct from `unhealthy`: it maps to a `degraded` overall status,\n * which is still a READY outcome. A dependency that is coming up must not evict the process from\n * its load balancer.\n */\nexport interface ReadinessDependencyHealth {\n  status: 'healthy' | 'unhealthy' | 'connecting';\n  latency?: number;\n  /**\n   * Why it is unhealthy, for the OPERATOR — this reaches the WARN log stream and nothing else.\n   * `/health/ready` is typically unauthenticated, so error text (which routinely carries hostnames,\n   * ports and credential paths) is deliberately never put on the response (#498).\n   */\n  error?: string;\n  details?: Record<string, unknown>;\n}\n\n/**\n * A process's own readiness dependency, contributed to `/health/ready`.\n *\n * ## The seam, and how a process opens it\n *\n * `HealthControllerBackendService` checks four components: MongoDB (only when this runtime has\n * one), the application configuration, the configured file storage, and — through this interface —\n * ONE dependency the engine cannot know about. Redis is the canonical example of why the seam\n * exists rather than a fifth hard-coded check: backend and companion startup both allow an\n * in-memory fallback, so Redis must not be a universal gate; a process that genuinely CANNOT serve\n * without it says so here instead.\n *\n * A process opens the seam from its own container, which already extends the engine's — this is\n * exactly how `platform-module-registry` binds its `StorageCredentialResolver`:\n *\n * ```ts\n * c.bind(SAAS_SERVICE_TYPES.HealthReadinessContributorService)\n *   .to(MyProcessReadinessContributor)\n *   .inSingletonScope();\n * ```\n *\n * The injection point is `@optional()`, so a process that binds nothing keeps the previous\n * behaviour exactly: the component reports healthy and never appears in `failing`.\n *\n * ## `getComponentName` is a PUBLISHED name, not a log label\n *\n * Since #498 it keys this component in the readiness response's `components` map and is the string\n * that appears in `failing`. So it is what an operator reads on a 503, and what an e2e lane asserts\n * on. Name the DEPENDENCY (`redis`, `searchIndex`, `licenceServer`), not the check.\n *\n * ## `checkReadiness` is called on EVERY probe\n *\n * Roughly every two seconds, per process. It is bounded at 5 s by the controller — a check that\n * never settles is reported as unhealthy rather than hanging the probe — but it must be cheap:\n * a ping, a cached connection state, a pool statistic. Never a query that does work.\n *\n * Throwing is a supported outcome and is reported as unhealthy with the thrown message; the\n * contributor does not need its own try/catch.\n */\nexport interface HealthReadinessContributorBackendService {\n  getComponentName(): string;\n  checkReadiness(): Promise<ReadinessDependencyHealth>;\n}\n"]}

package/dist/esm/runtime/services/http-server.backend.service.d.ts

@@ -30,6 +30,25 @@ import { RedisService } from '../../databases/services/redis.service';
  * - RuntimeConfigurationSchema (HTTP server specific settings)
  * - Environment variables (PORT, HOST overrides)
  */
+/**
+ * How long the perimeter limiter stays in its in-memory fallback before the degradation
+ * signal is REPEATED (the first request of any outage always signals immediately).
+ *
+ * Deliberately a fixed wall-clock interval and NOT derived from the configured
+ * `rateLimiting.windowMs`: the signal is about the shared counter's OUTAGE, not about the
+ * rate-limit window, and an application authoring an hour-long window would otherwise hide
+ * an hour of degradation behind a single line. One minute keeps a sustained outage legible
+ * to a human tailing logs while staying far away from one line per request.
+ */
+export declare const SHARED_RATE_LIMIT_COUNTER_DEGRADATION_SIGNAL_INTERVAL_MS: number;
+/**
+ * Stable, greppable identifiers stamped into the `degradation` log field so an operator (or
+ * a log-search alert) can select these two lines without matching on prose. Exported so the
+ * pinning test asserts the SAME identifier the runtime emits rather than a copied literal —
+ * a second copy of a machine-readable code is a second authority that silently drifts.
+ */
+export declare const PERIMETER_RATE_LIMIT_DEGRADED_SIGNAL: string;
+export declare const PERIMETER_RATE_LIMIT_RECOVERED_SIGNAL: string;
 /**
  * Options for HTTP server initialization
  */
@@ -161,6 +180,13 @@ export declare class HttpServerBackendService {
      *
      * M17: Uses Redis-backed atomic INCR+EXPIRE for distributed rate limiting.
      * Falls back to in-memory Map when Redis is unavailable (single-instance dev mode).
+     *
+     * Entering and leaving that fallback are both SIGNALLED (debounced `warn` lines carrying
+     * `degradation: PERIMETER_RATE_LIMIT_{DEGRADED,RECOVERED}_SIGNAL`) — see the long comment
+     * beside the signal state below for the destination, level and debounce reasoning. The
+     * fallback silently converted a deployment-wide ceiling into a per-replica one, and the
+     * one-time boot line at the end of this method cannot tell an operator whether it is in
+     * effect right now.
      */
     private setupRateLimit;
     /**

package/dist/esm/runtime/services/http-server.backend.service.d.ts.map

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

package/dist/esm/runtime/services/http-server.backend.service.js

@@ -25,6 +25,7 @@ import { CustomControllerMountPhase, } from '../../base-classes/services/control
 import { ErrorBuilderBackendService } from '../../errors/services/error-builder.backend.service.js';
 import { ErrorHandlerService } from '../../errors/services/error-handler.backend.service.js';
 import { relaxAbuseThrottleMaxForEnvironment } from '../../errors/utils/rate-limit-environment-relaxation.backend.utils.js';
+import { projectCaughtErrorLogFields } from '../../errors/utils/error-log-level-classification.backend.utils.js';
 import { applyOAuthBodyCap } from '../../runtime/services/utils/oauth-body-cap.backend.utils.js';
 import { RuntimeConfigurationSchema } from '../../runtime/models/runtime.backend.schemas.js';
 import { ClientInstanceIdScope, ErrorSeverity, ErrorType, ErrorCustomMessageReference, isAppConfigurationNotInitializedError, WildoHeaderKeys, ENGINE_ROOT_ROUTES, EngineRootRouteKey, MAIN_API_BASE_PATH, MANUAL_CONTROLLER_ROUTES_URLS, ManualControllerRouteKey, rfc8414AuthorizationServerMetadataPath, rfc9728ProtectedResourceMetadataPath, ResourceSerializationUtils } from '@wildo-ai/saas-models';
@@ -33,6 +34,46 @@ import { HealthControllerBackendService } from '../../runtime/controllers/health
 import { RedisService } from '../../databases/services/redis.service.js';
 import { AuthControllerUtils } from '../../security/authentications/services/utils/auth-controller.utils.js';
 import { runWithRequestContext, buildRequestContextFrame, setClientInstanceIdIngestPolicy } from '../../runtime/models/request-context.als.backend.js';
+/**
+ * HTTP Server Backend Service
+ *
+ * Orchestrates the Express HTTP server startup with complete configuration
+ * management, middleware setup, and route registration.
+ *
+ * Features:
+ * - Express server with configurable middleware stack
+ * - CORS, security headers, compression, rate limiting
+ * - Integration with ControllersRegistryHandlerBackendService
+ * - Support for additional custom controllers
+ * - Configuration-driven server setup
+ * - Graceful shutdown handling
+ * - Health check endpoints
+ * - Request logging and error handling
+ *
+ * Configuration Sources:
+ * - AppConfigurationService (platform + admin managed config)
+ * - RuntimeConfigurationSchema (HTTP server specific settings)
+ * - Environment variables (PORT, HOST overrides)
+ */
+/**
+ * How long the perimeter limiter stays in its in-memory fallback before the degradation
+ * signal is REPEATED (the first request of any outage always signals immediately).
+ *
+ * Deliberately a fixed wall-clock interval and NOT derived from the configured
+ * `rateLimiting.windowMs`: the signal is about the shared counter's OUTAGE, not about the
+ * rate-limit window, and an application authoring an hour-long window would otherwise hide
+ * an hour of degradation behind a single line. One minute keeps a sustained outage legible
+ * to a human tailing logs while staying far away from one line per request.
+ */
+export const SHARED_RATE_LIMIT_COUNTER_DEGRADATION_SIGNAL_INTERVAL_MS = 60_000;
+/**
+ * Stable, greppable identifiers stamped into the `degradation` log field so an operator (or
+ * a log-search alert) can select these two lines without matching on prose. Exported so the
+ * pinning test asserts the SAME identifier the runtime emits rather than a copied literal —
+ * a second copy of a machine-readable code is a second authority that silently drifts.
+ */
+export const PERIMETER_RATE_LIMIT_DEGRADED_SIGNAL = 'perimeter_rate_limit_shared_counter_unavailable';
+export const PERIMETER_RATE_LIMIT_RECOVERED_SIGNAL = 'perimeter_rate_limit_shared_counter_recovered';
 let HttpServerBackendService = class HttpServerBackendService {
     logger;
     appConfigService;
@@ -577,6 +618,13 @@ let HttpServerBackendService = class HttpServerBackendService {
      *
      * M17: Uses Redis-backed atomic INCR+EXPIRE for distributed rate limiting.
      * Falls back to in-memory Map when Redis is unavailable (single-instance dev mode).
+     *
+     * Entering and leaving that fallback are both SIGNALLED (debounced `warn` lines carrying
+     * `degradation: PERIMETER_RATE_LIMIT_{DEGRADED,RECOVERED}_SIGNAL`) — see the long comment
+     * beside the signal state below for the destination, level and debounce reasoning. The
+     * fallback silently converted a deployment-wide ceiling into a per-replica one, and the
+     * one-time boot line at the end of this method cannot tell an operator whether it is in
+     * effect right now.
      */
     setupRateLimit(rateLimitConfig) {
         const windowSeconds = Math.ceil(rateLimitConfig.windowMs / 1000);
@@ -593,6 +641,127 @@ let HttpServerBackendService = class HttpServerBackendService {
         // client-integration-app) presents as `127.0.0.1` and shares one bucket, so the
         // authored per-client ceiling behaves as a per-MACHINE ceiling locally.
         const effectiveMaxRequests = relaxAbuseThrottleMaxForEnvironment(rateLimitConfig.maxRequests, this.appConfigService.applicationEnv);
+        // ---------------------------------------------------------------------------------
+        // Shared-counter degradation signal.
+        //
+        // The in-memory fallback below is DELIBERATE and stays. The perimeter limiter is a
+        // noisy-neighbour preventer, not the security boundary — that is the per-endpoint
+        // `RateLimitBackendService`, which fail-CLOSES and propagates `ErrorType.DATABASE`
+        // when the shared counter is unavailable (see its file docstring, which names this
+        // limiter as the deliberate fail-OPEN exception). So a Redis outage must not take the
+        // application off the air.
+        //
+        // What was missing is any way for an operator to learn that it engaged, and the
+        // consequence is not cosmetic: once every replica counts in its own process memory,
+        // an authored ceiling of N is enforced N × replicas times globally, and it resets on
+        // every restart. A deployment can therefore sit at several times its stated cap
+        // indefinitely with nothing anywhere to read.
+        //
+        // DESTINATION — the logger, and only the logger. It is the one channel that provably
+        //   works while the shared counter is down: pino writes to stdout and, through the
+        //   OTLP log bridge wired in `otel-preload`, on to the collector — with no dependency
+        //   on Redis, on a repository, or on any other service. Rejected:
+        //     · an audit/SIEM row — a persisted write on the perimeter hot path, requiring a
+        //       SECOND subsystem to be healthy for a signal whose whole premise is that a
+        //       subsystem is not; and this is an infrastructure diagnostic, not a
+        //       security-authority decision;
+        //     · a readiness contribution — readiness is a REFUSAL. Turning a fallback that
+        //       exists to keep serving into a 503 gets the process respawned by the
+        //       supervisor, which is strictly worse than the degradation it reports;
+        //     · `this.logDebug` — this service ships with `HttpServer` debug logging OFF, so
+        //       the signal would be invisible in exactly the deployments that need it.
+        //
+        // LEVEL — `warn` for BOTH the degradation and the recovery. The cap is still enforced,
+        //   only its scope narrowed, and a single-instance development stack with no Redis
+        //   legitimately runs here from its first request; an `error` on every dev boot is how
+        //   a channel stops being read. Recovery shares the level on purpose: emitting it any
+        //   lower would let a `warn` threshold show an operator the degradation and never its
+        //   end, which is worse than not signalling at all.
+        //
+        // DEBOUNCE — one line on the first fallback request of an outage, then at most one more
+        //   per `SHARED_RATE_LIMIT_COUNTER_DEGRADATION_SIGNAL_INTERVAL_MS`, each carrying how
+        //   many requests the fallback served since the previous line so the VOLUME stays
+        //   legible without a line per request. A new outage always signals immediately, even
+        //   if the previous outage's line is only seconds old — otherwise a flapping counter
+        //   would be reported once and then muted.
+        // ---------------------------------------------------------------------------------
+        let sharedCounterDegradedSince = null;
+        let degradationSignalLastEmittedAt = 0;
+        // Two counters, because the two lines answer different questions. The degradation line
+        // answers "how loud is this right now" (volume BETWEEN lines, so it resets on every
+        // emit); the recovery line answers "how much traffic was actually capped per replica"
+        // (the whole outage, so it resets only at the transitions).
+        let fallbackRequestsSinceLastSignal = 0;
+        let fallbackRequestsThisOutage = 0;
+        const noteSharedCounterUnavailable = (now, cause) => {
+            // Both count the CURRENT request, so the first line of an outage reports 1.
+            fallbackRequestsSinceLastSignal++;
+            fallbackRequestsThisOutage++;
+            const isFirstRequestOfThisOutage = sharedCounterDegradedSince === null;
+            if (isFirstRequestOfThisOutage) {
+                sharedCounterDegradedSince = now;
+            }
+            else if (now - degradationSignalLastEmittedAt < SHARED_RATE_LIMIT_COUNTER_DEGRADATION_SIGNAL_INTERVAL_MS) {
+                return;
+            }
+            // Debounce state is advanced BEFORE the emit, and the emit itself cannot throw out of
+            // here. Both halves matter and neither is defensive habit:
+            //  · this runs inside the limiter's own `try`, whose `catch` calls `next(error)` — so
+            //    a logger that throws (a closed stdout, an EPIPE on a detached process) would turn
+            //    every request into a 500 for the duration of a Redis outage. A diagnostic must
+            //    never be able to refuse the traffic it is describing;
+            //  · advancing the state first means a throwing logger degrades to SILENCE with the
+            //    debounce intact, rather than re-attempting the same throwing call on every
+            //    subsequent request.
+            const requestsCoveredByThisSignal = fallbackRequestsSinceLastSignal;
+            const degradedForMs = now - sharedCounterDegradedSince;
+            degradationSignalLastEmittedAt = now;
+            fallbackRequestsSinceLastSignal = 0;
+            try {
+                this.logger.warn('Perimeter rate limiting degraded to per-replica in-memory counting: the shared counter is unavailable, '
+                    + 'so the configured ceiling is enforced per process instead of across the deployment and resets on restart.', {
+                    degradation: PERIMETER_RATE_LIMIT_DEGRADED_SIGNAL,
+                    effectiveMaxRequests,
+                    windowMs: rateLimitConfig.windowMs,
+                    enforcementScope: 'per-replica-in-memory',
+                    degradedForMs,
+                    fallbackRequestsSinceLastSignal: requestsCoveredByThisSignal,
+                    nextSignalNotBeforeMs: SHARED_RATE_LIMIT_COUNTER_DEGRADATION_SIGNAL_INTERVAL_MS,
+                    ...projectCaughtErrorLogFields(cause),
+                });
+            }
+            catch {
+                // Nothing to escalate to: the logger IS the escalation channel.
+            }
+        };
+        const noteSharedCounterAvailable = (now) => {
+            // The happy path pays one null check per request; everything below runs once per
+            // recovery, at the transition only.
+            if (sharedCounterDegradedSince === null)
+                return;
+            // Same ordering and same guard as the degradation emit above, for the same two
+            // reasons: state first so a throwing logger cannot re-attempt on every later request,
+            // and no throw out of a diagnostic sitting on the request path.
+            const degradedForMs = now - sharedCounterDegradedSince;
+            const fallbackRequestsServedDuringOutage = fallbackRequestsThisOutage;
+            sharedCounterDegradedSince = null;
+            degradationSignalLastEmittedAt = 0;
+            fallbackRequestsSinceLastSignal = 0;
+            fallbackRequestsThisOutage = 0;
+            try {
+                this.logger.warn('Perimeter rate limiting recovered: the shared counter answered again, so the configured ceiling is '
+                    + 'once more enforced across the deployment.', {
+                    degradation: PERIMETER_RATE_LIMIT_RECOVERED_SIGNAL,
+                    effectiveMaxRequests,
+                    enforcementScope: 'shared-counter',
+                    degradedForMs,
+                    fallbackRequestsServedDuringOutage,
+                });
+            }
+            catch {
+                // Nothing to escalate to: the logger IS the escalation channel.
+            }
+        };
         const limiter = async (req, res, next) => {
             try {
                 const clientId = req.ip || 'unknown';
@@ -603,6 +772,11 @@ let HttpServerBackendService = class HttpServerBackendService {
                     // M17: Redis-backed rate limiting — works across multiple instances
                     const identifier = `http_rate_limit:${clientId}`;
                     count = await this.redisService.incrementRateLimit(identifier, windowSeconds);
+                    // The shared counter answered. If we were in the fallback, this is the recovery
+                    // transition — signalled here rather than after the TTL lookup below, because a
+                    // failing TTL degrades only the accuracy of `Retry-After`; the COUNTER, which is
+                    // what makes the cap deployment-wide, is demonstrably back.
+                    noteSharedCounterAvailable(now);
                     try {
                         const ttl = await this.redisService.getRateLimitTtl(identifier);
                         retryAfterSeconds = ttl >= 0 ? ttl : windowSeconds;
@@ -611,10 +785,16 @@ let HttpServerBackendService = class HttpServerBackendService {
                         retryAfterSeconds = windowSeconds;
                     }
                 }
-                catch {
+                catch (sharedCounterError) {
                     // Fallback to in-memory when Redis is unavailable.
                     // Mirrors Redis INCR+EXPIRE fixed-window: window starts on first request,
                     // resets after windowMs elapses (not a sliding window).
+                    //
+                    // The caught value is bound (this was a bare `catch {}`) so the degradation
+                    // signal can carry WHY the shared counter refused — a connection refusal, a
+                    // timeout and an auth failure need different operator responses, and without the
+                    // cause the line only says that something is wrong.
+                    noteSharedCounterUnavailable(now, sharedCounterError);
                     for (const [key, value] of fallbackRequests.entries()) {
                         if (now >= value.resetTime)
                             fallbackRequests.delete(key);