@onlineapps/mq-client-core 4.2.0 → 5.1.0

package/src/buffer/InMemoryBuffer.js

@@ -10,6 +10,19 @@ const { assertLogger } = require('@onlineapps/logger-contract');
  * Primárně určený pro transient scénáře (health checky apod.).
  */
 
+/**
+ * How a log line names where a buffered message was going: its exchange when it was published
+ * to one, its queue otherwise.
+ *
+ * @param {{queue: string, options: Object}} item
+ * @returns {string}
+ */
+function describeTarget(item) {
+  return item.options && typeof item.options.exchange === 'string' && item.options.exchange !== ''
+    ? `exchange "${item.options.exchange}"`
+    : `queue "${item.queue}"`;
+}
+
 class InMemoryBuffer {
   /**
    * Both numbers are REQUIRED and have no stand-in here.
@@ -61,7 +74,7 @@ class InMemoryBuffer {
     this._maxSize = options.maxSize;
     this._ttlMs = options.ttlMs;
 
-    /** @type {Array<{queue:string, buffer:Buffer, options:Object, createdAt:number, priority:string}>} */
+    /** @type {Array<{queue:string, buffer:Buffer, options:Object, createdAt:number, priority:string, sent:boolean}>} */
     this._items = [];
   }
 
@@ -69,7 +82,18 @@ class InMemoryBuffer {
    * Přidá zprávu do bufferu.
    * Staré/expirující zprávy jsou průběžně čištěny, při překročení kapacity odhazujeme nejstarší.
    */
-  async add(queue, buffer, options = {}, priority = 'normal') {
+  async add(queue, buffer, options = {}, priority = 'normal', sent) {
+    // Whether the frame of this message already LEFT the client (d.1145, conf
+    // `mq-publish-buffer` 001): the flush after `unblocked` re-sends only the entries that
+    // never did, because the broker delivers the frames it was holding by itself. Required —
+    // an entry that cannot say would be re-sent or dropped by a guess.
+    if (typeof sent !== 'boolean') {
+      throw new Error(
+        `[InMemoryBuffer] Cannot hold a message for queue '${queue}' without knowing whether its frame was sent - `
+          + `got sent=${JSON.stringify(sent)}. Expected: a boolean from the failed publish (error.sent). `
+          + 'Fix: pass it from PublishLayer, which reads it off the transport\'s error.'
+      );
+    }
     const now = Date.now();
     this._cleanupExpired(now);
 
@@ -86,6 +110,7 @@ class InMemoryBuffer {
       options,
       createdAt: now,
       priority,
+      sent,
     });
   }
 
@@ -94,7 +119,20 @@ class InMemoryBuffer {
    * @param {Function} flushFn - async (queue, buffer, options) => void
    * @returns {Promise<number>} - počet úspěšně flushnutých zpráv
    */
-  async flush(flushFn) {
+  async flush(flushFn, { sentEntries } = {}) {
+    // What happens to an entry whose frame already LEFT the client (d.1145, conf
+    // `mq-publish-buffer` 001): 'resend' after a reconnect — the old socket and whatever the
+    // broker had not read from it are gone; 'drop' after the broker unblocked the connection —
+    // it reads what was waiting in the socket and delivers those frames by itself, so a
+    // re-send would be one more copy. Required: a flush that guessed would do one or the other
+    // wrong.
+    if (sentEntries !== 'resend' && sentEntries !== 'drop') {
+      throw new Error(
+        `[InMemoryBuffer] flush() needs to know what to do with a sent entry - got sentEntries=${JSON.stringify(sentEntries)}. `
+          + "Expected: 'resend' (after a reconnect) or 'drop' (after the broker unblocked the connection). "
+          + 'Fix: flush through PublishLayer.flushBuffered(trigger), which maps its trigger to one of them.'
+      );
+    }
     const now = Date.now();
     this._cleanupExpired(now);
 
@@ -103,9 +141,23 @@ class InMemoryBuffer {
     }
 
     // Zkopírujeme a vyprázdníme interní pole, abychom se vyhnuli reentrancy problémům
-    const items = this._items.slice();
+    let items = this._items.slice();
     this._items = [];
 
+    if (sentEntries === 'drop') {
+      for (const item of items.filter((entry) => entry.sent)) {
+        this._logger.warn(
+          `[InMemoryBuffer] A buffered message for ${describeTarget(item)} is not re-sent after the broker unblocked `
+            + `the connection: its frame had been sent, and it was buffered ${now - item.createdAt} ms ago - Expected: the broker delivers `
+            + 'the frames it held during the alarm by itself once it reads the socket again, so a re-send would '
+            + 'be one more copy. Fix: nothing to do here; a consumer that must not see a message twice '
+            + 'deduplicates it (conf mq-consumer-contract 009), and a message the broker did NOT keep is '
+            + 'a broker-side loss this client cannot see.'
+        );
+      }
+      items = items.filter((entry) => !entry.sent);
+    }
+
     // Kritické zprávy (priority === 'critical') házíme dopředu
     items.sort((a, b) => {
       if (a.priority === b.priority) return a.createdAt - b.createdAt;
@@ -125,7 +177,9 @@ class InMemoryBuffer {
         this._logger.warn(
           `[InMemoryBuffer] Failed to flush message for queue '${item.queue}': ${err.message}`
         );
-        await this.add(item.queue, item.buffer, item.options, item.priority);
+        // The replay is one more attempt: if IT wrote the frame, the entry says so from now on.
+        const sent = item.sent || (err !== null && typeof err === 'object' && err.sent === true);
+        await this.add(item.queue, item.buffer, item.options, item.priority, sent);
       }
     }
 
@@ -140,15 +194,46 @@ class InMemoryBuffer {
     return this._items.length;
   }
 
+  /**
+   * Drop the entries older than the TTL — and say, as an ERROR, what was dropped (d.1145, conf
+   * `mq-publish-buffer` 001).
+   *
+   * Until d.1145 this was one `info` line with a count and nothing else, the only trace of a
+   * message nobody would ever deliver (a memory alarm keeps the connection alive, so no
+   * reconnect flush comes — d.1143). One error per destination and `sent` value, with the
+   * count and the age of the oldest: a message whose frame never left is LOST, one whose frame
+   * had been sent may have been delivered by the broker on its own, and the two are never
+   * folded into one sentence.
+   *
+   * @param {number} now - the clock reading the caller took
+   * @private
+   */
   _cleanupExpired(now) {
-    const before = this._items.length;
-    this._items = this._items.filter(
-      (item) => now - item.createdAt <= this._ttlMs
-    );
-    const removed = before - this._items.length;
-    if (removed > 0) {
-      this._logger.info(
-        `[InMemoryBuffer] Removed ${removed} expired buffered messages`
+    const expired = this._items.filter((item) => now - item.createdAt > this._ttlMs);
+    if (expired.length === 0) {
+      return;
+    }
+    this._items = this._items.filter((item) => now - item.createdAt <= this._ttlMs);
+
+    const groups = new Map();
+    for (const item of expired) {
+      const key = `${describeTarget(item)}|${item.sent}`;
+      const group = groups.get(key) || { target: describeTarget(item), sent: item.sent, count: 0, oldestMs: 0 };
+      group.count += 1;
+      group.oldestMs = Math.max(group.oldestMs, now - item.createdAt);
+      groups.set(key, group);
+    }
+    for (const { target, sent, count, oldestMs } of groups.values()) {
+      this._logger.error(
+        `[InMemoryBuffer] ${count} buffered message(s) for ${target} expired after the buffer TTL `
+          + `(${this._ttlMs} ms; oldest ${oldestMs} ms), sent=${sent} - `
+          + (sent
+            ? 'the frame had been sent, so the broker may have delivered it on its own; nothing re-sends it now. '
+            : 'the frame never left this client, so the message is LOST; nothing re-sends it now. ')
+          + 'Expected: a reconnect, or the broker unblocking the connection, within publishBufferTtlMs. '
+          + 'Fix: find why the broker stayed away that long (an alarm: management API /api/health/checks/alarms; '
+          + 'an outage: the connection log); a message that must survive longer belongs to a caller that keeps '
+          + 'it durably and publishes with bufferOnFailure: false.'
       );
     }
   }

package/src/buffer/MessageBuffer.js

@@ -50,7 +50,9 @@ class MessageBuffer {
   async add(queue, buffer, options = {}, meta = {}) {
     const priority = meta.priority || 'normal';
 
-    await this._inMemory.add(queue, buffer, options, priority);
+    // `sent` is passed through unread: the in-memory buffer owns the rule that it is required
+    // (d.1145, conf `mq-publish-buffer` 001).
+    await this._inMemory.add(queue, buffer, options, priority, meta.sent);
   }
 
   /**
@@ -58,8 +60,8 @@ class MessageBuffer {
    * @param {Function} flushFn - async (queue, buffer, options) => void
    * @returns {Promise<number>} how many messages were replayed
    */
-  async flush(flushFn) {
-    return await this._inMemory.flush(flushFn);
+  async flush(flushFn, flushPolicy) {
+    return await this._inMemory.flush(flushFn, flushPolicy);
   }
 
   /**

package/src/config/configSchema.js

@@ -136,15 +136,20 @@ module.exports = {
       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).',
+        'AMQP heartbeat in SECONDS, proposed to the broker in the connection URL (?heartbeat=) at '
+        + 'connect. Explicit value, else ENV RABBITMQ_HEARTBEAT, else the module default '
+        + '(../defaults.js heartbeatSeconds). 0 does NOT switch the heartbeat off: amqplib\'s '
+        + 'negotiation takes whichever side sets a limit, so the broker\'s own value applies '
+        + '(RabbitMQ 60 s unless its configuration says otherwise; measured d.1126: a paused broker '
+        + 'detected after 179 s). Only a broker that also offers 0 disables it.',
     },
     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).',
+        '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 +253,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',
@@ -270,10 +291,12 @@ module.exports = {
       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.',
+        'How long this client waits for an ANSWER from the broker, in milliseconds — every wait: the '
+        + 'confirm of one publish attempt, the close-ok of each handle disconnect() closes, and every '
+        + 'request a channel sends and waits on (queue/exchange declarations, checkQueue, bindQueue, '
+        + 'purge, delete, consume, cancel, prefetch, channel open; conf mq-broker-answer-budget 001, '
+        + 'd.1135). One number for one question — it was named publishConfirmationTimeout until d.299, '
+        + 'after the teardown had been spending it since d.283.',
     },
     connectTimeout: {
       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
@@ -110,12 +120,13 @@ module.exports = {
   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.
+  // How long this client waits for an ANSWER from the broker, in ms — every wait:
+  // the confirm of one publish attempt, the `close-ok` of each handle
+  // `disconnect()` closes, and every request a channel sends and waits on
+  // (conf `mq-broker-answer-budget` 001, d.1135) — one number for all of them,
+  // which is why it carries the name of none. 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

package/src/config/deliveryPolicy.js

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

package/src/config/queueConfig.js

@@ -129,8 +129,11 @@ const templateShape = (template) =>
  * @returns {{serviceName: string, queueType: string}|null} The service and the
  *   template key that declares the queue's arguments, or `null` for a name no
  *   template matches.
- * @throws {ValidationError} If two templates match one name - a defect in this file,
- *   never a runtime condition, and one that would otherwise be resolved by key order.
+ * @throws {ValidationError} If two templates of the same kind match one name - a defect in
+ *   this file, never a runtime condition, and one that would otherwise be resolved by key
+ *   order. A literal shape and a placeholder shape matching the same name is NOT that case:
+ *   the literal wins, because it declares the name while the placeholder only fits it
+ *   (d.817b, `registry.events` against `registry.{instance_id}`).
  */
 const matchBusinessTemplate = (business, queueName) => {
   const parts = queueName.split('.');
@@ -145,15 +148,24 @@ const matchBusinessTemplate = (business, queueName) => {
     );
   });
 
-  if (matched.length > 1) {
+  // A LITERAL BEATS A PLACEHOLDER (d.817b). `registry.events` names a queue;
+  // `registry.{instance_id}` names a shape — so `<svc>.registry.events` fits both, and a
+  // wildcard must not claim a name another template DECLARES. It is the same tie-break this
+  // file makes one level up, where a name an infrastructure section declares is never a
+  // business queue however well it fits a template (d.279). Ambiguity between two templates
+  // of the SAME kind is still a defect and still refused below.
+  const literals = matched.filter((template) => !templateShape(template).includes(null));
+  const decided = literals.length > 0 ? literals : matched;
+
+  if (decided.length > 1) {
     throw new ValidationError(
-      `[queueConfig] Business queue ${queueName} matches more than one template: ${matched.join(', ')} - `
+      `[queueConfig] Business queue ${queueName} matches more than one template: ${decided.join(', ')} - `
         + 'Expected: exactly one template declares a name, so one queue has one definition. '
         + 'Fix: make the overlapping keys in the `business` section of src/config/queueConfig.js distinct.'
     );
   }
 
-  return matched.length === 1 ? { serviceName: parts[0], queueType: matched[0] } : null;
+  return decided.length === 1 ? { serviceName: parts[0], queueType: decided[0] } : null;
 };
 
 /**
@@ -277,33 +289,11 @@ module.exports = {
       }
     },
 
-    /**
-     * workflow.control - Shared queue for service-agnostic control-flow steps
-     * All business services listen as competing consumers (same pattern as workflow.init).
-     *
-     * Purpose:
-     * - Execute control-flow steps that are not pinned to a specific service
-     * - Keep workflow.init as a clear "gateway entrypoint" queue (no semantic overload)
-     *
-     * TTL: 30 seconds - if no business service processes message within 30s, it expires
-     * DLQ routing: Expired messages go to workflow.failed
-     */
-    control: {
-      durable: true,
-      arguments: {
-        'x-message-ttl': 30000,
-        'x-max-length': 10000,
-        'x-dead-letter-exchange': '',
-        'x-dead-letter-routing-key': 'workflow.failed'
-      }
-    },
-
     /**
      * workflow.completed - Completed workflows
      *
      * Dead-letters to workflow.dlq over the DEFAULT exchange, where the routing key
-     * is the destination queue name — the shape workflow.init/workflow.control
-     * already use. The dispatcher rejects a message here on an invalid payload, a
+     * is the destination queue name — the shape workflow.init already uses. The dispatcher rejects a message here on an invalid payload, a
      * schema violation and a delivery failure; until d.278 the broker dropped each
      * one, because the queue declared nowhere to put it.
      *
@@ -492,6 +482,41 @@ module.exports = {
         'x-dead-letter-exchange': DEAD_LETTER_EXCHANGE,
         'x-dead-letter-routing-key': '{service}.dlq'
       }
+    },
+
+    /**
+     * {service}.registry.{instance_id} - the queue ONE INSTANCE gets its registry answers
+     * on, beside the shared `{service}.registry` the registry uses for its own prompts.
+     *
+     * The owner settled the name and the split (`registry-instance-identity` 001,
+     * Conditions): answers travel to `<svc>.registry.<instanceId>` through the existing
+     * `responseQueue`, the shared queue carries the registry's prompts. Measured by the
+     * registry thread in d.817: without a template here `getDeadLetterRoute()` answered
+     * null, `consume()` refuses a queue with no declared route (`mq-consumer-contract`
+     * 002), and the client had to go on answering on the shared queue — the state the
+     * confirmation moved away from.
+     *
+     * ITS LIFETIME IS `x-expires` (question 14, variant A; `registry-instance-identity`
+     * 003). Every boot of a copy names a new queue (the
+     * instance id is a UUID per process unless `SERVICE_INSTANCE_ID` names one), and
+     * nothing deletes the old one — not `deregister()`, not the wrapper's shutdown, not the
+     * registry, which only checks the queue exists before it answers. A durable queue with
+     * no lifetime would therefore stay behind after every restart, crash or clean stop
+     * alike. The broker deletes a queue with `x-expires` once it has gone that long with no
+     * consumer, so a live copy (its consumer attached) keeps it and a gone copy loses it.
+     * 60 s: longer than a reconnect of a live copy, shorter than the monitoring orphan
+     * window (`queue_orphan_alert.min_orphan_minutes`, seed 5), so a dead copy's queue
+     * never opens a `no_owner` episode. One rail: the lifetime lives in this declaration
+     * only — the transport refuses a caller's `autoDelete`/`exclusive` on a classified
+     * queue, and no caller deletes it.
+     */
+    'registry.{instance_id}': {
+      durable: true,
+      arguments: {
+        'x-expires': 60000,            // 60 s with no consumer, then the broker deletes it (question 14, A)
+        'x-dead-letter-exchange': DEAD_LETTER_EXCHANGE,
+        'x-dead-letter-routing-key': '{service}.dlq'  // Placeholder, replaced with actual service name
+      }
     }
   },
 
@@ -766,11 +791,12 @@ module.exports = {
      * `mq-consumer-contract` 002 point 2, 003 point 1).
      *
      * **A declaration is not a creation instruction. The terminal is brought into being
-     * by the owner of the prefix that NAMES it.** `initInfrastructureQueues()` derives
-     * the whole list from these sections only when its caller passes no `queues` list;
-     * every caller passes one, and the gateway's names exactly the five `workflow.*`
-     * queues it owns (`infra/api_gateway/index.js`). `monitoring.dlq` therefore belongs
-     * to the monitoring service's own call, beside the queues it consumes. Until that
+     * by the owner of the prefix that NAMES it.** `initInfrastructureQueues()` creates
+     * exactly the names its caller passes in `queues`, a list that is required since
+     * d.668 — it derives nothing from these sections, and the gateway's list names
+     * exactly the five `workflow.*` queues it owns (`infra/api_gateway/index.js`).
+     * `monitoring.dlq` therefore belongs to the monitoring service's own call, beside
+     * the queues it consumes. Until that
      * call names it, a `nack(requeue=false)` on a queue of this family dead-letters onto
      * a routing key no queue carries and the broker DROPS the message — measured
      * 2026-09-16 on the dev broker: 78 queues, and the only `.dlq` among them
@@ -1096,7 +1122,8 @@ module.exports = {
      * travels on that exchange, so the scheduler reads it there rather than asking the
      * observer over HTTP or reading a database that is not its own. No producer changes; the
      * binding is the scheduler's own act at boot (the pattern
-     * `infra/api_delivery_endpoint/src/index.js:164` already uses), and this file only
+     * `infra/api_delivery_endpoint/src/index.js` already uses with its
+     * `mq.bindQueueToFanout(…)` calls), and this file only
      * DECLARES what that queue is.
      *
      * WHICH event_type values those are is NOT written here: the vocabulary has one owner and
@@ -1264,8 +1291,11 @@ module.exports = {
 
   /**
    * The infrastructure prefixes this configuration classifies by, in declaration
-   * order. Published so a caller — `initInfrastructureQueues()`, a queue-ownership
-   * probe, a document generator — reads the list instead of keeping a copy of it.
+   * order. Published so a caller reads the list instead of keeping a copy of it.
+   * It named `initInfrastructureQueues()` as such a caller until d.668, when that
+   * function stopped deriving a queue list at all and started requiring `queues`;
+   * what reads it today is this package's own coverage of the classification
+   * (`tests/unit/queue-name-collision.test.js`, `queueConfig-telemetry.test.js`).
    * @returns {ReadonlyArray<string>} Prefixes WITHOUT the trailing dot.
    */
   infrastructurePrefixes() {
@@ -1507,8 +1537,7 @@ module.exports = {
    *
    * ONE owner of the mapping name → options. Every path that declares a queue
    * reads it here and nowhere else: the public `assertQueue()` of the transport
-   * (and through it `RecoveryWorker.createQueue()`, the cookbook-router's
-   * QueueManager and the publish path's 404 branch), and the consumer's
+   * (and through it the cookbook-router's QueueManager), and the consumer's
    * `_prepareQueueForConsume()`.
    *
    * Until d.410 those two worked the same three lines out separately —
@@ -1609,7 +1638,7 @@ module.exports = {
    *
    * The counterpart of `getDeadLetterRoute()`, and the reason a queue may have no
    * route without that being a defect. `workflow.failed` is named in
-   * `x-dead-letter-routing-key` by `workflow.init` and `workflow.control`;
+   * `x-dead-letter-routing-key` by `workflow.init`;
    * `{service}.dlq` by every business template; `workflow.dlq` and `delivery.dlq`
    * by their own families. Giving such a queue a route of its own would either
    * close a loop or start an endless chain, which is why the confirmed topology

package/src/config.js

@@ -20,7 +20,11 @@ const runtimeCfg = createRuntimeConfig({
 
     // Client behavior
     heartbeat: { env: 'RABBITMQ_HEARTBEAT', defaultKey: 'heartbeatSeconds', type: 'number' },
-    serviceName: { env: 'SERVICE_NAME', defaultKey: 'serviceName' },
+    // The caller's own identity — required, never defaulted (d.770). Two legs, both the
+    // caller's: the explicit key, or ENV SERVICE_NAME. There is no third, because a
+    // library that invents a service name makes every row it writes name the wrong
+    // service (`architecture-principles.md` §3, and `./defaults.js` for the measurement).
+    serviceName: { env: 'SERVICE_NAME', required: true },
 
     // Connection-level recovery budget. Resolved here (explicit → env →
     // module default) instead of an inline `|| 10` in the transport, so the

package/src/defaults.js

@@ -7,11 +7,17 @@
  * - This module owns defaults for MQ client behavior (heartbeat, connectionName prefix).
  * - Infrastructure topology (RabbitMQ URL) is NOT defaulted; it must be provided via
  *   explicit config.host or ENV RABBITMQ_URL (fail-fast).
+ * - The CALLER's own identity is not defaulted either. `serviceName` used to be
+ *   `'oa-service'` here until d.770: a name this module cannot know and must not invent
+ *   (`architecture-principles.md` §3). What it bought was measured, and it was a lie —
+ *   every client built without the key published its monitoring events, and named its
+ *   queues, under a service that does not exist. It is now required, with the same two
+ *   legs every caller already uses: explicit `serviceName`, or ENV `SERVICE_NAME`
+ *   (`../config.js`).
  */
 
 module.exports = {
   heartbeatSeconds: 30,
-  serviceName: 'oa-service',
 
   // How many times connection-level recovery retries before the connection is
   // declared permanently lost. Client BEHAVIOUR, so it is owned here (the same