@onlineapps/mq-client-core 2.0.1 → 3.0.1

package/src/config/queueConfig.js

@@ -1,18 +1,246 @@
 'use strict';
 
+/**
+ * The platform's dead-letter exchange.
+ *
+ * A name three services must agree on has to have ONE owner, or it has as many
+ * as the places that type it: this file typed the name four times, and
+ * `@onlineapps/conn-infra-mq` reads it back out of a queue's arguments
+ * (`getBusinessQueueConfig('queue')['x-dead-letter-exchange']`) because there was
+ * nothing to import. Same reasoning as `src/index.js` § topology, which gave the
+ * queue names that travel on the wire one declaration each.
+ *
+ * Exported as `deadLetterExchange()` — a getter, not the bare constant, so an
+ * importer cannot rebind platform topology.
+ */
+const DEAD_LETTER_EXCHANGE = 'dlx';
+
 /**
  * queueConfig.js
  *
- * Central configuration for INFRASTRUCTURE queues only.
- * Business queues ({service}.workflow, {service}.queue, {service}.dlq) are created
- * by individual services via QueueManager.setupServiceQueues().
+ * Central configuration for INFRASTRUCTURE queues, and for the TEMPLATES of the
+ * queues a business service owns. `{service}.workflow`, `{service}.queue` and
+ * `{service}.dlq` are created by the service itself via
+ * QueueManager.setupServiceQueues(); the registry-client templates are declared here
+ * for the same reason — one declaration per queue, which is what the dead-letter gate
+ * of consume() reads.
  *
  * This ensures consistent configuration for infrastructure queues across all services.
  * 
  * NOTE: This is part of mq-client-core (spodní vrstva) because it's used by both:
  * - Infrastructure services (via mq-client-core)
  * - Business services (via conn-infra-mq connector)
+ *
+ * Every lookup below fails fast with a `ValidationError`: an unknown queue name is a
+ * caller mistake, not a runtime condition, and the package has one error rail
+ * (`utils/errorHandler.js`) rather than a mix of typed and bare errors.
+ */
+
+const { ValidationError } = require('../utils/errorHandler');
+
+/**
+ * The prefix each section's keys carry ON THE WIRE.
+ *
+ * A section name is NOT automatically the prefix of the names it declares, and
+ * assuming it was is the defect d.267 fixed: `deliveryEvents` declares three
+ * `delivery.` queues, so a lookup that stripped `delivery.` and read only the
+ * `delivery` section answered "not defined" for every one of them. The mapping is
+ * stated once, here, and every lookup and every message derives from it rather
+ * than repeating a list by hand (`single-source-of-truth.md`).
+ *
+ * `business` is absent on purpose: it holds TEMPLATES (`{service}.workflow`), not
+ * full names, so no prefix composes a wire name from it.
+ */
+const SECTION_PREFIXES = Object.freeze({
+  workflow: 'workflow',
+  delivery: 'delivery',
+  deliveryEvents: 'delivery',
+  validation: 'validation',
+  infrastructure: 'infrastructure',
+  monitoring: 'monitoring',
+  telemetry: 'telemetry',
+  alerts: 'alert',
+  registry: 'registry'
+});
+
+/**
+ * Every infrastructure prefix and the lookup that answers for it — ONE map, read by
+ * the classifier, by the dispatch and by the refusal message alike.
+ *
+ * It is a map rather than three lists because of d.269: `isInfrastructureQueue()`
+ * accepted `telemetry.` while `getInfrastructureQueueConfig()` had no branch for it,
+ * so a telemetry name was classified as infrastructure and then refused as not being
+ * one — and the refusal listed four prefixes while the classifier knew seven, because
+ * the sentence was typed by hand. A prefix the classifier knows but nothing can look
+ * up is not expressible here (`single-source-of-truth.md`).
+ */
+const INFRASTRUCTURE_PREFIX_LOOKUPS = Object.freeze({
+  workflow: 'getWorkflowQueueConfig',
+  registry: 'getRegistryQueueConfig',
+  infrastructure: 'getInfrastructureHealthQueueConfig',
+  validation: 'getValidationQueueConfig',
+  monitoring: 'getMonitoringQueueConfig',
+  telemetry: 'getTelemetryQueueConfig',
+  delivery: 'getDeliveryQueueConfig'
+});
+
+const INFRASTRUCTURE_PREFIXES = Object.freeze(Object.keys(INFRASTRUCTURE_PREFIX_LOOKUPS));
+
+/** Every section declaring names under one prefix — derived, never a second list. */
+const sectionsForPrefix = (prefix) =>
+  Object.keys(SECTION_PREFIXES).filter((section) => SECTION_PREFIXES[section] === prefix);
+
+const DELIVERY_SECTIONS = sectionsForPrefix('delivery');
+
+/** A `{placeholder}` segment of a business template key: matches any ONE name part. */
+const TEMPLATE_PLACEHOLDER = /^\{[^.{}]+\}$/;
+
+/**
+ * One business template key as a SHAPE: the parts a queue name must carry after the
+ * service name, with `null` where the template accepts anything (`registry.events`
+ * -> `['registry', 'events']`; a key writing `registry.{kind}` would give
+ * `['registry', null]`).
+ *
+ * A declared dead-letter routing key is written in the same notation
+ * (`{service}.dlq`), so `isDeadLetterTarget()` reads it through this one function
+ * rather than through a second placeholder rule.
+ */
+const templateShape = (template) =>
+  template.split('.').map((part) => (TEMPLATE_PLACEHOLDER.test(part) ? null : part));
+
+/**
+ * Match a queue name against the templates the `business` section declares.
+ *
+ * The section IS the list — d.278 removed the hand-typed `['workflow', 'queue',
+ * 'dlq']`, which had to be edited in step with the templates and therefore could
+ * disagree with them. A template nobody can express here is a queue nobody can
+ * classify, which is the state `{service}.registry` was in: declared nowhere,
+ * classified as neither kind, and so refused by the dead-letter gate of consume().
+ *
+ * @param {Object} business - The `business` section (templates keyed by their shape).
+ * @param {string} queueName - Full queue name.
+ * @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.
+ */
+const matchBusinessTemplate = (business, queueName) => {
+  const parts = queueName.split('.');
+  if (parts.length < 2 || parts[0] === '') return null;
+
+  const tail = parts.slice(1);
+  const matched = Object.keys(business).filter((template) => {
+    const shape = templateShape(template);
+    return (
+      shape.length === tail.length
+      && shape.every((part, index) => (part === null ? tail[index] !== '' : part === tail[index]))
+    );
+  });
+
+  if (matched.length > 1) {
+    throw new ValidationError(
+      `[queueConfig] Business queue ${queueName} matches more than one template: ${matched.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;
+};
+
+/**
+ * Every full wire name the infrastructure sections DECLARE.
+ *
+ * Derived from the sections themselves — `SECTION_PREFIXES` says which prefix each
+ * one puts on the wire, and only sections whose prefix has a lookup take part, so a
+ * name this set contains can always be resolved (the invariant d.269 established).
+ * `alerts` is therefore absent, exactly as it is today: nothing looks up `alert.`.
+ *
+ * @param {Object} config - The queueConfig object (its sections are read from `this`).
+ * @returns {Set<string>} The declared names, e.g. `registry.register`, `workflow.dlq`.
  */
+const declaredInfrastructureNames = (config) => {
+  const names = new Set();
+
+  for (const [section, prefix] of Object.entries(SECTION_PREFIXES)) {
+    if (!Object.prototype.hasOwnProperty.call(INFRASTRUCTURE_PREFIX_LOOKUPS, prefix)) continue;
+    for (const key of Object.keys(config[section] || {})) {
+      names.add(`${prefix}.${key}`);
+    }
+  }
+
+  return names;
+};
+
+/**
+ * Every name this configuration dead-letters TO — the END of a chain.
+ *
+ * Derived from the declarations themselves: the value of every
+ * `x-dead-letter-routing-key` any section writes, placeholders and all
+ * (`{service}.dlq`, `workflow.failed`, `workflow.dlq`, `delivery.dlq`). A list of
+ * names typed here would have to be edited in step with the templates and could
+ * therefore disagree with them — the defect d.278 removed from
+ * `matchBusinessTemplate()`, and the reason `declaredInfrastructureNames()` above
+ * derives its set the same way.
+ *
+ * The `.dlq` family needs no rule of its own: every `.dlq` this configuration
+ * declares — `workflow.dlq`, `delivery.dlq`, `{service}.dlq` — is already the
+ * target of a declared routing key (measured 2026-09-14), so the set covers it.
+ * A `.dlq` nothing routes to would be a queue with no writer, which is a defect
+ * in the declaration, not a case to paper over here.
+ *
+ * @param {Object} config - The queueConfig object (its sections are read from `this`).
+ * @returns {Set<string>} The routing keys, e.g. `workflow.failed`, `{service}.dlq`.
+ */
+const declaredDeadLetterTargets = (config) => {
+  const targets = new Set();
+
+  for (const section of Object.values(config)) {
+    if (section === null || typeof section !== 'object') continue;
+    for (const entry of Object.values(section)) {
+      if (entry === null || typeof entry !== 'object') continue;
+      const routingKey = entry.arguments && entry.arguments['x-dead-letter-routing-key'];
+      if (typeof routingKey === 'string' && routingKey !== '') targets.add(routingKey);
+    }
+  }
+
+  return targets;
+};
+
+/**
+ * The two ways out of "this configuration declares no such queue", named in the
+ * refusal itself.
+ *
+ * A name like `registry.foo` can be two different mistakes, and the message cannot
+ * tell which: an infrastructure queue nobody declared, or a queue owned by a service
+ * named `registry` written in a shape no template matches. Naming only the first sends
+ * the reader to add a platform queue for something a service owns — the very confusion
+ * d.279 came from. The service-owned alternatives are rendered from the `business`
+ * templates, never typed out, so the sentence cannot fall behind them.
+ *
+ * @param {Object} business - The `business` section.
+ * @param {string} queueName - The full name that was not found.
+ * @returns {string} The `Fix:` sentence (`architecture-principles.md` §5).
+ */
+const waysOut = (business, queueName) => {
+  const parts = queueName.split('.');
+  const owner = parts[0];
+  const declare = 'Fix: declare the entry in src/config/queueConfig.js if the platform owns the queue';
+
+  // Only the templates a name of THIS shape could take: offering `registry.registry.events`
+  // as the fix for `registry.foo` would be a suggestion that cannot be followed.
+  const owned = Object.keys(business)
+    .filter((template) => template.split('.').length === parts.length - 1)
+    .map((template) => `${owner}.${template}`);
+
+  if (owned.length === 0) {
+    return `${declare}; no queue a service owns has this shape, so the name is not a service-owned one either.`;
+  }
+
+  return `${declare}, or — if the service named "${owner}" owns it — use one of the names that service's own `
+    + `queues take (${owned.join(', ')}), which this configuration already classifies.`;
+};
 
 module.exports = {
   /**
@@ -65,23 +293,67 @@ module.exports = {
 
     /**
      * 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
+     * schema violation and a delivery failure; until d.278 the broker dropped each
+     * one, because the queue declared nowhere to put it.
+     *
+     * @see api/docs/governance/confirmations/mq-consumer-contract.md 003
      */
     completed: {
       durable: true,
       arguments: {
         'x-message-ttl': 300000,      // 5 minutes TTL
-        'x-max-length': 10000
+        'x-max-length': 10000,
+        'x-dead-letter-exchange': '',        // Default exchange: routing key IS the queue name
+        'x-dead-letter-routing-key': 'workflow.dlq'
+      }
+    },
+
+    /**
+     * workflow.delivery_requested - a run handed over to the Delivery Dispatcher.
+     *
+     * The hand-over is NOT the end of a run. A cookbook declaring `delivery.on_result`
+     * has one step left when the document is ready to leave the platform: the step that
+     * records how the delivery went. Publishing that hand-over on `workflow.completed`
+     * made the terminal message mean "not finished yet", and left the real end of such a
+     * run without a message at all. The owner gave the hand-over a name of its own:
+     * `workflow.delivery_requested`, carrying `status: "delivery_requested"`, while
+     * `workflow.completed` stays the single terminal message.
+     *
+     * Same arguments as `workflow.completed` — a hand-over is the same payload with a
+     * different verb, read by the same consumer, so it expires and caps the same way —
+     * and the same dead-letter destination: the mechanical rule of confirmation
+     * `mq-consumer-contract` 003 routes every queue of this family to `workflow.dlq`
+     * over the DEFAULT exchange, where the routing key IS the destination queue's name.
+     *
+     * @see api/docs/governance/confirmations/delivery-receipt-chain.md 002, 003
+     * @see api/docs/governance/confirmations/mq-consumer-contract.md 003
+     */
+    delivery_requested: {
+      durable: true,
+      arguments: {
+        'x-message-ttl': 300000,      // 5 minutes TTL, as workflow.completed
+        'x-max-length': 10000,
+        'x-dead-letter-exchange': '',        // Default exchange: routing key IS the queue name
+        'x-dead-letter-routing-key': 'workflow.dlq'
       }
     },
 
     /**
      * workflow.failed - Failed workflows (DLQ entry point)
-     * Workflows land here after max retries exhausted, waiting for human decision
+     * Workflows land here after max retries exhausted, waiting for human decision.
+     *
+     * No TTL: the queue is read by an operator, not by a service, and it has no
+     * dead-letter exchange — an expiring message is a deleted message.
+     *
+     * @see api/docs/governance/confirmations/mq-consumer-contract.md 002
      */
     failed: {
       durable: true,
       arguments: {
-        'x-message-ttl': 300000,      // 5 minutes TTL
         'x-max-length': 10000
       }
     },
@@ -89,17 +361,28 @@ module.exports = {
     /**
      * workflow.discarded - Discarded workflows (final state)
      * Workflows land here after human decision to discard from DLQ
+     *
+     * Dead-letters to workflow.dlq, like every other queue of this family
+     * (confirmation mq-consumer-contract 003). The operator's own queues —
+     * workflow.failed and workflow.dlq — are the two that keep no onward route.
      */
     discarded: {
       durable: true,
       arguments: {
         'x-message-ttl': 300000,      // 5 minutes TTL
-        'x-max-length': 10000
+        'x-max-length': 10000,
+        'x-dead-letter-exchange': '',
+        'x-dead-letter-routing-key': 'workflow.dlq'
       }
     },
 
     /**
      * workflow.dlq - Dead letter queue for workflows
+     *
+     * The end of the road for this family: read by an operator through the DLQ
+     * dashboard contract, never forwarded onward. No TTL and no dead-letter route,
+     * for the same reason workflow.failed has neither — an expiring or forwarded
+     * message is one the operator never gets to decide about.
      */
     dlq: {
       durable: true,
@@ -111,9 +394,22 @@ module.exports = {
   },
 
   /**
-   * Business queue templates
-   * These are templates for service-specific queues ({service}.workflow, {service}.queue, {service}.dlq)
-   * Used by QueueManager.setupServiceQueues() to ensure consistent configuration
+   * Business queue templates - every queue a business service OWNS.
+   *
+   * A key here is the queue name's tail after the service name, and it is read as a
+   * PATTERN: a `{placeholder}` segment matches any one part. That is what makes
+   * `isBusinessQueue()`/`parseBusinessQueue()` derive from this section instead of
+   * repeating a list of types by hand, and it is the shape
+   * docs/standards/queue-ownership.md prescribes - "infrastructure knows them by
+   * that pattern, never by a list of names".
+   *
+   * Every one of them dead-letters over `dlx` to `{service}.dlq`, the queue each
+   * service already has and the one binding d.198a left behind
+   * (api/docs/governance/confirmations/mq-consumer-contract.md 003).
+   *
+   * `{service}.workflow`, `{service}.queue` and `{service}.dlq` are created by
+   * QueueManager.setupServiceQueues(); the registry-client queues by
+   * @onlineapps/conn-orch-registry.
    */
   business: {
     /**
@@ -125,7 +421,7 @@ module.exports = {
       arguments: {
         'x-message-ttl': 300000,      // 5 minutes TTL
         'x-max-length': 10000,        // Max 10k messages
-        'x-dead-letter-exchange': 'dlx',
+        'x-dead-letter-exchange': DEAD_LETTER_EXCHANGE,
         'x-dead-letter-routing-key': '{service}.dlq'  // Placeholder, replaced with actual service name
       }
     },
@@ -139,7 +435,7 @@ module.exports = {
       arguments: {
         'x-message-ttl': 30000,       // 30 seconds TTL
         'x-max-length': 10000,        // Max 10k messages
-        'x-dead-letter-exchange': 'dlx',
+        'x-dead-letter-exchange': DEAD_LETTER_EXCHANGE,
         'x-dead-letter-routing-key': '{service}.dlq'  // Placeholder, replaced with actual service name
       }
     },
@@ -154,6 +450,41 @@ module.exports = {
         // No TTL for DLQ - messages should persist
         'x-max-length': 50000         // Higher limit for DLQ
       }
+    },
+
+    /**
+     * {service}.registry - The service's own queue for registry control messages
+     * (register.confirmed and the rest), asserted by @onlineapps/conn-orch-registry.
+     *
+     * No TTL and no length cap: that is what the queues carry on the broker today
+     * (measured 2026-09-12, every `<service>.registry` reports `arguments = {}`), and
+     * a value invented here would be a second truth about a running queue. What the
+     * template adds is the dead-letter route the queue never had.
+     */
+    registry: {
+      durable: true,
+      arguments: {
+        'x-dead-letter-exchange': DEAD_LETTER_EXCHANGE,
+        'x-dead-letter-routing-key': '{service}.dlq'  // Placeholder, replaced with actual service name
+      }
+    },
+
+    /**
+     * {service}.registry.events - The service's copy of the registry event fanout,
+     * bound to the `registry.changes` exchange by @onlineapps/conn-orch-registry.
+     *
+     * TTL and cap are the ones that connector asserts today, kept to the value, so
+     * moving it onto this template cannot produce a 406 on a queue that already
+     * exists with them.
+     */
+    'registry.events': {
+      durable: true,
+      arguments: {
+        'x-message-ttl': 60000,       // 1 minute TTL - a stale index event is useless
+        'x-max-length': 1000,
+        'x-dead-letter-exchange': DEAD_LETTER_EXCHANGE,
+        'x-dead-letter-routing-key': '{service}.dlq'
+      }
     }
   },
 
@@ -169,7 +500,9 @@ module.exports = {
     retry: {
       durable: true,
       arguments: {
-        'x-max-length': 10000 // Allow up to 10k pending retry messages
+        'x-max-length': 10000, // Allow up to 10k pending retry messages
+        'x-dead-letter-exchange': '',        // Default exchange: routing key IS the queue name
+        'x-dead-letter-routing-key': 'delivery.dlq'
       }
     },
 
@@ -188,7 +521,28 @@ module.exports = {
       durable: true,
       arguments: {
         'x-message-ttl': 60000, // Notifications older than 60s are irrelevant
-        'x-max-length': 10000
+        'x-max-length': 10000,
+        'x-dead-letter-exchange': '',
+        'x-dead-letter-routing-key': 'delivery.dlq'
+      }
+    },
+
+    /**
+     * delivery.dlq - Dead letter queue of the whole delivery family
+     *
+     * Every delivery queue — the dispatcher's retry and websocket queues, and the
+     * four event queues the endpoint consumes — rejects into this one, over the
+     * default exchange, so no binding has to exist for the route to work. Declared
+     * with the arguments every other dead-letter queue carries: durable, capped, no
+     * TTL, no onward route. The operator's dashboard matches `*.dlq`, which is why
+     * the family gets its own queue rather than sharing one with the rest of the
+     * infrastructure (confirmation mq-consumer-contract 003, variant A2 rejected).
+     */
+    dlq: {
+      durable: true,
+      arguments: {
+        // No TTL for DLQ - messages should persist
+        'x-max-length': 50000         // Higher limit for DLQ
       }
     }
   },
@@ -233,6 +587,23 @@ module.exports = {
         'x-message-ttl': 10000,       // 10 seconds TTL (prevent stale data)
         'x-max-length': 1000
       }
+    },
+
+    /**
+     * infrastructure.health.events - Fanout exchange for infrastructure health events
+     *
+     * Registry publishes; the monitoring consumer and the delivery endpoint each bind a
+     * queue of their own (`monitoring.infrastructure.health.events`,
+     * `delivery.health.events`). The name is a contract between THREE sides of one
+     * wire, which is why batch 243g-C removed the per-service env override: an override
+     * on one side loses the events silently. It then left the name as a private
+     * constant in each of the three services, so d.270 gave it an owner here and
+     * `src/index.js` publishes it.
+     */
+    'health.events': {
+      type: 'exchange',
+      exchangeType: 'fanout',
+      durable: true
     }
   },
 
@@ -298,6 +669,56 @@ module.exports = {
       type: 'exchange',
       exchangeType: 'fanout',
       durable: true
+    },
+
+    /**
+     * monitoring.infrastructure.health.events - the monitoring consumer's own copy of
+     * the infrastructure health events, bound to the infrastructure.health.events
+     * fanout exchange. Declared with `durable` and nothing else, exactly as the
+     * consumer creates it.
+     */
+    'infrastructure.health.events': {
+      durable: true
+    }
+  },
+
+  /**
+   * Telemetry queue configurations
+   *
+   * The OpenTelemetry intake of the monitoring consumer: every service publishes
+   * logs, metrics and spans to `telemetry.exchange` with a routing key carrying its
+   * own name, and these three queues are bound to it
+   * (`docs/standards/monitoring-queues.md`, `docs/architecture/monitoring.md`).
+   *
+   * The values are the ones the queues are created with today; this config is their
+   * declaration, so whoever asserts them reads it here rather than retyping it.
+   */
+  telemetry: {
+    /** telemetry.logs.queue - OpenTelemetry log records, drained into Loki. */
+    'logs.queue': {
+      durable: true,
+      arguments: {
+        'x-message-ttl': 60000,       // 1 minute TTL for unprocessed messages
+        'x-max-length': 100000        // Max 100k messages in queue
+      }
+    },
+
+    /** telemetry.metrics.queue - OpenTelemetry metric samples. */
+    'metrics.queue': {
+      durable: true,
+      arguments: {
+        'x-message-ttl': 60000,
+        'x-max-length': 100000
+      }
+    },
+
+    /** telemetry.traces.queue - OpenTelemetry spans. */
+    'traces.queue': {
+      durable: true,
+      arguments: {
+        'x-message-ttl': 60000,
+        'x-max-length': 100000
+      }
     }
   },
 
@@ -314,7 +735,9 @@ module.exports = {
       durable: true,
       arguments: {
         'x-message-ttl': 60000,       // 60s TTL - real-time events, stale ones are useless
-        'x-max-length': 10000
+        'x-max-length': 10000,
+        'x-dead-letter-exchange': '',        // Default exchange: routing key IS the queue name
+        'x-dead-letter-routing-key': 'delivery.dlq'
       }
     },
 
@@ -326,7 +749,9 @@ module.exports = {
       durable: true,
       arguments: {
         'x-message-ttl': 60000,
-        'x-max-length': 5000
+        'x-max-length': 5000,
+        'x-dead-letter-exchange': '',
+        'x-dead-letter-routing-key': 'delivery.dlq'
       }
     },
 
@@ -338,7 +763,33 @@ module.exports = {
       durable: true,
       arguments: {
         'x-message-ttl': 300000,      // 5 minutes - alerts are more important
-        'x-max-length': 5000
+        'x-max-length': 5000,
+        'x-dead-letter-exchange': '',
+        'x-dead-letter-routing-key': 'delivery.dlq'
+      }
+    },
+
+    /**
+     * delivery.resource.events - Resource-changed events for WS clients
+     * Bound to the monitoring.resource exchange by the routing pattern
+     * `resource.changed.#` - the one binding of this family that is not a fanout
+     * (docs/standards/queue-ownership.md).
+     *
+     * The queue has existed on the broker since the endpoint started asserting it
+     * with `{ durable: true }` and nothing else; it was the only queue of the
+     * family this configuration did not declare, so the d.259 gate had nothing to
+     * read for it. The arguments are its sibling's — same TTL, same cap — because
+     * it carries the same kind of real-time event.
+     *
+     * @see api/docs/governance/confirmations/mq-consumer-contract.md 003
+     */
+    'resource.events': {
+      durable: true,
+      arguments: {
+        'x-message-ttl': 60000,
+        'x-max-length': 10000,
+        'x-dead-letter-exchange': '',
+        'x-dead-letter-routing-key': 'delivery.dlq'
       }
     }
   },
@@ -398,6 +849,42 @@ module.exports = {
     }
   },
 
