@onlineapps/mq-client-core 2.0.1-rc.1 → 3.0.0

package/src/config/configSchema.js

@@ -3,51 +3,432 @@
 /**
  * configSchema.js
  *
- * JSON Schema used by Ajv to validate the user-supplied configuration object.
- * 
- * FLEXIBLE SCHEMA for infrastructure services:
- * - Only requires 'type' and 'host'
- * - Allows additional properties for flexibility
- * - Queue is optional (infrastructure services may not need default queue)
+ * JSON Schema used by Ajv (in the `BaseClient` constructor) to validate the
+ * configuration object a caller hands this client.
+ *
+ * WHAT A DECLARATION IS FOR, and what it is not.
+ *
+ * It is the place a reader looks up what a key means, and the place a validator
+ * checks the value against. Until 2026-09-13 it was neither for most of the
+ * client: `src/` read 43 keys off `this._config`, this file declared 10, and the
+ * remaining 34 reached their mechanism only through `additionalProperties: true`
+ * — a door that was labelled "for flexibility" and that admitted `onFatal`
+ * (whether a spent reconnect budget ends the process), `recoveryScope` (which
+ * kind of service this client is) and `queueCreationCallback` (which, until
+ * d.419, declared a queue nobody owned). Undeclared is not merely undocumented:
+ * `reconnectEnabled: 'no'` was accepted, and the transport read it as
+ * `'no' !== false` → recovery ON, the exact opposite of what the caller wrote
+ * (`transports/rabbitmqClient.js`, `_reconnectEnabled`). Declaring the type is
+ * what turns that into a refusal at construction (`architecture-principles.md`
+ * §3, §4).
+ *
+ * A NAME THAT IS NOT A KEY IS NOT DECLARED HERE EITHER. `url` (the name
+ * `@onlineapps/conn-infra-mq` documents for the broker URL) and `queue` (a
+ * "default queue name" nothing has read since the library was extracted) were
+ * declared here until 2026-09-14, which made a reader believe both were inputs.
+ * Removing them from `properties` is now a REFUSAL and not merely a silence:
+ * the schema ends with `additionalProperties: false` since d.291b, so a name no
+ * side declares is rejected at construction, named, together with the declared
+ * key it is closest to.
+ *
+ * `url` is refused BY NAME in `BaseClient` (`NOT_A_KEY_OF_THIS_CLIENT`) all the
+ * same, and that is not a second rail for the same concern: the schema can say
+ * "this is not a key", it cannot say WHICH key the value belongs under, which an
+ * Ajv `not` cannot word either. The named list runs first and answers the caller
+ * with the rename; everything it does not know falls through to the schema. Same
+ * order, and the same reason, as `assertLogger()` running before Ajv.
+ *
+ * DEFAULTS ARE NOT DECLARED HERE — one concern, one rail. Every default already
+ * has an owner, and a second copy here would be free to drift from it:
+ *   - `config/defaultConfig.js` — every CONSTANT default, composed into the config
+ *     BEFORE this validation runs, so what it says is what is validated and built;
+ *   - `../config.js` + `../defaults.js` — the runtime-resolved ones (`host`,
+ *     `heartbeat`, `serviceName`, `maxReconnectAttempts`, `maxDeliveryAttempts`),
+ *     explicit → env → module default;
+ *   - `transports/rabbitmqClient.js` — `reconnectWaitTimeout` alone, because it is
+ *     DERIVED from two other settings rather than being a constant.
+ * So a property here carries a type, a description and where its default comes
+ * from — never the default itself. `tests/unit/config-schema-declares-every-key-src-reads.test.js`
+ * holds both halves of that: no property carries `default`, and no key read in
+ * `src/` is missing from `properties`. Ajv is compiled WITHOUT `useDefaults` since
+ * d.292 §7 — the switch had nothing to write and was an invitation to open a
+ * second rail of defaults right here.
+ *
+ * A FUNCTION HAS NO JSON TYPE. Several keys are callbacks (or `null` for "none"),
+ * and JSON Schema's seven types are the JSON ones — `function` is not among them.
+ * The constraint is therefore written as "none of the JSON types", which admits
+ * exactly a function or `null` and rejects a string, number, object or array
+ * (`callbackOrNull()` below). Not a formality: a `healthReportCallback` that is a
+ * string would be awaited at the moment the client is already unwell, and an
+ * `onFatal` that is a string would be called at the moment the reconnect budget
+ * is already spent.
+ *
+ * @see ../../README.md § Configuration
  */
 
