@onlineapps/mq-client-core 5.1.0 → 6.0.0

package/src/transports/rabbitmqClient.js

@@ -16,6 +16,7 @@ const {
   AMQP_NOT_FOUND,
   AMQP_PRECONDITION_FAILED,
   TransientPublishError,
+  RecoveryEndedPublishError,
   PermanentPublishError,
   QueueNotFoundError,
   classifyPublishError,
@@ -32,7 +33,8 @@ const {
   CONNECTION_CLOSED_UNEXPECTEDLY,
   connectionClosedUnexpectedly,
   CONSUMER_QUEUE_MISSING,
-  CONSUMER_DEAD_LETTER_ROUTE_MISSING
+  CONSUMER_DEAD_LETTER_ROUTE_MISSING,
+  carryVerdict
 } = require('../utils/errorHandler');
 const { assertLogger } = require('@onlineapps/logger-contract');
 const PublishLayer = require('../layers/PublishLayer');
@@ -338,6 +340,10 @@ class RabbitMQClient extends EventEmitter {
     // the cycle cap is spent. From that point this client will not try again and
     // it must not report itself as connected.
     this._connectionFatal = false;
+    // The verdict itself — the error `_failFatally()` built, handed to `onFatal` and
+    // `connection:fatal`. Kept so that a later use of this client can carry THE SAME object
+    // as its `cause` (d.1281): one error, however many readers; never a copy.
+    this._connectionFatalError = null;
     // Injected by the owner of this client (service/wrapper). The LIBRARY never
     // ends the process — that decision belongs to whoever owns the lifecycle.
     this._onFatal = this._config.onFatal;
@@ -412,9 +418,12 @@ class RabbitMQClient extends EventEmitter {
     // Health reporting callbacks
     this._healthReportCallback = this._config.healthReportCallback; // (health) => Promise<void>
     this._healthCriticalCallback = this._config.healthCriticalCallback; // (health) => Promise<void>
-    this._criticalHealthShutdown = this._config.criticalHealthShutdown;
-    this._criticalHealthShutdownDelay = this._config.criticalHealthShutdownDelay;
-    this._criticalHealthStartTime = null; // Track when critical health started
+    // When the current critical stretch began — read only by the two log lines that open and
+    // close it ("Critical health detected at", "Health recovered after"). Since d.1275 it arms
+    // nothing: `criticalHealthShutdown` and the `health:shutdown` event it armed are gone
+    // (owner 2026-10-06), because ending the process is the lifecycle owner's decision
+    // (`_failFatally()`), and nothing listened.
+    this._criticalHealthStartTime = null;
 
     // Publish layer (retry + buffer)
     this._publishLayer = new PublishLayer({
@@ -426,6 +435,13 @@ class RabbitMQClient extends EventEmitter {
           ttlMs: this._config.publishBufferTtlMs,
         },
       },
+      // The buffer's expiry clock is THIS client's timer rail (d.1275): its handle sits in
+      // `_activeTimers` like every other timer the client arms, so `disconnect()` ends it and
+      // `timers-have-one-evidence` can see it (d.759e).
+      timers: {
+        setTimeout: (callback, ms) => this._setTimeout(callback, ms),
+        clearTimeout: (handle) => this._clearTimeout(handle),
+      },
     });
 
     // Publish monitor (metriky) — counts only, reports through return values,
@@ -565,11 +581,19 @@ class RabbitMQClient extends EventEmitter {
   /**
    * THE definition of "this client's consumer is attached to that queue".
    *
-   * The tag is the one fact that is about THIS client: the broker gives it to
-   * the attachment it created, and since d.386b / d.605 the entry carries it
-   * only while that attachment exists — a refused re-registration and a cancel
-   * sent by the broker both drop it while the consumer stays TRACKED, because
-   * the next recovery must find it on the list.
+   * Two facts, both about THIS client, and both are needed:
+   *   - the consumer channel is alive (`_isChannelAlive()`, d.260) — an attachment lives
+   *     on that channel and dies with it, while the entry keeps its tag until the
+   *     re-registration on the next channel replaces it;
+   *   - the entry carries a tag: the broker gives it to the attachment it created, and
+   *     since d.386b / d.605 the entry carries it only while that attachment exists — a
+   *     refused re-registration and a cancel sent by the broker both drop it while the
+   *     consumer stays TRACKED, because the next recovery must find it on the list.
+   *
+   * Nothing here asks the broker, and nothing here reads the QUEUE channel. Until d.1275
+   * the health check counted `active` only inside its `checkQueue` loop, so a dead queue
+   * channel or an unanswered probe reported 0 attached for a client whose consumer channel
+   * was alive and receiving (INFRA 531, W224 on the dev scheduler).
    *
    * It is a method rather than an expression repeated twice for the reason
    * `change-discipline.md` § One rail per concern states: until d.613
@@ -584,7 +608,9 @@ class RabbitMQClient extends EventEmitter {
    * @private
    */
   _isConsumerAttached(consumerInfo) {
-    return typeof consumerInfo?.consumerTag === 'string' && consumerInfo.consumerTag !== '';
+    return this._isChannelAlive(this._consumerChannel)
+      && typeof consumerInfo?.consumerTag === 'string'
+      && consumerInfo.consumerTag !== '';
   }
 
   /**
@@ -1059,6 +1085,33 @@ class RabbitMQClient extends EventEmitter {
     return error;
   }
 
+  /**
+   * Carry a verdict that is ALREADY written — on the error a caller is about to receive.
+   *
+   * `_markBrokerRefusal()` and `_failFatally()` write the verdict; this does not write
+   * one, it copies `code` and `reason` from a verdict the client produced onto the error
+   * built around it, so the receiver reads it where every receiver reads it: on the error
+   * itself (`BaseClient._consumerRefusal()`, `@onlineapps/service-wrapper` FÁZE 0.3/0.7 read
+   * `error.code`, never a `cause` chain — a reader walking the chain would be a fallback
+   * over a buried marker, `architecture-principles.md` §3). Measured (d.1294, finding of
+   * d.1278/d.1281): the `consume()` refusals built around the recovery verdict kept
+   * `MQ_CONNECTION_FATAL` one `cause` down, so `_consumerRefusal()` wrapped them in a
+   * `ConsumeError` and the lifecycle owner never saw the verdict it ends the process on.
+   *
+   * An error that is not a fatal verdict (a spent cycle carries no code, by contract)
+   * leaves the error untouched.
+   *
+   * @param {Error} error - the error being built for the caller; `cause` already set
+   * @param {Error|null|undefined} verdict - what the recovery produced
+   * @returns {Error} the same error, with the verdict readable on top when there is one
+   * @private
+   */
+  _carryVerdict(error, verdict) {
+    // One body, in `utils/errorHandler.js`: `PublishLayer` and `BaseClient.publish()` carry the
+    // same verdict the same way (d.1300), so the rule is not written three times.
+    return carryVerdict(error, verdict);
+  }
+
   /**
    * A recovery cycle is over and the client is NOT connected, but the broker
    * never refused it — so this is not the end.
@@ -1106,6 +1159,24 @@ class RabbitMQClient extends EventEmitter {
     return standby;
   }
 
+  /**
+   * Whether a recovery cycle may start on this client without the caller's action — the
+   * ONE statement of the three states that forbid it (d.1319): the connection declared lost
+   * (`_connectionFatal`), the caller closed the client (`_closedByCaller`), recovery disabled
+   * by configuration (`reconnectEnabled: false`). Read by `_resumeRecovery()` (may the next use
+   * start a cycle), by `_recoveryEndedForPublish()` (`replayable` — may a `reconnected` still
+   * come to replay a held message) and by every rail that meets a closed connection
+   * (`_requireQueueChannel()`, `cancelConsumer()`, `ack()`/`nack()`: wait for the reconnect, or
+   * say through `_refusalWithoutRecovery()` why none is coming). Until d.1319 the first two
+   * carried their own copy of these three checks.
+   *
+   * @returns {boolean}
+   * @private
+   */
+  _recoveryMayStart() {
+    return !this._connectionFatal && !this._closedByCaller && this._reconnectEnabled === true;
+  }
+
   /**
    * Somebody wants to use a client that is not connected. Start the next
    * recovery cycle if the contract allows one, and say whether a recovery is now
@@ -1122,9 +1193,7 @@ class RabbitMQClient extends EventEmitter {
    */
   _resumeRecovery() {
     if (this._reconnecting) return true;
-    if (this._connectionFatal) return false;
-    if (this._closedByCaller) return false;
-    if (!this._reconnectEnabled) return false;
+    if (!this._recoveryMayStart()) return false;
 
     this._logger.info(
       `[RabbitMQClient] [mq-client-core] Client used while disconnected - starting recovery cycle `
@@ -1232,6 +1301,7 @@ class RabbitMQClient extends EventEmitter {
     fatal.attempts = this._maxReconnectAttempts;
     fatal.cycles = this._reconnectCycles;
     fatal.cause = lastError;
+    this._connectionFatalError = fatal;
 
     // The log line is the RECORD and is unconditional; the two lines below are
     // the NOTIFICATION, and only a caller that is not awaiting needs it.
@@ -1845,6 +1915,15 @@ class RabbitMQClient extends EventEmitter {
    * Close the connection an abandoned handshake produces, whenever it completes.
    * A handshake that fails after its timeout opened nothing; its error adds
    * nothing to the timeout the caller already received.
+   *
+   * The close waits for the broker's `close-ok` no longer than `brokerAnswerTimeout` — the
+   * one budget every wait on the broker has (conf `mq-broker-answer-budget` 001), on the one
+   * rail the teardown already uses (`_closeWithinTeardownBudget()` → `_awaitBrokerAnswer()`),
+   * and an unanswered close drops the socket (`_dropUnansweredConnection()`) exactly as
+   * `connect()` does for a half-open connection. Until d.1322 this was a bare
+   * `await late.close()`: a broker that never answered it left the late connection, its
+   * socket and its heartbeat alive for the life of the process — the handshake leak of
+   * INFRA wave 5.
    * @private
    * @param {Promise<Object>} connectPromise - the handshake the timeout abandoned
    * @param {string} phase - 'connect' or 'reconnect'
@@ -1856,11 +1935,16 @@ class RabbitMQClient extends EventEmitter {
           `[RabbitMQClient] Handshake completed after the ${phase} timeout (${this._connectTimeout} ms) - `
             + 'closing that connection, nothing in this client owns it'
         );
-        try {
-          await late.close();
-        } catch (closeErr) {
+        const closing = await this._closeWithinTeardownBudget(
+          `abandoned ${phase} handshake`,
+          late,
+          this._brokerAnswerTimeout
+        );
+        if (closing.status === 'unanswered') {
+          this._dropUnansweredConnection(late);
+        } else if (closing.status === 'refused') {
           this._logger.warn(
-            `[RabbitMQClient] Error closing the connection whose handshake outlived the ${phase} timeout: ${closeErr.message}`
+            `[RabbitMQClient] Error closing the connection whose handshake outlived the ${phase} timeout: ${closing.error.message}`
           );
         }
       },
@@ -2209,32 +2293,59 @@ class RabbitMQClient extends EventEmitter {
       // process.
       this._logger.warn('[RabbitMQClient] [mq-client-core] Cannot recreate publisher channel: connection is closed (waiting for reconnection)');
 
+      // Every way this branch ends without a channel is ONE class, `RecoveryEndedPublishError`
+      // (B1, owner's decision 2026-10-06, d.1300): the message is held in the buffer and
+      // replayed after the next `reconnected` / `unblocked`, like every other transiently
+      // failed publish — one rail with the retry that waited for a reconnect and saw it fail
+      // (`PublishLayer`). Until d.1300 the wait's ending was thrown raw and the "no recovery"
+      // cases as a `ConnectionError`, so the caller got a `PublishError` with no `buffered` at
+      // all and the message was not held (INFRA-DOCS ID254 point 1). The verdict of a fatal
+      // ending rides on top (`_carryVerdict()`, d.1297); a spent cycle carries no code.
       if (this._resumeRecovery()) {
-        await this._waitForReconnection();
+        try {
+          await this._waitForReconnection();
+        } catch (err) {
+          throw this._recoveryEndedForPublish(role, `the recovery it waited for did not arrive - ${err.message}`, err);
+        }
 
         // After reconnection, try again
         if (this._isChannelAlive(this._sendChannelOf(role))) {
           return; // Channel was recreated during reconnection
         }
-        // If still no channel, connection might have failed - check again
+        // The wait ended on `reconnected`, and the connection is already gone again (its
+        // `close` fired before this continuation ran). Nothing holds that second death as an
+        // object, so there is no cause.
         if (!this._connectionAlive) {
-          throw new ConnectionError(
-            '[RabbitMQClient] Connection reconnection failed - cannot create publisher channel. '
-              + 'Expected: an open connection once the reconnect completed. '
-              + 'Fix: check the broker is reachable; the client spends RABBITMQ_MAX_RECONNECT_ATTEMPTS per cycle and '
-              + 'RABBITMQ_MAX_RECONNECT_CYCLES cycles in all, then emits connection:fatal.'
+          throw this._recoveryEndedForPublish(
+            role,
+            'the recovery it waited for completed, but the connection is not alive any more',
+            null
           );
         }
       } else {
-        // No recovery can be started: the connection is permanently lost (the
-        // broker refused it, or every cycle is spent), the caller ended this
-        // client, or recovery is disarmed by configuration.
-        throw new ConnectionError(
-          '[RabbitMQClient] Connection is closed and no recovery can be started - cannot create publisher channel. '
-            + 'Expected: either an open connection, or a recovery this client is still allowed to run. '
-            + 'Fix: read connection:fatal for which of the two ended it — a broker refusal (credentials, vhost, '
-            + 'topology) or RABBITMQ_MAX_RECONNECT_CYCLES spent; reconnectEnabled: false and disconnect() also '
-            + 'leave the client here, on purpose.'
+        // No recovery can be started: the connection is permanently lost (the broker refused
+        // it, or every cycle is spent), the caller ended this client, or recovery is disarmed
+        // by configuration — the same three states, in the same order, as the consumer path
+        // (`_consumerChannelWithoutRecovery()`, d.1281).
+        if (this._connectionFatal) {
+          const fatal = this._connectionFatalError;
+          throw this._recoveryEndedForPublish(
+            role,
+            `the connection is permanently lost and no recovery may start - ${fatal ? fatal.message : 'the verdict was not recorded'}`,
+            fatal
+          );
+        }
+        if (this._closedByCaller) {
+          throw this._recoveryEndedForPublish(
+            role,
+            'the caller closed this client (disconnect()) and no recovery may start — only an explicit connect() re-arms it',
+            null
+          );
+        }
+        throw this._recoveryEndedForPublish(
+          role,
+          'the connection is closed and recovery is disabled by configuration (reconnectEnabled: false)',
+          null
         );
       }
     }
@@ -2386,6 +2497,16 @@ class RabbitMQClient extends EventEmitter {
    *   d.1003d), never assumed: until d.1003d this branch answered
    *   `_activeConsumers.size` as re-registered, counting a consumer whose
    *   re-registration the broker had refused (tracked, no tag — d.262, d.386b).
+   * @throws {ConnectionError} when the recovery this call waited for did not arrive —
+   *   `cause` is the error that ended the wait, the same object the cycle produced
+   *   (`code: 'MQ_CONNECTION_FATAL'` when it was the last cycle, and `onFatal` has already
+   *   received it — the thrown error then carries that `code` and `reason` on top too
+   *   (`_carryVerdict()`, d.1297); no `code` for a spent cycle — the contract keeps
+   *   `MQ_CONNECTION_STANDBY` inside the client); when the connection is closed and no recovery may start
+   *   (`_consumerChannelWithoutRecovery()`: permanently lost — `cause` is the fatal error
+   *   `onFatal` received; closed by the caller; recovery disabled); when the recovery it
+   *   waited for completed but the connection is not alive; or when the open connection
+   *   refuses the channel.
    */
   async _ensureConsumerChannel() {
     if (this._isChannelAlive(this._consumerChannel)) {
@@ -2399,16 +2520,39 @@ class RabbitMQClient extends EventEmitter {
       this._logger.warn('[RabbitMQClient] [mq-client-core] Cannot recreate consumer channel: connection is closed (reconnection in progress)');
 
       if (!this._resumeRecovery()) {
-        return { reRegistered: 0, failed: this._activeConsumers.size };
+        // No recovery may start, and the caller is told WHY (d.1281, finding of d.1278):
+        // until then this branch answered `{ failed }`, `consume()` went on without a
+        // channel and the caller got the queue-channel rail's "queue channel is not
+        // available … Fix: await client.connect()" — the right fix for one of the three
+        // states and wrong for the other two. The three are the three `_resumeRecovery()`
+        // refuses, asked in its order; the fatal one carries the verdict `onFatal` already
+        // received as `cause` — the same object, so there is no second rail of reporting.
+        throw this._consumerChannelWithoutRecovery();
       }
 
       try {
         await this._waitForReconnection();
       } catch (err) {
-        this._logger.warn(
-          `[RabbitMQClient] [mq-client-core] Consumer channel waited for a recovery that did not arrive: ${err.message}`
-        );
-        return { reRegistered: 0, failed: this._activeConsumers.size };
+        // The wait's ending is the caller's answer, the way it is on the publisher path
+        // (`_ensurePublisherChannel()` lets it through). Until d.1278 this branch wrote a
+        // WARN line and answered `{ failed }` as if that were an outcome; `consume()` then
+        // went on without a channel and the caller got the queue-channel rail's refusal
+        // ("queue channel is not available … Fix: await client.connect()") — no cause, no
+        // cycle, and the verdict of a fatal cycle reached `onFatal` and nobody else
+        // (INFRA-DOCS ID254). The cause is the SAME object the cycle produced, never a
+        // copy: `onFatal` and this caller hold one error between them, so there is no
+        // second channel of reporting to keep in step.
+        // The verdict rides on top (d.1297): `code`/`reason` of a fatal ending are copied
+        // onto this error, so `BaseClient._consumerRefusal()` lets it through unchanged and
+        // the lifecycle owner reads `error.code` as everywhere else.
+        throw this._carryVerdict(new ConnectionError(
+          `[RabbitMQClient] Cannot recreate the consumer channel: the recovery it waited for did not arrive - ${err.message} `
+            + 'Expected: the recovery to re-establish the connection before a consumer attaches. '
+            + 'Fix: read error.code — MQ_CONNECTION_FATAL ends this client (onFatal has been called; error.cause is '
+            + 'that verdict, error.reason says broker-refused or cycles-spent); a spent cycle carries no code and is '
+            + 'an outage: the next consume(), publish() or performHealthCheck() starts the next cycle.',
+          err
+        ), err);
       }
 
       if (this._isChannelAlive(this._consumerChannel)) {
@@ -2417,7 +2561,18 @@ class RabbitMQClient extends EventEmitter {
         return this._consumerAttachmentCounts();
       }
       if (!this._connectionAlive) {
-        return { reRegistered: 0, failed: this._activeConsumers.size };
+        // The wait ended on `reconnected`, and the connection is already gone again
+        // (its `close` fired before this continuation ran). Nothing holds that second
+        // death as an object here, so there is no `cause`; the sentence says what
+        // happened and what starts the next cycle (d.1281).
+        throw new ConnectionError(
+          '[RabbitMQClient] Cannot recreate the consumer channel: the recovery it waited for completed, '
+            + 'but the connection is not alive any more - '
+            + 'Expected: a live connection at the end of the recovery. '
+            + "Fix: run consume() again — the connection's close handler starts the next recovery cycle; "
+            + 'if it keeps ending here, the broker is dropping the connection right after accepting it '
+            + '(read the broker log).'
+        );
       }
     }
     
@@ -2465,6 +2620,104 @@ class RabbitMQClient extends EventEmitter {
     }
   }
 
+  /**
+   * The refusal a consumer gets when the connection is closed and `_resumeRecovery()`
+   * will not start a recovery — one sentence per state, in the order `_resumeRecovery()`
+   * asks them (d.1281).
+   *
+   *   - the connection is permanently lost (`_connectionFatal`): `cause` is THE fatal
+   *     error, the object `_failFatally()` handed to `onFatal` / `connection:fatal`;
+   *   - the caller closed this client (`_closedByCaller`): no cause — `disconnect()` is
+   *     not an error, and only `connect()` undoes it;
+   *   - recovery is disabled by configuration (`reconnectEnabled: false`): no cause.
+   *
+   * @returns {ConnectionError}
+   * @private
+   */
+  _consumerChannelWithoutRecovery() {
+    return this._refusalWithoutRecovery('[RabbitMQClient] Cannot recreate the consumer channel', 'consume');
+  }
+
+  /**
+   * ONE builder of the refusal for "the connection is closed and no recovery may start" —
+   * three states, three sentences, read in `_resumeRecovery()`'s order (d.1281, d.1314).
+   * Every operation that meets a closed connection it cannot wait out says it through this
+   * function: the consumer channel (`_consumerChannelWithoutRecovery()`), the queue-channel
+   * rail (`_requireQueueChannel()`), `cancelConsumer()`, `ack()`/`nack()` — so the verdict of a
+   * lost connection is written on the error once and the same way everywhere, and nothing
+   * advises `connect()` to a client whose owner must end the process instead.
+   *
+   * @param {string} headline - `[RabbitMQClient] Cannot <what>` — what was asked
+   * @param {string} verb - the public operation, named in the `disconnect()` Fix
+   * @returns {ConnectionError} with the fatal verdict carried on top when that is the state
+   * @private
+   */
+  _refusalWithoutRecovery(headline, verb) {
+    if (this._connectionFatal) {
+      const fatal = this._connectionFatalError;
+      return this._carryVerdict(new ConnectionError(
+        `${headline}: the connection is permanently lost and no `
+          + `recovery may start - ${fatal ? fatal.message : 'the verdict was not recorded'} `
+          + 'Expected: a client whose connection was not declared lost. '
+          + 'Fix: this client is over — error.code is MQ_CONNECTION_FATAL and error.cause the verdict onFatal '
+          + '(and connection:fatal) already carried; the owner of the client stops the process so its restart '
+          + 'policy boots a new one against a verified broker.',
+        fatal || undefined
+      ), fatal);
+    }
+    if (this._closedByCaller) {
+      return new ConnectionError(
+        `${headline}: the caller closed this client (disconnect()) `
+          + 'and no recovery may start - '
+          + 'Expected: a client that has not been disconnected. '
+          + `Fix: await client.connect() before ${verb}(); only an explicit connect() re-arms recovery.`
+      );
+    }
+    return new ConnectionError(
+      `${headline}: the connection is closed and recovery is `
+        + 'disabled by configuration (reconnectEnabled: false) - '
+        + 'Expected: either an open connection, or a client allowed to recover one. '
+        + 'Fix: await client.connect() to open a new connection, or run the client with reconnectEnabled: true '
+        + 'so the next consume(), publish() or performHealthCheck() starts a recovery cycle.'
+    );
+  }
+
+  /**
+   * The refusal a publish gets when its send channel cannot be had because the connection
+   * stayed down (B1, d.1300) — one class for every ending of that branch, with the reason in
+   * the sentence and the verdict, when there is one, on top.
+   *
+   * @param {'publisher'|'telemetry'} role - whose channel it was
+   * @param {string} why - what ended it, already including the wait's own sentence when one exists
+   * @param {Error|null} ended - the error that ended the recovery (the fatal verdict is the very
+   *   object `onFatal` received), or null when nothing holds the state as an object
+   * @returns {RecoveryEndedPublishError}
+   * @private
+   */
+  _recoveryEndedForPublish(role, why, ended) {
+    // Whether a `reconnected` can still come on this client without the caller's action —
+    // read from the state AFTER the ending, so a wait that ended fatal answers false. The
+    // three states that refuse `_resumeRecovery()` are exactly the three where it never comes
+    // (d.1301, lead's decision: a hold makes sense only where a reconnect can replay it).
+    const replayable = this._recoveryMayStart();
+    const fix = replayable
+      ? 'Fix: nothing to retry here — PublishLayer holds the message in the buffer (unless the call passed '
+        + 'bufferOnFailure: false) and replays it after the next reconnect or after the broker unblocks the '
+        + 'connection; the next publish(), consume() or performHealthCheck() starts the next recovery cycle. '
+      : 'Fix: this client will not reconnect on its own, so PublishLayer holds nothing (error.buffered === false) — '
+        + 'the caller holds the only copy; the lifecycle owner decides what happens to the process (onFatal), '
+        + 'and only an explicit connect() would open a new connection. ';
+    return this._carryVerdict(new RecoveryEndedPublishError(
+      `[RabbitMQClient] Cannot recreate the ${role} channel: ${why} `
+        + 'Expected: a live connection before the send. '
+        + fix
+        + 'error.code MQ_CONNECTION_FATAL (with error.reason) means this client is over and onFatal has been '
+        + 'called; error.cause is what ended the recovery, when an object exists for it.',
+      ended || undefined,
+      { replayable }
+    ), ended);
+  }
+
   /**
    * Re-register every tracked consumer on the current consumer channel.
    *
@@ -2793,7 +3046,11 @@ class RabbitMQClient extends EventEmitter {
       queues: {
         checked: 0,
         missing: [],
-        noConsumer: []
+        noConsumer: [],
+        // The BROKER's count of consumers on each tracked queue (`checkQueue().consumerCount`
+        // — everybody's, not only this client's), or 'unknown' where the probe did not run
+        // or got no answer. Never 0 for "not asked" (d.1275).
+        consumers: {}
       },
       healthy: true,
       issues: []
@@ -2819,7 +3076,23 @@ class RabbitMQClient extends EventEmitter {
       health.issues.push('Consumer channel is closed or missing');
     }
     
-    // Check tracked consumers - verify queues exist and have active consumers
+    // Which of this client's consumers are attached is THIS client's fact, counted from its
+    // own state — the consumer channel and the tags (`_isConsumerAttached()`, the definition
+    // `getConsumerState()` reads too, d.613). Counted BEFORE the broker is asked and whatever
+    // the broker answers: until d.1275 `active` was incremented only inside the probe loop
+    // below, so a dead queue channel or an unanswered `checkQueue` left it at 0 and the
+    // verdict further down told the operator a consuming client consumed nothing (INFRA 531).
+    for (const [queue, consumerInfo] of this._activeConsumers.entries()) {
+      health.queues.consumers[queue] = 'unknown';
+      if (this._isConsumerAttached(consumerInfo)) {
+        health.consumers.active++;
+      } else {
+        health.consumers.inactive.push(queue);
+      }
+    }
+
+    // The probe only ADDS what the broker knows: does each queue exist, and how many
+    // consumers does it count on it. Where it cannot ask, the count stays 'unknown'.
     if (this.isConnected() && this._isChannelAlive(this._queueChannel)) {
       for (const [queue, consumerInfo] of this._activeConsumers.entries()) {
         health.queues.checked++;
@@ -2832,25 +3105,19 @@ class RabbitMQClient extends EventEmitter {
             () => queueChannel.checkQueue(queue)
           );
           if (queueInfo) {
-            // Queue exists - is THIS client's consumer attached to it?
-            //
-            // The tag is what answers, because it is the only fact that is about
-            // this client. `checkQueue()` does return `consumerCount` — the
-            // comment that stood here said RabbitMQ offers no way to ask, which
-            // is not true — but that number counts every consumer on the queue,
-            // this client's and everybody else's alike, so it cannot say whether
-            // the one asking is among them. The tag can: it is the name the
-            // broker gave THIS client's attachment, and since d.386b it is set
-            // only while that attachment exists. The question is asked through
-            // `_isConsumerAttached()` — the one definition `getConsumerState()`
-            // now reads too (d.613).
-            if (this._isConsumerAttached(consumerInfo)) {
-              health.consumers.active++;
-            } else {
-              health.consumers.inactive.push(queue);
+            // Queue exists. The broker's `consumerCount` counts every consumer on the
+            // queue, this client's and everybody else's alike, so it is REPORTED, never
+            // used to decide whether the one asking is among them — that is
+            // `_isConsumerAttached()`, counted above.
+            health.queues.consumers[queue] = queueInfo.consumerCount;
+            if (!this._isConsumerAttached(consumerInfo)) {
               health.queues.noConsumer.push(queue);
               health.healthy = false;
-              health.issues.push(`Queue ${queue} has no active consumer (consumerTag missing)`);
+              health.issues.push(
+                this._isChannelAlive(this._consumerChannel)
+                  ? `Queue ${queue} has no active consumer (consumerTag missing)`
+                  : `Queue ${queue} has no active consumer (consumer channel is not alive)`
+              );
             }
           } else {
             health.queues.missing.push(queue);
@@ -2874,12 +3141,15 @@ class RabbitMQClient extends EventEmitter {
     // that is its own verdict — not something a reader infers from two numbers
     // sitting beside the channel findings. The per-queue issues above name WHICH
     // queue lost its consumer, and they do not always exist: when the probe loop
-    // does not run (no connection, or a dead queue channel) the snapshot's only
-    // consumer evidence is `tracked` and `active`, and every issue names a
+    // does not run (no connection, or a dead queue channel) every issue names a
     // channel instead. Measured 2026-09-08 (INFRA-monitoring): the whole account
     // a reader got of a client taking no message off any queue was the line
     // `Health check OK: 0/0 consumers active`.
     //
+    // `active` is this client's own count (above), so the verdict is never the
+    // probe's absence restated: a dead queue channel beside a live consumer
+    // channel is a channel finding, not "no consumer" (d.1275).
+    //
     // `tracked === 0` is a different client, not a lesser failure: a publisher
     // registered no consumer and has none to lose. It stays healthy, and the OK
     // line below says which of the two it is.
@@ -2898,7 +3168,7 @@ class RabbitMQClient extends EventEmitter {
     // Emit health check result
     this.emit('health:check', health);
     
-    // If unhealthy, log and potentially trigger shutdown
+    // If unhealthy, log and report
     if (!health.healthy) {
       this._logger.error(`[RabbitMQClient] [mq-client-core] Health check FAILED:`, health.issues);
       this._logger.error(`[RabbitMQClient] [mq-client-core] Health details:`, JSON.stringify(health, null, 2));
@@ -2927,21 +3197,13 @@ class RabbitMQClient extends EventEmitter {
         }
       }
       
-      // Emit critical health event
+      // Emit critical health event. That is the whole of it: the client REPORTS critical
+      // health and decides nothing about the process. `health:shutdown` and the
+      // `criticalHealthShutdown*` keys that armed it were removed in d.1275 (owner
+      // 2026-10-06) — the event reached no listener anywhere, and the line announcing it
+      // promised a shutdown nobody performed. A lifecycle owner that wants to act on a
+      // sustained critical state reads this event or `healthCriticalCallback`.
       this.emit('health:critical', health);
-      
-      // Check if we should shutdown after delay
-      if (this._criticalHealthShutdown) {
-        const timeSinceCritical = Date.now() - this._criticalHealthStartTime;
-        if (timeSinceCritical >= this._criticalHealthShutdownDelay) {
-          this._logger.error(`[RabbitMQClient] [mq-client-core] Critical health persisted for ${timeSinceCritical}ms (threshold: ${this._criticalHealthShutdownDelay}ms) - triggering shutdown`);
-          this.emit('health:shutdown', health);
-          // Note: Actual shutdown should be handled by the application using this event
-        } else {
-          const remaining = this._criticalHealthShutdownDelay - timeSinceCritical;
-          this._logger.warn(`[RabbitMQClient] [mq-client-core] Critical health will trigger shutdown in ${remaining}ms if not resolved`);
-        }
-      }
     } else {
       // Health is OK - reset critical health tracking
       if (this._criticalHealthStartTime) {
@@ -3286,6 +3548,14 @@ class RabbitMQClient extends EventEmitter {
   async _requireQueueChannel(verb, queue) {
     await this._ensureQueueChannel();
     if (!this._isChannelAlive(this._queueChannel)) {
+      // A connection that is down and will not recover on its own is not "wait for the
+      // reconnect": none is coming. The three states say so through the one builder every rail
+      // uses — the verdict on top for a lost connection (d.1314), the state named for
+      // `disconnect()` and `reconnectEnabled: false` (d.1319). A spent cycle (standby) keeps the
+      // sentence below: the next publish, consume or health check starts the next one.
+      if (!this._connectionAlive && !this._recoveryMayStart()) {
+        throw this._refusalWithoutRecovery(`[RabbitMQClient] Cannot ${verb} ${queue}`, verb);
+      }
       throw new ConnectionError(
         `[RabbitMQClient] Cannot ${verb} ${queue}: queue channel is not available - `
           + 'Expected: an open queue channel after _ensureQueueChannel(). '
@@ -3824,6 +4094,14 @@ class RabbitMQClient extends EventEmitter {
     // its tag named is gone (d.386b). There is nothing to cancel on the broker,
     // and asking anyway is a channel error rather than a cancel, so the caller
     // is told plainly instead of being handed one.
+    // Asked before the tag: on a connection that is down and will not recover the tag is gone
+    // too, and the sentence that matters is the state — the verdict for a lost connection
+    // (d.1314), `disconnect()` or `reconnectEnabled: false` otherwise (d.1319) — not "tracked
+    // but not attached".
+    if (!this._connectionAlive && !this._recoveryMayStart()) {
+      throw this._refusalWithoutRecovery(`[RabbitMQClient] Cannot cancelConsumer ${queue}`, 'cancelConsumer');
+    }
+
     if (info.consumerTag === null || info.consumerTag === undefined) {
       throw new ValidationError(
         `[RabbitMQClient] Cannot cancelConsumer ${queue}: the consumer is tracked but not attached - `
@@ -5687,7 +5965,10 @@ class RabbitMQClient extends EventEmitter {
           // catch polykal jako `warn`, takže konzumenti tiše přestali dostávat zprávy.
           // `_ensureConsumerChannel()` odpovídá `ConnectionError` s chybou amqplibu
           // v `cause` — jeden článek, vlastní příčina obalu (vzor obnovy frontového
-          // kanálu níž, d.696).
+          // kanálu níž, d.696). Od d.1278 i s chybou, kterou skončilo čekání na obnovu
+          // (standby bez `code`, nebo fatální s `MQ_CONNECTION_FATAL`): spojení tehdy
+          // neživé, takže `_connectionIsGoingAway()` odpoví `warn` — standby i fatal už
+          // ohlásily samy sebe na vlastním kanálu, druhé hlášení na `error` sem nepatří.
           if (this._connectionIsGoingAway(err.cause)) {
             this._logger.warn(`[RabbitMQClient] [mq-client-core] Failed to recreate consumer channel (connection may be closing): ${err.message}`);
           } else {
@@ -6116,6 +6397,12 @@ class RabbitMQClient extends EventEmitter {
     if (msg._mqProcessed) {
       return; // Already acked/nacked — idempotent
     }
+    // On a connection that is down and will not recover on its own (lost, `disconnect()`,
+    // `reconnectEnabled: false`) the delivery cannot be settled — the broker has requeued it
+    // already; the caller learns the state, the verdict included (d.1314, d.1319).
+    if (!this._connectionAlive && !this._recoveryMayStart()) {
+      throw this._refusalWithoutRecovery('[RabbitMQClient] Cannot ack', 'ack');
+    }
     if (!this._consumerChannel) {
       throw new ConnectionError(
         '[RabbitMQClient] Cannot ack: consumer channel is not initialized - Expected: an open consumer channel. '
@@ -6158,6 +6445,9 @@ class RabbitMQClient extends EventEmitter {
     if (msg._mqProcessed) {
       return; // Already acked/nacked — idempotent
     }
+    if (!this._connectionAlive && !this._recoveryMayStart()) {
+      throw this._refusalWithoutRecovery('[RabbitMQClient] Cannot nack', 'nack');
+    }
     if (!this._consumerChannel) {
       throw new ConnectionError(
         '[RabbitMQClient] Cannot nack: consumer channel is not initialized - Expected: an open consumer channel. '