@onlineapps/mq-client-core 4.2.0 → 5.0.0

package/src/config/queueConfig.js

@@ -129,8 +129,11 @@ const templateShape = (template) =>
  * @returns {{serviceName: string, queueType: string}|null} The service and the
  *   template key that declares the queue's arguments, or `null` for a name no
  *   template matches.
- * @throws {ValidationError} If two templates match one name - a defect in this file,
- *   never a runtime condition, and one that would otherwise be resolved by key order.
+ * @throws {ValidationError} If two templates of the same kind match one name - a defect in
+ *   this file, never a runtime condition, and one that would otherwise be resolved by key
+ *   order. A literal shape and a placeholder shape matching the same name is NOT that case:
+ *   the literal wins, because it declares the name while the placeholder only fits it
+ *   (d.817b, `registry.events` against `registry.{instance_id}`).
  */
 const matchBusinessTemplate = (business, queueName) => {
   const parts = queueName.split('.');
@@ -145,15 +148,24 @@ const matchBusinessTemplate = (business, queueName) => {
     );
   });
 
-  if (matched.length > 1) {
+  // A LITERAL BEATS A PLACEHOLDER (d.817b). `registry.events` names a queue;
+  // `registry.{instance_id}` names a shape — so `<svc>.registry.events` fits both, and a
+  // wildcard must not claim a name another template DECLARES. It is the same tie-break this
+  // file makes one level up, where a name an infrastructure section declares is never a
+  // business queue however well it fits a template (d.279). Ambiguity between two templates
+  // of the SAME kind is still a defect and still refused below.
+  const literals = matched.filter((template) => !templateShape(template).includes(null));
+  const decided = literals.length > 0 ? literals : matched;
+
+  if (decided.length > 1) {
     throw new ValidationError(
-      `[queueConfig] Business queue ${queueName} matches more than one template: ${matched.join(', ')} - `
+      `[queueConfig] Business queue ${queueName} matches more than one template: ${decided.join(', ')} - `
         + 'Expected: exactly one template declares a name, so one queue has one definition. '
         + 'Fix: make the overlapping keys in the `business` section of src/config/queueConfig.js distinct.'
     );
   }
 
-  return matched.length === 1 ? { serviceName: parts[0], queueType: matched[0] } : null;
+  return decided.length === 1 ? { serviceName: parts[0], queueType: decided[0] } : null;
 };
 
 /**
@@ -277,33 +289,11 @@ module.exports = {
       }
     },
 
-    /**
-     * workflow.control - Shared queue for service-agnostic control-flow steps
-     * All business services listen as competing consumers (same pattern as workflow.init).
-     *
-     * Purpose:
-     * - Execute control-flow steps that are not pinned to a specific service
-     * - Keep workflow.init as a clear "gateway entrypoint" queue (no semantic overload)
-     *
-     * TTL: 30 seconds - if no business service processes message within 30s, it expires
-     * DLQ routing: Expired messages go to workflow.failed
-     */
-    control: {
-      durable: true,
-      arguments: {
-        'x-message-ttl': 30000,
-        'x-max-length': 10000,
-        'x-dead-letter-exchange': '',
-        'x-dead-letter-routing-key': 'workflow.failed'
-      }
-    },
-
     /**
      * workflow.completed - Completed workflows
      *
      * Dead-letters to workflow.dlq over the DEFAULT exchange, where the routing key
-     * is the destination queue name — the shape workflow.init/workflow.control
-     * already use. The dispatcher rejects a message here on an invalid payload, a
+     * is the destination queue name — the shape workflow.init already uses. The dispatcher rejects a message here on an invalid payload, a
      * schema violation and a delivery failure; until d.278 the broker dropped each
      * one, because the queue declared nowhere to put it.
      *
@@ -492,6 +482,41 @@ module.exports = {
         'x-dead-letter-exchange': DEAD_LETTER_EXCHANGE,
         'x-dead-letter-routing-key': '{service}.dlq'
       }
+    },
+
+    /**
+     * {service}.registry.{instance_id} - the queue ONE INSTANCE gets its registry answers
+     * on, beside the shared `{service}.registry` the registry uses for its own prompts.
+     *
+     * The owner settled the name and the split (`registry-instance-identity` 001,
+     * Conditions): answers travel to `<svc>.registry.<instanceId>` through the existing
+     * `responseQueue`, the shared queue carries the registry's prompts. Measured by the
+     * registry thread in d.817: without a template here `getDeadLetterRoute()` answered
+     * null, `consume()` refuses a queue with no declared route (`mq-consumer-contract`
+     * 002), and the client had to go on answering on the shared queue — the state the
+     * confirmation moved away from.
+     *
+     * ITS LIFETIME IS `x-expires` (question 14, variant A; `registry-instance-identity`
+     * 003). Every boot of a copy names a new queue (the
+     * instance id is a UUID per process unless `SERVICE_INSTANCE_ID` names one), and
+     * nothing deletes the old one — not `deregister()`, not the wrapper's shutdown, not the
+     * registry, which only checks the queue exists before it answers. A durable queue with
+     * no lifetime would therefore stay behind after every restart, crash or clean stop
+     * alike. The broker deletes a queue with `x-expires` once it has gone that long with no
+     * consumer, so a live copy (its consumer attached) keeps it and a gone copy loses it.
+     * 60 s: longer than a reconnect of a live copy, shorter than the monitoring orphan
+     * window (`queue_orphan_alert.min_orphan_minutes`, seed 5), so a dead copy's queue
+     * never opens a `no_owner` episode. One rail: the lifetime lives in this declaration
+     * only — the transport refuses a caller's `autoDelete`/`exclusive` on a classified
+     * queue, and no caller deletes it.
+     */
+    'registry.{instance_id}': {
+      durable: true,
+      arguments: {
+        'x-expires': 60000,            // 60 s with no consumer, then the broker deletes it (question 14, A)
+        'x-dead-letter-exchange': DEAD_LETTER_EXCHANGE,
+        'x-dead-letter-routing-key': '{service}.dlq'  // Placeholder, replaced with actual service name
+      }
     }
   },
 
