@onlineapps/mq-client-core 3.2.0 → 4.0.1

package/src/transports/rabbitmqClient.js

@@ -415,10 +415,11 @@ class RabbitMQClient extends EventEmitter {
 
     // Recovery worker — connection recovery, and the report of a queue that does
     // not exist. It creates none: queue creation left it with the two callbacks
-    // that fed it (d.419).
+    // that fed it (d.419) and with `recoveryScope`, the permission they were
+    // filtered by (d.514). Which rule the report names is decided by the
+    // ownership class in the error, not by who built this client.
     this._recoveryWorker = new RecoveryWorker({
       client: this,
-      scope: this._config.recoveryScope,
       logger: this._logger,
     });
 
@@ -524,13 +525,52 @@ class RabbitMQClient extends EventEmitter {
   }
 
   /**
-   * Get current consumer state
-   * @returns {Object} Consumer state information
+   * 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.
+   *
+   * It is a method rather than an expression repeated twice for the reason
+   * `change-discipline.md` § One rail per concern states: until d.613
+   * `getConsumerState()` answered from `_activeConsumers.keys()` and
+   * `_performHealthCheck()` from the tag, so one file held two definitions of
+   * "active" — and the cheap synchronous reader, the one a service and an
+   * operator actually read, was the one that answered about a consumer the
+   * broker had already cancelled.
+   *
+   * @param {Object|undefined} consumerInfo - The entry `_activeConsumers` holds
+   * @returns {boolean}
+   * @private
+   */
+  _isConsumerAttached(consumerInfo) {
+    return typeof consumerInfo?.consumerTag === 'string' && consumerInfo.consumerTag !== '';
+  }
+
+  /**
+   * Get current consumer state.
+   *
+   * `tracked` counts the consumers this client would restore; `active` names the
+   * ones that are ATTACHED right now (`_isConsumerAttached()`, the same question
+   * `_performHealthCheck()` asks). `tracked > active.length` is therefore the
+   * cheap, synchronous statement that this client takes no message off some
+   * queue it registered — the state
+   * `docs/operations/rabbitmq-connection-recovery-troubleshooting.md` sends an
+   * operator here to read, and which the queue-name list could not carry.
+   *
+   * @returns {{tracked: number, active: string[]}} Consumer state information
    */
   getConsumerState() {
+    const active = [];
+    for (const [queue, consumerInfo] of this._activeConsumers.entries()) {
+      if (this._isConsumerAttached(consumerInfo)) active.push(queue);
+    }
+
     return {
       tracked: this._activeConsumers.size,
-      active: Array.from(this._activeConsumers.keys())
+      active
     };
   }
 
@@ -696,6 +736,142 @@ class RabbitMQClient extends EventEmitter {
     return REFUSAL_REPLY_CODES.some((code) => message.includes(`server: ${code} (`));
   }
 
+  /**
+   * State the broker's refusal of a QUEUE the same way `_failFatally()` states
+   * its refusal of a CONNECTION — as a marker on the error, read by the caller
+   * that must decide what to do about it.
+   *
+   * Measured defect (d.577, sonda W532 against the live broker): a queue that
+   * already exists with other arguments answers `assertQueue()` with `406
+   * PRECONDITION-FAILED`, and `_prepareQueueForConsume()` built a `ConsumeError`
+   * for it with no `code` and no `reason`. The reply code survived in `cause`
+   * alone — and one wrapping further up (`@onlineapps/conn-orch-registry`) in
+   * `cause.cause`, where nothing looks. `@onlineapps/service-wrapper` ends FÁZE
+   * 0.7 permanently only on `code: 'MQ_CONNECTION_FATAL'`, so a 406 on a queue
+   * was classified TRANSIENT and the service went on booting against a queue it
+   * will never be allowed to declare. Every attempt gets the same answer.
+   *
+   * ONE vocabulary for one fact, therefore: the marker is the one `_failFatally()`
+   * already writes for `broker-refused` (d.295/d.490), not a second spelling of
+   * it. A refusal of the topology and a refusal of the connection ask the reader
+   * for the same thing — stop retrying, fix what the broker named — and the
+   * lifecycle owner reads one marker, not a list of them.
+   *
+   * What it deliberately does NOT do is `_failFatally()`: that declares the
+   * CONNECTION permanently lost and stands the client down. The connection here
+   * is healthy; it is this queue the broker refuses, and the publish path over
+   * the same connection has nothing to answer for.
+   *
+   * The decision is taken on the REPLY CODE (`_isBrokerRefusal()`,
+   * `REFUSAL_REPLY_CODES`), never on the wording of a sentence somebody may
+   * reword — the defect d.164 measured. The broker's own error is kept as
+   * `cause`, so its reply code stays readable.
+   *
+   * BOTH rails that talk to the broker about a queue go through this one
+   * function (d.582). `consume()` was the first; `assertQueue()` is the other
+   * half of the same fact, and it is the one FÁZE 0.8 walks — a service that
+   * declares its business queues gets the 406 there, not on the consume path.
+   * Two copies of one classification would be free to drift
+   * (`change-discipline.md` § One rail per concern), so `kind` decides only the
+   * SENTENCE and the class of the wrapper; the verdict is written once.
+   *
+   * @param {'consume'|'declare'} kind - which rail is answering.
+   * @param {string} queue - the queue the broker was asked about.
+   * @param {Error} err - what that rail threw.
+   * @returns {Error} the same error carrying the verdict, a typed error carrying
+   *   it when the throw was the broker's raw one, or `err` untouched when the
+   *   broker refused nothing.
+   * @private
+   */
+  _asRefusal(kind, queue, err) {
+    const brokerError = this._brokerRefusalCause(err);
+
+    if (!brokerError) return err;
+
+    // Already stated, and in the shape this rail hands out: the verdict is
+    // written once, not once per layer that passes it on.
+    const alreadyStated = err.code === 'MQ_CONNECTION_FATAL'
+      && (kind !== 'consume' || err instanceof ConsumeError);
+    if (alreadyStated) return err;
+
+    // An error this rail built itself — the 406 sentence of
+    // `_prepareQueueForConsume()` — is marked in place: it names the fix more
+    // precisely than anything this function could write.
+    if (kind === 'consume' && err instanceof ConsumeError) {
+      return this._markBrokerRefusal(err);
+    }
+
+    const refusal = kind === 'consume'
+      ? new ConsumeError(
+        `[RabbitMQClient] Cannot consume from queue "${queue}": the broker REFUSED the operation, `
+          + `so retrying cannot change the answer (reason: ${brokerError.message}). `
+          + 'Expected: an account allowed to use this queue, and a queue whose declaration is the one '
+          + 'queueConfig prescribes. '
+          + 'Fix: correct the permission or the topology the broker named, then restart the process; '
+          + 'error.cause carries the broker reply code.',
+        queue,
+        brokerError
+      )
+      : new Error(
+        `[RabbitMQClient] Cannot declare queue "${queue}": the broker REFUSED the declaration, `
+          + `so retrying cannot change the answer (reason: ${brokerError.message}). `
+          + 'Expected: the queue to exist with the arguments queueConfig prescribes, and an account '
+          + 'allowed to declare it. '
+          + 'Fix: align the declaration the broker named (406 means the queue exists with other '
+          + 'arguments) or correct the permission, then restart the process; '
+          + 'error.cause carries the broker reply code.',
+        { cause: brokerError }
+      );
+
+    if (kind !== 'consume') refusal.queue = queue;
+    return this._markBrokerRefusal(refusal);
+  }
+
+  /**
+   * The broker error behind a failure, or `null` when the broker refused nothing.
+   *
+   * One `cause` deep, because that is how far the rails here wrap: the
+   * declaration step throws the broker's error, and the sentence built around it
+   * keeps it as `cause`. The decision is taken on the REPLY CODE
+   * (`_isBrokerRefusal()`, `REFUSAL_REPLY_CODES`), never on the wording of a
+   * sentence somebody may reword — the defect d.164 measured.
+   *
+   * @param {Error|null} err
+   * @returns {Error|null} the error carrying the broker's reply code
+   * @private
+   */
+  _brokerRefusalCause(err) {
+    if (!err) return null;
+
+    // An error already carrying the verdict is NOT the broker's own — the
+    // broker's is one `cause` below it. Asked of the marked error, the text half
+    // of `_isBrokerRefusal()` would answer yes about the wrapper, because the
+    // sentence built here quotes the broker's message verbatim (measured while
+    // writing d.582: `error.cause.code` came back `'MQ_CONNECTION_FATAL'`
+    // instead of `406`). The code is asked first, so the quote cannot be
+    // mistaken for the answer.
+    if (err.code === 'MQ_CONNECTION_FATAL') {
+      return this._isBrokerRefusal(err.cause) ? err.cause : null;
+    }
+
+    if (this._isBrokerRefusal(err)) return err;
+    if (this._isBrokerRefusal(err.cause)) return err.cause;
+    return null;
+  }
+
+  /**
+   * Write the verdict. ONE spelling, the one `_failFatally()` uses.
+   *
+   * @param {Error} error
+   * @returns {Error} the same error, marked
+   * @private
+   */
+  _markBrokerRefusal(error) {
+    error.code = 'MQ_CONNECTION_FATAL';
+    error.reason = 'broker-refused';
+    return error;
+  }
+
   /**
    * A recovery cycle is over and the client is NOT connected, but the broker
    * never refused it — so this is not the end.
@@ -823,12 +999,27 @@ class RabbitMQClient extends EventEmitter {
    * confused with an ordinary transient error: the `connection:fatal` event and
    * the injected `onFatal` callback.
    *
+   * WHO IS TOLD, and why that is not always the same. The `connection:fatal`
+   * event and the injected `onFatal` callback exist for a loss that happens
+   * asynchronously, with nobody awaiting anything — the owner would otherwise
+   * never hear of it. On the BOOT path a caller IS awaiting `connect()`, so it
+   * learns by the throw, and announcing as well would be a second notification
+   * of one event: the harm `_reportRecoveryFailure()` documents a few methods
+   * up, and a crossing of the line the boot caller draws itself (a boot failure
+   * is the boot's outcome, not a lifecycle event — see the `BOOT budget` note in
+   * `@onlineapps/service-wrapper`'s `_initializeMQ()`). Hence `announce`. The
+   * verdict, the state and the sentence are identical either way; only the
+   * channel differs (d.295).
+   *
    * @param {Error} lastError - The error from the final failed attempt.
    * @param {'broker-refused'|'cycles-spent'} reason - Which of the two it is.
+   * @param {Object} [options] - Reporting options.
+   * @param {boolean} [options.announce=true] - Emit `connection:fatal` and call
+   *   `onFatal`. False on a path whose caller is awaiting the throw.
    * @returns {Error} The fatal error, so callers can throw it.
    * @private
    */
-  _failFatally(lastError, reason) {
+  _failFatally(lastError, reason, { announce = true } = {}) {
     this._connectionFatal = true;
     this._reconnecting = false;
     this._lastConnectionError = lastError || null;
@@ -855,16 +1046,21 @@ class RabbitMQClient extends EventEmitter {
     fatal.cycles = this._reconnectCycles;
     fatal.cause = lastError;
 
+    // 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.
     this._logger.error(`[RabbitMQClient] [mq-client-core] ${fatal.message}`);
-    this.emit('connection:fatal', fatal);
 
-    if (this._onFatal) {
-      try {
-        this._onFatal(fatal);
-      } catch (err) {
-        this._logger.error(
-          `[RabbitMQClient] [mq-client-core] onFatal handler threw: ${err.message}`
-        );
+    if (announce) {
+      this.emit('connection:fatal', fatal);
+
+      if (this._onFatal) {
+        try {
+          this._onFatal(fatal);
+        } catch (err) {
+          this._logger.error(
+            `[RabbitMQClient] [mq-client-core] onFatal handler threw: ${err.message}`
+          );
+        }
       }
     }
 
@@ -1327,6 +1523,25 @@ class RabbitMQClient extends EventEmitter {
         }
         this._connection = null;
       }
+
+      // The broker ANSWERED and refused — 403, 530, 406. The same verdict
+      // `_reconnectWithBackoff()` reaches at runtime, on the same rail
+      // (`_isBrokerRefusal`), because it is the same question: did anybody
+      // answer? Until d.295 this catch rethrew whatever amqplib raised, with no
+      // verdict on it, and the boot caller could only guess — `ServiceWrapper`
+      // guessed "transient" and spent its whole connection budget, backoff and
+      // all, on an answer no further attempt can change
+      // (`architecture-principles.md` §4).
+      //
+      // Anything unrecognised still leaves here as it arrived, and that is the
+      // owner's decision, not an omission: giving up forever on a broker that
+      // never answered is forbidden
+      // (`docs/governance/confirmations/mq-client-lifecycle-contract.md` 001
+      // point 3), so only an ANSWERED refusal ends the attempts.
+      if (this._isBrokerRefusal(err)) {
+        throw this._failFatally(err, 'broker-refused', { announce: false });
+      }
+
       throw err;
     } finally {
       if (connectTimeoutTimer) {
@@ -1682,54 +1897,160 @@ class RabbitMQClient extends EventEmitter {
     if (this._activeConsumers.size > 0) {
       this._logger.info(`[RabbitMQClient] [mq-client-core] Re-registering ${this._activeConsumers.size} consumers...`);
       for (const [queue, consumerInfo] of this._activeConsumers.entries()) {
-        try {
-          await this._prepareQueueForConsume(queue, {
-            durable: consumerInfo.options.durable,
-            queueOptions: consumerInfo.options.queueOptions
-          });
-
-          // The consumer's prefetch is re-applied here for the same reason the
-          // queue step is: the channel is new, and QoS lives on the channel.
-          await this._applyConsumerPrefetch(queue, consumerInfo.options.prefetch);
-
-          const consumeResult = await this._consumerChannel.consume(
-            queue,
-            consumerInfo.handler,
-            { noAck: consumerInfo.options.noAck }
-          );
-          consumerInfo.consumerTag = consumeResult.consumerTag;
+        if (await this._reRegisterConsumer(queue, consumerInfo)) {
           reRegistered++;
-          this._logger.info(`[RabbitMQClient] [mq-client-core] \u2713 Re-registered consumer for queue: ${queue} (consumerTag: ${consumeResult.consumerTag})`);
-        } catch (err) {
+        } else {
           failed++;
-          this._logger.error(`[RabbitMQClient] [mq-client-core] Failed to re-register consumer for queue ${queue}:`, err.message);
-          // The consumer STAYS tracked. Whatever refused it — a 406 against the
-          // owner's declaration, a missing infrastructure queue, a channel that
-          // went away mid-flight — is a condition somebody fixes at its source,
-          // and the next recreate must find the consumer still on the list.
-          //
-          // Its TAG does not stay, and the two are not the same fact (d.386b). A
-          // consumer tag names an attachment on ONE channel; the channel that
-          // issued this one is gone and the new one refused to re-attach, so the
-          // string the entry carried names nothing on the broker. Two readers
-          // took it for an attachment that exists: `_performHealthCheck()` counts
-          // `active` by "is the tag set", so a client whose only consumer had
-          // just been refused reported `healthy: true` and `1/1 consumers active`
-          // — the false OK d.386 exists to end, one layer below where d.386 could
-          // reach it; and `cancelConsumer()` sent `basic.cancel` with it, asking
-          // the broker to stop a consumer it does not hold.
-          consumerInfo.consumerTag = null;
-          // The broker's own code is what a listener acts on (406 = the queue
-          // exists with different arguments), and the rail wraps it in a typed
-          // error, so it is read from the cause when the wrapper carries none.
-          const code = err.code !== undefined ? err.code : (err.cause ? err.cause.code : undefined);
-          this.emit('consumer:re-registration:failed', { queue, error: err.message, code });
         }
       }
     }
     return { reRegistered, failed };
   }
 
+  /**
+   * Re-attach ONE tracked consumer on the current consumer channel.
+   *
+   * This is the body of the loop above, given a name in d.605 because a second
+   * event needs exactly it: `basic.cancel` from the broker takes ONE consumer
+   * away while every other one stays attached, so re-running the whole loop
+   * would re-attach consumers that never lost their place — a second
+   * `basic.consume` for each of them on the broker. One rail, one set of
+   * consequences (`change-discipline.md` § One rail per concern).
+   *
+   * Everything a first `consume()` does is done here: the queue is classified,
+   * declared or checked by `_prepareQueueForConsume()` — so an owned business
+   * queue is re-declared and an unowned infrastructure queue is only checked,
+   * its absence answered with `CONSUMER_QUEUE_MISSING` rather than a silent
+   * creation — and the prefetch is re-applied, because QoS lives on the channel.
+   *
+   * @param {string} queue - Queue name
+   * @param {Object} consumerInfo - The entry `_activeConsumers` holds for it
+   * @returns {Promise<boolean>} `true` when the consumer is attached again
+   * @private
+   */
+  async _reRegisterConsumer(queue, consumerInfo) {
+    try {
+      await this._prepareQueueForConsume(queue, {
+        durable: consumerInfo.options.durable,
+        queueOptions: consumerInfo.options.queueOptions
+      });
+
+      // The consumer's prefetch is re-applied here for the same reason the
+      // queue step is: the channel is new, and QoS lives on the channel.
+      await this._applyConsumerPrefetch(queue, consumerInfo.options.prefetch);
+
+      const consumeResult = await this._consumerChannel.consume(
+        queue,
+        consumerInfo.handler,
+        { noAck: consumerInfo.options.noAck }
+      );
+      consumerInfo.consumerTag = consumeResult.consumerTag;
+      this._logger.info(`[RabbitMQClient] [mq-client-core] ✓ Re-registered consumer for queue: ${queue} (consumerTag: ${consumeResult.consumerTag})`);
+      return true;
+    } catch (err) {
+      this._logger.error(`[RabbitMQClient] [mq-client-core] Failed to re-register consumer for queue ${queue}:`, err.message);
+      // The consumer STAYS tracked. Whatever refused it — a 406 against the
+      // owner's declaration, a missing infrastructure queue, a channel that
+      // went away mid-flight — is a condition somebody fixes at its source,
+      // and the next recreate must find the consumer still on the list.
+      //
+      // Its TAG does not stay, and the two are not the same fact (d.386b). A
+      // consumer tag names an attachment on ONE channel; the channel that
+      // issued this one is gone and the new one refused to re-attach, so the
+      // string the entry carried names nothing on the broker. Two readers
+      // took it for an attachment that exists: `_performHealthCheck()` counts
+      // `active` by "is the tag set", so a client whose only consumer had
+      // just been refused reported `healthy: true` and `1/1 consumers active`
+      // — the false OK d.386 exists to end, one layer below where d.386 could
+      // reach it; and `cancelConsumer()` sent `basic.cancel` with it, asking
+      // the broker to stop a consumer it does not hold.
+      consumerInfo.consumerTag = null;
+      // The broker's own code is what a listener acts on (406 = the queue
+      // exists with different arguments), and the rail wraps it in a typed
+      // error, so it is read from the cause when the wrapper carries none.
+      const code = err.code !== undefined ? err.code : (err.cause ? err.cause.code : undefined);
+      this.emit('consumer:re-registration:failed', { queue, error: err.message, code });
+      return false;
+    }
+  }
+
+  /**
+   * The broker cancelled one of this client's consumers.
+   *
+   * `basic.cancel` sent BY THE BROKER is not an error frame and does not touch
+   * the channel or the connection: the queue was deleted, or the broker moved it
+   * (`x-cancel-on-ha-failover`). Nothing else in this client hears it — the
+   * channel handlers listen for `error` and `close`, and both stay silent — so
+   * this method is the whole of the client's answer, and until d.605 that answer
+   * was nothing at all.
+   *
+   * Three things happen, in this order:
+   *
+   *   1. the TAG is dropped, first, because it is the one fact
+   *      `_performHealthCheck()` reads to answer "is THIS client's consumer
+   *      attached" (d.386b). Dropping it before anything else leaves no window in
+   *      which the check reports an attachment the broker has already cancelled;
+   *   2. the loss is stated at ERROR level, naming the queue and the cancelled
+   *      tag. A consumer that stops reading a queue is not a debug-level event,
+   *      and the record is what tells an operator which queue went quiet;
+   *   3. the consumer is re-attached through `_reRegisterConsumer()`, the rail a
+   *      channel recreate already uses. A refusal there keeps the consumer
+   *      tracked with no tag and travels on `consumer:re-registration:failed` —
+   *      which is why this method introduces no event and no public method of its
+   *      own: every state it can reach is a state the package already reports.
+   *
+   * @param {string} queue - The queue whose consumer the broker cancelled
+   * @returns {Promise<void>}
+   * @private
+   */
+  async _onBrokerCancel(queue) {
+    if (this._closedByCaller) {
+      // An intentional close is not a fault — the doctrine `disconnect()` states
+      // and both channel handlers already follow.
+      this._logger.debug(
+        `[RabbitMQClient] [mq-client-core] [CONSUMER] Broker cancelled the consumer for queue "${queue}" while the client was being closed by its caller - no alarm, no re-attachment`
+      );
+      return;
+    }
+
+    const consumerInfo = this._activeConsumers.get(queue);
+    const cancelledTag = consumerInfo ? consumerInfo.consumerTag : null;
+
+    if (consumerInfo) {
+      consumerInfo.consumerTag = null;
+    }
+
+    this._logger.error(
+      `[RabbitMQClient] Consumer cancelled by the broker - the consumer on queue "${queue}" `
+        + `(consumerTag: ${cancelledTag}) was stopped by the BROKER, not by this client: the queue `
+        + 'was deleted, or the broker moved it (x-cancel-on-ha-failover). '
+        + 'Expected: a consumer stays attached until cancelConsumer() or disconnect(). '
+        + 'Fix: none here - the client re-attaches it on the rail a channel recreate uses; if that '
+        + 'is refused, the consumer stays tracked with no tag, performHealthCheck() reports this '
+        + 'client unhealthy and names the queue, and consumer:re-registration:failed carries the '
+        + 'broker reason.',
+      { queue, consumerTag: cancelledTag }
+    );
+
+    if (!consumerInfo) {
+      // The client no longer holds this consumer, so there is nothing to
+      // re-attach and no state left to correct. The loss is still stated above.
+      return;
+    }
+
+    if (!this._isChannelAlive(this._consumerChannel)) {
+      // Re-attaching on a dead channel is not this method's job: the channel
+      // recovery re-registers every tracked consumer when it recreates the
+      // channel (d.262), and the consumer stays tracked for exactly that.
+      this._logger.warn(
+        `[RabbitMQClient] [mq-client-core] [CONSUMER] Consumer for queue "${queue}" stays tracked and unattached - the consumer channel is not alive, so the channel recovery re-registers it`
+      );
+      return;
+    }
+
+    await this._reRegisterConsumer(queue, consumerInfo);
+  }
+
   /**
    * Disconnects: closes channel and connection.
    * @returns {Promise<void>}
@@ -1885,8 +2206,10 @@ class RabbitMQClient extends EventEmitter {
             // 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.
-            if (consumerInfo.consumerTag) {
+            // 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);
@@ -2203,7 +2526,19 @@ class RabbitMQClient extends EventEmitter {
 
     const channel = await this._requireQueueChannel('assertQueue', queue);
 
-    return await channel.assertQueue(queue, queueOptions);
+    try {
+      return await channel.assertQueue(queue, queueOptions);
+    } catch (err) {
+      // The SAME verdict the consume rail states, through the SAME function
+      // (d.582). This is the rail FÁZE 0.8 walks: a service declaring its own
+      // business queues meets the 406 here, and until this batch the raw amqplib
+      // error left with the reply code as a NUMBER and no classification at all,
+      // so `@onlineapps/conn-orch-registry` had nothing to carry and
+      // `@onlineapps/service-wrapper` — which reads `error.code` — called a
+      // refusal transient. `_failFatally()` is deliberately not called: it is
+      // this QUEUE the broker refuses, not the connection.
+      throw this._asRefusal('declare', queue, err);
+    }
   }
 
   /**
@@ -2993,8 +3328,8 @@ class RabbitMQClient extends EventEmitter {
    * declared with.
    *
    * ONE rail for the first `consume()` and for every re-registration after a
-   * channel recreate. It classifies the queue (reply / infrastructure /
-   * business), resolves the arguments from the central config, refuses a queue
+   * channel recreate. It classifies the queue (infrastructure / business /
+   * neither), resolves the arguments from the central config, refuses a queue
    * whose config declares no dead-letter route, and then CHECKS an
    * infrastructure queue (consumers never create those) or ASSERTS a business
    * one.
@@ -3014,15 +3349,24 @@ class RabbitMQClient extends EventEmitter {
     const durable = options.durable !== undefined ? options.durable : this._config.durable;
     let queueOptions = options.queueOptions || { durable };
 
-    // Skip assertQueue for reply queues (they're already created with specific settings)
-    // Reply queues start with 'rpc.reply.' and are created as non-durable
-    const isReplyQueue = queue.startsWith('rpc.reply.');
     // Classification is read once and used by both blocks below — the one that
     // resolves the central arguments, and the one that checks or asserts the queue.
-    const isInfraQueue = !isReplyQueue && queueConfig.isInfrastructureQueue(queue);
-    const isBusinessQueue = !isReplyQueue && queueConfig.isBusinessQueue(queue);
+    //
+    // There is no third class. Until d.514 a name starting `rpc.reply.` was
+    // exempted here and again below: classification, declaration and the broker
+    // question were all skipped, because the retired RPC reply path declared such
+    // a queue itself, with its own non-durable lifetime. Both exemptions had been
+    // unreachable since d.259: `queueConfig` classifies that name as nothing, so
+    // it declares no dead-letter route, so the gate between the two blocks throws
+    // first — measured against the live broker on a reply queue that really
+    // existed (`tests/integration/dead-letter-route-required.integration.test.js`).
+    // The four questions are answered in the CHANGELOG of that batch; the path the
+    // exemption served is gone (`docs/governance/confirmations/mq-consumer-contract.md`
+    // 003 point 3 — "`rpc.reply.*` is not a topology question … it is a removal
+    // question", and `conn-infra-mq` removed `createTemporaryQueue()` in d.275b).
+    const isInfraQueue = queueConfig.isInfrastructureQueue(queue);
+    const isBusinessQueue = queueConfig.isBusinessQueue(queue);
 
-    if (!isReplyQueue) {
     // CRITICAL: Use queueConfig.js to get correct parameters (TTL, max-length, etc.)
     // This prevents 406 PRECONDITION-FAILED errors from TTL mismatches.
     // queueConfig is loaded once at the top of this module; it used to be required
@@ -3066,9 +3410,6 @@ class RabbitMQClient extends EventEmitter {
           : `[RabbitMQClient] [mq-client-core] [CONSUMER] Asserting business queue ${queue} with the declaration queueConfig owns`
       );
     }
-    // End of the queue-classification block. What follows applies to EVERY
-    // queue this consumer may attach to, reply queues included.
-    }
 
     // The dead-letter policy below rejects a spent message with
     // `nack(requeue=false)`, and the broker then moves it ONLY if the queue
@@ -3122,7 +3463,6 @@ class RabbitMQClient extends EventEmitter {
       );
     }
 
-    if (!isReplyQueue) {
     this._logger.debug(`[RabbitMQClient] [mq-client-core] [CONSUMER] Asserting queue ${queue} before consume() at ${new Date().toISOString()}`);
     this._logger.debug(`[RabbitMQClient] [mq-client-core] [CONSUMER] Queue options:`, JSON.stringify(queueOptions, null, 2));
     this._logger.debug(`[RabbitMQClient] [mq-client-core] [CONSUMER] _queueChannel state: exists=${!!this._queueChannel}, closed=${!this._isChannelAlive(this._queueChannel)}`);
@@ -3194,7 +3534,11 @@ class RabbitMQClient extends EventEmitter {
       } catch (assertErr) {
         // If queue exists with different arguments (406), this is a CRITICAL ERROR
         // We should NOT proceed - the root cause must be fixed
-        if (assertErr.code === 406) {
+        // Read off the BROKER's reply code, which since d.582 travels as the
+        // `cause` of the declaration rail's own refusal — never off the marker,
+        // which says "refused" without saying which of the three codes it was.
+        const brokerError = this._brokerRefusalCause(assertErr);
+        if (brokerError && brokerError.code === 406) {
           this._logger.error(`[RabbitMQClient] [mq-client-core] [CONSUMER] ✗ CRITICAL: Queue ${queue} exists with different arguments!`);
           this._logger.error(`[RabbitMQClient] [mq-client-core] [CONSUMER] Error:`, assertErr.message);
           this._logger.error(`[RabbitMQClient] [mq-client-core] [CONSUMER] Expected options:`, JSON.stringify(queueOptions, null, 2));
@@ -3205,14 +3549,15 @@ class RabbitMQClient extends EventEmitter {
               + 'Fix: find the assertQueue() call that declared it without parameters and fix that call; '
               + 'the queue is NOT redeclared here, because doing so would hide the drift instead of ending it.',
             queue,
-            assertErr
+            // The BROKER's error, not the declaration rail's wrapper around it:
+            // one `cause` hop, and `error.cause.code` is the reply code (d.582).
+            brokerError
           );
         }
         // Other error - rethrow
         throw assertErr;
       }
     }
-    }
 
     return queueOptions;
   }
@@ -3334,7 +3679,21 @@ class RabbitMQClient extends EventEmitter {
       // Wrap handler to track message processing and prefetch utilization
       const messageHandler = async (msg) => {
         if (msg === null) {
-          return; // Consumer cancellation
+          // `null` is not a message. It is `basic.cancel` FROM THE BROKER,
+          // handed to this callback by amqplib (`handleCancel()` →
+          // `dispatchMessage(fields, null)`), and it is the only way a consumer
+          // learns that its attachment is gone while the channel and the
+          // connection stay up: the queue was deleted, or the broker moved it
+          // (`x-cancel-on-ha-failover`).
+          //
+          // Until d.605 the answer was this bare `return`. Nothing was logged,
+          // the tag stayed set — so `_performHealthCheck()` went on counting the
+          // consumer as attached — and nothing re-attached it. The service
+          // reported itself healthy while no message was taken off the queue,
+          // which is the failure `automation-gates.md` §5 calls a defect of the
+          // same severity as a wrong result.
+          await this._onBrokerCancel(queue);
+          return;
         }
 
         // IMPORTANT:
@@ -3497,8 +3856,15 @@ class RabbitMQClient extends EventEmitter {
       // Return consumer tag for cancellation
       return consumeResult.consumerTag;
     } catch (err) {
-      this.emit('error', err);
-      throw err;
+      // ONE place states the broker's verdict for this whole rail — the queue
+      // classification, the declaration and the consumer registration alike —
+      // because it is ONE question ("did the broker answer and refuse?") and a
+      // copy of it per branch is free to drift (`change-discipline.md` § One rail
+      // per concern). Anything the broker did not refuse leaves exactly as it
+      // arrived (d.577).
+      const refusal = this._asRefusal('consume', queue, err);
+      this.emit('error', refusal);
+      throw refusal;
     }
   }
 
@@ -3941,7 +4307,22 @@ class RabbitMQClient extends EventEmitter {
   }
 
   /**
-   * Check prefetch utilization for a queue and alert if threshold exceeded
+   * Check prefetch utilization for a queue and alert if threshold exceeded.
+   *
+   * A window of ONE message has no utilisation to watch (d.550). Its only two
+   * states are 0 % (idle) and 100 % (the consumer is doing the one piece of work
+   * it is allowed), and 100 % is the normal state of a healthy consumer, not a
+   * finding anybody can act on. The alarm therefore fired on EVERY delivery to
+   * such a queue, whatever the threshold - `1/1 >= 0.8` holds exactly as
+   * `1/1 >= 0.99` does. MEASURED (BIZ-pdfgen, BIZ-converter, twice per boot):
+   * `Prefetch utilization high: queue 'biz-pdfgen.registry' has 1/1 messages
+   * in-flight (100%, threshold: 80%)` - a warning that cannot fail to happen
+   * says nothing, and it teaches the reader to skip the line where a real
+   * saturation will one day stand.
+   *
+   * The threshold itself is unchanged and no new one is introduced: a window
+   * larger than one message is measured exactly as before.
+   *
    * @private
    * @param {string} queue - Queue name
    * @param {Object} tracking - Prefetch tracking object
@@ -3950,7 +4331,11 @@ class RabbitMQClient extends EventEmitter {
     if (!tracking || tracking.prefetchCount === 0) {
       return; // No prefetch set or tracking not available
     }
-    
+
+    if (tracking.prefetchCount <= 1) {
+      return; // One-message window: 0 % or 100 %, and 100 % is the working state.
+    }
+
     const utilization = tracking.inFlight / tracking.prefetchCount;
     
     if (utilization >= this._prefetchUtilizationThreshold) {