@onlineapps/mq-client-core 2.0.1 → 3.0.1

package/README.md

@@ -1,3 +1,15 @@
+> Status: current
+> Owns: the base RabbitMQ client that infrastructure services and the MQ connector both build on
+
+<!-- BEGIN GENERATED: library-uniform — regenerate: npx oa-sync-template readme-uniform --all -->
+Uniform: [library/connector](../connector/conn-orch-validator/manifests/library.manifest.json)
+
+Duty sections that apply:
+
+- `all`: L-MAIN, L-ENGINES, L-TESTS, L-TEST-SCRIPT, L-PACK-TESTS, L-PINS, L-NO-FILE-RANGE, L-CHANGELOG, L-README, L-README-REGION, L-CONSUMER
+- `connector`: L-CONNECTOR-ENV
+<!-- END GENERATED: library-uniform -->
+
 # @onlineapps/mq-client-core
 
 Core MQ client library for RabbitMQ - shared by infrastructure services and connectors.
@@ -24,7 +36,7 @@ const BaseClient = require('@onlineapps/mq-client-core');
 const mqClient = new BaseClient({
   type: 'rabbitmq',
   host: 'amqp://localhost:5672',
-  queue: 'workflow.init' // Optional default queue
+  logger                  // REQUIRED: info/warn/error/debug
 });
 
 await mqClient.connect();
@@ -34,21 +46,83 @@ await mqClient.publish('workflow.control', { workflowId: '123', data: '...' });
 
 ### Configuration
 
-**Flexible Schema** - Only `type` and `host` are required:
+**Required:** `type`, `host`, `logger`. 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
+does not read configures nothing, and until 2026-09-14 the value written under it was
+lost in silence — `queue` rode that door from four callers for the lifetime of the
+package.
 
 ```javascript
 {
   type: 'rabbitmq',        // Required
   host: 'amqp://...',      // Required
-  queue: 'optional',        // Optional default queue
+  logger,                   // Required: info/warn/error/debug
   exchange: '',             // Optional exchange
   durable: true,            // Optional (default: true)
   prefetch: 1,              // Optional (default: 1)
   noAck: false,             // Optional (default: false)
-  logger: null              // Optional custom logger
+  maxReconnectAttempts: 10, // Optional; env RABBITMQ_MAX_RECONNECT_ATTEMPTS — attempts per cycle
+  maxReconnectCycles: 3,    // Optional; env RABBITMQ_MAX_RECONNECT_CYCLES — cycles before it is over
+  heartbeat: 30,            // Optional; env RABBITMQ_HEARTBEAT — SECONDS
+  connectTimeout: 10000,    // Optional; how long one handshake may take (ms)
+  brokerAnswerTimeout: 5000,// Optional; how long to wait for an answer from the broker (ms)
+  onFatal: null             // Optional callback, see § Connection loss
 }
 ```
 
+**The heartbeat is composed into the connection URL**, because that is the only
+place amqplib 0.10 reads it (`lib/connect.js`: `intOrDefault(query.heartbeat, 0)`).
+A `host` that already carries `?heartbeat=` is therefore **refused**: one fact, one
+declaration. Until 2026-09-14 the value was handed to amqplib's socket options
+instead, where it is not read, so the handshake asked for `0` — "whatever the peer
+says" — and every connection on the platform ran on the broker's number rather than
+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.
+
+`maxReconnectAttempts` and `maxReconnectCycles` resolve the usual way — explicit
+config → env (`RABBITMQ_MAX_RECONNECT_ATTEMPTS`, `RABBITMQ_MAX_RECONNECT_CYCLES`)
+→ module default in `src/defaults.js`. They are client *behaviour*, like
+`heartbeat`, so this module owns their defaults; broker topology
+(`host`/`RABBITMQ_URL`) stays required and is never defaulted. The first is the
+attempts inside ONE recovery cycle, the second how many cycles there may be — see
+§ Connection loss.
+
+### A subclass declares its own keys
+
+`new BaseClient(config, extraProperties?)`. The second argument is the JSON Schema
+`properties` of a SUBCLASS, for the keys it reads off the same config object — the one
+place the configuration contract is extended. `ConnectorMQClient`
+([`@onlineapps/conn-infra-mq`](../connector/conn-infra-mq)) passes its own four there:
+each side declares what it owns, so one key keeps one type, one description and one
+owner. A subclass that redeclares a key of this library is refused, naming the key; a
+key neither side declares is refused like any other unknown name.
+
+### Logging — one channel, injected
+
+The library owns NO logger. `logger` is required and validated in the
+`BaseClient` constructor by `assertLogger()` from
+[`@onlineapps/logger-contract`](../logger-contract): an object with
+`info`, `warn`, `error` and `debug`. A missing or incomplete
+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
+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
+that is thrown is not also logged.
+
+Owner decision: `api/docs/governance/confirmations/connector-logger-contract.md`
+001-004.
+
 ## API
 
 ### BaseClient