@@ -766,11 +791,12 @@ module.exports = {
      * `mq-consumer-contract` 002 point 2, 003 point 1).
      *
      * **A declaration is not a creation instruction. The terminal is brought into being
-     * by the owner of the prefix that NAMES it.** `initInfrastructureQueues()` derives
-     * the whole list from these sections only when its caller passes no `queues` list;
-     * every caller passes one, and the gateway's names exactly the five `workflow.*`
-     * queues it owns (`infra/api_gateway/index.js`). `monitoring.dlq` therefore belongs
-     * to the monitoring service's own call, beside the queues it consumes. Until that
+     * by the owner of the prefix that NAMES it.** `initInfrastructureQueues()` creates
+     * exactly the names its caller passes in `queues`, a list that is required since
+     * d.668 — it derives nothing from these sections, and the gateway's list names
+     * exactly the five `workflow.*` queues it owns (`infra/api_gateway/index.js`).
+     * `monitoring.dlq` therefore belongs to the monitoring service's own call, beside
+     * the queues it consumes. Until that
      * call names it, a `nack(requeue=false)` on a queue of this family dead-letters onto
      * a routing key no queue carries and the broker DROPS the message — measured
      * 2026-09-16 on the dev broker: 78 queues, and the only `.dlq` among them
@@ -1096,7 +1122,8 @@ module.exports = {
      * travels on that exchange, so the scheduler reads it there rather than asking the
      * observer over HTTP or reading a database that is not its own. No producer changes; the
      * binding is the scheduler's own act at boot (the pattern
-     * `infra/api_delivery_endpoint/src/index.js:164` already uses), and this file only
+     * `infra/api_delivery_endpoint/src/index.js` already uses with its
+     * `mq.bindQueueToFanout(…)` calls), and this file only
      * DECLARES what that queue is.
      *
      * WHICH event_type values those are is NOT written here: the vocabulary has one owner and
