@onlineapps/mq-client-core 4.2.0 → 5.0.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)
@@ -114,7 +119,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
@@ -130,6 +135,11 @@ 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
+- `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 +194,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 +206,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 +314,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 +330,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 +407,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 +535,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,7 +561,9 @@ 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
 
@@ -605,6 +638,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 +720,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 +849,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 +907,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.0.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));
 
@@ -736,6 +758,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 +779,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 +815,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 +1034,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,

package/src/config/configSchema.js

@@ -143,8 +143,9 @@ module.exports = {
       type: 'string',
       minLength: 1,
       description:
-        'Name this client publishes under and names its queues with. Explicit value, else '
-        + 'ENV SERVICE_NAME, else the module default (../defaults.js serviceName).',
+        'Name this client publishes under and names its queues with. Required: the explicit '
+        + 'value, else ENV SERVICE_NAME — there is no module default, because a name this '
+        + 'library invented would name a service that does not exist (d.770).',
     },
     connectionName: {
       type: 'string',
@@ -248,8 +249,24 @@ module.exports = {
     },
     publishMaxRetries: {
       type: 'integer',
-      minimum: 0,
-      description: 'How many publish attempts one message gets before the publish fails.',
+      // ONE, not zero (d.685b). The key counts ATTEMPTS, the first one included, so `0`
+      // is not a smaller amount of retrying — it is a publish that never happens: the
+      // loop `while (attempt < this._maxRetries)` does not run its body, the message is
+      // never offered to the broker and is not buffered on the way out either (measured,
+      // d.684). `PublishLayer`'s constructor has refused it by name since that batch,
+      // while this declaration still said it was legal — one key with two answers, and
+      // the one a service author READS said the wrong one. The declaration is the
+      // prescriptive half (`doc-code-binding.md` §1), so it is the half that moved.
+      //
+      // Both doors stay: this one refuses the value at CONSTRUCTION of a `BaseClient`,
+      // the layer's refuses it wherever a transport is built past the schema
+      // (`transports/transportFactory.js` validates nothing) or the caller hands the
+      // layer its own `options.maxRetries`.
+      //
+      // "Do not retry" is `publishMaxRetries: 1`; leaving the retry rail is
+      // `publishRetryEnabled: false`. Both are explicit (`architecture-principles.md` §8).
+      minimum: 1,
+      description: 'How many publish attempts one message gets before the publish fails; at least 1, because the first attempt is one of them.',
     },
     publishRetryBaseDelay: {
       type: 'integer',

package/src/config/defaultConfig.js

@@ -16,9 +16,15 @@
  * (`change-discipline.md`), and the `||` was worse than the duplication: it means
  * "if falsy", not "if absent", and the schema declares `minimum: 0` for these
  * knobs. A caller who wrote `reconnectBaseDelay: 0` ("retry immediately"),
- * `publishMaxRetries: 0` ("do not retry") or `thrashingThreshold: 0` ("alert on
- * the first close") had the value replaced by its opposite, without a word.
- * Measured on 2026-09-14: twelve knobs swallowed a written `0`.
+ * `publishRetryBaseDelay: 0` ("no wait between attempts") or `thrashingThreshold: 0`
+ * ("alert on the first close") had the value replaced by its opposite, without a
+ * word. Measured on 2026-09-14: twelve knobs swallowed a written `0`.
+ *
+ * `publishMaxRetries: 0` was named among those examples until d.684, glossed as "do
+ * not retry". It never meant that: the key counts ATTEMPTS, the first one included
+ * (see it below, and `configSchema.js`), so `0` says "never offer this message to the
+ * broker" — which is what the loop did. It is now refused by name at construction
+ * (`layers/PublishLayer.js`); "one attempt, no retry" is `1`.
  *
  * `??` was not the answer either. It fixes the falsy half and leaves the value
  * written in two places, which is the half that rots.
@@ -100,7 +106,11 @@ module.exports = {
 
   publishRetryEnabled: true,
 
-  // How many attempts one publish gets before it is buffered or reported.
+  // How many attempts one publish gets before it is buffered or reported — the first
+  // attempt included, so `1` is "one attempt, no retry". At least 1: `0` would mean the
+  // message is never offered to the broker, and it is refused by name rather than
+  // obeyed (`layers/PublishLayer.js`, d.684). To leave the retry rail entirely, write
+  // `publishRetryEnabled: false`.
   publishMaxRetries: 3,
 
   // First wait between two attempts, in ms, multiplied by

package/src/config/deliveryPolicy.js

@@ -51,16 +51,22 @@
  * environment form goes through numeric coercion, because an environment
  * variable has no other shape (`../config.js`, `../defaults.js`).
  *
- * Both refusals are raised at the throw site itself
- * (`transports/rabbitmqClient.js` `consume()`), not here: a message this library
- * hands a caller must open with the context that produced it
- * (`architecture-principles.md` §5), and a context passed in as a parameter is
- * invisible to the guard that checks that
- * (`tests/unit/error-message-contract.test.js`).
+ * The option rules — `requeueOnError` a boolean, `requeueOnError: false` meaning
+ * one attempt and contradicting any other `maxAttempts`, the budget an integer
+ * >= 1, `classify` a function — live in `validateConsumeOptions` below, the one
+ * owner the transport's `consume()` calls and the package exports (d.1005), so a
+ * consumer's test double asks the same function instead of copying the rules.
+ * Every refusal opens with the literal context of the call it guards,
+ * `[RabbitMQClient]`, written at the throw site: a context passed in as a
+ * parameter would be invisible to the guard that checks it
+ * (`tests/unit/error-message-contract.test.js`), and the texts are the ones
+ * `consume()` has always thrown.
  *
  * @see ../../README.md § consume() — the delivery contract
  */
 
+const { ValidationError } = require('../utils/errorHandler');
+
 /** Header carrying how many attempts a message has already cost. Never a literal elsewhere. */
 const ATTEMPTS_HEADER = 'x-oa-delivery-attempts';
 
@@ -153,6 +159,79 @@ function classifyError(classify, error) {
   return { classification: answer, failure: null };
 }
 
+/**
+ * Validate the options of `consume()` and resolve the delivery policy they ask for.
+ *
+ * `requeueOnError` is the SAME policy as `maxAttempts` said in one word, never a
+ * second one: `false` means a budget of one attempt, `true` or absent leaves the
+ * budget to `maxAttempts` or the default. `requeueOnError: false` together with
+ * any `maxAttempts` other than 1 is refused rather than resolved by preferring
+ * one of the two. An explicit `maxAttempts` is taken exactly as written — never
+ * coerced. `classify` defaults to `defaultClassification`.
+ *
+ * @param {Object} options the options passed to `consume()`
+ * @param {function(): number} resolveDefaultMaxAttempts returns the budget when
+ *   the caller names none — the transport resolves its configuration there
+ *   (explicit → env RABBITMQ_MAX_DELIVERY_ATTEMPTS → defaults.js). Called ONLY
+ *   when the options leave the budget open: resolving it reads configuration,
+ *   which can refuse on its own, and an explicit `maxAttempts` or
+ *   `requeueOnError: false` never needed it. Its value is validated like an
+ *   explicit one.
+ * @returns {{maxAttempts: number, classify: function(Error): string}}
+ * @throws {ValidationError} the first rule the options break, in the words
+ *   `consume()` refuses them with
+ */
+function validateConsumeOptions(options, resolveDefaultMaxAttempts) {
+  if (options.requeueOnError !== undefined && typeof options.requeueOnError !== 'boolean') {
+    throw new ValidationError(
+      '[RabbitMQClient] Invalid requeueOnError - Expected: true or false, got '
+        + `${JSON.stringify(options.requeueOnError)}. Fix: pass consume(queue, handler, `
+        + '{ requeueOnError: false }) to dead-letter on the first failure, or leave it out and '
+        + 'let the delivery budget decide.'
+    );
+  }
+
+  const noRequeue = options.requeueOnError === false;
+
+  if (noRequeue && options.maxAttempts !== undefined && options.maxAttempts !== 1) {
+    throw new ValidationError(
+      '[RabbitMQClient] Contradictory delivery policy - requeueOnError: false means one attempt, '
+        + `but maxAttempts says ${JSON.stringify(options.maxAttempts)}. Expected: one statement about `
+        + 'how many times a handler may run. Fix: drop requeueOnError to keep the budget, or drop '
+        + 'maxAttempts to dead-letter on the first failure.'
+    );
+  }
+
+  const maxAttempts = noRequeue
+    ? 1
+    : options.maxAttempts === undefined
+      ? resolveDefaultMaxAttempts()
+      : options.maxAttempts;
+
+  if (!Number.isInteger(maxAttempts) || maxAttempts < 1) {
+    throw new ValidationError(
+      '[RabbitMQClient] Invalid delivery budget - maxAttempts must be an integer >= 1, got '
+        + `${JSON.stringify(maxAttempts)}. Fix: pass consume(queue, handler, { maxAttempts: <integer >= 1> }), `
+        + 'or leave it out and let the module default (defaults.js maxDeliveryAttempts, '
+        + 'env RABBITMQ_MAX_DELIVERY_ATTEMPTS) decide.'
+    );
+  }
+
+  const classify = options.classify === undefined
+    ? defaultClassification
+    : options.classify;
+
+  if (typeof classify !== 'function') {
+    throw new ValidationError(
+      '[RabbitMQClient] Invalid error classifier - classify must be a function returning '
+        + `'transient' or 'permanent', got ${typeof options.classify}. Fix: pass consume(queue, handler, `
+        + '{ classify: (error) => … }), or leave it out and every error is treated as transient.'
+    );
+  }
+
+  return { maxAttempts, classify };
+}
+
 module.exports = {
   ATTEMPTS_HEADER,
   TRANSIENT,
@@ -162,4 +241,5 @@ module.exports = {
   defaultClassification,
   readAttemptsMade,
   classifyError,
+  validateConsumeOptions,
 };