+  /**
+   * The full wire name of a declared entry: the section's prefix + the entry's key.
+   *
+   * Composed here, never retyped by a caller — and never composed from the section
+   * NAME, because a section name is not automatically a prefix (`deliveryEvents`
+   * declares `delivery.` names, `alerts` declares `alert.`). The entry must exist:
+   * a name this configuration does not declare would be asserted against the broker
+   * by whoever imported it, which is how a typo becomes a second queue.
+   *
+   * @param {string} section - Section holding the entry (e.g. 'deliveryEvents').
+   * @param {string} key - The entry's key within that section (e.g. 'health.events').
+   * @returns {string} The full name (e.g. 'delivery.health.events').
+   * @throws {ValidationError} If the section composes no wire name, or the entry is undeclared.
+   */
+  queueName(section, key) {
+    const prefix = SECTION_PREFIXES[section];
+
+    if (prefix === undefined) {
+      throw new ValidationError(
+        `[queueConfig] Cannot compose a name: section "${section}" declares no wire prefix - `
+          + `Expected: one of ${Object.keys(SECTION_PREFIXES).join(', ')}. `
+          + 'Fix: name a section that declares full queue names; "business" holds templates, not names.'
+      );
+    }
+
+    if (!this[section]?.[key]) {
+      throw new ValidationError(
+        `[queueConfig] Cannot compose a name: queueConfig declares no "${key}" under "${section}" - `
+          + `Expected: the entry to exist before its name is published. `
+          + 'Fix: declare it in src/config/queueConfig.js, or use the key the owning service declares.'
+      );
+    }
+
+    return `${prefix}.${key}`;
+  },
+
   /**
    * Get infrastructure queue configuration by type and name
    * @param {string} type - Queue type: 'workflow', 'registry'
@@ -407,7 +894,11 @@ module.exports = {
   getQueueConfig(type, name) {
     const config = this[type]?.[name];
     if (!config) {
-      throw new Error(`Infrastructure queue config not found: ${type}.${name}`);
+      throw new ValidationError(
+        `[queueConfig] Infrastructure queue config not found: ${type}.${name} - `
+          + `Expected: queueConfig to define the "${name}" entry under "${type}". `
+          + waysOut(this.business, `${type}.${name}`)
+      );
     }
 
     // Deep clone to avoid modifying original
@@ -422,7 +913,10 @@ module.exports = {
   getWorkflowQueueConfig(queueName) {
     const parts = queueName.split('.');
     if (parts.length !== 2 || parts[0] !== 'workflow') {
-      throw new Error(`Invalid workflow queue name: ${queueName}. Expected format: workflow.{name}`);
+      throw new ValidationError(
+        `[queueConfig] Invalid workflow queue name: ${queueName}. Expected format: workflow.{name} - `
+          + 'Fix: pass exactly two dot-separated parts whose first part is "workflow", e.g. "workflow.init".'
+      );
     }
     return this.getQueueConfig('workflow', parts[1]);
   },
@@ -435,37 +929,103 @@ module.exports = {
   getRegistryQueueConfig(queueName) {
     const parts = queueName.split('.');
     if (parts.length !== 2 || parts[0] !== 'registry') {
-      throw new Error(`Invalid registry queue name: ${queueName}. Expected format: registry.{name}`);
+      throw new ValidationError(
+        `[queueConfig] Invalid registry queue name: ${queueName}. Expected format: registry.{name} - `
+          + 'Fix: pass exactly two dot-separated parts whose first part is "registry", e.g. "registry.register".'
+      );
     }
     return this.getQueueConfig('registry', parts[1]);
   },
 
   /**
-   * Check if queue name is an infrastructure queue
+   * 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.
+   * @returns {ReadonlyArray<string>} Prefixes WITHOUT the trailing dot.
+   */
+  infrastructurePrefixes() {
+    return INFRASTRUCTURE_PREFIXES;
+  },
+
+  /**
+   * Check if queue name is an infrastructure queue.
+   *
+   * Three questions, in this order, because a prefix alone answers the wrong one:
+   *
+   * 1. **Does an infrastructure section declare this exact name?** Then it is
+   *    infrastructure, whatever else it resembles — the declaration is the platform's
+   *    own statement about that queue (`workflow.dlq`, `delivery.dlq`).
+   * 2. **Does it match a business template?** Then a service owns it. `registry` is a
+   *    legal service name — `docs/biz/60-templates/naming.md` § Infrastructure Services
+   *    gives it as the example — and the service by that name has `registry.workflow`,
+   *    `registry.queue` and `registry.dlq` on the broker today, with exactly the
+   *    arguments the templates prescribe (measured 2026-09-13). Before d.279 the
+   *    `registry.` prefix claimed them for the platform, the registry lookup then had no
+   *    entry for `queue`/`workflow`/`dlq`, and so `getDeadLetterRoute()` threw for a
+   *    queue whose route is declared — which the d.259 consume gate reads as "no route",
+   *    refusing the owner's own consumer.
+   * 3. **Otherwise, does it carry an infrastructure prefix?** Then it is infrastructure
+   *    TERRITORY: declared nowhere, but a publisher must still refuse to auto-create it
+   *    with default arguments rather than treat it as an ordinary name
+   *    (`rabbitmqClient.js`, the 404 branch). The lookup that owns the prefix is what
+   *    reports the missing declaration.
+   *
    * @param {string} queueName - Queue name to check
    * @returns {boolean} True if infrastructure queue
    */
   isInfrastructureQueue(queueName) {
-    return queueName.startsWith('workflow.') ||
-           queueName.startsWith('registry.') ||
-           queueName.startsWith('infrastructure.') ||
-           queueName.startsWith('validation.') ||
-           queueName.startsWith('monitoring.') ||
-           queueName.startsWith('telemetry.') ||
-           queueName.startsWith('delivery.');
+    if (declaredInfrastructureNames(this).has(queueName)) {
+      return true;
+    }
+
+    if (matchBusinessTemplate(this.business, queueName) !== null) {
+      return false;
+    }
+
+    return INFRASTRUCTURE_PREFIXES.some((prefix) => queueName.startsWith(`${prefix}.`));
   },
 
   /**
-   * Get delivery queue configuration
-   * @param {string} queueName - Queue name (e.g., 'delivery.retry')
+   * Get delivery queue configuration.
+   *
+   * The `delivery.` prefix is declared by TWO sections — `delivery` (queues the
+   * dispatcher owns) and `deliveryEvents` (queues the delivery endpoint consumes) —
+   * so the lookup searches both. Which section holds a name is authoring history;
+   * the prefix is what travels on the wire, and a caller knows only that.
+   *
+   * @param {string} queueName - Queue name (e.g., 'delivery.retry', 'delivery.health.events')
    * @returns {Object} Queue configuration
+   * @throws {ValidationError} If no section declares the name, or — a defect, not a
+   *   runtime condition — if more than one does.
    */
   getDeliveryQueueConfig(queueName) {
     if (!queueName.startsWith('delivery.')) {
-      throw new Error(`Queue ${queueName} is not a delivery queue`);
+      throw new ValidationError(
+        `[queueConfig] Queue ${queueName} is not a delivery queue - Expected: a name starting with "delivery.". `
+          + 'Fix: call getInfrastructureQueueConfig(), which routes each prefix to the right lookup.'
+      );
+    }
+    const name = queueName.slice('delivery.'.length);
+    const sections = DELIVERY_SECTIONS.filter((section) => this[section]?.[name]);
+
+    if (sections.length > 1) {
+      throw new ValidationError(
+        `[queueConfig] Delivery queue ${queueName} is declared in more than one section: ${sections.join(', ')} - `
+          + 'Expected: exactly one section declares a name, so one queue has one definition. '
+          + 'Fix: delete the duplicate entry in src/config/queueConfig.js.'
+      );
+    }
+
+    if (sections.length === 0) {
+      throw new ValidationError(
+        `[queueConfig] Infrastructure queue config not found: ${queueName} - `
+          + `Expected: queueConfig to define the "${name}" entry under one of the delivery sections `
+          + `(${DELIVERY_SECTIONS.join(', ')}). `
+          + waysOut(this.business, queueName)
+      );
     }
-    const name = queueName.replace('delivery.', '');
-    return this.getQueueConfig('delivery', name);
+
+    return this.getQueueConfig(sections[0], name);
   },
 
   /**
@@ -475,39 +1035,48 @@ module.exports = {
    */
   getValidationQueueConfig(queueName) {
     if (!queueName.startsWith('validation.')) {
-      throw new Error(`Queue ${queueName} is not a validation queue`);
+      throw new ValidationError(
+        `[queueConfig] Queue ${queueName} is not a validation queue - Expected: a name starting with "validation.". `
+          + 'Fix: call getInfrastructureQueueConfig(), which routes each prefix to the right lookup.'
+      );
     }
     const name = queueName.replace('validation.', '');
     return this.getQueueConfig('validation', name);
   },
 
   /**
-   * Check if queue name is a business queue
+   * Check if queue name is a business queue - a queue a business service OWNS.
+   *
+   * Answered from the templates the `business` section declares, so the classifier
+   * and the arguments can never disagree: `{service}.workflow`, `{service}.queue`,
+   * `{service}.dlq` and the two registry-client queues.
+   *
    * @param {string} queueName - Queue name to check
    * @returns {boolean} True if business queue
    */
   isBusinessQueue(queueName) {
-    // Business queues follow pattern: {service}.{type}
-    // where type is: workflow, queue, dlq
-    const parts = queueName.split('.');
-    if (parts.length !== 2) return false;
-    return ['workflow', 'queue', 'dlq'].includes(parts[1]);
+    return this.parseBusinessQueue(queueName) !== null;
   },
 
   /**
    * Parse business queue name to extract service name and queue type
+   *
+   * A name an infrastructure section DECLARES is never a business queue, however well
+   * it fits a template: `workflow.dlq`, `delivery.dlq` and `monitoring.workflow` all
+   * match one, and all three are declared platform queues. Until d.279 both classifiers
+   * answered `true` for them, so which arguments such a queue got was decided by the
+   * order of branches in whichever caller asked.
+   *
    * @param {string} queueName - Business queue name (e.g., 'hello-service.workflow')
-   * @returns {Object} { serviceName, queueType } or null if not a business queue
+   * @returns {{serviceName: string, queueType: string}|null} The service and the
+   *   template key to pass to getBusinessQueueConfig(), or null if not a business queue
    */
   parseBusinessQueue(queueName) {
-    if (!this.isBusinessQueue(queueName)) {
+    if (declaredInfrastructureNames(this).has(queueName)) {
       return null;
     }
-    const parts = queueName.split('.');
-    return {
-      serviceName: parts[0],
-      queueType: parts[1]
-    };
+
+    return matchBusinessTemplate(this.business, queueName);
   },
 
   /**
@@ -519,7 +1088,12 @@ module.exports = {
   getBusinessQueueConfig(queueType, serviceName) {
     const template = this.business?.[queueType];
     if (!template) {
-      throw new Error(`Business queue template not found: ${queueType}`);
+      throw new ValidationError(
+        `[queueConfig] Business queue template not found: ${queueType} - `
+          + `Expected: one of the declared business queue templates (${Object.keys(this.business).join(', ')}). `
+          + 'Fix: pass a declared template key - parseBusinessQueue() returns it for any business queue name - '
+          + 'or add the template to the `business` section of src/config/queueConfig.js.'
+      );
     }
 
     // Deep clone to avoid modifying original
@@ -544,7 +1118,10 @@ module.exports = {
   getInfrastructureHealthQueueConfig(queueName) {
     const parts = queueName.split('.');
     if (parts.length < 2 || parts[0] !== 'infrastructure') {
-      throw new Error(`Invalid infrastructure health queue name: ${queueName}. Expected format: infrastructure.{name}`);
+      throw new ValidationError(
+        `[queueConfig] Invalid infrastructure health queue name: ${queueName}. Expected format: infrastructure.{name} - `
+          + 'Fix: pass at least two dot-separated parts whose first part is "infrastructure", e.g. "infrastructure.health.checks".'
+      );
     }
     const name = parts.slice(1).join('.');
     return this.getQueueConfig('infrastructure', name);
@@ -557,32 +1134,213 @@ module.exports = {
    */
   getMonitoringQueueConfig(queueName) {
     if (!queueName.startsWith('monitoring.')) {
-      throw new Error(`Queue ${queueName} is not a monitoring queue`);
+      throw new ValidationError(
+        `[queueConfig] Queue ${queueName} is not a monitoring queue - Expected: a name starting with "monitoring.". `
+          + 'Fix: call getInfrastructureQueueConfig(), which routes each prefix to the right lookup.'
+      );
     }
     const name = queueName.replace('monitoring.', '');
     return this.getQueueConfig('monitoring', name);
   },
 
+  /**
+   * Get telemetry queue configuration
+   * @param {string} queueName - Queue name (e.g., 'telemetry.logs.queue')
+   * @returns {Object} Queue configuration
+   */
+  getTelemetryQueueConfig(queueName) {
+    if (!queueName.startsWith('telemetry.')) {
+      throw new ValidationError(
+        `[queueConfig] Queue ${queueName} is not a telemetry queue - Expected: a name starting with "telemetry.". `
+          + 'Fix: call getInfrastructureQueueConfig(), which routes each prefix to the right lookup.'
+      );
+    }
+    const name = queueName.slice('telemetry.'.length);
+    return this.getQueueConfig('telemetry', name);
+  },
+
+  /**
+   * The COMPLETE declaration a queue is brought into being with — `durable` and
+   * every argument, dead-letter route included.
+   *
+   * 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
+   * `_prepareQueueForConsume()`.
+   *
+   * Until d.410 those two worked the same three lines out separately —
+   * `{ durable: cfg.durable !== false, arguments: { ...cfg.arguments } }`, once
+   * per path — and the consumer then declared on the raw queue channel instead of
+   * the public rail. Two implementations of one concern
+   * (`change-discipline.md` § One rail per concern). They agreed on the config of
+   * the day, so nothing failed; what they cost is the guarantee: edit one copy and
+   * the other keeps declaring the old arguments, and whichever declarer the broker
+   * hears second is answered `406 PRECONDITION_FAILED` — the exact failure the
+   * central config exists to prevent, and the one a service hits at boot, when its
+   * consumer meets a queue somebody else already declared differently.
+   *
+   * Ownership is NOT decided here. This answers only "what does the declaration
+   * say", never "who may declare it": the publish path still refuses to create an
+   * infrastructure or business queue (`docs/standards/queue-ownership.md`), and
+   * the consumer still CHECKS an infrastructure queue rather than asserting it.
+   *
+   * @param {string} queueName - Full queue name.
+   * @returns {{durable: boolean, arguments: Object}|null} A fresh copy of the
+   *   declaration, or `null` when no section declares this name — there is no
+   *   declaration to hand out, and the caller that needs one says so itself.
+   * @throws {ValidationError} If the name belongs to a section that has no entry
+   *   for it. A missing DEFINITION is reported by the lookup that owns it, never
+   *   flattened into "nothing declares it" — same contract as
+   *   `getDeadLetterRoute()` below.
+   */
+  declarationOptions(queueName) {
+    let config;
+
+    if (this.isInfrastructureQueue(queueName)) {
+      config = this.getInfrastructureQueueConfig(queueName);
+    } else if (this.isBusinessQueue(queueName)) {
+      const parsed = this.parseBusinessQueue(queueName);
+      config = this.getBusinessQueueConfig(parsed.queueType, parsed.serviceName);
+    } else {
+      return null;
+    }
+
+    return {
+      durable: config.durable !== false,
+      arguments: { ...config.arguments }
+    };
+  },
+
+  /**
+   * The dead-letter route this configuration declares for a queue.
+   *
+   * The DECLARATION is the only source of truth available on the consumer path.
+   * The broker cannot be asked: AMQP answers `checkQueue()` with `queue.declare-ok`,
+   * which carries `{ queue, messageCount, consumerCount }` and no arguments at all
+   * (measured against the live broker, 2026-09-12), so a consumer has no way to
+   * read a running queue's `x-dead-letter-*` over the channel it consumes on.
+   * Whoever declares a queue here declares its route here.
+   *
+   * A route is BOTH parts. With `x-dead-letter-exchange: ''` — the default
+   * exchange, which the shared workflow queues use — the routing key IS the
+   * destination queue name, so a declaration without it would send a rejected
+   * message back to the queue it came from: a loop, not a dead-letter route.
+   *
+   * @param {string} queueName - Full queue name.
+   * @returns {{exchange: string, routingKey: string}|null} The declared route, or
+   *   `null` when this configuration declares none — including a name no section
+   *   classifies, such as a temporary `rpc.reply.*` queue.
+   * @throws {ValidationError} If the name belongs to a section that has no entry
+   *   for it. A missing DEFINITION is reported by the lookup that owns it, never
+   *   flattened into "declares no route".
+   */
+  getDeadLetterRoute(queueName) {
+    let args;
+
+    if (this.isInfrastructureQueue(queueName)) {
+      args = this.getInfrastructureQueueConfig(queueName).arguments;
+    } else if (this.isBusinessQueue(queueName)) {
+      const parsed = this.parseBusinessQueue(queueName);
+      args = this.getBusinessQueueConfig(parsed.queueType, parsed.serviceName).arguments;
+    } else {
+      return null;
+    }
+
+    if (args === null || typeof args !== 'object') {
+      return null;
+    }
+
+    const exchange = args['x-dead-letter-exchange'];
+    const routingKey = args['x-dead-letter-routing-key'];
+
+    if (typeof exchange !== 'string' || typeof routingKey !== 'string' || routingKey === '') {
+      return null;
+    }
+
+    return { exchange, routingKey };
+  },
+
+  /**
+   * Is this queue the END of a dead-letter chain — a queue something
+   * dead-letters TO?
+   *
+   * 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`;
+   * `{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
+   * leaves them without one (`docs/governance/confirmations/mq-consumer-contract.md`
+   * 002 point 2, 003 point 2 — "workflow.failed and workflow.dlq themselves keep
+   * no route").
+   *
+   * The consumer's dead-letter gate reads this second question, so a terminal
+   * queue is consumable while every OTHER queue with no declared route stays
+   * refused (`transports/rabbitmqClient.js`, d.452). What happens to a message
+   * that fails there is unchanged and stated in the README: the budget is spent,
+   * `nack(requeue=false)` is issued, the broker DROPS the message — the end of the
+   * chain is the end — and the loss is logged as an error rather than turned into
+   * an endless requeue.
+   *
+   * Derived from the templates (`declaredDeadLetterTargets()`), never from a list
+   * of names: a `{placeholder}` segment matches any one part, exactly as a
+   * business template key does.
+   *
+   * @param {string} queueName - Full queue name.
+   * @returns {boolean} True if this configuration dead-letters to this name.
+   */
+  isDeadLetterTarget(queueName) {
+    if (typeof queueName !== 'string' || queueName === '') return false;
+
+    const parts = queueName.split('.');
+
+    for (const target of declaredDeadLetterTargets(this)) {
+      const shape = templateShape(target);
+      if (shape.length !== parts.length) continue;
+      if (shape.every((part, index) => (part === null ? parts[index] !== '' : part === parts[index]))) {
+        return true;
+      }
+    }
+
+    return false;
+  },
+
   /**
    * Get infrastructure queue configuration by queue name (auto-detect type)
+   *
+   * The prefix decides the lookup, read from `INFRASTRUCTURE_PREFIX_LOOKUPS` — the
+   * same map `isInfrastructureQueue()` classifies by, so the two can never disagree.
+   *
    * @param {string} queueName - Full queue name (e.g., 'workflow.init', 'registry.register', 'infrastructure.health.checks', 'monitoring.workflow')
    * @returns {Object} Queue configuration
    */
   getInfrastructureQueueConfig(queueName) {
-    if (queueName.startsWith('workflow.')) {
-      return this.getWorkflowQueueConfig(queueName);
-    } else if (queueName.startsWith('registry.')) {
-      return this.getRegistryQueueConfig(queueName);
-    } else if (queueName.startsWith('infrastructure.')) {
-      return this.getInfrastructureHealthQueueConfig(queueName);
-    } else if (queueName.startsWith('monitoring.')) {
-      return this.getMonitoringQueueConfig(queueName);
-    } else if (queueName.startsWith('validation.')) {
-      return this.getValidationQueueConfig(queueName);
-    } else if (queueName.startsWith('delivery.')) {
-      return this.getDeliveryQueueConfig(queueName);
-    } else {
-      throw new Error(`Queue ${queueName} is not an infrastructure queue. Infrastructure queues must start with 'workflow.', 'registry.', 'infrastructure.', or 'monitoring.'`);
+    const prefix = INFRASTRUCTURE_PREFIXES.find((candidate) => queueName.startsWith(`${candidate}.`));
+
+    if (prefix === undefined) {
+      throw new ValidationError(
+        `[queueConfig] Queue ${queueName} is not an infrastructure queue. Infrastructure queues must start with `
+          + `${INFRASTRUCTURE_PREFIXES.map((name) => `'${name}.'`).join(', ')} - `
+          + 'Fix: use isBusinessQueue()/getBusinessQueueConfig() for a service-owned queue, or correct the prefix.'
+      );
     }
+
+    return this[INFRASTRUCTURE_PREFIX_LOOKUPS[prefix]](queueName);
+  },
+
+  /**
+   * The platform's dead-letter exchange, as the one thing to import instead of
+   * the literal.
+   *
+   * Every business template routes here (`x-dead-letter-exchange`), and so does
+   * `getDeadLetterRoute()` for a business queue. `@onlineapps/conn-infra-mq` binds
+   * `<service>.dlq` to it and had to read the name back out of a queue's arguments
+   * for want of an export.
+   *
+   * @returns {string}
+   */
+  deadLetterExchange() {
+    return DEAD_LETTER_EXCHANGE;
   }
 };