+/**
+ * A callback key: a function, or `null` meaning "none".
+ *
+ * Written as six single-type alternatives rather than one type array because
+ * Ajv's strict mode warns about a union type inside `not` (`allowUnionTypes`),
+ * and a console warning on every client construction is noise in every service's
+ * boot log.
+ *
+ * @param {string} description - What the callback is called with, and by whom.
+ * @returns {Object} JSON Schema fragment.
+ */
+const callbackOrNull = (description) => ({
+  not: {
+    anyOf: [
+      { type: 'boolean' }, { type: 'object' }, { type: 'array' },
+      { type: 'number' }, { type: 'string' }, { type: 'integer' },
+    ],
+  },
+  description,
+});
+
 module.exports = {
   type: 'object',
   properties: {
+    // ---------------------------------------------------------------------
+    // Connection shape. Defaults: config/defaultConfig.js (merged before this
+    // validation runs); `host` is resolved by ../config.js and never defaulted.
+    // ---------------------------------------------------------------------
     type: {
       type: 'string',
       enum: ['rabbitmq'],
+      description:
+        "Transport to build. The only implemented one is 'rabbitmq' "
+        + '(transports/transportFactory.js).',
     },
     host: {
       type: 'string',
       minLength: 1,
-    },
-    // Queue is optional for infrastructure services
-    queue: {
-      type: 'string',
+      description:
+        'Broker URL (it carries the account password, and only the redacted form reaches '
+        + 'the log — utils/redactCredentials.js). Explicit value, else ENV RABBITMQ_URL; '
+        + 'never defaulted, missing is fatal (../config.js).',
     },
     exchange: {
       type: 'string',
+      description:
+        "Default exchange for publish(); empty string means the default direct exchange. "
+        + 'Per-call `options.exchange` wins.',
     },
     durable: {
       type: 'boolean',
+      description:
+        'Declare queues/exchanges as durable, and publish persistently unless a call '
+        + 'overrides it with `options.persistent`.',
     },
     prefetch: {
       type: 'integer',
       minimum: 0,
+      description: 'Default prefetch count for consumers; 0 means unlimited.',
     },
     noAck: {
       type: 'boolean',
+      description:
+        'Default auto-acknowledge setting for consumers. `true` means the broker considers '
+        + 'a message delivered the moment it is sent, so a handler failure loses it.',
     },
+    heartbeat: {
+      type: 'integer',
+      minimum: 0,
+      description:
+        'AMQP heartbeat in SECONDS, handed to amqplib at connect. Explicit value, else ENV '
+        + 'RABBITMQ_HEARTBEAT, else the module default (../defaults.js heartbeatSeconds).',
+    },
+    serviceName: {
+      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).',
+    },
+    connectionName: {
+      type: 'string',
+      minLength: 1,
+      description:
+        'Name shown against this connection in the broker UI. Built by the BaseClient '
+        + 'constructor as `<serviceName>:<pid>` when the caller passes none.',
+    },
+    clientName: {
+      type: 'string',
+      minLength: 1,
+      description:
+        'Fallback for `connectionName`, read by the transport when neither the caller nor '
+        + 'the BaseClient constructor set one.',
+    },
+    // REQUIRED, and not by this schema: presence and completeness are checked by
+    // `assertLogger()` from `@onlineapps/logger-contract` at the top of the
+    // BaseClient constructor, which names the four methods and the fix. Ajv would
+    // only be able to say "must have required property 'logger'", and two rails
+    // enforcing one contract is what confirmation 004 closed. The entry stays here
+    // because the schema is where a reader looks up what a key means.
     logger: {
-      oneOf: [
-        { type: 'null' },
-        { type: 'object' }
-      ],
-      description: 'Custom logger with methods: info, warn, error, debug (can be null)',
+      type: 'object',
+      description:
+        'Logger with methods: info, warn, error, debug — required, validated by '
+        + '@onlineapps/logger-contract in the BaseClient constructor',
+    },
+
+    // ---------------------------------------------------------------------
+    // Connection-level recovery. Read by the transport constructor; the defaults
+    // live there (and in ../defaults.js for the budget).
+    // ---------------------------------------------------------------------
+    maxReconnectAttempts: {
+      type: 'integer',
+      minimum: 0,
+      description:
+        'How many times connection-level recovery retries before the connection is declared '
+        + 'permanently lost and `onFatal` fires. Explicit value, else ENV '
+        + 'RABBITMQ_MAX_RECONNECT_ATTEMPTS, else the module default (../defaults.js).',
+    },
+    maxDeliveryAttempts: {
+      type: 'integer',
+      minimum: 1,
+      description:
+        'How many times a consumer\'s handler may run for ONE message before it is rejected '
+        + 'into `<svc>.dlq`, for every consumer of this client. Explicit value, else ENV '
+        + 'RABBITMQ_MAX_DELIVERY_ATTEMPTS, else the module default (../defaults.js); the '
+        + 'narrowest override is per call, `consume(queue, handler, { maxAttempts })`. '
+        + 'Below 1 would mean the handler never runs, which is not consuming at all.',
+    },
+    maxReconnectCycles: {
+      type: 'integer',
+      minimum: 1,
+      description:
+        'How many recovery CYCLES the client spends before the connection is declared '
+        + 'permanently lost. One cycle is the whole maxReconnectAttempts budget; the first '
+        + 'is started by the death of the connection, every further one lazily by the next '
+        + 'use (publish/consume/performHealthCheck). Explicit value, else ENV '
+        + 'RABBITMQ_MAX_RECONNECT_CYCLES, else the module default (../defaults.js). Below 1 '
+        + 'would mean no recovery at all, which is what reconnectEnabled: false says.',
+    },
+    reconnectEnabled: {
+      type: 'boolean',
+      description:
+        'Whether a lost connection is recovered at all. Anything other than `false` means '
+        + 'enabled, which is why the type matters: a string was read as "enabled".',
+    },
+    reconnectBaseDelay: {
+      type: 'integer',
+      minimum: 0,
+      description: 'First backoff step between reconnect attempts, in milliseconds.',
+    },
+    reconnectMaxDelay: {
+      type: 'integer',
+      minimum: 0,
+      description: 'Ceiling for the reconnect backoff, in milliseconds.',
+    },
+    reconnectWaitTimeout: {
+      type: 'integer',
+      minimum: 0,
+      description:
+        'How long an operation waits for recovery to finish before giving up, in '
+        + 'milliseconds. Defaulted by the transport from the budget × the max delay.',
+    },
+    onFatal: callbackOrNull(
+      'Function (error) => void, or null. Called ONCE when the reconnect budget is spent '
+      + 'and this client will not try again. The library never ends the process — that '
+      + 'decision belongs to the owner of the lifecycle. Whether the value is callable is '
+      + 'checked by the transport constructor, which names the key and the fix '
+      + '(transports/rabbitmqClient.js, "Invalid config value for \\"onFatal\\""); this '
+      + 'entry declares the key, it does not open a second rail for that check.'
+    ),
+
+    // ---------------------------------------------------------------------
+    // Publish retry + confirmation. Read by the transport constructor.
+    // ---------------------------------------------------------------------
+    publishRetryEnabled: {
+      type: 'boolean',
+      description:
+        'Whether a failed publish is retried. Anything other than `false` means enabled.',
+    },
+    publishMaxRetries: {
+      type: 'integer',
+      minimum: 0,
+      description: 'How many publish attempts one message gets before the publish fails.',
+    },
+    publishRetryBaseDelay: {
+      type: 'integer',
+      minimum: 0,
+      description: 'First backoff step between publish attempts, in milliseconds.',
+    },
+    publishRetryMaxDelay: {
+      type: 'integer',
+      minimum: 0,
+      description: 'Ceiling for the publish backoff, in milliseconds.',
+    },
+    publishRetryBackoffMultiplier: {
+      type: 'number',
+      exclusiveMinimum: 0,
+      description: 'Factor each publish backoff step is multiplied by (2 = exponential).',
+    },
+    brokerAnswerTimeout: {
+      type: 'integer',
+      minimum: 0,
+      description:
+        'How long this client waits for an ANSWER from the broker, in milliseconds: the confirm of '
+        + 'one publish attempt, and the close-ok of each handle disconnect() closes. One number, two '
+        + 'consumers — it was named publishConfirmationTimeout until d.299, after the teardown had '
+        + 'been spending it since d.283.',
+    },
+    connectTimeout: {
+      type: 'integer',
+      minimum: 1,
+      description:
+        'How long the connect handshake may take before the attempt is abandoned, in milliseconds. '
+        + 'Applies to the first connect and to every reconnect.',
+    },
+    publishConfirmWatchdogDelay: {
+      type: 'integer',
+      minimum: 0,
+      description:
+        'How long after sendToQueue() one publish attempt waits before checking whether the missing '
+        + 'confirm is a dead channel rather than a slow broker, in milliseconds.',
+    },
+
+    // ---------------------------------------------------------------------
+    // Publish buffer (layers/PublishLayer.js → buffer/MessageBuffer.js).
+    // ---------------------------------------------------------------------
+    publishBufferMaxSize: {
+      type: 'integer',
+      minimum: 0,
+      description: 'How many messages the in-memory publish buffer holds while disconnected.',
+    },
+    publishBufferTtlMs: {
+      type: 'integer',
+      minimum: 0,
+      description: 'How long a buffered message stays publishable, in milliseconds.',
+    },
+    // NO `persistentBufferEnabled` / `persistentRedisClient`. They declared a
+    // persistent publish buffer this package never had: `buffer/RedisBuffer.js`
+    // stored and returned nothing, so `true` dropped the critical messages it
+    // claimed to protect. Both names are refused BY NAME in `BaseClient`
+    // (`NOT_A_KEY_OF_THIS_CLIENT`), for the reason two paragraphs up — the
+    // schema can only say the name is not a key, while the named list can say
+    // the mechanism itself is gone and what stands in its place (d.343).
+
+    // ---------------------------------------------------------------------
+    // Channel thrashing detection. Read by the transport constructor.
+    // ---------------------------------------------------------------------
+    thrashingThreshold: {
+      type: 'integer',
+      minimum: 0,
+      description: 'How many closes of one channel type within the window count as thrashing.',
+    },
+    thrashingWindowMs: {
+      type: 'integer',
+      minimum: 0,
+      description: 'Width of the window the thrashing threshold is counted over, in milliseconds.',
+    },
+    thrashingAlertCallback: callbackOrNull(
+      'Function (type, count, windowMs) => void, or null. Called once per channel type when '
+      + 'the close rate crosses thrashingThreshold.'
+    ),
+
+    // ---------------------------------------------------------------------
+    // Prefetch utilization monitoring. Read by the transport constructor.
+    // ---------------------------------------------------------------------
+    prefetchUtilizationThreshold: {
+      type: 'number',
+      exclusiveMinimum: 0,
+      maximum: 1,
+      description:
+        'Fraction of the prefetch window in flight (0.8 = 80%) above which the alert '
+        + 'callback is called for that queue.',
+    },
+    prefetchCheckInterval: {
+      type: 'integer',
+      minimum: 0,
+      description: 'How often prefetch utilization is sampled, in milliseconds.',
+    },
+    prefetchAlertCallback: callbackOrNull(
+      'Function (queue, utilization, inFlight, prefetchCount) => void, or null. Called when '
+      + 'a queue crosses prefetchUtilizationThreshold.'
+    ),
+
+    // ---------------------------------------------------------------------
+    // Health monitoring. The periodic loop is OFF for business services — see
+    // `@onlineapps/service-wrapper` `_initializeMQ()` for why.
+    // ---------------------------------------------------------------------
+    healthCheckEnabled: {
+      type: 'boolean',
+      description:
+        'Whether the transport runs its periodic health check. Anything other than `false` '
+        + 'means enabled.',
+    },
+    healthCheckInterval: {
+      type: 'integer',
+      minimum: 0,
+      description: 'Period of that health check, in milliseconds. Read only when it is enabled.',
+    },
+    healthReportCallback: callbackOrNull(
+      'Async function (health) => void, or null. Called with every health result — it only '
+      + 'reports, it decides nothing.'
+    ),
+    healthCriticalCallback: callbackOrNull(
+      'Async function (health) => void, or null. Called when a health result is critical.'
+    ),
+    criticalHealthShutdown: {
+      type: 'boolean',
+      description:
+        'Whether a sustained critical health result makes the transport emit `health:shutdown`. '
+        + 'Anything other than `false` means enabled. It only arms the event; ending the '
+        + 'process remains the owner\'s decision.',
+    },
+    criticalHealthShutdownDelay: {
+      type: 'integer',
+      minimum: 0,
+      description:
+        'How long health must stay critical before that event is emitted, in milliseconds.',
+    },
+
+    // ---------------------------------------------------------------------
+    // Which kind of service this client belongs to. `queueCreationFilter` and
+    // `queueCreationCallback` stood here until d.419: they were the two keys by
+    // which a client declared a queue nobody owns, and a queue now comes into
+    // being from a declaration or not at all
+    // (`docs/governance/confirmations/mq-consumer-contract.md` 006). A config
+    // still carrying either is refused by name at construction — the schema is
+    // CLOSED, which is what makes the removal visible to the caller instead of
+    // silently ignored.
+    // ---------------------------------------------------------------------
+    recoveryScope: {
+      type: 'string',
+      enum: ['infrastructure', 'business'],
+      description:
+        'Which kind of service this client belongs to. It decides nothing about queue '
+        + 'creation: no client declares a queue (workers/RecoveryWorker.js).',
     },
   },
   required: ['type', 'host'], // Only type and host required
