@onlineapps/mq-client-core 4.2.0 → 5.1.0

package/README.md

@@ -36,17 +36,21 @@ const BaseClient = require('@onlineapps/mq-client-core');
 const mqClient = new BaseClient({
   type: 'rabbitmq',
   host: 'amqp://localhost:5672',
+  serviceName: 'api_gateway', // REQUIRED unless ENV SERVICE_NAME is set
   logger                  // REQUIRED: info/warn/error/debug
 });
 
 await mqClient.connect();
 await mqClient.publish('workflow.init', { workflowId: '123', data: '...' });
-await mqClient.publish('workflow.control', { workflowId: '123', data: '...' });
+await mqClient.publish('workflow.completed', { workflowId: '123', data: '...' });
 ```
 
 ### Configuration
 
-**Required:** `type`, `host`, `logger`. Every other key is optional — but it has to
+**Required:** `type`, `host`, `logger`, and `serviceName` — the explicit key, or ENV
+`SERVICE_NAME`. The library invents no name: a client with neither is refused at
+construction (d.770), because a default would file every monitoring event, and name every
+queue and connection, under a service that does not exist. Every other key is optional — but it has to
 be a key this client declares: a name nothing declares is **refused at construction**,
 named, together with the declared key it is closest to. There is no "anything else"
 door (`src/config/configSchema.js`, `additionalProperties: false`). A key the client
@@ -59,6 +63,7 @@ package.
   type: 'rabbitmq',        // Required
   host: 'amqp://...',      // Required
   logger,                   // Required: info/warn/error/debug
+  serviceName: 'billing',   // Required unless ENV SERVICE_NAME; names the connection and every event
   exchange: '',             // Optional exchange
   durable: true,            // Optional (default: true)
   prefetch: 1,              // Optional (default: 1)
@@ -81,11 +86,18 @@ says" — and every connection on the platform ran on the broker's number rather
 the configured one (measured on the dev broker: 39 live connections, `timeout: 60`
 on all of them).
 
-`brokerAnswerTimeout` bounds **both** things this client waits for the broker to
-answer: the confirm of one publish attempt, and the `close-ok` of each handle
-`disconnect()` closes. It was called `publishConfirmationTimeout` until
-2026-09-14 — the name of one of its two consumers — and writing that name now is
-refused, with the new one named.
+`brokerAnswerTimeout` bounds **every** wait on the broker's answer — the confirm of
+one publish attempt, the `close-ok` of each handle `disconnect()` closes, and every
+request a channel sends and waits on: `assertQueue`, `checkQueue` (also the check before a
+queue publish), `bindQueue`, `assertExchange`, `purgeQueue`, `deleteQueue`, `consume`,
+`cancelConsumer`, the prefetch, and every channel open (conf `mq-broker-answer-budget` 001).
+A request left unanswered for that long discards the channel that carried it (the next
+operation opens a fresh one) and ends in `ConnectionError` naming the operation, its target
+and the budget; on the publish path it is `TransientPublishError`, so retry, the buffer and
+`bufferOnFailure: false` apply as to any transient failure. This is what ends the wait on a
+broker in a memory alarm, which keeps the connection and its heartbeats alive while it
+answers nothing. It was called `publishConfirmationTimeout` until 2026-09-14 — the name of
+one of its consumers — and writing that name now is refused, with the new one named.
 
 `maxReconnectAttempts` and `maxReconnectCycles` resolve the usual way — explicit
 config → env (`RABBITMQ_MAX_RECONNECT_ATTEMPTS`, `RABBITMQ_MAX_RECONNECT_CYCLES`)
@@ -114,7 +126,7 @@ The library owns NO logger. `logger` is required and validated in the
 logger fails the constructor, it does not fall back to `console`.
 
 The same object is forwarded to everything the client builds — transport,
-publish layer, recovery worker, buffers — so one service configures one
+publish layer, buffers — so one service configures one
 channel and the whole client writes there. Levels: `info` for lifecycle
 (connected, consumer registered, channel recovered), `debug` for
 per-message and setup detail, `warn`/`error` for the rest. An error
@@ -129,7 +141,15 @@ Owner decision: `api/docs/governance/confirmations/connector-logger-contract.md`
 
 - `connect(options?)` - Connect to RabbitMQ
 - `disconnect()` - Disconnect from RabbitMQ
-- `publish(queue, message, options?)` - Publish message to queue
+- `publish(queue, message, options?)` - Publish message to queue. `options.bufferOnFailure`
+  (boolean, default `true`): `false` leaves the publish buffer for this one call — a
+  transiently failed message is NOT held and no reconnect replays it; the thrown
+  `PublishError` then carries `buffered: false` (see § The publish buffer).
+- `publishTelemetry(queue, message, options?)` - Publish the client's OWN event (the
+  monitoring helpers below use it) on a confirm channel of its own, opened with the
+  first such publish. A refusal there closes that channel only, never the one a
+  business message is waiting on (d.724). The channel is chosen by this call, never by
+  the queue name.
 - `consume(queue, handler, options?)` - Consume messages from queue; resolves with
   the broker's consumer tag. A failing handler is answered by the delivery policy,
   never by a bare requeue — see § `consume()` — the delivery contract.
@@ -184,7 +204,10 @@ Owner decision: `api/docs/governance/confirmations/connector-logger-contract.md`
   `flushed`, plus a per-queue breakdown; the second renders the same counters as
   Prometheus text.
 - `getChannelState()` / `getConsumerState()` / `getBufferState()` - Liveness of the
-  three channels, the consumers this client holds, and what is waiting in the
+  channels (`publisher`, `queue`, `consumer` and `telemetry`, each `{ exists, closed,
+  ready }`; `telemetry` opens with the first telemetry publish and reads
+  `{ exists: false, closed: true, ready: false }` until then — d.1007), the consumers
+  this client holds, and what is waiting in the
   publish buffer (`{ size, inMemory }` — there is one buffer). All five refuse
   before `connect()` has built a transport, rather than answering with an invented
   zero. `getConsumerState()` answers `{ tracked, active }`: `tracked` counts the
@@ -193,7 +216,9 @@ Owner decision: `api/docs/governance/confirmations/connector-logger-contract.md`
   this client takes no message off some queue it registered.
 - `disconnectAll()` (static, on the class and on the package export) - Close every
   client this module holds; see § Shutdown.
-- `onError(callback)` - Register error handler
+- `onError(callback)` - Register error handler for connection and channel faults. A
+  failed publish is NOT reported here: its verdict is the rejection of `publish()`
+  (d.811b).
 - `onFatal(callback)` - Register handler for the permanent loss of the
   connection (see § Connection loss)
 
@@ -299,6 +324,13 @@ const { deliveryPolicy } = require('@onlineapps/mq-client-core');
 deliveryPolicy.ATTEMPTS_HEADER; // 'x-oa-delivery-attempts' — read it, never retype it
 ```
 
