@onlineapps/mq-client-core 2.0.1 → 3.0.0

package/src/BaseClient.js

@@ -7,32 +7,288 @@
  */
 
 const Ajv = require('ajv');
-const merge = require('lodash.merge');
+const { assertLogger } = require('@onlineapps/logger-contract');
 
 const configSchema = require('./config/configSchema');
 const defaultConfig = require('./config/defaultConfig');
+const composeConfig = require('./config/composeConfig');
 const runtimeCfg = require('./config');
 const transportFactory = require('./transports/transportFactory');
 const serializer = require('./utils/serializer');
+const { redactConnectionTarget } = require('./utils/redactCredentials');
+const { nameUnknownKeys } = require('./utils/nearestKey');
+// The one rail for monitoring publishes in this package; a dead-letter event
+// travels it like every other monitoring event, never on a second path.
+const { publishToMonitoringWorkflow } = require('./monitoring-publish');
 const {
   ConnectionError,
   PublishError,
   ConsumeError,
   ValidationError,
   SerializationError,
+  CONSUMER_QUEUE_MISSING,
+  CONSUMER_DEAD_LETTER_ROUTE_MISSING,
 } = require('./utils/errorHandler');
 
+/**
+ * Names that are NOT keys of this client.
+ *
+ * An entry either names the key the value belongs under (`key`), or says the
+ * concept itself is gone (`key: null`). Both are refused where the caller wrote
+ * them, by one loop, because it is one concern — a name this client does not
+ * read, answered before its value can be lost in silence.
+ *
+ * `url` is `@onlineapps/conn-infra-mq`'s name for the broker URL (its
+ * `ConnectorMQClient` JSDoc documents `config.url`); this client's name is `host`.
+ * Until 2026-09-14 the transport read the two keys as `host || url`, and the
+ * right-hand side was unreachable: `host` is required by the schema and
+ * resolved from `RABBITMQ_URL` when the caller omits it (`./config.js`). So a
+ * caller who wrote `url` connected to whatever the environment said, and their
+ * value was dropped without a word.
+ *
+ * The key is not accepted as an alias — one concern, one rail
+ * (`change-discipline.md`). Leaving it undeclared would refuse it since d.291b
+ * (`config/configSchema.js` ends with `additionalProperties: false`), but it
+ * would refuse it as an unknown NAME: the schema can say the key does not exist,
+ * it cannot say which key the value belongs under. That sentence is the whole
+ * point of this list, so the list stays, ahead of the schema rather than beside
+ * it — every name it does not know falls through and is answered by Ajv
+ * (`architecture-principles.md` §3, §4, §5). It is checked BEFORE the schema and
+ * before the runtime resolution of `host`, so the answer is about the config the
+ * caller wrote rather than about the environment the process happens to run in.
+ */
+const NOT_A_KEY_OF_THIS_CLIENT = Object.freeze({
+  url: Object.freeze({
+    key: 'host',
+    what: 'the broker URL',
+    consequence:
+      'This client never reads "url", so the value written under it would be discarded and the '
+      + 'connection made with RABBITMQ_URL instead.',
+  }),
+  /**
+   * Renamed in d.299, and refused by name rather than accepted as an alias: the
+   * number bounds every ANSWER this client waits for from the broker — the publish
+   * confirm AND the close-ok of each handle `disconnect()` closes (d.283) — so a
+   * name owned by one of its two consumers made the other invisible. An alias
+   * would be the transition shim `architecture-principles.md` §11 forbids; a
+   * silent drop would repeat exactly what `url` did.
+   */
+  publishConfirmationTimeout: Object.freeze({
+    key: 'brokerAnswerTimeout',
+    what: 'the budget for an answer from the broker',
+    consequence:
+      'The key was renamed: it bounds the publish confirm AND the close-ok of every handle '
+      + 'disconnect() closes, so it no longer carries the name of one of the two. A value written '
+      + 'under the old name would be ignored and the default used instead.',
+  }),
+  /**
+   * Removed in d.343 with the mechanism they declared, and refused by name
+   * rather than quietly ignored. `buffer/RedisBuffer.js` was a stub: its `add()`
+   * and `flush()` stored and returned nothing, so `persistentBufferEnabled:
+   * true` sent every critical-priority message that failed transiently into it
+   * and the message was DROPPED — the opposite of what the key promised. That is
+   * a declaration with no mechanism (`automation-gates.md` §5).
+   * @see docs/architecture/mq-publish-reliability.md — the node that owns the
+   * publish-reliability model, and the buffering it describes. Nothing in the
+   * platform ever set either key outside a test (measured across `api`,
+   * `api_biz`, `infra`, `fe_adminui`, 2026-09-14). A silent drop would leave a
+   * caller believing in persistence that never existed, which is exactly the
+   * failure `url` taught this list.
+   */
+  persistentBufferEnabled: Object.freeze({
+    key: null,
+    what: 'a publish buffer that survives a process restart',
+    consequence:
+      'This client has ONE buffer, the in-memory one (publishBufferMaxSize / publishBufferTtlMs). '
+      + 'The Redis buffer this key switched on stored nothing, so the critical messages it was '
+      + 'meant to protect were dropped instead of buffered.',
+  }),
+  persistentRedisClient: Object.freeze({
+    key: null,
+    what: 'the Redis client of a persistent publish buffer',
+    consequence:
+      '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.',
+  }),
+});
+
+/**
+ * The whole sentence for a name this client does not read.
+ *
+ * A helper rather than two branches at the throw site: the message contract
+ * (`tests/unit/error-message-contract.test.js`) reads every caller-facing
+ * construction and can only see that it opens with `[Context]` when the sentence
+ * is one literal or one named helper. Two facts, two sentences — the value
+ * belongs under another name, or the thing it configured no longer exists — and
+ * both open the same way (`architecture-principles.md` §5).
+ *
+ * @param {string} written - the key the caller wrote
+ * @param {{key: string|null, what: string, consequence: string}} meant
+ * @returns {string}
+ */
+function notAKeyOfThisClientMessage(written, meant) {
+  if (meant.key === null) {
+    return `[BaseClient] Configuration key "${written}" does not exist - Expected: no such key; `
+      + `${meant.what} is not something this client has. `
+      + `Fix: remove "${written}" from the configuration. ${meant.consequence}`;
+  }
+  return `[BaseClient] Configuration key "${written}" does not exist - Expected: ${meant.what} under "${meant.key}". `
+    + `Fix: rename "${written}" to "${meant.key}". ${meant.consequence}`;
+}
+
+/**
+ * The whole sentence for a config Ajv rejected.
+ *
+ * One helper and one throw site, for the reason `notAKeyOfThisClientMessage()`
+ * exists: the message contract (`tests/unit/error-message-contract.test.js`) can
+ * only see that a construction opens with `[Context]` when its argument is one
+ * literal or one named helper.
+ *
+ * Two shapes, because the two failures are read by different people. A wrong
+ * TYPE on a declared key is a value problem — the paths in `error.details` are
+ * what the caller acts on. An UNDECLARED key is a name problem, and the name has
+ * to be in the sentence: the caller believes they configured something, and
+ * nothing in `error.details` tells them that the key was never read
+ * (`architecture-principles.md` §5).
+ *
+ * @param {string[]} unknownKeys - Keys no side of the schema declares; may be empty.
+ * @param {string[]} declaredKeys - Every key the schema declares, subclass keys included.
+ * @returns {string}
+ */
+function invalidConfigurationMessage(unknownKeys, declaredKeys) {
+  if (unknownKeys.length === 0) {
+    return '[BaseClient] Invalid configuration - Expected: the constructor config to satisfy the client schema. '
+      + 'Fix: correct the fields listed in error.details, each of which names its path and the reason it was rejected.';
+  }
+
+  const named = nameUnknownKeys(unknownKeys, declaredKeys);
+
+  return `[BaseClient] Configuration key not declared by this client: ${named} - `
+    + `Expected: only the keys src/config/configSchema.js declares and the ones a subclass adds through `
+    + `super(config, extraProperties) - ${declaredKeys.length} in total for this client. `
+    + 'Fix: correct the spelling, or remove the key - a key this client does not read configures nothing, '
+    + 'and the value written under it is lost in silence. A key that belongs to a subclass is declared in '
+    + 'that subclass schema, never here.';
+}
+
+/**
+ * The schema this construction validates against: the library's own, plus the
+ * properties a SUBCLASS declares.
+ *
+ * The one place a subclass extends the configuration contract. `ConnectorMQClient`
+ * (`@onlineapps/conn-infra-mq`) hands the caller's config straight to `super()` and
+ * then reads four keys of its own off the same `this._config`; the library cannot
+ * declare those — they configure mechanisms that live there — and that package must
+ * not declare the library's, or one type and one description would exist twice and
+ * be free to drift (`change-discipline.md` § One rail per concern). So each side
+ * declares what it owns, and the subclass passes its half here.
+ *
+ * A subclass REDECLARING a library key is refused rather than merged: silently
+ * letting the subclass win would be exactly the second rail this argument exists to
+ * avoid, and silently letting the library win would leave the subclass author
+ * believing a type they wrote is in force.
+ *
+ * The library schema is never mutated — a subclass must not change what every other
+ * caller of this client is validated against.
+ *
+ * @param {Object|null} extraProperties - JSON Schema `properties` of the subclass.
+ * @returns {Object} The schema to compile.
+ * @throws {ValidationError} If the argument is not a plain object of properties, or
+ *   redeclares a key the library already owns.
+ */
+function schemaWithSubclassProperties(extraProperties) {
+  if (extraProperties === null || extraProperties === undefined) {
+    return configSchema;
+  }
+
+  if (typeof extraProperties !== 'object' || Array.isArray(extraProperties)) {
+    throw new ValidationError(
+      '[BaseClient] Subclass configuration properties must be an object - '
+        + 'Expected: the `properties` object of the subclass JSON Schema as the second constructor argument, '
+        + 'or nothing at all. '
+        + `Fix: pass \`super(config, mySchema.properties)\`; received ${Array.isArray(extraProperties) ? 'an array' : typeof extraProperties}.`
+    );
+  }
+
+  for (const key of Object.keys(extraProperties)) {
+    if (Object.prototype.hasOwnProperty.call(configSchema.properties, key)) {
+      throw new ValidationError(
+        `[BaseClient] Subclass configuration property "${key}" is already declared by this client - `
+          + 'Expected: a subclass declares only the keys it reads itself, so one key keeps one type, one '
+          + 'description and one owner. '
+          + `Fix: remove "${key}" from the subclass schema and read it from src/config/configSchema.js, `
+          + 'or rename the subclass key if it means something else.'
+      );
+    }
+  }
+
+  return {
+    ...configSchema,
+    properties: { ...configSchema.properties, ...extraProperties }
+  };
+}
+
 class BaseClient {
   /**
    * @param {Object} config - User-supplied configuration.
-   * @throws {ValidationError} If required fields are missing or invalid.
+   * @param {Object} [extraProperties] - JSON Schema `properties` a SUBCLASS declares
+   *   for the keys IT reads off the same config object. The one place the
+   *   configuration contract is extended; see `schemaWithSubclassProperties()`.
+   *   A direct caller of this client passes nothing.
+   * @throws {ValidationError} If required fields are missing or invalid, if a key
+   *   neither side declares is present, or if the subclass declaration is malformed.
    */
-  constructor(config) {
-    const ajv = new Ajv({ allErrors: true, useDefaults: true });
-    const validate = ajv.compile(configSchema);
+  constructor(config, extraProperties = null) {
+    // The client reports its whole connection lifecycle and every consumer it
+    // registers. Until 2026-09-07 it wrote those to `console` while `config.logger`
+    // sat in the schema unused — an ambient channel no service configures and no
+    // collector attributes. Owner confirmation
+    // `docs/governance/confirmations/connector-logger-contract.md` 001/003.
+    // Validated BEFORE the schema, so the caller gets the actionable contract
+    // message rather than a generic Ajv complaint about a missing property.
+    this._logger = assertLogger(
+      'BaseClient',
+      config && config.logger,
+      'the client reports its connection lifecycle and every consumer it registers',
+      'pass config.logger (the logger your service already built)'
+    );
+
+    // A name this client does not read, refused before its value can be lost
+    // (see NOT_A_KEY_OF_THIS_CLIENT above).
+    for (const [written, meant] of Object.entries(NOT_A_KEY_OF_THIS_CLIENT)) {
+      if (config && Object.prototype.hasOwnProperty.call(config, written)) {
+        throw new ValidationError(
+          notAKeyOfThisClientMessage(written, meant),
+          [{
+            path: `/${written}`,
+            message: meant.key === null
+              ? `does not exist; ${meant.what} was removed`
+              : `does not exist; ${meant.what} is "${meant.key}"`
+          }]
+        );
+      }
+    }
 
-    // Merge user config with defaults
-    this._config = merge({}, defaultConfig, config || {});
+    // `allErrors` so a wrong config hears about every offending key at once
+    // rather than one per attempt. NO `useDefaults`: it arrived with the library's
+    // extraction (`7a47b2fa`, 2025-11-18) and never had anything to write —
+    // `config/configSchema.js` declares no `default` on any property, on purpose
+    // and under a test, because every default has an owner in
+    // `config/defaultConfig.js`, composed BEFORE this validation runs. A switch
+    // that writes nothing is not harmless: it is a standing invitation to answer
+    // "where do I put this default?" with a second rail (`automation-gates.md` §5,
+    // `change-discipline.md` § One rail per concern).
+    // The library's own declaration, plus the subclass's if there is one. Compiled
+    // per construction, like the schema it replaced: a subclass's properties are an
+    // argument, so there is no one schema to compile once.
+    const schema = schemaWithSubclassProperties(extraProperties);
+    const ajv = new Ajv({ allErrors: true });
+    const validate = ajv.compile(schema);
+
+    // The module defaults, then what the caller wrote. Composed SHALLOWLY and
+    // by reference: an injected dependency has to arrive as the object it was
+    // injected as, not as a deep copy of it (`config/composeConfig.js`).
+    this._config = composeConfig(defaultConfig, config);
 
     // Resolve runtime config (FAIL-FAST for host)
     const resolved = runtimeCfg.resolve({
@@ -51,16 +307,33 @@ class BaseClient {
     // Validate merged config
     const valid = validate(this._config);
     if (!valid) {
-      const details = validate.errors.map((err) => ({
-        path: err.instancePath,
-        message: err.message,
-      }));
-      throw new ValidationError('Invalid configuration', details);
+      // An undeclared key is reported by Ajv against the OBJECT (`instancePath: ''`)
+      // with the offending name in `params`, so it is unpacked here: a caller acting
+      // on `error.details` needs the path of the key they wrote, exactly as for a
+      // wrong type one line below.
+      const details = validate.errors.map((err) => (
+        err.keyword === 'additionalProperties'
+          ? {
+            path: `/${err.params.additionalProperty}`,
+            message: 'is not a configuration key of this client',
+          }
+          : { path: err.instancePath, message: err.message }
+      ));
+      const unknownKeys = validate.errors
+        .filter((err) => err.keyword === 'additionalProperties')
+        .map((err) => err.params.additionalProperty);
+
+      throw new ValidationError(
+        invalidConfigurationMessage(unknownKeys, Object.keys(schema.properties)),
+        details
+      );
     }
 
     this._transport = null;
     this._connected = false;
     this._errorHandlers = [];
+    this._fatalHandlers = [];
+    this._fatalError = null;
 
     BaseClient._registerInstance(this);
   }
@@ -74,9 +347,14 @@ class BaseClient {
   async connect(options = {}) {
     if (this._connected) return;
 
-    console.log(`[BaseClient] Starting connect() with config:`, JSON.stringify({ type: this._config.type, host: this._config.host }));
-    // Merge overrides into existing config
-    this._config = merge({}, this._config, options);
+    // `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.
+    this._logger.debug('[BaseClient] Starting connect()', {
+      type: this._config.type,
+      host: redactConnectionTarget(this._config.host),
+    });
+    // Overrides compose the same way as the constructor's sources do.
+    this._config = composeConfig(this._config, options);
     // Ensure runtime-derived values are applied (options can override explicitly)
     const resolved = runtimeCfg.resolve({
       host: this._config.host,
@@ -90,20 +368,38 @@ class BaseClient {
       `${resolved.serviceName}:${process.pid}`;
 
     try {
-      console.log(`[BaseClient] Creating transport...`);
-      // Instantiate appropriate transport: RabbitMQClient 
+      this._logger.debug('[BaseClient] Creating transport');
+      // Instantiate appropriate transport: RabbitMQClient. `this._config` carries
+      // the validated logger, so the transport logs through the same channel —
+      // it builds none of its own.
       this._transport = transportFactory.create(this._config);
-      console.log(`[BaseClient] Transport created:`, this._transport.constructor.name);
+      this._logger.debug('[BaseClient] Transport created', {
+        transport: this._transport.constructor.name,
+      });
 
       // Register internal error propagation
       this._transport.on('error', (err) => this._handleError(err));
 
-      console.log(`[BaseClient] Calling transport.connect()...`);
+      // The connection is permanently lost: the transport spent its whole
+      // recovery budget and will not try again. Flip the connected flag FIRST —
+      // publish/consume must refuse rather than block on a recovery that is not
+      // coming — and only then tell the owner.
+      this._transport.on('connection:fatal', (err) => {
+        this._connected = false;
+        this._fatalError = err;
+        this._handleFatal(err);
+      });
+
+      this._logger.debug('[BaseClient] Calling transport.connect()');
       await this._transport.connect(this._config);
-      console.log(`[BaseClient] Transport connected successfully`);
+      this._logger.info('[BaseClient] Transport connected successfully');
       this._connected = true;
     } catch (err) {
-      throw new ConnectionError('Failed to connect to broker', err);
+      throw new ConnectionError(
+        '[BaseClient] Failed to connect to broker - Expected: a reachable broker at the configured host. '
+          + 'Fix: read error.cause for the transport reason, then check the MQ url, credentials and network the service was started with.',
+        err
+      );
     }
   }
 
@@ -113,14 +409,27 @@ class BaseClient {
    * @throws {Error} If disconnecting fails unexpectedly.
    */
   async disconnect() {
-    if (!this._connected || !this._transport) return;
+    // Keyed on the TRANSPORT, not on `_connected`: since the fatal signal
+    // clears `_connected`, a client whose connection is permanently lost still
+    // owns a transport holding timers and listeners, and must still be
+    // tearable-down. Keying on `_connected` would have made that teardown a
+    // silent no-op.
+    if (!this._transport) {
+      this._connected = false;
+      BaseClient._unregisterInstance(this);
+      return;
+    }
     try {
       await this._transport.disconnect();
       this._connected = false;
       this._transport = null;
       BaseClient._unregisterInstance(this);
     } catch (err) {
-      throw new Error(`Error during disconnect: ${err.message}`);
+      throw new ConnectionError(
+        '[BaseClient] Failed to disconnect from broker - Expected: the transport to close its connection cleanly. '
+          + 'Fix: read error.cause for the transport reason; the client stays marked connected, so call disconnect() again before reusing it.',
+        err
+      );
     }
   }
 
@@ -128,14 +437,21 @@ class BaseClient {
    * Publishes a message to the specified queue.
    * @param {string} queue - Target queue name.
    * @param {Object|Buffer|string} message - Payload to send.
-   * @param {Object} [options] - RabbitMQ-specific overrides (routingKey, persistent, headers, queueOptions).
+   * @param {Object} [options] - RabbitMQ-specific overrides (routingKey, persistent, headers).
+   *   Not `queueOptions`: a publisher never declares a queue's arguments. An
+   *   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).
    * @returns {Promise<void>}
    * @throws {ConnectionError} If not connected.
    * @throws {PublishError} If publish fails.
    */
   async publish(queue, message, options = {}) {
     if (!this._connected || !this._transport) {
-      throw new ConnectionError('Cannot publish: client is not connected');
+      throw new ConnectionError(
+        '[BaseClient] Cannot publish: client is not connected - Expected: connect() to have completed. '
+          + 'Fix: await client.connect() before publish().'
+      );
     }
 
     let buffer;
@@ -149,28 +465,69 @@ class BaseClient {
         buffer = Buffer.from(json, 'utf8');
       }
     } catch (err) {
-      throw new SerializationError('Failed to serialize message', message, err);
+      throw new SerializationError(
+        '[BaseClient] Failed to serialize message - Expected: a JSON-serializable payload, a string or a Buffer. '
+          + 'Fix: read error.cause for the reason (circular reference, BigInt, …) and error.payload for the value that was rejected.',
+        message,
+        err
+      );
     }
 
     try {
       await this._transport.publish(queue, buffer, options);
     } catch (err) {
-      throw new PublishError(`Failed to publish to queue "${queue}"`, queue, err);
+      throw new PublishError(
+        `[BaseClient] Failed to publish to queue "${queue}" - Expected: the queue to exist and the channel to be open. `
+          + 'Fix: read error.cause for the broker reason; error.queue names the target queue.',
+        queue,
+        err
+      );
     }
   }
 
   /**
    * Begins consuming messages from the specified queue.
+   *
+   * A handler that throws does NOT get an unconditional requeue: the delivery
+   * policy counts the attempt, gives the message one more if the error is
+   * transient and the budget allows, and otherwise rejects it into the
+   * dead-letter queue the broker routes for this queue (`<svc>.dlq`), publishing
+   * a `message_dlq` event. The full contract is in the README
+   * (§ `consume()` — the delivery contract) and in `config/deliveryPolicy.js`.
+   *
+   * That policy needs somewhere to reject TO, so `consume()` REFUSES a queue for
+   * which `queueConfig` declares no `x-dead-letter-exchange`/`-routing-key` — at
+   * registration, before a consumer is attached, with no opt-out (d.259). On such
+   * a queue the broker drops a rejected message instead of moving it, so the
+   * `message_dlq` event would report a destination nothing routed to. The fix is
+   * always to declare the route, never to consume without one.
+   *
    * @param {string} queue - Name of the queue to consume from.
-   * @param {function(Object): Promise<void>} messageHandler - Async function to process each message.
+   * @param {function(Object, {attempt: number, maxAttempts: number, isFinalAttempt: boolean}): Promise<void>} messageHandler -
+   *   Async function to process each message. Its second argument says which
+   *   attempt this delivery is, so a side effect that must happen once — an RPC
+   *   error reply above all — happens on the final attempt only, not on every
+   *   redelivery. A handler declaring one parameter simply ignores it.
    * @param {Object} [options] - RabbitMQ-specific overrides (prefetch, noAck, queueOptions).
+   * @param {number} [options.maxAttempts] - How many times the handler may run for ONE
+   *   message before it is rejected into the dead-letter queue. Omitted → the module
+   *   default (`RABBITMQ_MAX_DELIVERY_ATTEMPTS`, then `defaults.js maxDeliveryAttempts`).
+   *   An integer >= 1, refused at entry otherwise.
+   * @param {function(Error): ('transient'|'permanent')} [options.classify] - Error
+   *   classifier. Omitted → every error is transient, so a permanent failure still
+   *   reaches the dead-letter queue, after `maxAttempts` attempts instead of one.
+   *   `permanent` rejects on the first failure.
    * @returns {Promise<void>}
    * @throws {ConnectionError} If not connected.
+   * @throws {ValidationError} If `maxAttempts` or `classify` cannot bound a delivery.
    * @throws {ConsumeError} If consumer setup fails.
    */
   async consume(queue, messageHandler, options = {}) {
     if (!this._connected || !this._transport) {
-      throw new ConnectionError('Cannot consume: client is not connected');
+      throw new ConnectionError(
+        '[BaseClient] Cannot consume: client is not connected - Expected: connect() to have completed. '
+          + 'Fix: await client.connect() before consume().'
+      );
     }
 
     // Apply prefetch and noAck overrides if provided
@@ -179,26 +536,204 @@ class BaseClient {
     if (typeof prefetch === 'number') consumeOptions.prefetch = prefetch;
     if (typeof noAck === 'boolean') consumeOptions.noAck = noAck;
     if (options.queueOptions) consumeOptions.queueOptions = options.queueOptions;
+    // Forwarded untouched, including their absence: the transport owns the
+    // validation and the module default, so there is exactly one place where a
+    // delivery budget is decided (`config/deliveryPolicy.js`).
+    if (options.maxAttempts !== undefined) consumeOptions.maxAttempts = options.maxAttempts;
+    if (options.classify !== undefined) consumeOptions.classify = options.classify;
+    // Same rule, same reason: `requeueOnError` is a statement ABOUT the delivery
+    // budget, so it is resolved where the budget is (`config/deliveryPolicy.js`,
+    // applied in the transport), not folded into a second number here.
+    if (options.requeueOnError !== undefined) consumeOptions.requeueOnError = options.requeueOnError;
+    // The monitoring rail belongs to this layer, not to the transport: the
+    // transport knows the broker, this client knows the service it speaks for
+    // and the queue monitoring events travel on.
+    consumeOptions.onDeadLetter = (event) => this._emitDeadLetterEvent(event);
 
     // CRITICAL: Log all consume() calls for transparency
-    console.log(`[BaseClient] [CONSUMER] Starting consume() for queue: ${queue} at ${new Date().toISOString()}`);
-    console.log(`[BaseClient] [CONSUMER] Options:`, JSON.stringify(consumeOptions, null, 2));
-    console.log(`[BaseClient] [CONSUMER] Transport type: ${this._transport?.constructor?.name || 'unknown'}`);
-    console.log(`[BaseClient] [CONSUMER] Connected: ${this._connected}`);
+    this._logger.info(`[BaseClient] [CONSUMER] Starting consume() for queue: ${queue}`, {
+      queue,
+    });
+    this._logger.debug(`[BaseClient] [CONSUMER] Consumer setup for queue: ${queue}`, {
+      queue,
+      options: consumeOptions,
+      transport: this._transport?.constructor?.name || 'unknown',
+      connected: this._connected,
+    });
 
     try {
       const consumeStartTime = Date.now();
       // Delegate message lifecycle (ack/nack/requeue) to the transport layer.
       // BaseClient only provides a broker-agnostic surface; transport decides how to handle handler errors.
-      await this._transport.consume(queue, async (msg) => messageHandler(msg), consumeOptions);
+      const consumerTag = await this._transport.consume(
+        queue,
+        async (msg, delivery) => messageHandler(msg, delivery),
+        consumeOptions
+      );
       const consumeEndTime = Date.now();
-      console.log(`[BaseClient] [CONSUMER] ✓ consume() completed for queue: ${queue} (took ${consumeEndTime - consumeStartTime}ms)`);
+      this._logger.info(`[BaseClient] [CONSUMER] ✓ consume() completed for queue: ${queue}`, {
+        queue,
+        durationMs: consumeEndTime - consumeStartTime,
+      });
+      // The broker's name for this consumer, handed back so the caller has
+      // something to pass to `cancelConsumer()`. Without it the tag existed
+      // inside the transport alone and the L8 cancel-by-tag half of the contract
+      // had no way to be used.
+      return consumerTag;
     } catch (err) {
-      console.error(`[BaseClient] [CONSUMER] ✗ consume() failed for queue: ${queue}`, err.message);
-      throw new ConsumeError(`Failed to start consumer for queue "${queue}"`, queue, err);
+      // The failure is not logged here: it is rethrown as a ConsumeError carrying
+      // the cause, and a rethrown error is logged by whoever stops handling it
+      // (confirmation connector-logger-contract 003).
+      throw this._consumerRefusal(queue, err);
     }
   }
 
+  /**
+   * Turn whatever stopped a consumer from starting into a refusal that says WHY.
+   *
+   * Until d.297 this was one sentence for every failure: "Expected: the queue to
+   * exist before consume() attaches to it … a missing queue is created by the
+   * service that owns it, never by the consumer." For a queue that genuinely does
+   * not exist it is true. For the OTHER refusal the same call makes — d.259, a
+   * queue for which `queueConfig` declares no dead-letter route — it is false in
+   * every clause: the queue exists, creating it changes nothing, and the owning
+   * service is not who has to act. The true sentence sat in `error.cause`, where
+   * a log line does not look, so the reader was sent to fix a thing that was not
+   * broken.
+   *
+   * Two classes, two sentences, each recognised by the transport's `code` rather
+   * than by its wording (`utils/errorHandler.js`, README § errors and errorCodes).
+   * Everything else gets a third sentence that claims NO cause and points at the
+   * one that knows: an invented likeliest-sounding reason is worse than an honest
+   * "read the cause", because it is acted upon (`architecture-principles.md` §5).
+   *
+   * @param {string} queue
+   * @param {Error} err - what the transport threw
+   * @returns {ConsumeError}
+   * @private
+   */
+  _consumerRefusal(queue, err) {
+    const code = err && err.code;
+
+    if (code === CONSUMER_DEAD_LETTER_ROUTE_MISSING) {
+      return new ConsumeError(
+        `[BaseClient] Cannot consume from queue "${queue}": queueConfig declares no dead-letter route for it - `
+          + 'Expected: the queue to declare x-dead-letter-exchange and x-dead-letter-routing-key, because the '
+          + 'delivery policy ends a spent message with nack(requeue=false) and the broker drops it where there '
+          + 'is nowhere to move it to. '
+          + 'Fix: declare the route in the section of src/config/queueConfig.js that owns this queue, and bind the queue that '
+          + 'receives it, or consume a queue that already declares one. The queue itself is fine — creating or '
+          + 'recreating it changes nothing.',
+        queue,
+        err,
+        CONSUMER_DEAD_LETTER_ROUTE_MISSING
+      );
+    }
+
+    if (code === CONSUMER_QUEUE_MISSING) {
+      return new ConsumeError(
+        `[BaseClient] Cannot consume from queue "${queue}": the queue does not exist - `
+          + 'Expected: it to have been created by the service that owns it, before any consumer starts. '
+          + 'Fix: start the owning service; a consumer never creates the queue it attaches to, because it would '
+          + 'declare it with default arguments and every later declaration would fail with 406. '
+          + 'error.cause carries the broker reason.',
+        queue,
+        err,
+        CONSUMER_QUEUE_MISSING
+      );
+    }
+
+    return new ConsumeError(
+      `[BaseClient] Failed to start consumer for queue "${queue}" - `
+        + 'Expected: consume() to attach a consumer to the queue. '
+        + 'Fix: read error.cause, which carries the reason and the action for it — this layer does not know '
+        + 'which one it was, and naming the likeliest would send you to fix something that may not be broken.',
+      queue,
+      err
+    );
+  }
+
+  /**
+   * Report one message rejected into a dead-letter queue.
+   *
+   * Published to `monitoring.workflow` ONLY when the envelope carries a
+   * `workflow_id`. Without one there is nothing to publish and nothing is
+   * invented: `monitoring.workflow` keys every trace on that id, and an event
+   * naming no workflow is either refused by the intake as faulty telemetry or —
+   * worse, when a marker like `'unknown'` is put in its place — written as a row
+   * claiming a workflow by that name (`docs/governance/confirmations/dlq-purge.md`
+   * 002; lead decision 2026-09-11 answering INFRA-monitoring). The absence is
+   * reported through the injected logger, naming the queue and the service, and
+   * the message itself stays readable in the dead-letter queue.
+   *
+   * `status` carries the broker's own word for the death — `'rejected'`, what
+   * RabbitMQ stamps into `x-death[0].reason` for exactly this move (measured on
+   * `api_services_queuer`, 2026-09-11). One vocabulary for both paths into a
+   * DLQ, as the monitoring intake requires (`api/shared/TODO.md`, INFRA-monitoring
+   * 2026-09-11); an event with no `status` is refused there under its own name.
+   *
+   * @param {Object} event - As the transport reports it.
+   * @returns {Promise<void>}
+   * @private
+   */
+  async _emitDeadLetterEvent(event) {
+    const { queue, content, attempts, maxAttempts, classification, error } = event;
+    const serviceName = runtimeCfg.get('serviceName', this._config.serviceName);
+
+    let workflowId = null;
+    try {
+      const envelope = serializer.deserialize(content);
+      if (envelope !== null && typeof envelope === 'object' && typeof envelope.workflow_id === 'string'
+        && envelope.workflow_id !== '') {
+        workflowId = envelope.workflow_id;
+      }
+    } catch (parseErr) {
+      // A payload that is not JSON carries no envelope, so it carries no
+      // workflow_id either. Same outcome as an envelope without one.
+      workflowId = null;
+    }
+
+    if (workflowId === null) {
+      this._logger.error(
+        '[BaseClient] Dead-lettered message carries no workflow_id - Expected: the envelope of a '
+          + 'workflow message to carry workflow_id, which monitoring.workflow keys every trace on. '
+          + 'Fix: the message is in the dead-letter queue and readable through the DLQ dashboard; '
+          + 'no message_dlq event was published, because an event without a workflow_id names no workflow.',
+        {
+          queue,
+          service_name: serviceName,
+          attempts,
+          max_attempts: maxAttempts,
+          classification,
+          error: error && error.message
+        }
+      );
+      return;
+    }
+
+    await publishToMonitoringWorkflow(
+      this,
+      {
+        event_type: 'message_dlq',
+        workflow_id: workflowId,
+        service_name: serviceName,
+        // The broker's word for this death; see the method comment.
+        status: 'rejected',
+        queue,
+        attempts,
+        max_attempts: maxAttempts,
+        classification,
+        error: {
+          message: error && error.message,
+          name: error && error.name
+        },
+        timestamp: new Date().toISOString()
+      },
+      this._logger,
+      { queue }
+    );
+  }
+
   /**
    * Assert queue existence (delegates to transport).
    * @param {string} queue - Queue name
@@ -207,14 +742,90 @@ class BaseClient {
    */
   async assertQueue(queue, options = {}) {
     if (!this._connected || !this._transport) {
-      throw new ConnectionError('Cannot assertQueue: client is not connected');
+      throw new ConnectionError(
+        '[BaseClient] Cannot assertQueue: client is not connected - Expected: connect() to have completed. '
+          + 'Fix: await client.connect() before assertQueue().'
+      );
     }
     if (typeof this._transport.assertQueue !== 'function') {
-      throw new Error('[BaseClient] Transport does not support assertQueue(queue, options)');
+      throw new Error(
+        '[BaseClient] Transport does not support assertQueue(queue, options) - Expected: a transport implementing assertQueue. '
+          + 'Fix: use the rabbitmq transport, or drop the assertQueue() call for this transport type.'
+      );
     }
     return await this._transport.assertQueue(queue, options);
   }
 
+  /**
+   * Declare an exchange (delegates to transport).
+   *
+   * One of the four operations `mq-client-lifecycle-contract` 001 point 4
+   * ("L8") requires this client to expose. Until d.302 the only `assertExchange`
+   * in the package was a private line on the publish path, so a service that had
+   * to declare an exchange reached around the library for a raw amqplib channel.
+   *
+   * @param {string} exchange - Exchange name.
+   * @param {string} type - `direct`, `topic`, `fanout` or `headers`; required,
+   *   because an exchange's type is the caller's topology decision.
+   * @param {Object} [options] - amqplib exchange options; `durable` defaults to
+   *   the client's configured value.
+   * @returns {Promise<Object>}
+   * @throws {ConnectionError} If not connected.
+   * @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().'
+      );
+    }
+    return await this._transport.assertExchange(exchange, type, options);
+  }
+
+  /**
+   * Bind a queue to an exchange under a routing pattern (delegates to transport).
+   *
+   * @param {string} queue - Queue to bind.
+   * @param {string} exchange - Exchange to bind it to.
+   * @param {string} pattern - Routing pattern; required, and `''` is legal (a
+   *   fanout exchange ignores the key).
+   * @returns {Promise<Object>}
+   * @throws {ConnectionError} If not connected.
+   * @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().'
+      );
+    }
+    return await this._transport.bindQueue(queue, exchange, pattern);
+  }
+
+  /**
+   * Stop one consumer this client registered (delegates to transport).
+   *
+   * Accepts the consumer tag `consume()` returns, or the queue name. The
+   * consumer is dropped from the client's registry as well as cancelled on the
+   * broker, so connection-level recovery does not bring it back.
+   *
+   * @param {string} consumerTagOrQueue - The tag, or the queue name.
+   * @returns {Promise<Object>}
+   * @throws {ConnectionError} If not connected.
+   * @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().'
+      );
+    }
+    return await this._transport.cancelConsumer(consumerTagOrQueue);
+  }
+
   /**
    * Check queue existence (delegates to transport).
    * @param {string} queue - Queue name
@@ -222,10 +833,16 @@ class BaseClient {
    */
   async checkQueue(queue) {
     if (!this._connected || !this._transport) {
-      throw new ConnectionError('Cannot checkQueue: client is not connected');
+      throw new ConnectionError(
+        '[BaseClient] Cannot checkQueue: client is not connected - Expected: connect() to have completed. '
+          + 'Fix: await client.connect() before checkQueue().'
+      );
     }
     if (typeof this._transport.checkQueue !== 'function') {
-      throw new Error('[BaseClient] Transport does not support checkQueue(queue)');
+      throw new Error(
+        '[BaseClient] Transport does not support checkQueue(queue) - Expected: a transport implementing checkQueue. '
+          + 'Fix: use the rabbitmq transport, or drop the checkQueue() call for this transport type.'
+      );
     }
     return await this._transport.checkQueue(queue);
   }
@@ -237,10 +854,16 @@ class BaseClient {
    */
   async purgeQueue(queue) {
     if (!this._connected || !this._transport) {
-      throw new ConnectionError('Cannot purgeQueue: client is not connected');
+      throw new ConnectionError(
+        '[BaseClient] Cannot purgeQueue: client is not connected - Expected: connect() to have completed. '
+          + 'Fix: await client.connect() before purgeQueue().'
+      );
     }
     if (typeof this._transport.purgeQueue !== 'function') {
-      throw new Error('[BaseClient] Transport does not support purgeQueue(queue)');
+      throw new Error(
+        '[BaseClient] Transport does not support purgeQueue(queue) - Expected: a transport implementing purgeQueue. '
+          + 'Fix: use the rabbitmq transport, or drop the purgeQueue() call for this transport type.'
+      );
     }
     return await this._transport.purgeQueue(queue);
   }
@@ -253,10 +876,16 @@ class BaseClient {
    */
   async deleteQueue(queue, options = {}) {
     if (!this._connected || !this._transport) {
-      throw new ConnectionError('Cannot deleteQueue: client is not connected');
+      throw new ConnectionError(
+        '[BaseClient] Cannot deleteQueue: client is not connected - Expected: connect() to have completed. '
+          + 'Fix: await client.connect() before deleteQueue().'
+      );
     }
     if (typeof this._transport.deleteQueue !== 'function') {
-      throw new Error('[BaseClient] Transport does not support deleteQueue(queue, options)');
+      throw new Error(
+        '[BaseClient] Transport does not support deleteQueue(queue, options) - Expected: a transport implementing deleteQueue. '
+          + 'Fix: use the rabbitmq transport, or drop the deleteQueue() call for this transport type.'
+      );
     }
     return await this._transport.deleteQueue(queue, options);
   }
@@ -281,10 +910,16 @@ class BaseClient {
    */
   async ack(msg) {
     if (!this._connected || !this._transport) {
-      throw new ConnectionError('Cannot ack: client is not connected');
+      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.'
+      );
     }
     if (typeof this._transport.ack !== 'function') {
-      throw new Error('[BaseClient] Transport does not support ack(msg)');
+      throw new Error(
+        '[BaseClient] Transport does not support ack(msg) - Expected: a transport implementing ack. '
+          + 'Fix: use the rabbitmq transport, or consume with noAck for this transport type.'
+      );
     }
     return await this._transport.ack(msg);
   }
@@ -292,15 +927,26 @@ class BaseClient {
   /**
    * Negative-acknowledge a raw broker message (delegates to transport).
    * @param {Object} msg - Broker message object
-   * @param {Object} [options] - { requeue: boolean }
+   * @param {Object} [options] - { requeue: boolean }; `requeue` defaults to
+   *   `true` in the transport, so a caller that wants the message discarded
+   *   must pass `{ requeue: false }`. This is an options OBJECT, never
+   *   amqplib's positional `(msg, allUpTo, requeue)` — see
+   *   transports/rabbitmqClient.js nack() and
+   *   tests/unit/nack-options-signature.test.js.
    * @returns {Promise<void>}
    */
   async nack(msg, options = {}) {
     if (!this._connected || !this._transport) {
-      throw new ConnectionError('Cannot nack: client is not connected');
+      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.'
+      );
     }
     if (typeof this._transport.nack !== 'function') {
-      throw new Error('[BaseClient] Transport does not support nack(msg, options)');
+      throw new Error(
+        '[BaseClient] Transport does not support nack(msg, options) - Expected: a transport implementing nack. '
+          + 'Fix: use the rabbitmq transport, or consume with noAck for this transport type.'
+      );
     }
     return await this._transport.nack(msg, options);
   }
@@ -331,54 +977,281 @@ class BaseClient {
   }
 
   /**
-   * Check if client is connected
+   * Registers a handler for the permanent loss of the broker connection.
+   *
+   * It fires at most once per client, after connection-level recovery has spent
+   * its whole budget (`RABBITMQ_MAX_RECONNECT_ATTEMPTS`). At that point the
+   * client is dead until the process restarts: it makes no further attempts,
+   * `isConnected()` returns false, and publish/consume refuse.
+   *
+   * The library does not end the process — that decision belongs to the owner
+   * of the lifecycle. A service typically logs and exits non-zero here, so its
+   * restart policy boots it again and boot re-verifies every dependency.
+   *
+   * @param {function(Error): void} callback - Receives the fatal error
+   *   (`code: 'MQ_CONNECTION_FATAL'`, `attempts: <budget>`).
+   */
+  onFatal(callback) {
+    if (typeof callback === 'function') {
+      this._fatalHandlers.push(callback);
+    }
+  }
+
+  /**
+   * Internal helper to invoke all registered fatal handlers.
+   * @param {Error} error
+   * @private
+   */
+  _handleFatal(error) {
+    this._fatalHandlers.forEach((cb) => {
+      try {
+        cb(error);
+      } catch (err) {
+        this._logger.error(`[BaseClient] onFatal handler threw: ${err.message}`, {
+          message: err.message,
+        });
+      }
+    });
+  }
+
+  /**
+   * What this client's publishes have done so far — the counters
+   * `monitoring/PublishMonitor.js` keeps: `attempts`, `successes`, `failures`,
+   * `retries`, `buffered`, `flushed`, plus a per-queue breakdown.
+   *
+   * Delegated, never recomputed: the transport owns the counting, this class
+   * owns the surface a service can reach. Until 2026-09-14 it owned neither —
+   * the five reporting methods were on the transport alone, and
+   * `new RabbitMQClient` is called in exactly one place in the workspace
+   * (`transports/transportFactory.js`, inside this library), so the counters
+   * were documented (`docs/architecture/mq-publish-reliability.md`) and readable
+   * by nobody.
+   *
+   * @returns {Object} `{ attempts, successes, failures, retries, buffered, flushed, queues }`
+   * @throws {ConnectionError} Before `connect()` has built a transport: there is
+   *   nothing to report, and a zeroed object would be an invented answer
+   *   (`architecture-principles.md` §3).
+   */
+  getPublishMetrics() {
+    return this._reportFromTransport('getPublishMetrics');
+  }
+
+  /**
+   * The same counters as Prometheus text exposition (`mq_publish_attempts`,
+   * `mq_publish_successes`, `mq_publish_failures`, `mq_publish_retries`,
+   * `mq_publish_buffered`, `mq_publish_flushed`).
+   *
+   * @returns {string}
+   * @throws {ConnectionError} Before `connect()` has built a transport.
+   */
+  getPrometheusMetrics() {
+    return this._reportFromTransport('getPrometheusMetrics');
+  }
+
+  /**
+   * Liveness of the three channels this client runs on, each as
+   * `{ exists, closed, ready }` — the publisher's ConfirmChannel, the queue
+   * channel and the consumer channel (`docs/architecture/rabbitmq-channel-lifecycle.md`).
+   *
+   * @returns {Object} `{ publisher, queue, consumer }`
+   * @throws {ConnectionError} Before `connect()` has built a transport.
+   */
+  getChannelState() {
+    return this._reportFromTransport('getChannelState');
+  }
+
+  /**
+   * The consumers this client currently holds: how many, and on which queues.
+   *
+   * @returns {Object} `{ tracked: <count>, active: [<queue names>] }`
+   * @throws {ConnectionError} Before `connect()` has built a transport.
+   */
+  getConsumerState() {
+    return this._reportFromTransport('getConsumerState');
+  }
+
+  /**
+   * How much is waiting in the publish buffer, in memory and in Redis.
+   *
+   * @returns {Object} `{ size, inMemory, persistent }`
+   * @throws {ConnectionError} Before `connect()` has built a transport.
+   */
+  getBufferState() {
+    return this._reportFromTransport('getBufferState');
+  }
+
+  /**
+   * The ONE rail for the reporting methods above: ask the transport, or say why
+   * there is no answer.
+   *
+   * Keyed on the TRANSPORT, not on `_connected` — the same distinction
+   * `disconnect()` makes. A client whose connection has just died still owns a
+   * transport whose counters are real, and that is exactly the moment somebody
+   * asks. What there is no answer to is a client that has never connected: it
+   * holds no transport, so it has counted nothing, and a zeroed object would be
+   * an invented value rather than a measurement.
+   *
+   * @param {string} method - The transport method to report from.
+   * @returns {*} Whatever that method answers.
+   * @throws {ConnectionError} If no transport has been built yet.
+   * @private
+   */
+  _reportFromTransport(method) {
+    if (!this._transport) {
+      throw new ConnectionError(
+        `[BaseClient] Cannot ${method}(): the client has no transport - Expected: connect() to have built one. `
+          + `Fix: await client.connect() before ${method}(); a client that never connected has counted nothing, `
+          + 'and a zeroed answer would be invented rather than measured.'
+      );
+    }
+
+    return this._transport[method]();
+  }
+
+  /**
+   * Is this client's connection permanently lost?
+   *
+   * The difference between "the broker is away" and "this connection is over" is
+   * what a healthcheck and a restart decision turn on, and until d.341 only the
+   * TRANSPORT could answer it — while `new RabbitMQClient` is called in exactly
+   * one place in the whole workspace, inside this library. A service holding a
+   * `BaseClient` had `isConnected() === false` and no way to learn which of the
+   * two it was: wait, or restart.
+   *
+   * Delegated, never recomputed — the transport owns the state, this class owns
+   * the surface. It does NOT follow the rule of the five reporting methods
+   * (`_reportFromTransport`, which refuses before `connect()`): a counter has
+   * nothing to report before the first connection, but "is this client's
+   * connection permanently lost" has a true answer for a client that never had
+   * one — no. A healthcheck asks this question, and it must not be answered by
+   * an exception.
+   *
+   * @returns {boolean} true once the broker refused the connection, or every
+   *   recovery cycle has been spent (`README.md` § Connection loss).
+   */
+  isConnectionFatal() {
+    if (!this._transport || typeof this._transport.isConnectionFatal !== 'function') {
+      return false;
+    }
+    return this._transport.isConnectionFatal();
+  }
+
+  /**
+   * Ask the client to check itself now: connection, the three channels, and the
+   * queues its tracked consumers run on.
+   *
+   * The same probe the internal health monitor runs on its interval, exposed for
+   * the caller who wants an answer at a moment of its own choosing (before a
+   * workflow step, from a readiness endpoint) — documented as callable in
+   * `docs/architecture/rabbitmq-channel-lifecycle.md` and, until d.341, callable
+   * only on a transport no service holds.
+   *
+   * Since d.339 it is also a USE: a client that stood down after a spent recovery
+   * cycle starts the next one here. It does not wait for it — the answer is the
+   * state now, "not connected", and the next call says whether the cycle worked.
+   *
+   * @returns {Promise<Object>} `{ timestamp, connection, channels, consumers, queues, healthy, issues }`
+   * @throws {ConnectionError} Before `connect()` has built a transport: there is
+   *   nothing to check, and a green verdict would be an invented answer.
+   */
+  async performHealthCheck() {
+    return this._reportFromTransport('performHealthCheck');
+  }
+
+  /**
+   * Check if client is connected.
+   *
+   * BREAKING since 2026-09-07: the answer comes from the transport's live
+   * connection state, not from a flag set once in `connect()`. The old version
+   * returned `true` for the entire outage AND after the recovery budget was
+   * spent — measured on 2026-09-07 as `true` for 100+ s against a broker that
+   * was down and then back up, with the client permanently dead. Every
+   * healthcheck built on this method (including `conn-infra-mq`'s
+   * `getHealth().connected`) reported a zombie process as healthy.
+   *
    * @returns {boolean} Connection status
    */
   isConnected() {
-    return this._connected === true;
+    if (this._connected !== true) return false;
+    if (this._transport && typeof this._transport.isConnected === 'function') {
+      return this._transport.isConnected();
+    }
+    return true;
   }
 }
 
 module.exports = BaseClient;
 
+/**
+ * The clients this module currently holds — every instance that has been
+ * constructed and not yet disconnected.
+ *
+ * It exists for exactly one reason: `disconnectAll()` has to know what "all"
+ * means. One `BaseClient` owns one transport, so closing one client is already
+ * `disconnect()`; "all" can only be the set of live instances, and that set has
+ * to be kept where the instances are created.
+ */
 BaseClient._instances = new Set();
-BaseClient._cleanupRegistered = false;
-BaseClient._cleanupRunning = false;
 
 BaseClient._registerInstance = function registerInstance(instance) {
   BaseClient._instances.add(instance);
-  if (!BaseClient._cleanupRegistered) {
-    BaseClient._registerCleanupHooks();
-  }
 };
 
 BaseClient._unregisterInstance = function unregisterInstance(instance) {
   BaseClient._instances.delete(instance);
 };
 
-BaseClient._registerCleanupHooks = function registerCleanupHooks() {
-  const handler = async (signal) => {
-    if (BaseClient._cleanupRunning) return;
-    BaseClient._cleanupRunning = true;
-    const disconnects = Array.from(BaseClient._instances).map((instance) =>
-      instance
-        .disconnect()
-        .catch((err) =>
-          console.warn('[BaseClient] Failed to disconnect during shutdown:', err.message)
-        )
-    );
-    await Promise.allSettled(disconnects);
-    BaseClient._instances.clear();
-    BaseClient._cleanupRunning = false;
-    if (signal && signal !== 'beforeExit') {
-      process.exit(0); // eslint-disable-line no-process-exit
-    }
-  };
+/**
+ * Close every client this module holds. The service calls it; nothing in this
+ * library calls it for them.
+ *
+ * This is the whole of the library's side of the shutdown contract
+ * (`docs/governance/confirmations/mq-client-lifecycle-contract.md` 001 point 1):
+ * the library registers no signal handler and never ends the process, and in
+ * exchange it offers one named call the lifecycle owner can put wherever its own
+ * sequence needs it — before the Redis clients, after the HTTP server, in the
+ * order THAT process decided.
+ *
+ * What it replaced, and why the replacement is not a smaller version of it:
+ * until this batch the library installed `SIGINT`/`SIGTERM`/`beforeExit`
+ * listeners on the first instance anyone constructed, and that listener ended in
+ * `process.exit(0)`. The registry service traced the result live
+ * (`infra/api_services_registry/src/shutdown.js`, batch 140, dev stack
+ * 2026-08-31): `TRACE_END mq t=12` → `TRACE_PROCESS_EXIT code=0 t=16`. Node
+ * copies the listener array before it emits, so the service could not remove the
+ * library's listener in time; the library's exit won the race after the MQ
+ * connection had closed and BEFORE four Redis clients, the HTTP server and six
+ * timers were handed back. The service had written a complete shutdown sequence
+ * and got a truncated one, with nothing in its own repository to explain it.
+ *
+ * Failure is reported, never swallowed. The deleted hook logged a warning per
+ * failed client and exited 0 anyway — a shutdown that could not close a client
+ * looked exactly like one that did. Here every client gets its turn (one dead
+ * socket must not leave the others open), and if any refused, the call rejects
+ * with a `ConnectionError` naming how many of how many failed, carrying the
+ * first reason as its cause. The clients that failed stay in the set, because
+ * `disconnect()` removes an instance only when it actually closed — so a second
+ * `disconnectAll()` reaches them again, where the hook's blanket `clear()` made
+ * the retry a silent no-op.
+ *
+ * @returns {Promise<void>} Resolves when every client held by this module has
+ *   closed — including when there were none.
+ * @throws {ConnectionError} If one or more clients could not close. `error.cause`
+ *   is the first underlying failure.
+ */
+BaseClient.disconnectAll = async function disconnectAll() {
+  const instances = Array.from(BaseClient._instances);
+  const results = await Promise.allSettled(instances.map((instance) => instance.disconnect()));
+  const failures = results.filter((result) => result.status === 'rejected');
 
-  ['SIGINT', 'SIGTERM'].forEach((sig) => {
-    process.on(sig, () => handler(sig));
-  });
-  process.on('beforeExit', () => handler('beforeExit'));
-  BaseClient._cleanupRegistered = true;
+  if (failures.length > 0) {
+    throw new ConnectionError(
+      `[BaseClient] Failed to disconnect ${failures.length} of ${instances.length} clients - `
+        + 'Expected: every client this module holds to close its transport. '
+        + 'Fix: read error.cause for the first transport reason; the clients that failed are still '
+        + 'held, so a repeated disconnectAll() reaches them again.',
+      failures[0].reason
+    );
+  }
 };