@@ -56,15 +130,317 @@ await mqClient.publish('workflow.control', { workflowId: '123', data: '...' });
 - `connect(options?)` - Connect to RabbitMQ
 - `disconnect()` - Disconnect from RabbitMQ
 - `publish(queue, message, options?)` - Publish message to queue
-- `consume(queue, handler, options?)` - Consume messages from queue
+- `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.
+- `cancelConsumer(consumerTagOrQueue)` - Stop one consumer this client registered,
+  by the tag `consume()` returned or by the queue name. The consumer is dropped
+  from the client's registry too, so a later reconnect does not bring it back.
+  A consumer that is **tracked but not attached** — its re-registration was
+  refused, so the tag it held names nothing — is refused by name instead: there
+  is nothing on the broker to cancel, and it stays tracked so the next channel
+  recreate can re-attach it. Listen for `consumer:re-registration:failed` to
+  learn why it could not.
+- `isConnectionFatal()` - Is this connection permanently lost (the broker refused
+  it, or every recovery cycle is spent)? The difference between "wait" and
+  "restart me" — see § Connection loss. `false` on a client that never connected:
+  a healthcheck asks this, so it answers rather than throwing.
+- `performHealthCheck()` - Run the client's own check now and return its verdict
+  (`{ timestamp, connection, channels, consumers, queues, healthy, issues }`).
+  Also counts as a use, so a client that stood down starts its next recovery
+  cycle here. A client that TRACKS consumers and has none attached is **not
+  healthy** — `healthy: false`, with an issue naming how many it tracks — because
+  such a client takes no message off any queue. A client that registered no
+  consumer at all is a publisher and stays healthy; the check's own log line says
+  which of the two it is.
+- `assertQueue(queue, options?)` / `checkQueue(queue)` / `purgeQueue(queue)` /
+  `deleteQueue(queue, options?)` - Queue operations, on the queue channel.
+  `assertQueue()` reads exactly four options — `durable`, `arguments`,
+  `exclusive`, `autoDelete` — and refuses any other key by name, together with
+  the declared key it is closest to. An option nobody reads declares nothing, and
+  the caller acts on a guarantee nobody gave. `exclusive` (the queue dies with
+  the connection that declared it) and `autoDelete` (it dies with its last
+  consumer) are the only way to say a queue is temporary; a key left out is left
+  out of the declaration rather than sent as `false`. For an INFRASTRUCTURE or
+  BUSINESS name the central `queueConfig` decides `durable` and `arguments` as
+  always, and a lifetime asked for on such a name is refused — those queues
+  outlive their declarer by design (see § Queue ownership).
+- `assertExchange(exchange, type, options?)` - Declare an exchange. `type` is
+  required (`direct`, `topic`, `fanout`, `headers`): an exchange's type is a
+  topology decision, so the library does not choose one. `durable` defaults to
+  the client's configured value. This is the ONLY place this client declares an
+  exchange — `publish()` names one, it never declares it (see § Queue ownership).
+- `bindQueue(queue, exchange, pattern)` - Bind a queue to an exchange. `pattern`
+  is required and `''` is legal — a fanout exchange ignores the key, but which
+  key a binding carries is never guessed.
 - `ack(msg)` - Acknowledge message
-- `nack(msg, options?)` - Negative acknowledge message
-- `isConnected()` - Check connection status
+- `nack(msg, options?)` - Negative acknowledge message. `options` is an OBJECT
+  `{ requeue: boolean }`, never amqplib's positional `(msg, allUpTo, requeue)`;
+  `requeue` defaults to `true`, so discarding a message needs an explicit
+  `{ requeue: false }`.
+- `isConnected()` - Live connection status, read from the transport
+- `getPublishMetrics()` / `getPrometheusMetrics()` - What this client's publishes
+  have done so far: `attempts`, `successes`, `failures`, `retries`, `buffered`,
+  `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
+  publish buffer (`{ size, inMemory }` — there is one buffer). All five refuse
+  before `connect()` has built a transport, rather than answering with an invented
+  zero.
+- `disconnectAll()` (static, on the class and on the package export) - Close every
+  client this module holds; see § Shutdown.
 - `onError(callback)` - Register error handler