+**The option rules have one owner, and it is exported.** `consume()` validates its options
+through `deliveryPolicy.validateConsumeOptions(options, resolveDefaultMaxAttempts)`, which
+returns `{ maxAttempts, classify }` or throws the `ValidationError` `consume()` throws, in
+the same words. A consumer's test double of `consume()` calls it instead of copying the
+rules. `resolveDefaultMaxAttempts` is a function, called only when the options leave the
+budget open (d.1005).
+
 **The `message_dlq` event** goes to `monitoring.workflow` and carries `status: 'rejected'`
 — the broker's own word for this death, what it stamps into `x-death[0].reason`. It is
 published **only when the envelope carries a `workflow_id`**. Without one nothing is
@@ -308,6 +340,11 @@ queue through the DLQ dashboard. `monitoring.workflow` keys every trace on that
 event naming no workflow is either refused as faulty telemetry or — with a marker like
 `'unknown'` in its place — written as a row claiming a workflow by that name.
 
+It also names WHAT died: `operation`, written **only when the envelope carried one** — the
+invocation envelope has the field, the workflow message never does — and left out entirely
+otherwise, with no `unknown` and no `null` standing in for it. The run's identity stays one
+key, `workflow_id`; no event on `monitoring.workflow` carries a `correlation_id`.
+
 **`x-message-ttl` and the budget do not cooperate.** The service queues carry a TTL
 (`<service>.queue` 30 s, `<service>.workflow` 5 min) and each attempt re-publishes the
 message, which restarts that clock. So the TTL bounds ONE attempt, never the whole budget,
