@onlineapps/mq-client-core 4.1.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
@@ -619,8 +672,16 @@ 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
+queueConfig.deadLetterExchange();                   // 'dlx' — composed from queueConfig.deadLetter
 ```
 
+- The platform's dead-letter exchange is declared like every other exchange here —
+  `queueConfig.deadLetter.dlx` is `{ type: 'exchange', exchangeType: 'direct', durable: true }`,
+  the shape its founder (`@onlineapps/conn-infra-mq` `setupServiceQueues()`) asserts. Its wire
+  name carries no prefix: the `deadLetter` section declares an empty one, so
+  `queueName('deadLetter', 'dlx')` is `'dlx'`, and a reader walking the `type: 'exchange'`
+  entries finds it with the rest.
+
 - `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
@@ -659,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
@@ -720,6 +782,159 @@ trade a real effect for a record of it — a lost copy is reported through the l
 answers `false`. The one exception is a missing logger, which is the transport half's rule:
 without it the promise "every failure is reported" cannot hold.
 
+**The two builders of this package fail differently, on purpose.** This one answers `false` and
+reports; `scheduler.publishSchedulerRequest()` below throws. A lost monitoring copy is a missing
+record of work that happened; a lost registration is work that will never happen, and nothing
+rings for it.
+
+### scheduler — what a service says to the platform's owner of time
+
+A service that runs work on a schedule ANSWERS with the recurrences it owns, through one hook
+the wrapper asks at boot, and the wrapper re-asserts each of them as a `scheduler.request` of
+kind `recurring` ([scheduler.md §7](/docs/architecture/scheduler.md)). Re-registration is an
+upsert — a recurring request's `idempotency_key` IS the schedule id — so a boot that re-asserts
+the declared state costs nothing and drifts nowhere.
+
+ONE RAIL FOR BOTH KINDS (confirmation `scheduler` 011): the hook answers a constant list for
+platform recurrences and a list derived from the service's own data for tenant ones. This
+package owns the SHAPE of a record and the message built from it — never where the record comes
+from, which is the service's business.
+
+```javascript
+// In the service, the hook the wrapper asks at boot (FÁZE 0.7b). Every record carries its own
+// tenancy, derived from the service's data — at boot there is no invocation envelope to take
+// it from (confirmations `scheduler` 002, 010):
+new ServiceWrapper({
+  scheduler: {
+    recurrences: async () => ([
+      { id: '31bf8bac:servant-poll', cookbookRef: 'servant-poll', cron: '0 * * * *',
+        timezone: 'Europe/Prague', tenantId: 101, workspaceId: 1, input: { source_uuid: '31bf8bac' } }
+    ])
+  }
+});
+
+// What the wrapper does with the answer — the port this package builds:
+const { scheduler } = require('@onlineapps/mq-client-core');
+const port = scheduler.createSchedulerPublisher({ mqClient, requestedBy: serviceName });
+for (const record of answered) await port.registerRecurring(record);
+```
+
+The port record is camelCase — `{ id, cookbookRef, cron, timezone, tenantId, workspaceId,
+input?, catchUp? }` — and the port turns it into the declaration record below, which is what
+`validateRecurrences()` and `buildRecurringRequest({ declaration, tenantId, workspaceId,
+requestedBy })` take. One declaration record, and nothing else:
+
+| Key | Required | Meaning |
+|---|---|---|
+| `id` | ✅ | The schedule's stable id; it travels as `idempotency_key`, so two records of one id are refused |
+| `cookbook_ref` | ✅ | The cookbook to run. Its `triggers` must name this service and the kind `recurring`, or the scheduler refuses the request |
+| `cron` | ✅ | Five fields, the same expression the scheduler's contract takes |
+| `timezone` | ✅ | An explicit IANA zone; there is no implicit one |
+| `input` | – | Handed to the cookbook unchanged — a scheduled run that writes says so in the record, while the same cookbook run by hand can be given a different input |
+| `catch_up` | – | Absent means false, and the scheduler materialises that default |
+
+- **Tenancy is the caller's, on every recurrence — never the environment, never a default.**
+  Both ids are mandatory and ≥ 1 (the owner rejected `0/0` as a platform scope, confirmation
+  `scheduler` 002), and a missing one is refused by name. The declaration record above does not
+  carry them; the builder takes them beside it, and the port record carries them per entry.
+  Who fills them depends on where the call comes from: the boot hook's records must carry
+  them (no envelope exists at boot), while `ctx.scheduler` inside a handler fills them from the
+  invocation envelope and refuses them from the caller.
+- **An empty answer is an answer.** A service with no recurrences has no hook, or answers an
+  empty list, and the wrapper skips its step. An answer that does NOT hold throws — a
+  recurrence nobody registered is work that never happens, and nothing else rings for it.
+- **`validateRecurrences(document, source)` names its source**, and the name is required: every
+  refusal quotes it, so a default here would put one caller's name on another caller's mistake.
+- **Sending is fail-fast**, unlike the monitoring helpers beside it. A lost monitoring copy
+  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:
+
+```javascript
+// THAT something happened. It names no cookbook: the scheduler starts every recipe whose
+// `triggers` declare this event, so a producer naming a recipe would map work to something it
+// may not own.
+await scheduler.publishSchedulerRequest(mqClient, scheduler.buildEventRequest({
+  event: { service: 'biz-ingest', name: 'job-persisted' },
+  idempotencyKey: `biz-ingest:job-persisted:${jobId}`,   // the identity of the fact
+  tenantId, workspaceId, requestedBy: serviceName,
+  input: { source_uuid }                                  // optional, handed to every cookbook it starts
+}));
+
+// An item back, by the key it was registered with.
+await scheduler.publishSchedulerRequest(mqClient, scheduler.buildCancelRequest({
+  idempotencyKey: 'servant-poll',
+  requestedBy: serviceName
+}));
+```
+
+- **The key is always the caller's.** `idempotency_key` is required for every kind, and the
+  scheduler decides a one-shot item ONCE by it — a second `event` carrying a known key is
+  answered `duplicate`. A key this package invented per call would turn every retry of one fact
+  into a second run, so no builder makes one up.
+- **`cancel` carries no tenancy**, and needs none: the key names an item that already holds the
+  context it was registered with. Cancelling a key that names nothing is a result rather than an
+  error — the scheduler answers `cancel-nothing` — so the builder judges nothing about it.
+- **One send, `publishSchedulerRequest()`**, for every kind: the kind is a field of the message,
+  never a second function. It is fail-fast like the registration above, and it refuses a message
+  none of these builders produced.
+
+A service that speaks to the scheduler more than once holds a port instead of repeating its own
+name and the queue:
+
+```javascript
+const port = scheduler.createSchedulerPublisher({ mqClient, requestedBy: serviceName });
+
+await port.registerRecurring({ id, cookbookRef, cron, timezone, tenantId, workspaceId, input, catchUp });
+await port.publishEvent({ name: 'job-persisted', idempotencyKey: jobUuid, tenantId, workspaceId, input });
+await port.cancel({ id });
+```
+
+- **The client and the queue are decided at construction**, not at the first call: a service that
+  announces facts has to fall over at boot rather than at its first document. On a pin whose
+  `queueConfig` declares no `scheduler` section this module refuses when it is required, earlier
+  still. Every refusal names the slot it is about and how to fix it, so a defect of the wiring can
+  never be read as the operation's own error.
+- **Tenancy stays explicit on every call**, because two kinds of caller hold this port: a service
+  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.1.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