@@ -1264,8 +1291,11 @@ module.exports = {
 
   /**
    * The infrastructure prefixes this configuration classifies by, in declaration
-   * order. Published so a caller — `initInfrastructureQueues()`, a queue-ownership
-   * probe, a document generator — reads the list instead of keeping a copy of it.
+   * order. Published so a caller reads the list instead of keeping a copy of it.
+   * It named `initInfrastructureQueues()` as such a caller until d.668, when that
+   * function stopped deriving a queue list at all and started requiring `queues`;
+   * what reads it today is this package's own coverage of the classification
+   * (`tests/unit/queue-name-collision.test.js`, `queueConfig-telemetry.test.js`).
    * @returns {ReadonlyArray<string>} Prefixes WITHOUT the trailing dot.
    */
   infrastructurePrefixes() {
@@ -1507,8 +1537,7 @@ module.exports = {
    *
    * ONE owner of the mapping name → options. Every path that declares a queue
    * reads it here and nowhere else: the public `assertQueue()` of the transport
-   * (and through it `RecoveryWorker.createQueue()`, the cookbook-router's
-   * QueueManager and the publish path's 404 branch), and the consumer's
+   * (and through it the cookbook-router's QueueManager), and the consumer's
    * `_prepareQueueForConsume()`.
    *
    * Until d.410 those two worked the same three lines out separately —
@@ -1609,7 +1638,7 @@ module.exports = {
    *
    * The counterpart of `getDeadLetterRoute()`, and the reason a queue may have no
    * route without that being a defect. `workflow.failed` is named in
-   * `x-dead-letter-routing-key` by `workflow.init` and `workflow.control`;
+   * `x-dead-letter-routing-key` by `workflow.init`;
    * `{service}.dlq` by every business template; `workflow.dlq` and `delivery.dlq`
    * by their own families. Giving such a queue a route of its own would either
    * close a loop or start an endless chain, which is why the confirmed topology

package/src/config.js

@@ -20,7 +20,11 @@ const runtimeCfg = createRuntimeConfig({
 
     // Client behavior
     heartbeat: { env: 'RABBITMQ_HEARTBEAT', defaultKey: 'heartbeatSeconds', type: 'number' },
-    serviceName: { env: 'SERVICE_NAME', defaultKey: 'serviceName' },
+    // The caller's own identity — required, never defaulted (d.770). Two legs, both the
+    // caller's: the explicit key, or ENV SERVICE_NAME. There is no third, because a
+    // library that invents a service name makes every row it writes name the wrong
+    // service (`architecture-principles.md` §3, and `./defaults.js` for the measurement).
+    serviceName: { env: 'SERVICE_NAME', required: true },
 
     // Connection-level recovery budget. Resolved here (explicit → env →
     // module default) instead of an inline `|| 10` in the transport, so the

package/src/defaults.js

@@ -7,11 +7,17 @@
  * - This module owns defaults for MQ client behavior (heartbeat, connectionName prefix).
  * - Infrastructure topology (RabbitMQ URL) is NOT defaulted; it must be provided via
  *   explicit config.host or ENV RABBITMQ_URL (fail-fast).
+ * - The CALLER's own identity is not defaulted either. `serviceName` used to be
+ *   `'oa-service'` here until d.770: a name this module cannot know and must not invent
+ *   (`architecture-principles.md` §3). What it bought was measured, and it was a lie —
+ *   every client built without the key published its monitoring events, and named its
+ *   queues, under a service that does not exist. It is now required, with the same two
+ *   legs every caller already uses: explicit `serviceName`, or ENV `SERVICE_NAME`
+ *   (`../config.js`).
  */
 
 module.exports = {
   heartbeatSeconds: 30,
-  serviceName: 'oa-service',
 
   // How many times connection-level recovery retries before the connection is
   // declared permanently lost. Client BEHAVIOUR, so it is owned here (the same

package/src/index.js

@@ -8,9 +8,6 @@
  * 
  * NOTE: Infrastructure orchestration utilities (waitForInfrastructureReady, initInfrastructureQueues)
  * have been moved to @onlineapps/infrastructure-tools to keep this library focused on core MQ operations.
- * 
- * @version 1.0.49
- * @updated 2024-12-08 - Test publish-library.sh workflow
  */
 
 const BaseClient = require('./BaseClient');
@@ -48,9 +45,11 @@ const {
   buildCancelRequest,
   publishSchedulerRequest,
   createSchedulerPublisher,
+  SCHEDULER_REQUEST_INVALID,
 } = require('./scheduler-request');
 const queueConfig = require('./config/queueConfig');
 const deliveryPolicy = require('./config/deliveryPolicy');
+const { decodeMessage } = require('./utils/decodeMessage');
 const { redactUrl, UNPARSEABLE_PLACEHOLDER } = require('@onlineapps/logger-contract');
 
 // Export BaseClient as default (constructor), with additional named exports
@@ -119,6 +118,8 @@ module.exports.scheduler = {
   buildCancelRequest,
   publishSchedulerRequest,
   createSchedulerPublisher,
+  // The code on every refusal of a builder, and on nothing a failed send throws.
+  SCHEDULER_REQUEST_INVALID,
 };
 /** The only public way to reach the central queue classification; `src/config/queueConfig` is an internal path, not a contract. */
 module.exports.queueConfig = queueConfig;
@@ -175,7 +176,25 @@ module.exports.topology = Object.freeze({
   /** The same consumer's metric-sample intake on that exchange. */
   telemetryMetricsQueue: queueConfig.queueName('telemetry', 'metrics.queue'),
   /** The same consumer's span intake on that exchange. */
-  telemetryTracesQueue: queueConfig.queueName('telemetry', 'traces.queue')
+  telemetryTracesQueue: queueConfig.queueName('telemetry', 'traces.queue'),
+  /**
+   * Topic exchange: every telemetry producer on the platform publishes logs, metrics and
+   * spans here with a routing key of the shape `telemetry.<signal>.<service_name>`, and
+   * the three queues above are bound to it.
+   *
+   * Declared in `queueConfig` since d.708, which ended the state where one name had three
+   * owners: a module constant in the monitoring consumer
+   * (`api/infra/api_monitoring/src/consumer/topology.js`) and a config default in each of
+   * monitoring-core's two publishers. The declaration alone does not finish that move —
+   * the consumer resolves every platform name it does not own through THIS export, and
+   * `src/config/queueConfig` is an internal path rather than a contract (see the note on
+   * the module export above). So the name it must import belongs here, the same step d.461
+   * made for the three queues it is bound to.
+   *
+   * @see api/infra/api_monitoring/src/consumer/index.js — assertMonitoringTopology()
+   * @see api/shared/monitoring/monitoring-core/src/exporters/rabbitmq.js
+   */
+  telemetryExchange: queueConfig.queueName('telemetry', 'exchange')
 });
 /**
  * The dead-letter policy of `consume()` as a contract, not as an implementation
@@ -186,6 +205,24 @@ module.exports.topology = Object.freeze({
  * return one of those two words.
  */
 module.exports.deliveryPolicy = deliveryPolicy;
+/**
+ * The one rail from a delivery to the message it carries.
+ *
+ * `consume()` hands its handler the RAW amqplib delivery, so every consumer wrote that
+ * translation itself: d.788 measured FOUR copies (dispatcher, scheduler, service-wrapper,
+ * registry) which disagree about what happens to a BAD message — dead-letter, loss rail,
+ * `INVALID_JSON` reply, or requeue for ever — and two of which pass a delivery with no
+ * `content` on AS the body.
+ *
+ * The decoding was never the missing part (`utils/serializer.js` has done it all along);
+ * the missing part was this door, because `src/…` is an internal path rather than a
+ * contract. Exported ADDITIVELY: nothing in this package calls it and `consume()` is
+ * unchanged, because converting those four changes the fate of a malformed message —
+ * BREAKING, and for the registry only after its queue has a dead-letter route (d.784).
+ *
+ * @see ./utils/decodeMessage.js — what it refuses, and with which of this package's classes
+ */
+module.exports.decodeMessage = decodeMessage;
 /**
  * Redaction of the credential a connection URL carries, as a DECLARED export.
  *

package/src/layers/PublishLayer.js

@@ -51,10 +51,10 @@ class PublishLayer {
     // transport constructor reads it from there (d.292 §5).
     //
     // Asked with `=== undefined`, never with `||`. `||` means "if falsy", so the
-    // three numbers below lost a legally written `0` — `publishMaxRetries: 0`
-    // means "do not retry a publish", and it arrived here as 3. d.292 removed
-    // exactly that shape from the transport and said in as many words that this
-    // layer still carried its own copies; this is that floor (d.311).
+    // three numbers below lost a legally written `0` — `publishRetryBaseDelay: 0`
+    // means "retry immediately", and it arrived here as 100. d.292 removed exactly
+    // that shape from the transport and said in as many words that this layer still
+    // carried its own copies; this is that floor (d.311).
     this._retryEnabled = options.retryEnabled !== undefined 
       ? options.retryEnabled 
       : (this._client._publishRetryEnabled !== false);
@@ -71,6 +71,45 @@ class PublishLayer {
       ? options.retryBackoffMultiplier
       : this._client._publishRetryBackoffMultiplier;
 
+    // `publishMaxRetries` counts ATTEMPTS, the first one included — that is what the
+    // key means in every place it is written down (`config/configSchema.js`,
+    // `config/defaultConfig.js`, `docs/architecture/mq-publish-reliability.md` § the
+    // config table, `docs/standards/rabbitmq-channel-best-practices.md`), and what
+    // `_publishWithRetry()` below does for every value from 1 up.
+    //
+    // So `0` is not "do not retry" — three comments in this package said it was, and
+    // the loop obeyed the key instead: `while (attempt < this._maxRetries)` never runs
+    // its body, so the message is never offered to the broker, is NOT buffered on the
+    // way out, and the caller is handed an error blaming this layer for a defect its
+    // own configuration caused (measured, d.684). "One attempt, no retry" is `1`, and
+    // leaving the retry rail entirely is `publishRetryEnabled: false`; both are
+    // explicit, and neither needs a magic zero (`architecture-principles.md` §8).
+    //
+    // Refused HERE, at construction, because this is the one place both doors meet —
+    // the caller's `options.maxRetries` and the client's resolved config — and a value
+    // that can only fail is refused before it is used, not when a publish needs it
+    // (§4 fail-fast).
+    //
+    // `config/configSchema.js` refuses the same value too since d.685b (`minimum: 1`),
+    // and that is not a second rail for one concern: the schema answers what may be
+    // WRITTEN in a client's configuration, this answers what may be USED as a number of
+    // attempts — and the second is reachable without the first. Measured 2026-09-20: the
+    // schema is compiled and applied in exactly one place, `BaseClient`'s constructor,
+    // while the only `new RabbitMQClient` in the workspace is
+    // `transports/transportFactory.js`, which validates nothing. The two also answer at
+    // different moments, because `BaseClient` builds the transport in `connect()` rather
+    // than in its constructor — so a client built past the front desk still arrives here
+    // with whatever it was given.
+    if (!Number.isInteger(this._maxRetries) || this._maxRetries < 1) {
+      throw new ValidationError(
+        `[PublishLayer] publishMaxRetries must be at least 1 - got ${JSON.stringify(this._maxRetries)}. `
+          + 'Expected: a whole number of publish attempts, because it counts ATTEMPTS, the first one '
+          + 'included — 0 means the message is never offered to the broker at all. '
+          + 'Fix: write publishMaxRetries: 1 for one attempt and no retry, or publishRetryEnabled: false '
+          + 'to leave the retry rail entirely.'
+      );
+    }
+
     // Buffer
     this._buffer = new MessageBuffer({
       inMemory: options.bufferConfig?.inMemory,
@@ -118,7 +157,48 @@ class PublishLayer {
     let lastError = null;
     let attempt = 0;
 
+    /**
+     * The broker's numbered refusal of THIS message, if it arrived after the confirmation
+     * budget had already answered an attempt.
+     *
+     * Measured (d.801): when the budget is shorter than the broker's answer, the attempt
+     * is answered "transient" while the frame underneath says 404 — and the loop below
+     * used to publish the message again, `publishMaxRetries` times, and then buffer it,
+     * where the flush re-offers it on every reconnect until its TTL drops it. d.801b made
+     * that verdict audible (`publish:refused-late`); this listener is what ACTS on it.
+     *
+     * No new evidence and no new timer: the frame is read where it has always been read
+     * (the transport's `channel._closeError` + `_closeFrameNamesThisSend()`), the event is
+     * the one already emitted, and the subscription lives exactly as long as this publish.
+     */
+    let lateRefusal = null;
+    const onRefusedLate = (event) => {
+      if (event.queue === queue && event.verdict === 'PermanentPublishError' && event.error) {
+        lateRefusal = event.error;
+      }
+    };
+    this._client.on('publish:refused-late', onRefusedLate);
+
+    try {
     while (attempt < this._maxRetries) {
+      // A message the broker has REFUSED is not published again. The question is asked
+      // before every attempt but the first, because the first is what earns the answer.
+      if (attempt > 0 && lateRefusal !== null) {
+        this._logger.warn(
+          `[PublishLayer] The broker refused this message while attempt ${attempt} was in flight, `
+            + `so attempt ${attempt + 1} of ${this._maxRetries} is not made for queue "${queue}" - `
+            + `${lateRefusal.message}`
+        );
+        this._client.emit('publish:failed', {
+          queue,
+          attempt,
+          error: lateRefusal.message,
+          retryable: false,
+          refusedLate: true
+        });
+        throw lateRefusal;
+      }
+
       attempt++;
 
       try {
@@ -133,7 +213,12 @@ class PublishLayer {
           this._logger.debug(`[PublishLayer] Retry attempt ${attempt}/${this._maxRetries} for queue "${queue}"`);
         }
 
-        await this._client._publishOnce(queue, buffer, options);
+        // WHICH attempt this is travels with the send, and is read by exactly one thing:
+        // the transport's report of a broker verdict that arrived after the confirmation
+        // budget had already answered (`publish:refused-late`, d.801b). It reaches no
+        // broker property — `buildAmqpMessageProperties()` copies only the AMQP keys it
+        // declares — and it changes nothing about the publish itself.
+        await this._client._publishOnce(queue, buffer, { ...options, attempt });
 
         // Track success (always emit, even for first attempt)
         this._client.emit('publish:success', {
@@ -198,6 +283,24 @@ class PublishLayer {
               this._retryMaxDelay
             );
             this._logger.warn(`[PublishLayer] Retryable error for queue "${queue}" (attempt ${attempt}/${this._maxRetries}), waiting ${delay}ms before retry: ${err.message}`);
+            // THE BARE TIMER IS THE POINT, and it is not a copy of the transport's rail.
+            //
+            // The transport sleeps through `_setTimeout()`, which files the handle in
+            // `_activeTimers` so that a teardown can END the wait (d.759e). That is right
+            // THERE: what waits is the client's own recovery loop, and a teardown must
+            // stop it. It is wrong HERE, because what waits is the CALLER's `publish()`.
+            // Měřeno d.766 on this runtime: a sleep armed through `_setTimeout()` and
+            // swept by `_clearAllTimers()` mid-wait NEVER settles (the same sleep on the
+            // bare timer always does), so the one rail would turn a disconnect during a
+            // backoff into a `publish()` that never returns. The layer HAS the client
+            // (injected, required in the constructor), so this is a difference of
+            // obligation and not of reach.
+            //
+            // One owner at this level: the retry wait is the layer's, it is always
+            // awaited by the caller, and it always ends.
+            // @see ../transports/rabbitmqClient.js — `_setInterval` / `_clearAllTimers`
+            // @see ../../tests/unit/publish-max-retries-counts-attempts.test.js — the
+            //      control case that fails if this is ever "unified"
             await new Promise(resolve => setTimeout(resolve, delay));
             continue;
           }
@@ -235,6 +338,11 @@ class PublishLayer {
         null
       )
     );
+    } finally {
+      // The subscription lives exactly as long as this publish: no listener survives the
+      // call that opened it, whichever way the loop ended.
+      this._client.removeListener('publish:refused-late', onRefusedLate);
+    }
   }
 
   /**

package/src/monitoring-publish.js

@@ -18,19 +18,66 @@
  *   await publishToMonitoringWorkflow(mqClient, { event_type: 'completed', workflow_id: '...', ... }, logger);
  */
 
-const { PublishError, ConnectionError } = require('./utils/errorHandler');
+const { ConnectionError } = require('./utils/errorHandler');
 const { assertLogger } = require('@onlineapps/logger-contract');
-const { QueueNotFoundError, classifyPublishError } = require('./utils/publishErrors');
+const {
+  AMQP_NOT_FOUND,
+  QueueNotFoundError,
+  TransientPublishError
+} = require('./utils/publishErrors');
 
 /**
- * Check if error indicates queue doesn't exist or RabbitMQ is unavailable
+ * The socket-level codes that mean the broker was not reachable at all. Node sets
+ * them, not this package, and they are codes rather than words.
+ */
+const UNREACHABLE_SOCKET_CODES = new Set(['ECONNREFUSED', 'ENOTFOUND', 'ETIMEDOUT']);
+
+/**
+ * How deep a cause chain this function is willing to walk.
  *
- * The queue is named because the last question it asks —
- * `classifyPublishError()` — builds a `QueueNotFoundError`, and that error carries
- * a queue name it must be told (d.435); the caller has had it all along.
+ * The measured chain is three links — `PublishError` (BaseClient) → the publish
+ * classification → amqplib's raw error — so the bound is an upper limit on a real
+ * shape, not a guess about an unknown one. It exists because `error.cause` is set by
+ * whoever threw, and a chain that points back at itself would otherwise spin.
+ */
+const MAX_CAUSE_DEPTH = 8;
+
+/**
+ * Does this error — or anything it was caused by — mean the queue was not there to
+ * publish into, or the broker was not reachable?
+ *
+ * DECIDED BY CLASS AND CODE, NEVER BY THE MESSAGE. Until d.676 the decision read
+ * substrings: `'not connected'`, `'Connection closed'`, `'NOT_FOUND'`, `'404'`,
+ * `'no queue'`, `'queue does not exist'`, `'Channel closed'`. Every one of those
+ * sentences belongs to somebody else — amqplib writes the broker's refusal, this
+ * package writes its own — so the classification broke on any rewording and nothing
+ * reported the break (`docs/biz/70-contracts/error-handling.md` §6: "Message-based
+ * routing; breaks on any wording change — branch on `err.code`").
+ *
+ * WHY THE CHAIN AND NOT THE ERROR ITSELF: `BaseClient.publish()` wraps every
+ * transport failure in a `PublishError` and puts the real error in `cause`. So the
+ * object handed to this function is the wrapper, its `instanceof` tests never
+ * matched, and only the substrings ever fired — by accident, because the wrapper's
+ * message quotes the cause's sentence. Two shapes were measured answering `false`
+ * although the queue really was unavailable: a `QueueNotFoundError` with
+ * `kind: 'unowned'`, whose sentence carries none of the substrings, and a
+ * retry-exhausted publish, whose sentence quotes no cause at all.
+ *
+ * The carriers this walks for, and what each stands for:
+ *   - `QueueNotFoundError` — the publish path's own ownership refusal (the queue is
+ *     absent, whichever owner should have created it);
+ *   - `ConnectionError` — the client is not connected, or the connection dropped
+ *     (`CONNECTION_CLOSED_UNEXPECTEDLY`);
+ *   - `TransientPublishError` — the channel or connection went away mid-publish;
+ *     amqplib's `IllegalOperationError` ("Channel closed"), which carries no code of
+ *     its own, reaches here as exactly this class;
+ *   - `code === 404` — amqplib's raw `NOT_FOUND`;
+ *   - `ECONNREFUSED` / `ENOTFOUND` / `ETIMEDOUT` — the broker was unreachable.
  *
  * @param {Error} error - The error a publish to `queueName` produced.
- * @param {string} queueName - The queue that publish was aimed at.
+ * @param {string} queueName - The queue that publish was aimed at. Required since
+ *   d.435 and part of the exported contract; it is what the refusal below names.
+ * @returns {boolean}
  * @private
  */
 function isQueueUnavailableError(error, queueName) {
@@ -43,39 +90,21 @@ function isQueueUnavailableError(error, queueName) {
     );
   }
 
-  if (!error) return false;
-  
-  const errorMessage = error.message || String(error);
-  const errorCode = error.code || '';
-  const errorName = error.name || '';
-  
-  // Connection errors
-  if (error instanceof ConnectionError || 
-      errorCode === 'ECONNREFUSED' || 
-      errorCode === 'ENOTFOUND' || 
-      errorCode === 'ETIMEDOUT' ||
-      errorMessage.includes('not connected') ||
-      errorMessage.includes('Connection closed')) {
-    return true;
-  }
-  
-  // Queue doesn't exist errors
-  if (error instanceof QueueNotFoundError ||
-      errorName === 'QueueNotFoundError' ||
-      errorMessage.includes('NOT_FOUND') || 
-      errorMessage.includes('404') ||
-      errorMessage.includes('no queue') ||
-      errorMessage.includes('queue does not exist') ||
-      errorMessage.includes('Channel closed')) {
-    return true;
-  }
-  
-  // Classify publish errors
-  const classified = classifyPublishError(error, queueName);
-  if (classified instanceof QueueNotFoundError) {
-    return true;
+  let link = error;
+
+  for (let depth = 0; depth < MAX_CAUSE_DEPTH && link instanceof Error; depth += 1) {
+    if (link instanceof QueueNotFoundError
+      || link instanceof ConnectionError
+      || link instanceof TransientPublishError
+      || link.code === AMQP_NOT_FOUND
+      || UNREACHABLE_SOCKET_CODES.has(link.code)) {
+      return true;
+    }
+
+    if (link.cause === link) break;
+    link = link.cause;
   }
-  
+
   return false;
 }
 
@@ -115,6 +144,26 @@ async function publishToMonitoringResilient(mqClient, queueName, message, logger
     return false;
   }
 
+  // The client's own events go out on the client's own channel (d.724). Said here, in the
+  // one place that knows these messages are the client talking about itself; `publish()`
+  // would put them on the channel carrying the caller's business messages, where a
+  // refusal of an event closes the channel and takes those with it (measured d.711).
+  // Reported and skipped rather than thrown, like every other precondition in this
+  // function: it is fail-safe about publishing by contract (§ Principles above), and a
+  // transport without the method would otherwise turn a monitoring event into a caller's
+  // exception.
+  if (typeof mqClient.publishTelemetry !== 'function') {
+    logger.warn(
+      `Monitoring publish skipped: the client has no publishTelemetry() (queue: ${queueName}) - `
+        + 'Expected: a client whose telemetry has a channel of its own, so a refused event cannot '
+        + 'close the channel a business message is waiting on. '
+        + 'Fix: pass a @onlineapps/mq-client-core BaseClient, or a client that forwards '
+        + 'publishTelemetry() to one.',
+      context
+    );
+    return false;
+  }
+
   if (!message || !message.event_type) {
     logger.warn(`Monitoring publish skipped: message missing event_type (queue: ${queueName})`, {
       ...context,
@@ -140,7 +189,7 @@ async function publishToMonitoringResilient(mqClient, queueName, message, logger
     const publishOptions = queueName === 'monitoring.workflow'
       ? { exchange: WORKFLOW_FANOUT, routingKey: '' }
       : {};
-    await mqClient.publish(queueName, message, publishOptions);
+    await mqClient.publishTelemetry(queueName, message, publishOptions);
 
     logger.debug(`Published to ${queueName}`, {
       ...context,