@@ -380,7 +417,8 @@ exponential backoff, up to `maxReconnectAttempts` times. That whole budget is on
 where the socket is already back.** "Connected" means the client can be used, and a
 re-established connection whose channels are still being recreated cannot publish or
 consume. The two answers therefore agree at every instant: the moment `isConnected()`
-turns `true`, `getChannelState()` reports all three channels ready.
+turns `true`, `getChannelState()` reports the publisher, queue and consumer channels ready
+(the telemetry channel is opened on demand, so it may still read as not opened).
 
 **Standing down is not dying, and the difference is the point.** An outage the
 broker will come back from must not turn a client into a corpse
@@ -507,9 +545,12 @@ A missing queue is answered by who owns the name, not by the client's scope:
 Publishing must never create an owned queue: `sendToQueue()`/`assertQueue()` would
 declare it with default arguments — no TTL, no DLQ — and the owner's later
 `setupServiceQueues()` then fails with 406 `PRECONDITION_FAILED` because the
-arguments no longer match. The rule is enforced in two places, and both are
-required: the 404 branch of `_publishOnce()` refuses the publish, and
-`RecoveryWorker.handleQueueNotFound()` refuses to create the queue behind it.
+arguments no longer match. The rule is enforced in ONE place: the 404 branch of
+`_publishOnce()` refuses the publish and declares nothing, and the caller gets the
+verdict as the rejection — `PublishError` with the `QueueNotFoundError` as its
+`cause` (`queueName`, `kind`, and per class the owner and the Fix). Nothing else
+answers a missing queue: the worker that once did, from the client's `error`
+channel, is gone (d.971).
 
 Which of the three sentences the refusal carries is decided by the ownership class
 in the error (`kind`), which the central declaration answers — never by how the
@@ -530,15 +571,49 @@ configured publishers declared one exchange two ways, and a client whose
 that was itself faultless. Measured against the live broker: `inequivalent arg
 'type' … received 'direct' but current is 'fanout'`. An exchange nobody declared
 is now a broker-side 404 on the publish, not an exchange invented by whoever
-published first — the same rule as for queues, one object up.
+published first — the same rule as for queues, one object up. The publish answers it
+as a `PermanentPublishError` with the broker's frame in `cause`: one attempt, nothing
+buffered, because no retry and no reconnect declares the exchange (d.693).
 
 ### The publish buffer — one buffer, every priority
 
 A publish that fails transiently (the connection is closing, a channel is being
 recreated, the broker did not confirm in time) is held in memory — bounded by
 `publishBufferMaxSize` messages and `publishBufferTtlMs` each — and replayed after
-the reconnect, critical priority first. `getBufferState()` reports it and
-`publish:buffered` / `buffer:flush:failed` announce it.
+the reconnect or after the broker unblocks the connection (below), critical priority first. `getBufferState()` reports it and
+`publish:buffered` / `buffer:flush:failed` announce it. That includes a publish whose
+confirm was still pending when the channel or the connection died under it (the broker
+closed it, restarted or stopped): the broker said nothing about that message, so it is
+transient, never a refusal — only a `nack` or a numbered close frame naming this send
+is permanent (d.1134).
+
+**One call can leave the buffer: `publish(queue, message, { bufferOnFailure: false })`.**
+It is for a caller that keeps the message durably elsewhere and must not have a second
+copy replayed behind its back — the orchestrator writing a `publish_pending` record
+(`docs/governance/confirmations/step-publish-failure.md` 001). On each of the three
+transient paths (retries exhausted, `publishRetryEnabled: false`, the reconnect a retry
+waited for failed) the error `publish()` throws carries `buffered` (boolean): `true` only
+when the buffer holds the message for the next reconnect, `false` when nothing will
+replay it. A permanent refusal never reaches the buffer and carries no `buffered`. A
+value that is not a boolean is refused before any attempt (`ValidationError`). Retry
+stays the library's either way — the option decides only what happens after it.
+
+**Every failed publish says whether its frame left the client: `error.sent`** (boolean, on
+the `PublishError` from `publish()` and on its cause; conf
+`docs/governance/confirmations/mq-publish-buffer.md` 001). `true` when any attempt wrote the
+frame to the channel — the broker may hold it, and after a memory alarm deliver it, although
+the call failed; `false` when no attempt got that far. It says nothing about whether the
+broker stored the message. The buffer entry records the same fact, and it decides what
+happens when the outage ends:
+
+| The outage ends with | A held message whose frame was never sent | … whose frame was sent |
+|---|---|---|
+| a reconnect (`reconnected`) | re-sent | re-sent — the old socket and what the broker had not read are gone |
+| the broker unblocking the connection (`connection.unblocked`, end of a memory or disk alarm) | re-sent | dropped with a `warn` — the broker delivers the frames it held by itself |
+
+`connection.blocked` is logged as a `warn` with the broker's reason. A held message that
+outlives `publishBufferTtlMs` is logged as an `error` naming its queue or exchange, the
+count, the age and `sent` — `sent=false` is a message lost for good.
 
 **There is no persistent buffer, and `persistentBufferEnabled` /
 `persistentRedisClient` are refused by name.** They declared one until
