@onlineapps/mq-client-core 4.2.0 → 5.1.0

package/src/index.js

@@ -8,9 +8,6 @@
  * 
  * NOTE: Infrastructure orchestration utilities (waitForInfrastructureReady, initInfrastructureQueues)
  * have been moved to @onlineapps/infrastructure-tools to keep this library focused on core MQ operations.
- * 
- * @version 1.0.49
- * @updated 2024-12-08 - Test publish-library.sh workflow
  */
 
 const BaseClient = require('./BaseClient');
@@ -48,9 +45,11 @@ const {
   buildCancelRequest,
   publishSchedulerRequest,
   createSchedulerPublisher,
+  SCHEDULER_REQUEST_INVALID,
 } = require('./scheduler-request');
 const queueConfig = require('./config/queueConfig');
 const deliveryPolicy = require('./config/deliveryPolicy');
+const { decodeMessage } = require('./utils/decodeMessage');
 const { redactUrl, UNPARSEABLE_PLACEHOLDER } = require('@onlineapps/logger-contract');
 
 // Export BaseClient as default (constructor), with additional named exports
@@ -119,6 +118,8 @@ module.exports.scheduler = {
   buildCancelRequest,
   publishSchedulerRequest,
   createSchedulerPublisher,
+  // The code on every refusal of a builder, and on nothing a failed send throws.
+  SCHEDULER_REQUEST_INVALID,
 };
 /** The only public way to reach the central queue classification; `src/config/queueConfig` is an internal path, not a contract. */
 module.exports.queueConfig = queueConfig;
@@ -175,7 +176,25 @@ module.exports.topology = Object.freeze({
   /** The same consumer's metric-sample intake on that exchange. */
   telemetryMetricsQueue: queueConfig.queueName('telemetry', 'metrics.queue'),
   /** The same consumer's span intake on that exchange. */
-  telemetryTracesQueue: queueConfig.queueName('telemetry', 'traces.queue')
+  telemetryTracesQueue: queueConfig.queueName('telemetry', 'traces.queue'),
+  /**
+   * Topic exchange: every telemetry producer on the platform publishes logs, metrics and
+   * spans here with a routing key of the shape `telemetry.<signal>.<service_name>`, and
+   * the three queues above are bound to it.
+   *
+   * Declared in `queueConfig` since d.708, which ended the state where one name had three
+   * owners: a module constant in the monitoring consumer
+   * (`api/infra/api_monitoring/src/consumer/topology.js`) and a config default in each of
+   * monitoring-core's two publishers. The declaration alone does not finish that move —
+   * the consumer resolves every platform name it does not own through THIS export, and
+   * `src/config/queueConfig` is an internal path rather than a contract (see the note on
+   * the module export above). So the name it must import belongs here, the same step d.461
+   * made for the three queues it is bound to.
+   *
+   * @see api/infra/api_monitoring/src/consumer/index.js — assertMonitoringTopology()
+   * @see api/shared/monitoring/monitoring-core/src/exporters/rabbitmq.js
+   */
+  telemetryExchange: queueConfig.queueName('telemetry', 'exchange')
 });
 /**
  * The dead-letter policy of `consume()` as a contract, not as an implementation
@@ -186,6 +205,24 @@ module.exports.topology = Object.freeze({
  * return one of those two words.
  */
 module.exports.deliveryPolicy = deliveryPolicy;