-  additionalProperties: true, // Allow additional properties for flexibility
-};
 
+  // CLOSED. A key nobody declares is refused at construction, naming the key and the
+  // declared key it is closest to (`../BaseClient.js`, `invalidConfigurationMessage()`).
+  //
+  // It stood open until d.291b for one measured reason, and the reason was answered
+  // rather than waived: `@onlineapps/conn-infra-mq`'s `ConnectorMQClient` is a SUBCLASS
+  // of `BaseClient` — it hands its own config straight to `super()` and then reads keys
+  // of its own off the same `this._config` (`autoSetupServiceQueues`, `defaultTTL`,
+  // `workflowInitQueue`, `workflowCompletedQueue`). Closing the door with those
+  // undeclared would have refused the construction of every business service at boot, and
+  // a gate lands together with compliance, never ahead of it (`automation-gates.md` §3).
+  // The compliance half is d.291 (that package declares its four keys in its own schema);
+  // the ONE place it hands them to this one is the second constructor argument,
+  // `super(config, extraProperties)`. The subclass never edits this file and this file
+  // never learns the subclass's keys, so one type and one description keep one owner
+  // (`change-discipline.md` § One rail per concern).
+  //
+  // What the flip COSTS, and who pays it, measured 2026-09-14 over every construction of
+  // this client in `api/shared`, `api/infra`, `api_biz` and `fe_adminui`: four callers
+  // still write `queue`, a name this package has read nowhere since it was extracted
+  // (§ A NAME THAT IS NOT A KEY above). They drop it in the same 8.x cascade that pins
+  // this version — `api/infra/api_gateway/index.js`,
+  // `api/infra/api_delivery_dispatcher/src/services/DeliveryDispatcher.js`,
+  // `api/infra/api_meta_reader/src/index.js` and
+  // `@onlineapps/service-wrapper` `_initializeMQ()`.
+  additionalProperties: false,
+};