@@ -605,6 +680,26 @@ it did — every refusal wore the sentence "Expected: the queue to exist before
 attaches to it", which for a queue with no declared route is false in every clause and
 sent the reader to fix something that was not broken.
 
+**The monitoring publish helper asks the same question.**
+`publishToMonitoringResilient()` never throws: a broker that is down, or a monitoring
+queue that does not exist yet, is reported through the logger and answered `false`.
+Which of its two sentences the operator reads — "queue … not available" or "failed to
+publish" — is decided by `isQueueUnavailableError(error, queueName)`, and since d.676
+that decision walks the error's `cause` chain and reads **classes and codes only**:
+`QueueNotFoundError`, `ConnectionError`, `TransientPublishError`, amqplib's numeric
+`code === 404`, and the socket codes `ECONNREFUSED` / `ENOTFOUND` / `ETIMEDOUT`. It
+walks the chain because `BaseClient.publish()` wraps every transport failure in a
+`PublishError` and puts the real class in `cause` — so the classes were never the object
+the function was handed, and until d.676 only its message substrings ever fired. Measured
+consequence of that: a `QueueNotFoundError` with `kind: 'unowned'` answered "not a queue
+problem", and an error whose text merely mentioned `404` answered that it was one.
+
+The helper publishes through `mqClient.publishTelemetry()` (d.724), so a refused
+monitoring event cannot close the channel a business message is waiting on. A client
+without that method — anything that is not a `BaseClient` or a subclass of it — is
+reported with a `warn` and answered `false`; the event is not sent on the business
+channel instead.
+
 ### queueConfig — the classification, as a declared export
 
 The table above is not a copy: the names, their arguments and the two predicates
@@ -667,9 +762,10 @@ topology.telemetryLogsQueue = 'mine';        // TypeError — the object is froz
 | `monitoringInfrastructureHealthEventsQueue` | `monitoring.infrastructure.health.events` | The monitoring consumer's queue on that fanout (`api/infra/api_monitoring/src/consumer/topology.js`, `MONITORING_INFRA_EVENT_QUEUE`). |
 | `deliveryHealthEventsQueue` | `delivery.health.events` | The delivery endpoint binds it to the fanout and consumes it for WS push (`api/infra/api_delivery_endpoint/src/index.js`, `bindQueueToFanout(config.healthEventsQueue, …)`). |
 | `deliveryResourceEventsQueue` | `delivery.resource.events` | Bound to the `monitoring.resource` exchange by `resource.changed.#`; published by the monitoring watcher `resourceChangedPublisher.js`, drained by `ResourceChangedConsumer.js` in the delivery endpoint. |
-| `telemetryLogsQueue` | `telemetry.logs.queue` | Bound to `telemetry.exchange`, which every service publishes to with its own name as the routing key; drained by the monitoring consumer (`api/infra/api_monitoring/src/consumer/index.js`, `topology.TELEMETRY_LOGS_QUEUE`). |
+| `telemetryLogsQueue` | `telemetry.logs.queue` | Bound to `telemetry.exchange` by `telemetry.logs.*`; every telemetry producer publishes there with a routing key of the shape `telemetry.<signal>.<service_name>` (logs: `telemetry.logs.<service_name>`); drained by the monitoring consumer (`api/infra/api_monitoring/src/consumer/index.js`, `topology.TELEMETRY_LOGS_QUEUE`). |
 | `telemetryMetricsQueue` | `telemetry.metrics.queue` | The same exchange, the same consumer — metric samples. |
 | `telemetryTracesQueue` | `telemetry.traces.queue` | The same exchange, the same consumer — spans. |
