@onlineapps/mq-client-core 5.0.0 → 6.0.0

package/README.md

@@ -6,7 +6,7 @@ Uniform: [library/connector](../connector/conn-orch-validator/manifests/library.
 
 Duty sections that apply:
 
-- `all`: L-MAIN, L-ENGINES, L-TESTS, L-TEST-SCRIPT, L-PACK-TESTS, L-PINS, L-NO-FILE-RANGE, L-CHANGELOG, L-README, L-README-REGION, L-CONSUMER
+- `all`: L-MAIN, L-ENGINES, L-TESTS, L-TEST-SCRIPT, L-PACK-TESTS, L-PINS, L-NO-FILE-RANGE, L-CHANGELOG, L-PACK-CHANGELOG, L-README, L-README-REGION, L-CONSUMER
 - `connector`: L-CONNECTOR-ENV
 <!-- END GENERATED: library-uniform -->
 
@@ -86,11 +86,18 @@ says" — and every connection on the platform ran on the broker's number rather
 the configured one (measured on the dev broker: 39 live connections, `timeout: 60`
 on all of them).
 
-`brokerAnswerTimeout` bounds **both** things this client waits for the broker to
-answer: the confirm of one publish attempt, and the `close-ok` of each handle
-`disconnect()` closes. It was called `publishConfirmationTimeout` until
-2026-09-14 — the name of one of its two consumers — and writing that name now is
-refused, with the new one named.
+`brokerAnswerTimeout` bounds **every** wait on the broker's answer — the confirm of
+one publish attempt, the `close-ok` of each handle `disconnect()` closes, and every
+request a channel sends and waits on: `assertQueue`, `checkQueue` (also the check before a
+queue publish), `bindQueue`, `assertExchange`, `purgeQueue`, `deleteQueue`, `consume`,
+`cancelConsumer`, the prefetch, and every channel open (conf `mq-broker-answer-budget` 001).
+A request left unanswered for that long discards the channel that carried it (the next
+operation opens a fresh one) and ends in `ConnectionError` naming the operation, its target
+and the budget; on the publish path it is `TransientPublishError`, so retry, the buffer and
+`bufferOnFailure: false` apply as to any transient failure. This is what ends the wait on a
+broker in a memory alarm, which keeps the connection and its heartbeats alive while it
+answers nothing. It was called `publishConfirmationTimeout` until 2026-09-14 — the name of
+one of its consumers — and writing that name now is refused, with the new one named.
 
 `maxReconnectAttempts` and `maxReconnectCycles` resolve the usual way — explicit
 config → env (`RABBITMQ_MAX_RECONNECT_ATTEMPTS`, `RABBITMQ_MAX_RECONNECT_CYCLES`)
@@ -100,6 +107,14 @@ config → env (`RABBITMQ_MAX_RECONNECT_ATTEMPTS`, `RABBITMQ_MAX_RECONNECT_CYCLE
 attempts inside ONE recovery cycle, the second how many cycles there may be — see
 § Connection loss.
 
+**`criticalHealthShutdown` and `criticalHealthShutdownDelay` are refused by name** (removed
+2026-10-06, d.1275, on the owner's word). They made the transport, after a minute
+of critical health, emit `health:shutdown` and log that it was "triggering shutdown" — but this
+library never ends the process (see § Connection loss), and nothing on the platform listened
+for the event, so the line promised an action that never came. The event went with the keys.
+Critical health is reported — `health:critical` and `healthCriticalCallback` on every failing
+check — and what to do about the process is the lifecycle owner's decision (`onFatal`).
+
 ### A subclass declares its own keys
 
 `new BaseClient(config, extraProperties?)`. The second argument is the JSON Schema
@@ -134,7 +149,10 @@ Owner decision: `api/docs/governance/confirmations/connector-logger-contract.md`
 
 - `connect(options?)` - Connect to RabbitMQ
 - `disconnect()` - Disconnect from RabbitMQ
-- `publish(queue, message, options?)` - Publish message to queue
+- `publish(queue, message, options?)` - Publish message to queue. `options.bufferOnFailure`
+  (boolean, default `true`): `false` leaves the publish buffer for this one call — a
+  transiently failed message is NOT held and no reconnect replays it; the thrown
+  `PublishError` then carries `buffered: false` (see § The publish buffer).
 - `publishTelemetry(queue, message, options?)` - Publish the client's OWN event (the
   monitoring helpers below use it) on a confirm channel of its own, opened with the
   first such publish. A refusal there closes that channel only, never the one a
@@ -162,7 +180,17 @@ Owner decision: `api/docs/governance/confirmations/connector-logger-contract.md`
   healthy** — `healthy: false`, with an issue naming how many it tracks — because
   such a client takes no message off any queue. A client that registered no
   consumer at all is a publisher and stays healthy; the check's own log line says
-  which of the two it is.
+  which of the two it is. `consumers.active` / `consumers.inactive` are this
+  client's own facts — a consumer is attached while the consumer channel is alive
+  and its entry holds the broker's tag (the definition `getConsumerState()` reads)
+  — so a dead QUEUE channel or an unanswered queue probe is reported as what it is,
+  a channel or probe issue, never as "no consumer" (d.1275). The probe adds what
+  only the broker knows: `queues.consumers` maps each tracked queue to the broker's
+  `consumerCount` (every consumer on the queue, not only this client's), or to
+  `'unknown'` where the probe did not run or got no answer — never `0` for "not
+  asked". A failing check emits `health:critical` and calls
+  `healthCriticalCallback`; it decides nothing about the process (there is no
+  `health:shutdown`, see § Configuration).
 - `assertQueue(queue, options?)` / `checkQueue(queue)` / `purgeQueue(queue)` /
   `deleteQueue(queue, options?)` - Queue operations, on the queue channel.
   `assertQueue()` reads exactly four options — `durable`, `arguments`,
@@ -448,8 +476,21 @@ Permanently lost means all of this, together:
   built on them;
 - no further reconnect attempts are made, by a use or otherwise — the client is
   dead until the process restarts, or until an explicit `connect()`;
-- `publish()`/`consume()` refuse immediately instead of blocking on a recovery
-  that is not coming.
+- `publish()`/`consume()` — and every other operation on the broker:
+  `assertQueue`, `checkQueue`, `purgeQueue`, `deleteQueue`, `assertExchange`,
+  `bindQueue`, `cancelConsumer`, `ack`, `nack` — refuse immediately instead of
+  blocking on a recovery that is not coming, with the verdict on the error
+  (`code: 'MQ_CONNECTION_FATAL'`, `reason`, the verdict as `cause`); through
+  `BaseClient` too, which after the verdict lets the lost client answer for
+  itself instead of advising `connect()`. The state readers (`isConnected()`,
+  `isConnectionFatal()`, `getConsumerState()`, `getChannelState()`,
+  `performHealthCheck()`, the metrics) do not throw: they describe the state. A `consume()`
+  that was waiting when the verdict fell, or that is asked of the lost client
+  afterwards, is refused with that verdict readable on the error (`code`,
+  `reason`) and the verdict itself in `cause`. A `publish()` in the same position
+  is refused with a `PublishError` that carries the same `code` and `reason` and
+  `buffered: false`: nothing is held, because no `reconnected` will ever come to
+  replay it (§ *The publish buffer*) — the caller holds the only copy.
 
 **The library never ends the process, and never listens for a signal.** Ending
 it is the lifecycle owner's decision: a service typically logs and exits
@@ -570,8 +611,65 @@ buffered, because no retry and no reconnect declares the exchange (d.693).
 A publish that fails transiently (the connection is closing, a channel is being
 recreated, the broker did not confirm in time) is held in memory — bounded by
 `publishBufferMaxSize` messages and `publishBufferTtlMs` each — and replayed after
-the reconnect, critical priority first. `getBufferState()` reports it and
-`publish:buffered` / `buffer:flush:failed` announce it.
+the reconnect or after the broker unblocks the connection (below), critical priority first. `getBufferState()` reports it and
+`publish:buffered` / `buffer:flush:failed` announce it. That includes a publish whose
+confirm was still pending when the channel or the connection died under it (the broker
+closed it, restarted or stopped): the broker said nothing about that message, so it is
+transient, never a refusal — only a `nack` or a numbered close frame naming this send
+is permanent (d.1134).
+
+**One call can leave the buffer: `publish(queue, message, { bufferOnFailure: false })`.**
+It is for a caller that keeps the message durably elsewhere and must not have a second
+copy replayed behind its back — the orchestrator writing a `publish_pending` record
+(`docs/governance/confirmations/step-publish-failure.md` 001). On each of the four
+transient paths (retries exhausted, `publishRetryEnabled: false`, the reconnect a retry
+waited for failed, and a send channel the attempt could not get because the connection stayed
+down — the recovery it waited for ended in standby or fatal, or none may start: the client is
+permanently lost, closed by `disconnect()`, or has `reconnectEnabled: false`; B1, the owner's
+decision of 2026-10-06) the error `publish()` throws carries `buffered` (boolean): `true` only
+when the buffer holds the message for the next reconnect or `unblocked`, `false` when
+nothing will replay it. A permanent refusal never reaches the buffer and carries no `buffered`. A
+value that is not a boolean is refused before any attempt (`ValidationError`). Retry
+stays the library's either way — the option decides only what happens after it.
+
+The fourth path is its own class on the transport, `RecoveryEndedPublishError` (a
+`TransientPublishError`, exported under `publishErrors`): `PublishLayer` holds the message at
+once instead of retrying, because the next use of the client is what starts the next recovery
+cycle. It holds it **only where a `reconnected` can still come** — the class says so in
+`replayable`: after a spent cycle (standby) the message is held; once the client is permanently
+lost, closed by `disconnect()`, or has `reconnectEnabled: false`, nothing will ever replay it, so
+nothing is held and the error says `buffered: false` with the reason. When the recovery ended
+fatally the `PublishError` carries the verdict on top — `code: 'MQ_CONNECTION_FATAL'`, `reason` —
+and the verdict itself at the end of `cause`; a spent cycle carries no code.
+
+**Every failed publish says whether its frame left the client: `error.sent`** (boolean, on
+the `PublishError` from `publish()` and on its cause; conf
+`docs/governance/confirmations/mq-publish-buffer.md` 001). `true` when any attempt wrote the
+frame to the channel — the broker may hold it, and after a memory alarm deliver it, although
+the call failed; `false` when no attempt got that far. It says nothing about whether the
+broker stored the message. The buffer entry records the same fact, and it decides what
+happens when the outage ends:
+
+| The outage ends with | A held message whose frame was never sent | … whose frame was sent |
+|---|---|---|
+| a reconnect (`reconnected`) | re-sent | re-sent — the old socket and what the broker had not read are gone |
+| the broker unblocking the connection (`connection.unblocked`, end of a memory or disk alarm) | re-sent | dropped with a `warn` — the broker delivers the frames it held by itself |
+
+`connection.blocked` is logged as a `warn` with the broker's reason. **Nothing else flushes
+the buffer**: an outage of the publisher CHANNEL alone, on a connection that stays up and is
+not blocked, ends with neither event, so a message held during it is not replayed when the
+next publish recreates the channel. Whether a channel recovery should flush too is an open
+decision (a sent entry re-sent then may be a second copy), and the error `publish()` throws
+says the gap in as many words: buffered for up to `publishBufferTtlMs`, replayed only after a
+reconnect or `unblocked`, reported as LOST at expiry.
+
+A held message that outlives `publishBufferTtlMs` is dropped **at its TTL, on the buffer's own
+timer** — not whenever the buffer is next touched (until d.1275 the expiry ran only inside the
+next `add()`/`flush()`/`getBufferState()`, and was measured on the dev scheduler up to 88
+minutes late; d.1275). The timer runs on the client's timer rail, so `disconnect()` ends it. The
+drop is logged as an `error` naming its queue or exchange, the count, the age and `sent` —
+`sent=false` reads `LOST after <ms>` and is a message lost for good; `sent=true` reads `expired
+after <ms>`, because the broker may have delivered it on its own.
 
 **There is no persistent buffer, and `persistentBufferEnabled` /
 `persistentRedisClient` are refused by name.** They declared one until
@@ -616,11 +714,15 @@ error had never once run (fixed 2026-09-08, `errors.ConnectionError` now carries
 | `CONSUMER_QUEUE_MISSING` | the queue does not exist | start the service that owns the queue — a consumer never creates one |
 | `CONSUMER_DEAD_LETTER_ROUTE_MISSING` | the queue exists, `queueConfig` declares no dead-letter route for it | declare `x-dead-letter-exchange`/`-routing-key` for that queue and bind the destination; the queue itself is fine |
 | `MQ_CONNECTION_FATAL` (with `reason: 'broker-refused'`) | the BROKER refused this queue — 406 PRECONDITION-FAILED for a queue that exists with other arguments, 403/530 for one this account may not use | correct the topology or the permission the broker named in `error.cause`, then restart; retrying gets the same answer |
+| `MQ_CONNECTION_FATAL` (with `reason: 'cycles-spent' \| 'broker-refused'`, and `isConnectionFatal()` now `true`) | the CONNECTION is permanently lost — the recovery this `consume()` waited for ended the client, or the client was already lost; `error.cause` is the very verdict `onFatal` received (§ *permanently lost*) | the lifecycle owner stops the process; the restart policy boots a new one against a verified broker |
 
 The third one is the SAME verdict a refused connection carries (§ *permanently lost*),
 because it asks the lifecycle owner for the same thing: stop retrying. It refuses the
 QUEUE, not the connection — the client stays connected and `isConnectionFatal()` stays
-`false`. `@onlineapps/service-wrapper` reads `code` to end FÁZE 0.7 permanently; before
+`false`. The fourth is that connection verdict itself, carried onto the `consume()` that met
+it (one rail, `_carryVerdict()`): the code is on the error, not only in its `cause`, so
+`BaseClient` lets it through unchanged as it does every refusal with a verdict. A recovery
+cycle that merely ran out (standby) is no verdict and carries no code. `@onlineapps/service-wrapper` reads `code` to end FÁZE 0.7 permanently; before
 2026-09-16 a 406 on a queue carried no code at all, so the service kept booting against a
 queue it will never be allowed to declare.
 
@@ -716,6 +818,7 @@ topology.telemetryLogsQueue = 'mine';        // TypeError — the object is froz
 
 | Key | Name on the wire | Who publishes / who drains it |
 |---|---|---|
+| `infrastructureHealthChecksQueue` | `infrastructure.health.checks` | Every infrastructure service publishes its health checks there (`@onlineapps/infrastructure-tools` `healthPublisher.js`); the registry drains it (`api/infra/api_services_registry/src/listeners/infrastructureHealth.listener.js`). Composed here since d.1307; no reader cites it yet — `@onlineapps/service-common` still carries the literal (`src/defaults.js`), and which side switches is the owner's decision (d.1306). |
 | `infrastructureHealthEventsExchange` | `infrastructure.health.events` | Fanout. The registry publishes (`api/infra/api_services_registry/src/services/infrastructureEventPublisher.js`); the two queues below are bound to it. |
 | `monitoringInfrastructureHealthEventsQueue` | `monitoring.infrastructure.health.events` | The monitoring consumer's queue on that fanout (`api/infra/api_monitoring/src/consumer/topology.js`, `MONITORING_INFRA_EVENT_QUEUE`). |
 | `deliveryHealthEventsQueue` | `delivery.health.events` | The delivery endpoint binds it to the fanout and consumes it for WS push (`api/infra/api_delivery_endpoint/src/index.js`, `bindQueueToFanout(config.healthEventsQueue, …)`). |
@@ -724,6 +827,7 @@ topology.telemetryLogsQueue = 'mine';        // TypeError — the object is froz
 | `telemetryMetricsQueue` | `telemetry.metrics.queue` | The same exchange, the same consumer — metric samples. |
 | `telemetryTracesQueue` | `telemetry.traces.queue` | The same exchange, the same consumer — spans. |
 | `telemetryExchange` | `telemetry.exchange` | Topic exchange the three queues above are bound to; every telemetry producer publishes to it, and the monitoring consumer asserts it (d.708b). |
+| `workflowObserverCopyQueues` | `['monitoring.workflow', 'delivery.workflow.events', 'scheduler.workflow.events']` (frozen array) | The observers' copies of a run: the queues bound to `monitoring.workflow.fanout` for a reader that watches the run and is not part of it (the monitoring consumer, the delivery endpoint's WS feed, the scheduler's end-of-run watch). A dead letter from one of them is a lost copy of the run's telemetry, not a lost run (INFRA 559). Declared once in `queueConfig` (`WORKFLOW_OBSERVER_COPIES`) — membership cannot be read off an entry, because the binding is each consumer's own act at boot — and composed by `queueName()` (d.1336). |
 
 - **Frozen on purpose.** An importer must not be able to rewrite platform topology: a
   name overridden on one side of a fanout loses the events silently, which is why batch

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/mq-client-core",
-  "version": "5.0.0",
+  "version": "6.0.0",
   "description": "Core MQ client library for RabbitMQ - shared by infrastructure services and connectors",
   "oa": {
     "category": "connector"
@@ -23,7 +23,7 @@
   "author": "OnlineApps",
   "license": "MIT",
   "dependencies": {
-    "@onlineapps/logger-contract": "2.0.0",
+    "@onlineapps/logger-contract": "2.1.0",
     "@onlineapps/runtime-config": "1.2.0",
     "ajv": "^8.12.0",
     "amqplib": "0.10.9"

package/src/BaseClient.js

@@ -28,6 +28,7 @@ const {
   SerializationError,
   CONSUMER_QUEUE_MISSING,
   CONSUMER_DEAD_LETTER_ROUTE_MISSING,
+  carryVerdict,
 } = require('./utils/errorHandler');
 
 /**
@@ -110,6 +111,32 @@ const NOT_A_KEY_OF_THIS_CLIENT = Object.freeze({
       'The persistent buffer it fed is gone (see persistentBufferEnabled): it never wrote to '
       + 'Redis at all, so the client injected here was held and never used.',
   }),
+  /**
+   * Removed in d.1275 with the `health:shutdown` event they armed, on the owner's word
+   * (2026-10-06): "volbu i událost ZRUŠIT, žádný slib". After `criticalHealthShutdownDelay`
+   * of critical health the transport emitted `health:shutdown` and logged that it was
+   * "triggering shutdown" — but the library never ends the process (`_failFatally()` says
+   * why), and nothing in the repository listened: `@onlineapps/service-wrapper` dropped its
+   * listener on 2026-09-07, no infra service ever had one (measured 2026-10-06). The four
+   * questions of `change-discipline.md` § Removing are answered in CHANGELOG.md, in the release that removed them.
+   * Refused by name, not ignored: a caller writing `false` to silence the promise needs to
+   * hear that there is no promise left to silence.
+   */
+  criticalHealthShutdown: Object.freeze({
+    key: null,
+    what: 'a shutdown on sustained critical health',
+    consequence:
+      'The client reports critical health (health:critical, healthCriticalCallback) and decides '
+      + 'nothing about the process; the health:shutdown event this key armed reached no listener, '
+      + 'so it was removed. Ending the process is the lifecycle owner\'s decision (onFatal).',
+  }),
+  criticalHealthShutdownDelay: Object.freeze({
+    key: null,
+    what: 'the delay before a shutdown on sustained critical health',
+    consequence:
+      'It timed the health:shutdown event, which is gone (see criticalHealthShutdown): the client '
+      + 'reports critical health on every failing check and decides nothing about the process.',
+  }),
 });
 
 /**
@@ -370,6 +397,9 @@ class BaseClient {
    */
   async connect(options = {}) {
     if (this._connected) return;
+    // An explicit `connect()` builds a NEW transport below, so the verdict of the old one
+    // ends here — like `_closedByCaller` on the transport, it is undone by nothing else (d.1301).
+    this._fatalError = null;
 
     // `host` is the broker URL and carries the account password. It is redacted
     // on the way to the log — the only rail for that is utils/redactCredentials.
@@ -485,6 +515,30 @@ class BaseClient {
     }
   }
 
+  /**
+   * The one guard every operation on the broker runs first (d.1314; the predicate is
+   * d.1301's). It refuses only the two states where "connect()" is true advice — the client
+   * never connected, or the caller closed it with `disconnect()`. After `connection:fatal`
+   * it lets the call through to the transport, which knows that state and answers it with
+   * the verdict on top (`code: 'MQ_CONNECTION_FATAL'`, `reason`, the verdict as `cause`), so
+   * no second sentence about a lost connection is written here. Until d.1314 each of the
+   * eleven operations carried its own copy of this guard, nine of them still advising
+   * `connect()` after the verdict.
+   *
+   * @param {string} op - the public method asking, used in the sentence
+   * @param {string} [tail='.'] - what ends the Fix sentence
+   * @throws {ConnectionError}
+   * @private
+   */
+  _requireUsable(op, tail = '.') {
+    if (!this._transport || (!this._connected && !this._fatalError)) {
+      throw new ConnectionError(
+        `[BaseClient] Cannot ${op}: client is not connected - Expected: connect() to have completed. `
+          + `Fix: await client.connect() before ${op}()${tail}`
+      );
+    }
+  }
+
   /**
    * Publishes a message to the specified queue.
    * @param {string} queue - Target queue name.
@@ -494,17 +548,23 @@ class BaseClient {
    *   infrastructure or business queue is created by its owner before anything
    *   publishes to it, and an ownerless name is declared with the arguments the
    *   central `queueConfig` resolves (`transports/rabbitmqClient.js`, the 404 branch).
+   * @param {boolean} [options.bufferOnFailure=true] - `false` = a transiently failed message
+   *   is NOT held in the library's buffer, so no reconnect replays it; for a caller that keeps
+   *   the message durably elsewhere. Owned by `layers/PublishLayer.js`; a non-boolean is refused.
    * @returns {Promise<void>}
    * @throws {ConnectionError} If not connected.
-   * @throws {PublishError} If publish fails.
+   * @throws {PublishError} If publish fails. After a transient failure (retries exhausted,
+   *   retry disabled, the awaited reconnect failed) it carries `buffered` (boolean): `true`
+   *   only when the buffer holds the message for the next reconnect.
    */
   async publish(queue, message, options = {}) {
-    if (!this._connected || !this._transport) {
-      throw new ConnectionError(
-        '[BaseClient] Cannot publish: client is not connected - Expected: connect() to have completed. '
-          + 'Fix: await client.connect() before publish().'
-      );
-    }
+    // A client whose connection was declared LOST is not "not connected": `connect()` is
+    // exactly what its lifecycle owner must not be told to do (d.1301). The transport still
+    // exists and answers that state itself — a `RecoveryEndedPublishError` with the verdict
+    // on top and `buffered: false` (`_ensurePublisherChannel()`, d.1300/d.1301) — so the call
+    // is let through to it; this guard keeps only the two states where the advice is true:
+    // never connected, and closed by `disconnect()`.
+    this._requireUsable('publish');
 
     let buffer;
     try {
@@ -539,7 +599,7 @@ class BaseClient {
       // answer as d.297 one call over (`_consumerRefusal()`): name no likeliest
       // cause, carry the one actually caught. `cause` is unchanged, so a caller
       // deciding on the class still reads the object.
-      throw new PublishError(
+      const failure = new PublishError(
         `[BaseClient] Failed to publish to queue "${queue}": ${describeThrown(err)} - `
           + 'Expected: publish() to hand the message to the broker. '
           + 'Fix: act on the reason above — this layer does not know which failure it was, and naming the '
@@ -548,6 +608,25 @@ class BaseClient {
         queue,
         err
       );
+      // Whether the library's buffer holds the message is decided and written by
+      // `PublishLayer` (options.bufferOnFailure, d.1122); it is carried up here unchanged so
+      // the caller reads it on the error it catches. Absent when the failure never reached
+      // the buffer decision — "not asked" is not "false".
+      if (err && typeof err.buffered === 'boolean') {
+        failure.buffered = err.buffered;
+      }
+      // Whether any attempt wrote the frame (d.1145, conf `mq-publish-buffer` 001): carried
+      // like `buffered`, so the caller — the orchestrator's `publish_pending` record
+      // (`step-publish-failure` 003) — reads it on the error it catches.
+      if (err && typeof err.sent === 'boolean') {
+        failure.sent = err.sent;
+      }
+      // The verdict of a lost connection, carried like `buffered` and `sent` (d.1300, the
+      // publish half of d.1297): a publish whose recovery ended fatally reaches the caller
+      // with `code: 'MQ_CONNECTION_FATAL'` and `reason` on the error it catches — where the
+      // lifecycle owner reads them — not two `cause` down.
+      carryVerdict(failure, err);
+      throw failure;
     }
   }
 
@@ -597,12 +676,11 @@ class BaseClient {
    * @throws {ConsumeError} If consumer setup fails.
    */
   async consume(queue, messageHandler, options = {}) {
-    if (!this._connected || !this._transport) {
-      throw new ConnectionError(
-        '[BaseClient] Cannot consume: client is not connected - Expected: connect() to have completed. '
-          + 'Fix: await client.connect() before consume().'
-      );
-    }
+    // Same rule as `publish()` (d.1301): after `connection:fatal` the transport answers with
+    // the verdict on top (`_consumerChannelWithoutRecovery()`, d.1281/d.1297) and
+    // `_consumerRefusal()` lets it through unchanged; the "not connected" advice is kept
+    // for the two states where it is true.
+    this._requireUsable('consume');
 
     // Apply prefetch and noAck overrides if provided
     const { prefetch, noAck } = options;
@@ -880,12 +958,7 @@ class BaseClient {
    * @returns {Promise<Object>}
    */
   async assertQueue(queue, options = {}) {
-    if (!this._connected || !this._transport) {
-      throw new ConnectionError(
-        '[BaseClient] Cannot assertQueue: client is not connected - Expected: connect() to have completed. '
-          + 'Fix: await client.connect() before assertQueue().'
-      );
-    }
+    this._requireUsable('assertQueue');
     if (typeof this._transport.assertQueue !== 'function') {
       throw new Error(
         '[BaseClient] Transport does not support assertQueue(queue, options) - Expected: a transport implementing assertQueue. '
@@ -913,12 +986,7 @@ class BaseClient {
    * @throws {ValidationError} If the name or type cannot declare an exchange.
    */
   async assertExchange(exchange, type, options = {}) {
-    if (!this._connected || !this._transport) {
-      throw new ConnectionError(
-        '[BaseClient] Cannot assertExchange: client is not connected - Expected: connect() to have completed. '
-          + 'Fix: await client.connect() before assertExchange().'
-      );
-    }
+    this._requireUsable('assertExchange');
     return await this._transport.assertExchange(exchange, type, options);
   }
 
@@ -934,12 +1002,7 @@ class BaseClient {
    * @throws {ValidationError} If a name or the pattern cannot form a binding.
    */
   async bindQueue(queue, exchange, pattern) {
-    if (!this._connected || !this._transport) {
-      throw new ConnectionError(
-        '[BaseClient] Cannot bindQueue: client is not connected - Expected: connect() to have completed. '
-          + 'Fix: await client.connect() before bindQueue().'
-      );
-    }
+    this._requireUsable('bindQueue');
     return await this._transport.bindQueue(queue, exchange, pattern);
   }
 
@@ -956,12 +1019,7 @@ class BaseClient {
    * @throws {ValidationError} If this client holds no such consumer.
    */
   async cancelConsumer(consumerTagOrQueue) {
-    if (!this._connected || !this._transport) {
-      throw new ConnectionError(
-        '[BaseClient] Cannot cancelConsumer: client is not connected - Expected: connect() to have completed. '
-          + 'Fix: await client.connect() before cancelConsumer().'
-      );
-    }
+    this._requireUsable('cancelConsumer');
     return await this._transport.cancelConsumer(consumerTagOrQueue);
   }
 
@@ -971,12 +1029,7 @@ class BaseClient {
    * @returns {Promise<Object>}
    */
   async checkQueue(queue) {
-    if (!this._connected || !this._transport) {
-      throw new ConnectionError(
-        '[BaseClient] Cannot checkQueue: client is not connected - Expected: connect() to have completed. '
-          + 'Fix: await client.connect() before checkQueue().'
-      );
-    }
+    this._requireUsable('checkQueue');
     if (typeof this._transport.checkQueue !== 'function') {
       throw new Error(
         '[BaseClient] Transport does not support checkQueue(queue) - Expected: a transport implementing checkQueue. '
@@ -992,12 +1045,7 @@ class BaseClient {
    * @returns {Promise<Object>}
    */
   async purgeQueue(queue) {
-    if (!this._connected || !this._transport) {
-      throw new ConnectionError(
-        '[BaseClient] Cannot purgeQueue: client is not connected - Expected: connect() to have completed. '
-          + 'Fix: await client.connect() before purgeQueue().'
-      );
-    }
+    this._requireUsable('purgeQueue');
     if (typeof this._transport.purgeQueue !== 'function') {
       throw new Error(
         '[BaseClient] Transport does not support purgeQueue(queue) - Expected: a transport implementing purgeQueue. '
@@ -1014,12 +1062,7 @@ class BaseClient {
    * @returns {Promise<Object>}
    */
   async deleteQueue(queue, options = {}) {
-    if (!this._connected || !this._transport) {
-      throw new ConnectionError(
-        '[BaseClient] Cannot deleteQueue: client is not connected - Expected: connect() to have completed. '
-          + 'Fix: await client.connect() before deleteQueue().'
-      );
-    }
+    this._requireUsable('deleteQueue');
     if (typeof this._transport.deleteQueue !== 'function') {
       throw new Error(
         '[BaseClient] Transport does not support deleteQueue(queue, options) - Expected: a transport implementing deleteQueue. '
@@ -1049,12 +1092,7 @@ class BaseClient {
    * @returns {Promise<void>}
    */
   async ack(msg) {
-    if (!this._connected || !this._transport) {
-      throw new ConnectionError(
-        '[BaseClient] Cannot ack: client is not connected - Expected: connect() to have completed. '
-          + 'Fix: await client.connect() before ack(); a message received before a reconnect can no longer be acked.'
-      );
-    }
+    this._requireUsable('ack', '; a message received before a reconnect can no longer be acked.');
     if (typeof this._transport.ack !== 'function') {
       throw new Error(
         '[BaseClient] Transport does not support ack(msg) - Expected: a transport implementing ack. '
@@ -1076,12 +1114,7 @@ class BaseClient {
    * @returns {Promise<void>}
    */
   async nack(msg, options = {}) {
-    if (!this._connected || !this._transport) {
-      throw new ConnectionError(
-        '[BaseClient] Cannot nack: client is not connected - Expected: connect() to have completed. '
-          + 'Fix: await client.connect() before nack(); a message received before a reconnect can no longer be nacked.'
-      );
-    }
+    this._requireUsable('nack', '; a message received before a reconnect can no longer be nacked.');
     if (typeof this._transport.nack !== 'function') {
       throw new Error(
         '[BaseClient] Transport does not support nack(msg, options) - Expected: a transport implementing nack. '