+- `onFatal(callback)` - Register handler for the permanent loss of the
+  connection (see § Connection loss)
 
 `publish()` and the workflow helpers built on it resolve to `undefined`; failure is
 signalled by a thrown `PublishError`, never by a falsy return.
 
+### `consume()` — the delivery contract
+
+A handler that throws does **not** get an unconditional requeue. Every failure is
+counted, and a message that cannot succeed ends in the dead-letter queue the broker
+routes for its queue (`x-dead-letter-routing-key`, i.e. `<service>.dlq`) instead of
+circling for ever. One rail for business and infrastructure consumers alike
+(`api/docs/governance/confirmations/mq-consumer-contract.md` 001 and 002 point 3).
+
+**A queue with no declared dead-letter route is refused, at registration.** The policy
+ends in `nack(requeue=false)`, and the broker moves that message ONLY if the queue
+declares where to (`x-dead-letter-exchange` + `x-dead-letter-routing-key`). Where it does
+not, the broker drops the message instead — so `consume()` throws a `ConsumeError` naming
+the queue before any consumer is attached, rather than losing messages later. There is no
+opt-out: a consumer that wants a queue declares that queue's route in
+`src/config/queueConfig.js`, which is also the only source of truth the check reads — the
+broker cannot be asked, because `checkQueue()` answers with `queue.declare-ok`, which
+carries `{ queue, messageCount, consumerCount }` and no arguments (measured, 2026-09-12).
+`queueConfig.getDeadLetterRoute(queue)` is the exported form of the same answer.
+
+**A TERMINAL queue is consumed, and it is not an exception to that rule but its other
+half.** A queue something else dead-letters TO — `<service>.dlq`, `workflow.failed`,
+`workflow.dlq`, `delivery.dlq` — declares no onward route because the topology says it
+must not have one: a dead-letter route on a dead-letter queue closes a loop or starts a
+chain with no end (`api/docs/governance/confirmations/mq-consumer-contract.md` 002
+point 2, 003 point 2). So the gate asks a second question, `queueConfig.isDeadLetterTarget(queue)`,
+derived from the templates themselves — the set of every `x-dead-letter-routing-key` they
+declare, `{service}` placeholder and all — never from a list of names. Every OTHER queue
+with no route is refused exactly as before, with the same sentence.
+
+What a terminal queue does NOT get is a different delivery policy: the budget is counted
+the same way, and a message that spends it is rejected with `nack(requeue=false)` the same
+way. The difference is what the broker then does with it — there is nowhere to move it to,
+so it is **dropped**. That loss is deliberate (the alternative is the endless requeue this
+policy exists to end) and it is never silent: the client logs it at error level, naming
+the queue, the attempts and the error, and the `message_dlq` event is published as for any
+other rejection.
+
+```javascript
+await client.consume(queue, async (msg, delivery) => {
+  // delivery = { attempt, maxAttempts, isFinalAttempt }
+  await handle(msg);
+}, {
+  maxAttempts: 3,                       // optional; module default otherwise
+  classify: (error) => error.name === 'ValidationError' ? 'permanent' : 'transient'
+});
+```
+
+| the handler | what happens to the message |
+|---|---|
+| returns | acked, once |
+| throws, error `transient`, attempts left | a copy carrying the advanced counter is published to the SAME queue, then the original is acked |
+| throws, error `transient`, `maxAttempts` reached | `nack(requeue=false)` → the broker dead-letters it into `<service>.dlq`, and a `message_dlq` event is published |
+| throws, error `permanent` | the same rejection, on the FIRST failure |
+| acks or nacks the message itself | untouched — the transport's `_mqProcessed` sentinel still wins |
+
+**`maxAttempts`** is how many times the handler may run for ONE message, not how many
+retries follow the first run; `maxAttempts: 1` means "no second attempt". Resolution is
+explicit → `RABBITMQ_MAX_DELIVERY_ATTEMPTS` → `defaults.js maxDeliveryAttempts` (3, the
+value `@onlineapps/error-handler-core` already declares for the same decision). An
+explicit value is taken exactly as written, so `'3'` and `2.5` are refused at `consume()`
+rather than coerced; only the environment form is parsed as a number.
+
+**`classify`** is optional. Without it every error is treated as transient — stated, not
+implied: a permanently failing message still reaches `<service>.dlq`, after `maxAttempts`
+attempts instead of after one. A classifier that throws, or answers with anything but
+`'transient'` / `'permanent'`, is reported through the logger and its message is rejected
+into the dead-letter queue: the library never guesses a classification.
+
+**Why an attempt costs a re-publish and not a requeue.** Measured on the live broker
+(2026-09-11): after `nack(requeue=true)` the redelivery carries `headers: {}` — the
+message returns byte-for-byte, and `fields.redelivered` is a boolean, not a count. A
+requeue is not a dead-letter, so the broker stamps no `x-death` to count from either.
+The counter therefore has to travel in a header this library writes, and only a NEW
+message can carry an advanced one. The copy is published first and the original acked
+second, so a failed publish can duplicate a message but never lose one; when the publish
+fails the original is requeued and the attempt is repeated rather than spent.
+
+```javascript
+const { deliveryPolicy } = require('@onlineapps/mq-client-core');
+deliveryPolicy.ATTEMPTS_HEADER; // 'x-oa-delivery-attempts' — read it, never retype it
+```
+
+**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
+published and nothing is invented: the absence is reported through the injected logger
+with the queue and the service name, and the message stays readable in the dead-letter
+queue through the DLQ dashboard. `monitoring.workflow` keys every trace on that id, so an
+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.
+
+**`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,
+and `maxAttempts` is the only bound on the total. A message that does expire mid-budget is
+dead-lettered by the broker to the same `<service>.dlq` with `x-death[0].reason: 'expired'`
+— and no `message_dlq` event, because the client is not involved in that move. Both
+reasons are visible on the dead message itself; the DLQ dashboard reads them
+(`infra/api_monitoring/src/consumer/deadLetterPeek.js`).
+
+#### `requeueOnError` — the same policy, said in one word
+
+`consume(queue, handler, { requeueOnError })` is folded ONTO the budget above,
+never placed beside it:
+
+| value | meaning |
+|---|---|
+| `false` | the budget is **one** attempt — the first failure rejects into `<svc>.dlq`, exactly as a `permanent` classification does |
+| `true` or absent | the budget is whatever configuration says (`maxAttempts` → `RABBITMQ_MAX_DELIVERY_ATTEMPTS` → `defaults.js`) |
+
+There is no third meaning. `requeueOnError: false` together with `maxAttempts`
+above 1 is a contradiction and is **refused where it was written**, rather than
+one of the two being silently ignored.
+
+### Connection loss — the contract
+
+When the broker goes away, the transport runs connection-level recovery with
+exponential backoff, up to `maxReconnectAttempts` times. That whole budget is one
+**cycle**. Three outcomes, no fourth:
+
+| Outcome | What the client does |
+|---|---|
+| a reconnect succeeds | channels are recreated, consumers re-registered, buffered messages flushed, `reconnected` is emitted; the attempt and cycle counters reset to 0 |
+| the cycle's attempts are spent, and the broker never answered | the client **stands down**: `connection:standby` is emitted, and the NEXT use starts the next cycle |
+| the broker REFUSED, or every cycle is spent | the connection is declared **permanently lost** |
+
+**While a recovery is running, `isConnected()` is `false` — including the part of it
+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.
+
+**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
+(`docs/governance/confirmations/mq-client-lifecycle-contract.md` 001 point 3 —
+"give up forever" is forbidden). So a spent cycle means:
+
+- `connection:standby` is emitted with `{ cycle, cyclesMax, attempts, lastError,
+  timestamp }`, and the client holds no timer and no socket;
+- `isConnected()` is `false`, `isConnectionFatal()` is `false`;
+- **nothing polls.** The retry is lazy: the next `publish()`, `consume()` or
+  `performHealthCheck()` starts the next cycle, and a client nobody uses costs
+  nothing while the broker is away;
+- a cycle that succeeds resets the counter, so the next outage starts again at
+  cycle 1.
+
+`maxReconnectCycles` bounds how many cycles this client will ever run (explicit
+config → `RABBITMQ_MAX_RECONNECT_CYCLES` → module default). It is what keeps the
+lazy retry finite: when the last cycle is spent, the connection is permanently
+lost.
+
+**A refusal is not an outage.** If the broker ANSWERED and said no — 403
+`ACCESS-REFUSED`, 530 `NOT-ALLOWED`, 406 `PRECONDITION-FAILED` — retrying cannot
+change the answer, so not one further attempt is spent on it and the connection is
+permanently lost immediately. (One refusal this client cannot recognise: amqplib
+renders a wrong vhost as `Expected ConnectionOpenOk; got <ConnectionClose
+channel:0>`, with the broker's 530 dropped before the error is built. That one is
+treated as an outage and ends at the cycle cap instead.)
+
+Permanently lost means all of this, together:
+
+- `connection:fatal` is emitted on the transport, and the injected `onFatal`
+  callback is called — once — with an `Error` carrying
+  `code: 'MQ_CONNECTION_FATAL'`, `reason: 'broker-refused' | 'cycles-spent'`,
+  `attempts: <budget per cycle>` and `cycles: <cycles spent>`;
+- `isConnected()` returns `false` — on the transport, on `BaseClient`, and
+  therefore in `conn-infra-mq`'s `getHealth().connected` and in any healthcheck
+  built on them;
+- no further reconnect attempts are made, by a use or otherwise — the client is
+  dead until the process restarts, or until an explicit `connect()`;
+- `publish()`/`consume()` refuse immediately instead of blocking on a recovery
+  that is not coming.
+
+**The library never ends the process, and never listens for a signal.** Ending
+it is the lifecycle owner's decision: a service typically logs and exits
+non-zero from `onFatal`, so its restart policy boots it again and boot
+re-verifies every dependency. What the library owes the owner is the truth,
+once, on a channel that cannot be confused with an ordinary transient error —
+and one call to close what it holds, `BaseClient.disconnectAll()`.
+
+```javascript
+const client = new BaseClient({
+  type: 'rabbitmq',
+  host: process.env.RABBITMQ_URL,
+  onFatal: (err) => {
+    logger.error(err.message, { code: err.code, reason: err.reason, cycles: err.cycles });
+    process.exit(1); // the SERVICE decides this, not the library
+  }
+});
+```
+
+### Shutdown — `BaseClient.disconnectAll()`
+
+The process signal belongs to the service. This library registers no
+`SIGTERM`/`SIGINT`/`beforeExit` handler and calls `process.exit()` nowhere; what
+it offers instead is one call the service puts in its own sequence, in its own
+order:
+
+```javascript
+const { BaseClient } = require('@onlineapps/mq-client-core');
+
+process.on('SIGTERM', async () => {        // the SERVICE registers this
+  await httpServer.close();
+  await BaseClient.disconnectAll();        // every MQ client this process holds
+  await redis.quit();
+  process.exit(0);                         // the SERVICE decides this
+});
+```
+
+- it closes every client constructed and not yet disconnected — **only** those:
+  a raw amqplib connection the service opened itself is not touched;
+- every client gets its turn even if one fails; it then rejects with a
+  `ConnectionError` naming how many of how many failed, `error.cause` carrying
+  the first reason;
+- a client that failed to close stays held, so a repeated call reaches it again;
+- with nothing live it resolves and does nothing.
+
+**BREAKING (2026-09-14).** Until this release the library installed the signal
+handlers itself, on the first `BaseClient` anyone constructed, and ended them
+with `process.exit(0)`. A service with its own shutdown sequence got a truncated
+one: measured in the registry (`infra/api_services_registry/src/shutdown.js`,
+dev stack 2026-08-31) as `TRACE_END mq t=12` → `TRACE_PROCESS_EXIT code=0 t=16`,
+with four Redis clients, the HTTP server and six timers never handed back. A
+service that relied on the library closing its clients on `SIGTERM` must now
+call `BaseClient.disconnectAll()` from its own handler.
+
+**BREAKING (2026-09-14).** A spent attempt budget used to be the end: the client
+set its fatal flag on the first exhausted cycle and refused every operation for
+the life of the process, which is what this section used to document ("the client
+is dead until the process restarts"). A service whose broker was restarted for
+longer than `maxReconnectAttempts × reconnectMaxDelay` therefore needed a process
+restart to come back, even though the broker was healthy again. A caller that
+treated `connection:fatal` as "the first outage that outlasted the budget" must
+now read it as what it says — refused, or every cycle spent — and may see
+`connection:standby` in between.
+
+**BREAKING (2026-09-07).** `isConnected()` used to return a flag set once in
+`connect()`, so it answered `true` throughout an outage and kept answering
+`true` after the recovery budget was spent — measured that day as `true` for
+100+ s against a broker that was down and then back up, with the client
+permanently dead and every healthcheck green. A caller that used
+`isConnected()` as "was connect() ever called" must now read it as "is the
+connection up right now".
+
 ### Queue ownership — publishing never creates an owned queue
 
 A missing queue is answered by who owns the name, not by the client's scope:
@@ -73,7 +449,7 @@ A missing queue is answered by who owns the name, not by the client's scope:
 |---|---|---|
 | `workflow.*`, `registry.*`, `infrastructure.*`, `validation.*`, `monitoring.*`, `telemetry.*`, `delivery.*` | the infrastructure service that declares it | `QueueNotFoundError` (`kind: 'infrastructure'`) |
 | `{service}.workflow`, `{service}.queue`, `{service}.dlq` | the owning service, via `setupServiceQueues()` **after** registration | `QueueNotFoundError` (`kind: 'business'`) |
-| anything else | nobody | created with default options, if `recoveryScope` allows it |
+| anything else | nobody | `QueueNotFoundError` (`kind: 'unowned'`) — nothing is created (d.419) |
 
 Publishing must never create an owned queue: `sendToQueue()`/`assertQueue()` would
 declare it with default arguments — no TTL, no DLQ — and the owner's later
@@ -86,6 +462,137 @@ required: the 404 branch of `_publishOnce()` refuses the publish, and
 client belongs to a business service. It has never meant "may create business
 queues".
 
+**An exchange is named by a publisher, never declared by one.** `publish(queue,
+message, { exchange, routingKey })` sends to the exchange the caller names and
+declares nothing: an exchange's type and durability are topology, they are
+declared once in `config/queueConfig.js`, and the owning service asserts them
+through `assertExchange()`. Until 2026-09-14 the publish path re-declared the
+exchange on every call, with the type from `options.exchangeType || 'direct'` and
+the durability from the PUBLISHING client's config — so two differently
+configured publishers declared one exchange two ways, and a client whose
+`durable` disagreed with the owner's got 406 `PRECONDITION_FAILED` from a publish
+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.
+
+### 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.
+
+**There is no persistent buffer, and `persistentBufferEnabled` /
+`persistentRedisClient` are refused by name.** They declared one until
+2026-09-14: `buffer/RedisBuffer.js` was a placeholder whose `add()` stored nothing
+and whose `flush()` returned 0, and the buffer returned after that branch without
+falling back — so switching it on **dropped** exactly the critical-priority
+messages it claimed to protect, while the same message at normal priority was
+safely held. A key that inverts its own promise is worse than no key
+(`automation-gates.md` §5), so the stub, both keys and the branch went out
+together, and writing either name now fails the constructor with a sentence that
+says the mechanism is gone rather than a name to rename it to.
+
+### errors and errorCodes — recognise a state by its code, never by its wording
+
+`errors` hands out the error classes; `errorCodes` hands out the machine-readable
+classification a listener decides on. A service listening on the `error` channel gets
+the transport's own connection-close notification there, and it is a STATE — the
+connection dropped while a reconnect is already running — not a failure of whatever
+observed it.
+
+```javascript
+const { errors, errorCodes } = require('@onlineapps/mq-client-core');
+
+client.onError((err) => {
+  if (err.code === errorCodes.CONNECTION_CLOSED_UNEXPECTEDLY) {
+    return; // the client is already reconnecting; onFatal reports the permanent loss
+  }
+  logger.error(err.message, { code: err.code });
+});
+```
+
+**Compare the code, not the message.** A comparison against the sentence breaks the day
+somebody rewords it, and nothing reports the break: the client's own reconnect wait asked
+for `'Connection closed unexpectedly'` while the transport emitted `'RabbitMQ connection
+closed unexpectedly'`, one capital letter apart, so the branch written to ignore that
+error had never once run (fixed 2026-09-08, `errors.ConnectionError` now carries `code`).
+
+`consume()` refuses for two named reasons, and they ask for OPPOSITE actions:
+
+| `error.code` | what happened | what fixes it |
+|---|---|---|
+| `CONSUMER_QUEUE_MISSING` | the queue does not exist | start the service that owns the queue — a consumer never creates one |
+| `CONSUMER_DEAD_LETTER_ROUTE_MISSING` | the queue exists, `queueConfig` declares no dead-letter route for it | declare `x-dead-letter-exchange`/`-routing-key` for that queue and bind the destination; the queue itself is fine |
+
+Any other failure carries **no** code and its `ConsumeError` says so: the reason is in
+`error.cause`, and this layer does not name the likeliest-sounding one. Until 2026-09-14
+it did — every refusal wore the sentence "Expected: the queue to exist before consume()
+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.
+
+### queueConfig — the classification, as a declared export
+
+The table above is not a copy: the names, their arguments and the two predicates
+that decide them live in `src/config/queueConfig.js`, and the package exports that
+module.
+
+```javascript
+const { queueConfig } = require('@onlineapps/mq-client-core');
+
+queueConfig.isInfrastructureQueue('workflow.init'); // true
+queueConfig.isBusinessQueue('emailer.workflow');    // true
+queueConfig.getInfrastructureQueueConfig('workflow.init'); // { durable, arguments }
+queueConfig.getDeadLetterRoute('workflow.init');    // { exchange: '', routingKey: 'workflow.failed' }
+queueConfig.isDeadLetterTarget('workflow.failed');  // true — the end of that chain
+```
+
+- `workflow.failed` carries no `x-message-ttl`. It is read by an operator, not by a
+  service, and it has no dead-letter exchange, so a TTL there does not move a message
+  anywhere — it deletes it. See
+  `api/docs/governance/confirmations/mq-consumer-contract.md` 002.
+- `isDeadLetterTarget()` answers "does this configuration dead-letter TO this name",
+  derived from the declared routing keys rather than from a list. It is what lets
+  `consume()` attach to `workflow.failed` and to any `<service>.dlq` while every other
+  queue with no declared route stays refused — see § `consume()` — the delivery contract.
+
+**That require is the contract.** Reaching into
+`@onlineapps/mq-client-core/src/config/queueConfig` is an internal path the package
+never promised — it happens to resolve today, and it breaks silently the day the
+file moves. Callers holding the deep path switch to the named export; callers that
+receive `queueConfig` by injection (`initInfrastructureQueues` in
+`@onlineapps/infrastructure-tools`) pass it from here.
+
+### redactUrl — a connection URL that is safe to log
+
+`RABBITMQ_URL` carries the broker account, so anything that renders it verbatim
+puts that account in the service log and, through the monitoring consumer, in
+Loki. `redactUrl` removes the WHOLE userinfo — the account name is the other half
+of the credential, and the reader of a log line came for the host and the port.
+
+```javascript
+const { redactUrl, UNPARSEABLE_PLACEHOLDER } = require('@onlineapps/mq-client-core');
+
+redactUrl('amqp://oa_dev:secret@queuer:5672/oa_vhost'); // 'amqp://queuer:5672/oa_vhost'
+redactUrl('amqp://queuer:5672');                        // unchanged — nothing to remove
+redactUrl('queuer:5672');                               // '<unparseable-url>'
+redactUrl(undefined);                                   // '<unparseable-url>'
+```
+
+- A value that cannot be read as a URL is answered with `UNPARSEABLE_PLACEHOLDER`,
+  never echoed: that is precisely the case where nobody can say whether the string
+  holds a credential.
+- It never throws — its callers are log lines and error messages, where a throw
+  replaces the report with a second incident. The client's own connection target
+  goes through `redactConnectionTarget()` instead, which refuses a non-string
+  outright, because `host` is a declared config key and a wrong type there is a
+  boot-time defect.
+- It is the SAME function this package uses internally, and the same semantics as
+  `shared/service-common/src/redactUrl.js`. A dependant that renders a broker URL
+  imports it from here rather than keeping a copy.
+
 ## Architecture
 
 ```

package/package.json

@@ -1,12 +1,17 @@
 {
   "name": "@onlineapps/mq-client-core",
-  "version": "2.0.1",
+  "version": "3.0.1",
   "description": "Core MQ client library for RabbitMQ - shared by infrastructure services and connectors",
+  "oa": {
+    "category": "connector"
+  },
+  "engines": {
+    "node": ">=24.0.0 <25"
+  },
   "main": "src/index.js",
   "scripts": {
-    "test": "jest",
-    "test:unit": "jest --testPathPattern=tests/unit",
-    "test:component": "jest --testPathPattern=tests/component",
+    "test": "npm run test:unit && npm run test:integration",
+    "test:unit": "jest tests/unit",
     "test:integration": "jest --config=jest.integration.config.js"
   },
   "keywords": [
@@ -18,11 +23,10 @@
   "author": "OnlineApps",
   "license": "MIT",
   "dependencies": {
-    "@onlineapps/infra-logger": "2.0.0",
-    "@onlineapps/runtime-config": "1.0.3",
+    "@onlineapps/logger-contract": "1.1.0",
+    "@onlineapps/runtime-config": "1.1.0",
     "ajv": "^8.12.0",
-    "amqplib": "^0.10.3",
-    "lodash.merge": "^4.6.2"
+    "amqplib": "^0.10.3"
   },
   "devDependencies": {
     "jest": "^29.7.0"