+| `telemetryExchange` | `telemetry.exchange` | Topic exchange the three queues above are bound to; every telemetry producer publishes to it, and the monitoring consumer asserts it (d.708b). |
 
 - **Frozen on purpose.** An importer must not be able to rewrite platform topology: a
   name overridden on one side of a fanout loses the events silently, which is why batch
@@ -795,6 +891,12 @@ requestedBy })` take. One declaration record, and nothing else:
   is a missing record of work that happened; a lost registration is work that will not happen.
 - `scheduler.requestQueue` is the queue name, composed from the declaration in `queueConfig`
   — a caller never types `scheduler.request`.
+- **A request that cannot be built is told apart by code, never by wording.** Every refusal of
+  a builder — the port's key check, the declaration rules, tenancy, the key, the requester, the
+  event — carries `error.code === scheduler.SCHEDULER_REQUEST_INVALID`; a failed send (no
+  connection, a publish the broker refused) never does. The wrapper's boot uses exactly this to
+  isolate one bad record as a failed source while a broker that is gone still stops the boot
+  ([`scheduler` 020](/docs/governance/confirmations/scheduler.md)).
 
 Two more things a service says on that queue, and one send for all of them:
 
@@ -847,6 +949,34 @@ await port.cancel({ id });
   under the wrapper, which fills it from the envelope of the run, and an operator script that does
   not boot the wrapper at all and works row by row.
 
+### decodeMessage — a delivery, decoded by one rail
+
+`consume()` hands its handler the RAW amqplib delivery. `decodeMessage(raw)` is the one
+public way from that delivery to the message it carries (d.789), so a consumer does not
+keep its own copy of the translation.
+
+```javascript
+const { decodeMessage } = require('@onlineapps/mq-client-core');
+
+await client.consume(queue, async (raw) => {
+  const { body, headers, properties, fields } = decodeMessage(raw);
+  // …
+});
+```
+
+- It returns the decoded body, and `headers`, `properties` and `fields` exactly as they
+  arrived.
+- It refuses with `ValidationError`, naming what arrived: a delivery that is not an
+  object, `content` that is neither a `Buffer` nor a string, an empty body, or a
+  DECLARED content type other than `application/json`. No declaration is fine — the
+  platform envelope does not require one.
+- A body that is not JSON is the `SerializationError` the serializer throws, passed on
+  unchanged — the refused bytes in `payload`, the parser's reason in `cause`.
+- It carries no `retryable` flag: what happens to the message is decided by the
+  caller's `classify(error)` (§ `consume()` — the delivery contract), on the error's
+  class.
+- It is additive: `consume()` still hands over the raw delivery.
+
 ### redactUrl — a connection URL that is safe to log
 
 `RABBITMQ_URL` carries the broker account, so anything that renders it verbatim

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/mq-client-core",
-  "version": "4.2.0",
+  "version": "5.1.0",
   "description": "Core MQ client library for RabbitMQ - shared by infrastructure services and connectors",
   "oa": {
     "category": "connector"

package/src/BaseClient.js

@@ -318,6 +318,12 @@ class BaseClient {
     // Apply resolved runtime config
     this._config.host = resolved.host;
     this._config.heartbeat = this._config.heartbeat ?? resolved.heartbeat;
+    // The resolved identity is WRITTEN BACK, so the config carries what the client runs
+    // under whichever leg produced it — the explicit key or ENV SERVICE_NAME. Until d.770
+    // only the explicit key reached `_config.serviceName`, and everything downstream that
+    // needed the name asked the runtime config again; two readers of one fact, and the
+    // transport's copy answered the module default nobody wrote.
+    this._config.serviceName = resolved.serviceName;
     this._config.connectionName =
       this._config.connectionName ||
       `${resolved.serviceName}:${process.pid}`;
@@ -381,20 +387,36 @@ class BaseClient {
     });
     this._config.host = resolved.host;
     this._config.heartbeat = this._config.heartbeat ?? resolved.heartbeat;
+    this._config.serviceName = resolved.serviceName;
     this._config.connectionName =
       this._config.connectionName ||
       `${resolved.serviceName}:${process.pid}`;
 
-    try {
-      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);
-      this._logger.debug('[BaseClient] Transport created', {
-        transport: this._transport.constructor.name,
-      });
+    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.
+    //
+    // OUTSIDE THE `try` ON PURPOSE (d.736b). What this line can throw is a
+    // refusal of the CONFIGURATION — a target that is not a non-empty string, a
+    // URL declaring its own heartbeat, an `onFatal` that is not a function, a
+    // `type` no transport implements. Nothing has been asked of the broker yet,
+    // and nothing about the answer will change on a second attempt. Until this
+    // batch the `catch` below turned every one of them into `ConnectionError`
+    // ("a reachable broker … check the MQ url, credentials and network"), which
+    // is a transient fault by name — and `ServiceWrapper._initializeMQ()` reads
+    // it as one: it retries `connect()` `wrapper.mq.connectionRetries` times and
+    // stands down only for `code: 'MQ_CONNECTION_FATAL'` (10 attempts, 2 s base,
+    // 30 s cap — `service-wrapper/config/runtime-defaults.json`), so a typo in a
+    // URL cost ~200 s of backoff and then sent the operator to look at the
+    // network. The refusal already names the key and the fix
+    // (`architecture-principles.md` §5); it is passed on as it is.
+    this._transport = transportFactory.create(this._config);
+    this._logger.debug('[BaseClient] Transport created', {
+      transport: this._transport.constructor.name,
+    });
 
+    try {
       // Register internal error propagation
       this._transport.on('error', (err) => this._handleError(err));
 
@@ -472,9 +494,14 @@ class BaseClient {
    *   infrastructure or business queue is created by its owner before anything
    *   publishes to it, and an ownerless name is declared with the arguments the
    *   central `queueConfig` resolves (`transports/rabbitmqClient.js`, the 404 branch).
+   * @param {boolean} [options.bufferOnFailure=true] - `false` = a transiently failed message
+   *   is NOT held in the library's buffer, so no reconnect replays it; for a caller that keeps
+   *   the message durably elsewhere. Owned by `layers/PublishLayer.js`; a non-boolean is refused.
    * @returns {Promise<void>}
    * @throws {ConnectionError} If not connected.
-   * @throws {PublishError} If publish fails.
+   * @throws {PublishError} If publish fails. After a transient failure (retries exhausted,
+   *   retry disabled, the awaited reconnect failed) it carries `buffered` (boolean): `true`
+   *   only when the buffer holds the message for the next reconnect.
    */
   async publish(queue, message, options = {}) {
     if (!this._connected || !this._transport) {
@@ -517,7 +544,7 @@ class BaseClient {
       // answer as d.297 one call over (`_consumerRefusal()`): name no likeliest
       // cause, carry the one actually caught. `cause` is unchanged, so a caller
       // deciding on the class still reads the object.
-      throw new PublishError(
+      const failure = new PublishError(
         `[BaseClient] Failed to publish to queue "${queue}": ${describeThrown(err)} - `
           + 'Expected: publish() to hand the message to the broker. '
           + 'Fix: act on the reason above — this layer does not know which failure it was, and naming the '
@@ -526,6 +553,20 @@ class BaseClient {
         queue,
         err
       );
+      // Whether the library's buffer holds the message is decided and written by
+      // `PublishLayer` (options.bufferOnFailure, d.1122); it is carried up here unchanged so
+      // the caller reads it on the error it catches. Absent when the failure never reached
+      // the buffer decision — "not asked" is not "false".
+      if (err && typeof err.buffered === 'boolean') {
+        failure.buffered = err.buffered;
+      }
+      // Whether any attempt wrote the frame (d.1145, conf `mq-publish-buffer` 001): carried
+      // like `buffered`, so the caller — the orchestrator's `publish_pending` record
+      // (`step-publish-failure` 003) — reads it on the error it catches.
+      if (err && typeof err.sent === 'boolean') {
+        failure.sent = err.sent;
+      }
+      throw failure;
     }
   }
 
@@ -736,6 +777,18 @@ class BaseClient {
    * 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.
    *
+   * `operation` says WHAT died, and it is written ONLY when the envelope carried
+   * one: the invocation envelope has the field
+   * (`docs/biz/10-invocation/mq-envelope.md` § Inbound envelope), the workflow
+   * message of `docs/biz/70-contracts/workflow-message.md` §3.2 never does, and
+   * this event reports what it found rather than a marker. It has a reader
+   * already — `readReported(data.operation)` in the monitoring consumer
+   * (`infra/api_monitoring/src/consumer/apiflow-extension.js`), from where the
+   * value reaches the Loki line as `operation`; until it was written here, every
+   * dead letter arrived there as `null`. The run's identity stays ONE key,
+   * `workflow_id`: no event on this queue carries a `correlation_id`
+   * (`docs/biz/70-contracts/monitoring-events.md` § Rules).
+   *
    * @param {Object} event - As the transport reports it.
    * @returns {Promise<void>}
    * @private
@@ -745,16 +798,22 @@ class BaseClient {
     const serviceName = runtimeCfg.get('serviceName', this._config.serviceName);
 
     let workflowId = null;
+    let operation = 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;
+      if (envelope !== null && typeof envelope === 'object') {
+        if (typeof envelope.workflow_id === 'string' && envelope.workflow_id !== '') {
+          workflowId = envelope.workflow_id;
+        }
+        if (typeof envelope.operation === 'string' && envelope.operation !== '') {
+          operation = envelope.operation;
+        }
       }
     } 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;
+      operation = null;
     }
 
     if (workflowId === null) {
@@ -775,29 +834,64 @@ class BaseClient {
       return;
     }
 
+    const payload = {
+      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()
+    };
+
+    // …and WHAT died, when the envelope says so. The key is written only when
+    // the envelope carried one, in the one spelling the invocation envelope
+    // uses; an envelope without it leaves the event without the key rather than
+    // with an invented marker, exactly as workflow_id is handled above.
+    if (operation !== null) {
+      payload.operation = operation;
+    }
+
     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()
-      },
+      payload,
       this._logger,
       { queue }
     );
   }
 
+  /**
+   * Publish one of the CLIENT'S OWN events — the messages nobody asked it to send.
+   *
+   * Same path as `publish()` in every respect but one: the send goes out on a channel of
+   * its own (`transports/rabbitmqClient.js` § _ensurePublisherChannel, role
+   * `'telemetry'`), so a refusal of an event can never close the channel a caller's
+   * message is waiting for a confirm on.
+   *
+   * WHY IT IS A SEPARATE METHOD and not a flag on `publish()`: the caller of `publish()`
+   * is sending its own message and has no business choosing a channel; the only code that
+   * may say "this is the client talking about itself" is the code that IS the client
+   * talking about itself (`src/monitoring-publish.js`). Measured cost of the shared
+   * channel, d.711: in a vhost where `monitoring.workflow.fanout` was not declared, the
+   * `404` for a dead-letter event took the business publish beside it down with it — 3 of
+   * 7 runs of a suite that had nothing to do with telemetry.
+   *
+   * @param {string} queue - Target queue name.
+   * @param {Object|Buffer|string} message - Payload to send.
+   * @param {Object} [options] - The same overrides `publish()` takes.
+   * @returns {Promise<void>}
+   */
+  async publishTelemetry(queue, message, options = {}) {
+    return this.publish(queue, message, { ...options, channelRole: 'telemetry' });
+  }
+
   /**
    * Assert queue existence (delegates to transport).
    * @param {string} queue - Queue name
@@ -959,7 +1053,8 @@ class BaseClient {
    *
    * Settling is idempotent: the transport marks the delivery via `msg._mqProcessed`
    * and `consume()` skips its own auto-ack for a message the handler already
-   * settled (`transports/rabbitmqClient.js:1769` and `:2268`). Calling this from
+   * settled (`RabbitMQClient.consume()` and `_applyDeliveryPolicy()` in
+   * `transports/rabbitmqClient.js`). Calling this from
    * inside a consume handler is therefore supported, not a double-settle.
    *
    * Until 2026-08-28 this method was declared TWICE in this class; the second,