+/**
+ * The one rail from a delivery to the message it carries.
+ *
+ * `consume()` hands its handler the RAW amqplib delivery, so every consumer wrote that
+ * translation itself: d.788 measured FOUR copies (dispatcher, scheduler, service-wrapper,
+ * registry) which disagree about what happens to a BAD message — dead-letter, loss rail,
+ * `INVALID_JSON` reply, or requeue for ever — and two of which pass a delivery with no
+ * `content` on AS the body.
+ *
+ * The decoding was never the missing part (`utils/serializer.js` has done it all along);
+ * the missing part was this door, because `src/…` is an internal path rather than a
+ * contract. Exported ADDITIVELY: nothing in this package calls it and `consume()` is
+ * unchanged, because converting those four changes the fate of a malformed message —
+ * BREAKING, and for the registry only after its queue has a dead-letter route (d.784).
+ *
+ * @see ./utils/decodeMessage.js — what it refuses, and with which of this package's classes
+ */
+module.exports.decodeMessage = decodeMessage;
 /**
  * Redaction of the credential a connection URL carries, as a DECLARED export.
  *

package/src/layers/PublishLayer.js

@@ -51,10 +51,10 @@ class PublishLayer {
     // transport constructor reads it from there (d.292 §5).
     //
     // Asked with `=== undefined`, never with `||`. `||` means "if falsy", so the
-    // three numbers below lost a legally written `0` — `publishMaxRetries: 0`
-    // means "do not retry a publish", and it arrived here as 3. d.292 removed
-    // exactly that shape from the transport and said in as many words that this
-    // layer still carried its own copies; this is that floor (d.311).
+    // three numbers below lost a legally written `0` — `publishRetryBaseDelay: 0`
+    // means "retry immediately", and it arrived here as 100. d.292 removed exactly
+    // that shape from the transport and said in as many words that this layer still
+    // carried its own copies; this is that floor (d.311).
     this._retryEnabled = options.retryEnabled !== undefined 
       ? options.retryEnabled 
       : (this._client._publishRetryEnabled !== false);
@@ -71,6 +71,45 @@ class PublishLayer {
       ? options.retryBackoffMultiplier
       : this._client._publishRetryBackoffMultiplier;
 
+    // `publishMaxRetries` counts ATTEMPTS, the first one included — that is what the
+    // key means in every place it is written down (`config/configSchema.js`,
+    // `config/defaultConfig.js`, `docs/architecture/mq-publish-reliability.md` § the
+    // config table, `docs/standards/rabbitmq-channel-best-practices.md`), and what
+    // `_publishWithRetry()` below does for every value from 1 up.
+    //
+    // So `0` is not "do not retry" — three comments in this package said it was, and
+    // the loop obeyed the key instead: `while (attempt < this._maxRetries)` never runs
+    // its body, so the message is never offered to the broker, is NOT buffered on the
+    // way out, and the caller is handed an error blaming this layer for a defect its
+    // own configuration caused (measured, d.684). "One attempt, no retry" is `1`, and
+    // leaving the retry rail entirely is `publishRetryEnabled: false`; both are
+    // explicit, and neither needs a magic zero (`architecture-principles.md` §8).
+    //
+    // Refused HERE, at construction, because this is the one place both doors meet —
+    // the caller's `options.maxRetries` and the client's resolved config — and a value
+    // that can only fail is refused before it is used, not when a publish needs it
+    // (§4 fail-fast).
+    //
+    // `config/configSchema.js` refuses the same value too since d.685b (`minimum: 1`),
+    // and that is not a second rail for one concern: the schema answers what may be
+    // WRITTEN in a client's configuration, this answers what may be USED as a number of
+    // attempts — and the second is reachable without the first. Measured 2026-09-20: the
+    // schema is compiled and applied in exactly one place, `BaseClient`'s constructor,
+    // while the only `new RabbitMQClient` in the workspace is
+    // `transports/transportFactory.js`, which validates nothing. The two also answer at
+    // different moments, because `BaseClient` builds the transport in `connect()` rather
+    // than in its constructor — so a client built past the front desk still arrives here
+    // with whatever it was given.
+    if (!Number.isInteger(this._maxRetries) || this._maxRetries < 1) {
+      throw new ValidationError(
+        `[PublishLayer] publishMaxRetries must be at least 1 - got ${JSON.stringify(this._maxRetries)}. `
+          + 'Expected: a whole number of publish attempts, because it counts ATTEMPTS, the first one '
+          + 'included — 0 means the message is never offered to the broker at all. '
+          + 'Fix: write publishMaxRetries: 1 for one attempt and no retry, or publishRetryEnabled: false '
+          + 'to leave the retry rail entirely.'
+      );
+    }
+
     // Buffer
     this._buffer = new MessageBuffer({
       inMemory: options.bufferConfig?.inMemory,
@@ -83,8 +122,35 @@ class PublishLayer {
    * @param {string} queue
    * @param {Buffer} buffer
    * @param {Object} [options]
+   * @param {boolean} [options.bufferOnFailure=true] - Whether a message whose publish failed
+   *   transiently is held in the buffer and replayed after the next reconnect. `false` is for
+   *   a caller that keeps the message durably elsewhere (conf `step-publish-failure` 001):
+   *   nothing is held, so nothing replays behind its back. On each of the three transient
+   *   paths (retries exhausted, retry disabled, the awaited reconnect failed) the thrown
+   *   error carries `buffered` (boolean) — `true` only when the buffer really holds the
+   *   message. A non-boolean value is refused before any attempt.
+   *
+   * Every error this method throws also carries `sent` (boolean, d.1145, conf
+   * `mq-publish-buffer` 001): `true` when ANY attempt of this call wrote the frame to the
+   * channel, so the broker may hold — and after a memory alarm deliver — the message even
+   * though the call failed; `false` when no attempt got that far. The buffer entry records the
+   * same fact, and the flush after `unblocked` reads it.
+   * @throws {ValidationError} When `options.bufferOnFailure` is present and not a boolean.
    */
   async publish(queue, buffer, options = {}) {
+    // Refused HERE, before any attempt: a value that cannot say yes or no must not be read
+    // as either — `'false'` is truthy, and `0` would be read as "no" by accident
+    // (`architecture-principles.md` §3, §4). The one owner of the option is this layer;
+    // `BaseClient.publish()` only carries it.
+    if (options.bufferOnFailure !== undefined && typeof options.bufferOnFailure !== 'boolean') {
+      throw new ValidationError(
+        `[PublishLayer] options.bufferOnFailure must be a boolean - got ${JSON.stringify(options.bufferOnFailure)} `
+          + `for queue "${queue}". Expected: true (hold a transiently failed message and replay it after `
+          + 'the reconnect — the default) or false (hold nothing; the caller keeps the message). '
+          + 'Fix: pass bufferOnFailure: true or bufferOnFailure: false, or omit it.'
+      );
+    }
+
     // `priority` still orders the buffer's replay (critical first). What it no
     // longer does is choose a DIFFERENT buffer: the persistent one was a stub
     // that stored nothing, so routing critical messages to it dropped them
@@ -106,8 +172,38 @@ class PublishLayer {
     try {
       await this._client._publishOnce(queue, buffer, options);
     } catch (err) {
-      return await this._handlePublishError(err, queue, buffer, options, priority);
+      const sent = this._sentOf(err, queue);
+      return await this._handlePublishError(err, queue, buffer, options, priority, sent);
+    }
+  }
+
+  /**
+   * Whether the transport says the failed attempt's frame left the client.
+   *
+   * The transport writes `sent` on every error of `_publishOnce()` (d.1145). An error without
+   * it is a defect of the neighbour, and it is refused here by name rather than read as
+   * `false`: a message whose frame did leave would then be re-sent after `unblocked`, and
+   * that is the duplicate conf `mq-publish-buffer` 001 exists to prevent.
+   *
+   * @param {*} err - what `client._publishOnce()` threw
+   * @param {string} queue
+   * @returns {boolean}
+   * @throws {Error} when the error carries no boolean `sent`
+   * @private
+   */
+  _sentOf(err, queue) {
+    if (err !== null && typeof err === 'object' && typeof err.sent === 'boolean') {
+      return err.sent;
     }
+    throw new Error(
+      '[PublishLayer] The transport reported a failed attempt without saying whether its frame was sent - '
+        + `queue "${queue}", error: ${err && err.message ? err.message : String(err)}. `
+        + 'Expected: every error of client._publishOnce() carries sent (boolean) — RabbitMQClient writes it on '
+        + 'every attempt (conf mq-publish-buffer 001). Fix: a stand-in transport must write err.sent as the '
+        + 'real one does; the message is neither buffered nor retried, because nobody can say whether '
+        + 'the broker may already hold it.',
+      { cause: err }
+    );
   }
 
   /**
@@ -118,7 +214,56 @@ class PublishLayer {
     let lastError = null;
     let attempt = 0;
 
+    /**
+     * The broker's numbered refusal of THIS message, if it arrived after the confirmation
+     * budget had already answered an attempt.
+     *
+     * Measured (d.801): when the budget is shorter than the broker's answer, the attempt
+     * is answered "transient" while the frame underneath says 404 — and the loop below
+     * used to publish the message again, `publishMaxRetries` times, and then buffer it,
+     * where the flush re-offers it on every reconnect until its TTL drops it. d.801b made
+     * that verdict audible (`publish:refused-late`); this listener is what ACTS on it.
+     *
+     * No new evidence and no new timer: the frame is read where it has always been read
+     * (the transport's `channel._closeError` + `_closeFrameNamesThisSend()`), the event is
+     * the one already emitted, and the subscription lives exactly as long as this publish.
+     */
+    // Whether ANY attempt of this call wrote the frame to the channel (d.1145). Written on
+    // every error this loop throws — `said()` — and on the buffer entry.
+    let sentAny = false;
+    const said = (error) => {
+      error.sent = sentAny;
+      return error;
+    };
+
+    let lateRefusal = null;
+    const onRefusedLate = (event) => {
+      if (event.queue === queue && event.verdict === 'PermanentPublishError' && event.error) {
+        lateRefusal = event.error;
+      }
+    };
+    this._client.on('publish:refused-late', onRefusedLate);
+
+    try {
     while (attempt < this._maxRetries) {
+      // A message the broker has REFUSED is not published again. The question is asked
+      // before every attempt but the first, because the first is what earns the answer.
+      if (attempt > 0 && lateRefusal !== null) {
+        this._logger.warn(
+          `[PublishLayer] The broker refused this message while attempt ${attempt} was in flight, `
+            + `so attempt ${attempt + 1} of ${this._maxRetries} is not made for queue "${queue}" - `
+            + `${lateRefusal.message}`
+        );
+        this._client.emit('publish:failed', {
+          queue,
+          attempt,
+          error: lateRefusal.message,
+          retryable: false,
+          refusedLate: true
+        });
+        throw said(lateRefusal);
+      }
+
       attempt++;
 
       try {
@@ -133,7 +278,12 @@ class PublishLayer {
           this._logger.debug(`[PublishLayer] Retry attempt ${attempt}/${this._maxRetries} for queue "${queue}"`);
         }
 
-        await this._client._publishOnce(queue, buffer, options);
+        // WHICH attempt this is travels with the send, and is read by exactly one thing:
+        // the transport's report of a broker verdict that arrived after the confirmation
+        // budget had already answered (`publish:refused-late`, d.801b). It reaches no
+        // broker property — `buildAmqpMessageProperties()` copies only the AMQP keys it
+        // declares — and it changes nothing about the publish itself.
+        await this._client._publishOnce(queue, buffer, { ...options, attempt });
 
         // Track success (always emit, even for first attempt)
         this._client.emit('publish:success', {
@@ -149,6 +299,7 @@ class PublishLayer {
 
       } catch (err) {
         lastError = err;
+        sentAny = this._sentOf(err, queue) || sentAny;
 
         // Non-retryable errors - fail immediately
         if (err instanceof PermanentPublishError || err instanceof QueueNotFoundError) {
@@ -158,7 +309,7 @@ class PublishLayer {
             error: err.message,
             retryable: false
           });
-          throw err;
+          throw said(err);
         }
 
         // Transient errors - check if we should retry or buffer
@@ -173,8 +324,8 @@ class PublishLayer {
                 this._logger.debug(`[PublishLayer] ✓ Reconnection completed, proceeding with retry ${attempt + 1}/${this._maxRetries}`);
                 continue; // Retry immediately after reconnect
               } catch (reconnectErr) {
-                // Reconnection failed - buffer and fail
-                await this._bufferMessage(queue, buffer, options, priority, err);
+                // Reconnection failed - buffer (unless the caller said not to) and fail
+                const held = await this._holdOnFailure(queue, buffer, options, priority, err, sentAny);
                 this._client.emit('publish:failed', {
                   queue,
                   attempt,
@@ -182,13 +333,15 @@ class PublishLayer {
                   retryable: false,
                   reconnectFailed: true
                 });
-                throw new PublishError(
+                const failure = new PublishError(
                   `[PublishLayer] Publish failed: reconnection failed after ${attempt} attempts for queue "${queue}" - `
                     + 'Expected: the transport to re-establish the connection before the retry. '
-                    + 'Fix: read error.cause for the reconnect reason; the message itself is buffered, so it is not lost.',
+                    + `Fix: read error.cause for the reconnect reason; ${held.sentence}`,
                   queue,
                   reconnectErr
                 );
+                failure.buffered = held.buffered;
+                throw said(failure);
               }
             }
 
@@ -198,12 +351,30 @@ class PublishLayer {
               this._retryMaxDelay
             );
             this._logger.warn(`[PublishLayer] Retryable error for queue "${queue}" (attempt ${attempt}/${this._maxRetries}), waiting ${delay}ms before retry: ${err.message}`);
+            // THE BARE TIMER IS THE POINT, and it is not a copy of the transport's rail.
+            //
+            // The transport sleeps through `_setTimeout()`, which files the handle in
+            // `_activeTimers` so that a teardown can END the wait (d.759e). That is right
+            // THERE: what waits is the client's own recovery loop, and a teardown must
+            // stop it. It is wrong HERE, because what waits is the CALLER's `publish()`.
+            // Měřeno d.766 on this runtime: a sleep armed through `_setTimeout()` and
+            // swept by `_clearAllTimers()` mid-wait NEVER settles (the same sleep on the
+            // bare timer always does), so the one rail would turn a disconnect during a
+            // backoff into a `publish()` that never returns. The layer HAS the client
+            // (injected, required in the constructor), so this is a difference of
+            // obligation and not of reach.
+            //
+            // One owner at this level: the retry wait is the layer's, it is always
+            // awaited by the caller, and it always ends.
+            // @see ../transports/rabbitmqClient.js — `_setInterval` / `_clearAllTimers`
+            // @see ../../tests/unit/publish-max-retries-counts-attempts.test.js — the
+            //      control case that fails if this is ever "unified"
             await new Promise(resolve => setTimeout(resolve, delay));
             continue;
           }
 
-          // Max retries exceeded - buffer and fail
-          await this._bufferMessage(queue, buffer, options, priority, err);
+          // Max retries exceeded - buffer (unless the caller said not to) and fail
+          const held = await this._holdOnFailure(queue, buffer, options, priority, err, sentAny);
           this._client.emit('publish:failed', {
             queue,
             attempt,
@@ -211,21 +382,23 @@ class PublishLayer {
             retryable: true,
             maxRetriesExceeded: true
           });
-          throw new PublishError(
+          const failure = new PublishError(
             `[PublishLayer] Publish failed after ${attempt} attempts for queue "${queue}" - `
               + 'Expected: a retryable broker error to clear within maxRetries. '
-              + 'Fix: read error.cause for the last broker reason; the message is buffered, so it is not lost.',
+              + `Fix: read error.cause for the last broker reason; ${held.sentence}`,
             queue,
             err
           );
+          failure.buffered = held.buffered;
+          throw said(failure);
         }
 
         // Unknown error - fail immediately
-        throw err;
+        throw said(err);
       }
     }
 
-    throw (
+    throw said(
       lastError
       || new PublishError(
         `[PublishLayer] Publish failed for queue "${queue}" after ${attempt} attempts - `
@@ -235,50 +408,114 @@ class PublishLayer {
         null
       )
     );
+    } finally {
+      // The subscription lives exactly as long as this publish: no listener survives the
+      // call that opened it, whichever way the loop ended.
+      this._client.removeListener('publish:refused-late', onRefusedLate);
+    }
   }
 
   /**
    * Handle publish error - buffer transient errors
    * @private
    */
-  async _handlePublishError(err, queue, buffer, options, priority) {
+  async _handlePublishError(err, queue, buffer, options, priority, sent) {
     if (err instanceof QueueNotFoundError) {
       this._logger.error(`[PublishLayer] QueueNotFoundError for '${queue}' (infra=${err.isInfrastructure}): ${err.message}`);
       throw err;
     }
 
     if (err instanceof TransientPublishError) {
-      await this._bufferMessage(queue, buffer, options, priority, err);
+      const held = await this._holdOnFailure(queue, buffer, options, priority, err, sent);
+      // The transport's own error, thrown as it came — this path has always done that —
+      // with the one fact only this layer knows written on it.
+      err.buffered = held.buffered;
       throw err;
     }
 
     throw err;
   }
 
+  /**
+   * Hold a transiently failed message in the buffer — or, when the caller passed
+   * `bufferOnFailure: false`, deliberately do not — and say which happened.
+   *
+   * The one decision point of the three transient paths, so the option cannot be honoured
+   * on one path and forgotten on another.
+   *
+   * @private
+   * @returns {Promise<{buffered: boolean, sentence: string}>} `buffered` is `true` only when
+   *   the buffer really holds the message; `sentence` ends the thrown error's `Fix:` with
+   *   what the caller can rely on.
+   */
+  async _holdOnFailure(queue, buffer, options, priority, err, sent) {
+    if (options.bufferOnFailure === false) {
+      this._logger.warn(
+        `[PublishLayer] Message for queue '${queue}' NOT buffered (bufferOnFailure: false) after a transient error: ${err.message}`
+      );
+      return {
+        buffered: false,
+        sentence: 'the message is NOT buffered (bufferOnFailure: false), so nothing replays it — '
+          + 'the caller holds the only copy (error.buffered === false).'
+      };
+    }
+    if (await this._bufferMessage(queue, buffer, options, priority, err, sent)) {
+      return { buffered: true, sentence: 'the message is buffered, so it is not lost.' };
+    }
+    return {
+      buffered: false,
+      sentence: 'the message is NOT buffered (the buffer refused it — see the error log line before this one), '
+        + 'so nothing replays it (error.buffered === false).'
+    };
+  }
+
   /**
    * Buffer message při transient error
    * @private
+   * @returns {Promise<boolean>} whether the buffer now holds the message
    */
-  async _bufferMessage(queue, buffer, options, priority, err) {
+  async _bufferMessage(queue, buffer, options, priority, err, sent) {
     try {
-      await this._buffer.add(queue, buffer, options, { priority });
+      await this._buffer.add(queue, buffer, options, { priority, sent });
       this._logger.warn(`[PublishLayer] Buffered message for queue '${queue}' due to transient error: ${err.message}`);
       this._client.emit('publish:buffered', { queue });
+      return true;
     } catch (bufferErr) {
       this._logger.error(`[PublishLayer] Failed to buffer message for queue '${queue}': ${bufferErr.message}`);
+      return false;
     }
   }
 
   /**
-   * Flush buffered messages po reconnectu
+   * Re-send what the buffer holds — the one flush, with two triggers (d.1145, conf
+   * `mq-publish-buffer` 001):
+   *
+   *   - `'reconnected'` — a new connection: every entry is re-sent, as it always was;
+   *   - `'unblocked'` — the broker ended a memory alarm on the SAME connection: only the
+   *     entries whose frame never left the client are re-sent; the sent ones are dropped with a
+   *     warning, because the broker delivers those itself (d.1143 measured it).
+   *
+   * Every entry is re-sent with the publish options it was held with — nothing else is
+   * merged in (d.1145 removed the `flushOptions` argument nobody passed).
+   *
+   * @param {'reconnected'|'unblocked'} trigger - what ended the outage
+   * @returns {Promise<number>} how many entries were re-sent successfully
+   * @throws {Error} when the trigger is not one of the two
    */
-  async flushBuffered(flushOptions = {}) {
+  async flushBuffered(trigger) {
+    const SENT_ENTRIES = { reconnected: 'resend', unblocked: 'drop' };
+    if (!Object.prototype.hasOwnProperty.call(SENT_ENTRIES, trigger)) {
+      throw new Error(
+        `[PublishLayer] flushBuffered() needs its trigger - got ${JSON.stringify(trigger)}. `
+          + "Expected: 'reconnected' or 'unblocked' — they differ in what happens to a message whose frame "
+          + 'was already sent (conf mq-publish-buffer 001). Fix: pass the event that ended the outage.'
+      );
+    }
     const result = await this._buffer.flush(async (queue, buf, opts) => {
-      const mergedOptions = Object.assign({}, opts, flushOptions);
-      await this._client._publishOnce(queue, buf, mergedOptions);
-    });
+      await this._client._publishOnce(queue, buf, opts);
+    }, { sentEntries: SENT_ENTRIES[trigger] });
 
-    this._logger.info(`[PublishLayer] Flushed ${result} buffered message(s)`);
+    this._logger.info(`[PublishLayer] Flushed ${result} buffered message(s) after ${trigger}`);
     return result;
   }
 }

package/src/monitoring-initiated.js

@@ -8,15 +8,12 @@
  * run `active` on it (`api/infra/api_monitoring/src/consumer/index.js`). A service that
  * does not file it starts runs that are invisible for their whole life.
  *
- * Until now two services built that event, each in its own words: the gateway
- * (`infra/api_gateway/shared/monitoringInitiatedCopy.js`, with a redacted cookbook) and
- * the scheduler (`infra/api_scheduler/src/publisher/workflowPublisher.js`, inline, the
- * cookbook verbatim and no `tenant_uuid` at all). Two implementations of one concern are
- * a defect by default (`change-discipline.md` § One rail per concern), and the owner
- * settled which rail survives: this one, in the library that already owns the transport
- * half of the same wire (`docs/governance/confirmations/scheduler.md` 009). Both copies
- * are retired by their own services in the change that adopts this module — no period
- * with both (`architecture-principles.md` §11).
+ * One producer rail, by the owner's decision (`docs/governance/confirmations/scheduler.md`
+ * 009 and 024): the event is built and filed by this module, in the library that already
+ * owns the transport half of the same wire (`./monitoring-publish.js`). Every service that
+ * starts a run files it through here — the decision names the gateway and the scheduler.
+ * A service that builds the event in its own words is a second implementation of one
+ * concern, a defect by default (`change-discipline.md` § One rail per concern).
  *
  * WHAT THIS MODULE DOES NOT DO, deliberately:
  *