package/src/config/defaultConfig.js

@@ -3,25 +3,57 @@
 /**
  * defaultConfig.js
  *
- * Provides default configuration values for MQ Client Core.
- * Users can override any of these by passing a custom config object
- * or by supplying overrides to connect().
+ * THE owner of every constant default this client applies. A caller overrides any
+ * of them by passing the key to the constructor or to `connect()`.
  *
- * NOTE:
- * - Infrastructure topology (RabbitMQ URL) is NOT defaulted here.
- * - BaseClient resolves host via @onlineapps/runtime-config (fail-fast when missing).
+ * WHY THEY ARE ALL HERE, and not next to the code that reads them. This object is
+ * composed into the configuration BEFORE the schema validation runs
+ * (`BaseClient`, `config/composeConfig.js`), so what it says is what the client is
+ * validated with and built from — there is exactly one value, and a reader looks
+ * it up in one place. Until 2026-09-14 the transport constructor carried its own
+ * literal for each of its twenty-two behaviour knobs, written as
+ * `this._config.<key> || <literal>`. That is two rails for one concern
+ * (`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`.
+ *
+ * `??` was not the answer either. It fixes the falsy half and leaves the value
+ * written in two places, which is the half that rots.
+ *
+ * NOT EVERY DEFAULT IS A CONSTANT, and the ones that are not do not belong here:
+ *   - `host`, `heartbeat`, `serviceName`, `maxReconnectAttempts`,
+ *     `maxDeliveryAttempts` are runtime-resolved (explicit → env → module
+ *     default) and owned by `../config.js` + `../defaults.js`;
+ *   - `reconnectWaitTimeout` is DERIVED from `maxReconnectAttempts` and
+ *     `reconnectMaxDelay` (`transports/rabbitmqClient.js`). A constant copy of it
+ *     here would be free to disagree with the two values it is computed from;
+ *   - `connectionName` is composed from the resolved service name and the pid.
+ *
+ * @see ./configSchema.js — what each key means and what type it must carry.
  */
 
 module.exports = {
+  // ---------------------------------------------------------------------
+  // Connection shape.
+  // ---------------------------------------------------------------------
+
   // Transport type: currently only 'rabbitmq' is fully supported.
   type: 'rabbitmq',
 
-  // RabbitMQ connection URI or hostname (resolved at runtime; required by schema).
-  // Provided via explicit config.host or ENV RABBITMQ_URL.
+  // NO `host` default. Infrastructure topology is never defaulted: it comes from
+  // the explicit config or from ENV RABBITMQ_URL, and its absence is fatal
+  // (`../config.js`, fail-fast).
 
-  // Default queue name; can be overridden per call to publish/consume.
-  // Optional for infrastructure services (they may not need a default queue).
-  queue: '',
+  // NO `queue` default. The client has no default queue: every `publish()` and
+  // `consume()` names the queue in the call, and the platform's queue names have
+  // one owner in `config/queueConfig.js`. `queue: ''` sat here from the library's
+  // extraction (`7a47b2fa`) until 2026-09-14 and no line of `src/` ever read the
+  // key back — an ambient default that could only ever redirect a
+  // publish away from the name the caller wrote (`queue-ownership.md`,
+  // `architecture-principles.md` §8).
 
   // Default exchange name (empty string → default direct exchange).
   exchange: '',
@@ -35,8 +67,130 @@ module.exports = {
   // Default auto-acknowledge setting for consumers.
   noAck: false,
 
-  // Custom logger object (if not provided, console.* will be used).
-  // Expected interface: { info(), warn(), error(), debug() }.
-  logger: null,
-};
+  // NO `logger` default. The logger is required and has no stand-in: the library
+  // writes through the one the caller injects, or it refuses to be built
+  // (`assertLogger`, confirmation connector-logger-contract 001/003). A `null`
+  // default sat here until 2026-09-07, with a comment promising that the global
+  // console would stand in — exactly the ambient channel that decision removed.
+
+  // ---------------------------------------------------------------------
+  // Connection-level recovery. The BUDGET (`maxReconnectAttempts`) is runtime
+  // resolved in `../config.js`; these are the shape of the backoff it spends.
+  // ---------------------------------------------------------------------
+
+  // Is recovery armed at all? A client that says `false` stays down when the
+  // connection dies, and its owner decides what to do about it.
+  reconnectEnabled: true,
+
+  // First wait before a recovery attempt, in ms; it grows exponentially up to
+  // `reconnectMaxDelay`.
+  reconnectBaseDelay: 1000,
+
+  // Ceiling of that growth, in ms.
+  reconnectMaxDelay: 30000,
+
+  // Injected by the owner of this client (service/wrapper), called when the
+  // recovery budget is spent. `null` means nobody is listening: the LIBRARY never
+  // ends the process — that decision belongs to whoever owns the lifecycle.
+  onFatal: null,
+
+  // ---------------------------------------------------------------------
+  // Publisher retry. One published message, several attempts.
+  // ---------------------------------------------------------------------
+
+  publishRetryEnabled: true,
+
+  // How many attempts one publish gets before it is buffered or reported.
+  publishMaxRetries: 3,
+
+  // First wait between two attempts, in ms, multiplied by
+  // `publishRetryBackoffMultiplier` on each further attempt, up to
+  // `publishRetryMaxDelay`.
+  publishRetryBaseDelay: 100,
+  publishRetryMaxDelay: 5000,
+  publishRetryBackoffMultiplier: 2,
+
+  // How long this client waits for an ANSWER from the broker, in ms: the confirm
+  // of one publish attempt, and the `close-ok` of each handle `disconnect()`
+  // closes — one number for two consumers, which is why it carries the name of
+  // neither. It was `publishConfirmationTimeout` until d.299, a name that was
+  // true of the publish path and false of the teardown that had used it since
+  // d.283.
+  brokerAnswerTimeout: 5000,
+
+  // How long the connect handshake may take before the attempt is abandoned, in
+  // ms. Written out twice as the literal `10000` — once in `connect()`, once in
+  // the recovery path — until d.299, together with two messages that said
+  // "after 10 seconds" whatever the number had been.
+  connectTimeout: 10000,
 
+  // How long after `sendToQueue()` one publish attempt waits before looking to
+  // see whether the missing confirm is a DEAD CHANNEL rather than a slow broker,
+  // in ms. The literal `1000` in the publish path until d.299.
+  publishConfirmWatchdogDelay: 1000,
+
+  // ---------------------------------------------------------------------
+  // Publish buffer: where a message goes while the broker is unreachable.
+  // ---------------------------------------------------------------------
+
+  // Messages held in memory, and how long each may wait there (ms).
+  publishBufferMaxSize: 100,
+  publishBufferTtlMs: 300000,
+
+  // NO `persistentBufferEnabled` / `persistentRedisClient`. There is ONE buffer,
+  // the in-memory one above. The pair declared a Redis buffer whose `add()` and
+  // `flush()` stored and returned nothing, so switching it on dropped the
+  // critical messages it was supposed to protect; both names are now refused by
+  // name in `BaseClient` rather than silently ignored (d.343).
+
+  // ---------------------------------------------------------------------
+  // Channel thrashing detection: a channel that keeps closing says something is
+  // wrong with what runs on it.
+  // ---------------------------------------------------------------------
+
+  // Closes per window that count as thrashing, and the window in ms.
+  thrashingThreshold: 5,
+  thrashingWindowMs: 60000,
+
+  // `(type, count, windowMs) => void`, injected by the owner; `null` = nobody.
+  thrashingAlertCallback: null,
+
+  // ---------------------------------------------------------------------
+  // Prefetch monitoring: how full a consumer's window runs.
+  // ---------------------------------------------------------------------
+
+  // Utilisation (0..1) at which the alert fires, and how often it is measured (ms).
+  prefetchUtilizationThreshold: 0.8,
+  prefetchCheckInterval: 10000,
+
+  // `(queue, utilization, inFlight, prefetchCount) => void`; `null` = nobody.
+  prefetchAlertCallback: null,
+
+  // ---------------------------------------------------------------------
+  // Health monitoring.
+  // ---------------------------------------------------------------------
+
+  healthCheckEnabled: true,
+
+  // Period of the periodic health check, in ms.
+  healthCheckInterval: 30000,
+
+  // `(health) => Promise<void>` — where a health report goes, and where a
+  // CRITICAL one goes. Injected; `null` = nobody.
+  healthReportCallback: null,
+  healthCriticalCallback: null,
+
+  // Does critical health end this client, and how long it stays critical first
+  // (ms)? The library only reports; the shutdown it asks for is the owner's
+  // `onFatal` path.
+  criticalHealthShutdown: true,
+  criticalHealthShutdownDelay: 60000,
+
+  // ---------------------------------------------------------------------
+  // Which kind of service this client belongs to. It decides nothing about queue
+  // creation: this client declares no queue at all, and the two callbacks that
+  // used to let it — `queueCreationFilter` and `queueCreationCallback` — left
+  // with that door (d.419, conf mq-consumer-contract 006).
+  // ---------------------------------------------------------------------
+  recoveryScope: 'infrastructure',
+};