@onlineapps/mq-client-core 4.1.0 → 5.0.0

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

@@ -61,7 +61,12 @@ const SECTION_PREFIXES = Object.freeze({
   telemetry: 'telemetry',
   alerts: 'alert',
   registry: 'registry',
-  scheduler: 'scheduler'
+  scheduler: 'scheduler',
+  // The one section whose names travel WITHOUT a prefix: `dlx` is the wire name every
+  // business queue dead-letters to (`x-dead-letter-exchange`), and renaming it would
+  // re-declare live topology. The empty prefix is a declared case, read explicitly by
+  // `queueName()`; a section absent from this map is still refused (d.902).
+  deadLetter: ''
 });
 
 /**
@@ -124,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('.');
@@ -140,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;
 };
 
 /**
@@ -272,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.
      *
@@ -487,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
+      }
     }
   },
 
@@ -629,10 +659,17 @@ module.exports = {
     /**
      * monitoring.workflow - Unified workflow lifecycle monitoring
      * Bound to monitoring.workflow.fanout exchange (fanout).
-     * Delivery Dispatcher publishes 'completed'/'failed' events after processing workflow.completed/workflow.failed
-     * Business services publish 'progress' events during workflow step processing
-     * Message format includes event_type: 'completed' | 'failed' | 'progress'
-     * Includes full cookbook and context snapshots for trace storage
+     *
+     * WHO publishes onto that fanout: the Delivery Dispatcher after it processes a terminal
+     * workflow message, the in-process orchestrator during a run, and this client's own
+     * dead-letter hook. WHICH event_type each of them sends is not written here - the
+     * vocabulary has one owner and it grows, so a list copied into this comment would be a
+     * hand-written descriptive fact that ages in silence
+     * (`.claude/rules/doc-code-binding.md` §1).
+     *
+     * The message carries the cookbook and the context snapshot the trace store keeps.
+     *
+     * @see api/docs/biz/70-contracts/monitoring-events.md
      */
     'workflow': {
       durable: true,
@@ -646,15 +683,20 @@ module.exports = {
 
     /**
      * monitoring.services - Service lifecycle events monitoring
-     * Registry publishes service lifecycle events (registered, validation.completed, version.changed, status.changed)
-     * InfrastructureHealthTracker publishes service status changes
-     * Message format includes event_type: 'service.registered' | 'service.validation.completed' | 
-     *   'service.version.changed' | 'service.deregistered' | 'service.status.changed'
+     *
+     * WHO publishes here: the Registry, which owns the service lifecycle, and the
+     * InfrastructureHealthTracker with service status changes. WHICH event_type each of them
+     * sends is not written here — that vocabulary has one owner and it grows, and a list
+     * copied into this comment would be a hand-written descriptive fact that ages in silence
+     * (`.claude/rules/doc-code-binding.md` §1).
+     *
      * NOTE: Heartbeats are NOT published here - they are too frequent. The cadence
      *   is not a number this file owns: see the `heartbeatInterval` constructor option
      *   of RegistryClient (@onlineapps/conn-orch-registry), which ServiceWrapper feeds
      *   from BIZ_HEARTBEAT_INTERVAL_MS.
      * NOTE: Healthcheck messages go to infrastructure.health.events exchange
+     *
+     * @see api/docs/biz/70-contracts/monitoring-events.md
      */
     'services': {
       durable: true,
@@ -749,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
@@ -830,7 +873,7 @@ module.exports = {
     'logs.queue': {
       durable: true,
       arguments: {
-        'x-message-ttl': 60000,       // 1 minute TTL for unprocessed messages
+        'x-message-ttl': 300000,      // 5 min — okno deploye bez konzumenta; conf telemetry-queue-ttl 001
         'x-max-length': 100000,       // Max 100k messages in queue
         'x-dead-letter-exchange': '',        // Default exchange: routing key IS the queue name
         'x-dead-letter-routing-key': 'telemetry.dlq'
@@ -841,7 +884,7 @@ module.exports = {
     'metrics.queue': {
       durable: true,
       arguments: {
-        'x-message-ttl': 60000,
+        'x-message-ttl': 300000, // 5 min — okno deploye bez konzumenta; conf telemetry-queue-ttl 001
         'x-max-length': 100000,
         'x-dead-letter-exchange': '',
         'x-dead-letter-routing-key': 'telemetry.dlq'
@@ -852,7 +895,7 @@ module.exports = {
     'traces.queue': {
       durable: true,
       arguments: {
-        'x-message-ttl': 60000,
+        'x-message-ttl': 300000, // 5 min — okno deploye bez konzumenta; conf telemetry-queue-ttl 001
         'x-max-length': 100000,
         'x-dead-letter-exchange': '',
         'x-dead-letter-routing-key': 'telemetry.dlq'
@@ -1075,12 +1118,17 @@ module.exports = {
      *
      * The third queue bound to `monitoring.workflow.fanout`, beside `monitoring.workflow`
      * and `delivery.workflow.events`. The owner settled it in
-     * `docs/governance/confirmations/scheduler.md` 007: the terminal event of a run
-     * (`completed` / `failed` / `discarded`) already 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 DECLARES what that queue is.
+     * `docs/governance/confirmations/scheduler.md` 007: the terminal event of a run already
+     * 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` 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
+     * it grows. A list copied into this comment would be a hand-written descriptive fact that
+     * ages in silence (`.claude/rules/doc-code-binding.md` §1).
      *
      * THE TTL IS STATED, NOT INHERITED, and it is a property of that decision rather than a
      * default: a fanout cannot filter, so this queue receives EVERY workflow event of the
@@ -1096,6 +1144,7 @@ module.exports = {
      * `CONSUMER_DEAD_LETTER_ROUTE_MISSING`; `mq-consumer-contract` 002).
      *
      * @see api/docs/governance/confirmations/scheduler.md 007
+     * @see api/docs/biz/70-contracts/monitoring-events.md
      */
     'workflow.events': {
       durable: true,
@@ -1123,6 +1172,31 @@ module.exports = {
     }
   },
 
+  /**
+   * The platform's dead-letter exchange, DECLARED — name, type and durability.
+   *
+   * Every business template dead-letters here (`x-dead-letter-exchange`), and
+   * `@onlineapps/conn-infra-mq` `QueueManager.setupServiceQueues()` brings it into
+   * being as a durable `direct` exchange before binding `{service}.dlq` to it. The
+   * broker compares type and durability at EVERY `assertExchange`, so they belong to
+   * the declaration, where a second reader — `api/scripts/ci/declare-broker-exchanges.mjs`,
+   * which declares exchanges on a CI broker nobody's services booted against — finds
+   * them through the same loop as every other exchange of this file, instead of keeping
+   * a copy of the founder's line (TODO INFRA 349, d.902).
+   *
+   * Its wire name carries no prefix (`SECTION_PREFIXES.deadLetter` is `''`), and the key
+   * is the one constant at the top of this file, so the name has one spelling.
+   * An exchange holds nothing to dead-letter, so — like every other exchange here — it
+   * carries no route.
+   */
+  deadLetter: {
+    [DEAD_LETTER_EXCHANGE]: {
+      type: 'exchange',
+      exchangeType: 'direct',
+      durable: true
+    }
+  },
+
   /**
    * The full wire name of a declared entry: the section's prefix + the entry's key.
    *
@@ -1132,9 +1206,13 @@ module.exports = {
    * 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.
    *
+   * A section whose declared prefix is `''` (`deadLetter`) composes the bare key: its
+   * names travel without a prefix. That is a value of the map, not a default — a
+   * section missing from it is refused below.
+   *
    * @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').
+   * @returns {string} The full name (e.g. 'delivery.health.events'; the bare key for 'deadLetter').
    * @throws {ValidationError} If the section composes no wire name, or the entry is undeclared.
    */
   queueName(section, key) {
@@ -1156,7 +1234,7 @@ module.exports = {
       );
     }
 
-    return `${prefix}.${key}`;
+    return prefix === '' ? key : `${prefix}.${key}`;
   },
 
   /**
@@ -1213,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() {
@@ -1456,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 —
@@ -1558,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
@@ -1627,11 +1707,12 @@ module.exports = {
    * 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.
+   * for want of an export. Composed from the `deadLetter` entry, which also declares
+   * the exchange's type and durability — one declaration, not a name beside it.
    *
    * @returns {string}
    */
   deadLetterExchange() {
-    return DEAD_LETTER_EXCHANGE;
+    return this.queueName('deadLetter', DEAD_LETTER_EXCHANGE);
   }
 };

package/src/config/recurrencesSchema.js

@@ -0,0 +1,121 @@
+'use strict';
+
+/**
+ * recurrencesSchema.js
+ *
+ * JSON Schema used by Ajv (in `src/scheduler-request.js`) to validate the recurrences a service
+ * declares about itself.
+ *
+ * WHY THE SHAPE LIVES HERE. `docs/architecture/scheduler.md` §7 has the wrapper register a
+ * service's recurrences at boot — "idempotent, so every boot re-asserts the declared state" —
+ * and the service answers with them through ONE hook, platform ones as a constant list and
+ * tenant ones derived from its own data (confirmation `scheduler` 011). The shape of a record
+ * is the library's; where the record comes from is not. One owner of the shape means every service's file is the
+ * same file, and the wrapper reading it never has to guess.
+ *
+ * WHAT THE FILE DOES NOT CARRY, and why that is a rule rather than an omission:
+ *
+ *   - **`tenant_id` and `workspace_id`.** They travel beside the record, not in it: the
+ *     builder takes them as `tenantId` and `workspaceId`, and the caller supplies them with
+ *     every recurrence — the service knows them from its own data, and nothing reads them from
+ *     the environment or defaults them.
+ *     @see api/docs/governance/confirmations/scheduler.md 002, 010
+ *   - **`requested_by`.** It is the service that declared the record; the caller passes the name
+ *     it already knows, so a record cannot disagree with the service that answered it.
+ *
+ * `additionalProperties: false` at both levels, deliberately: the consumer's own contract
+ * (`api/infra/api_scheduler/contracts/scheduler.request.schema.json`) closes its keys the same
+ * way, so a key accepted here and refused there would turn a boot into a dead-lettered
+ * request nobody reads.
+ *
+ * @see ../scheduler-request.js — the shape check, the builders and the send
+ * @see api/docs/architecture/scheduler.md §4, §7
+ */
+
+/**
+ * Five whitespace-separated fields — the same expression the scheduler's contract takes
+ * (`recurrence.cron`, pattern `^\S+( \S+){4}$`). Whether those fields describe a reachable
+ * instant is the tick engine's answer, not this file's.
+ */
+const CRON_PATTERN = '^\\S+( \\S+){4}$';
+
+/**
+ * The id of one schedule: it becomes `idempotency_key`, so it is a name, not a sentence.
+ *
+ * As WIDE as the consumer's own rule and no wider: the scheduler takes any string of 1–255
+ * characters for that key, so this file refuses only what would make the key a sentence —
+ * whitespace. The narrower spelling this schema first carried (lower-case letters and dashes)
+ * was the library being stricter than the contract for no reason, and it refused the very
+ * convention the first caller uses: `<source_uuid>:<cookbook_ref>` (BIZ-ingest, 2026-09-23).
+ */
+const ID_PATTERN = '^\\S+$';
+
+const recurrencesSchema = {
+  $schema: 'http://json-schema.org/draft-07/schema#',
+  $id: 'https://onlineapps.cz/schemas/mq-client-core/recurrences.v1.schema.json',
+  title: 'Service recurrence declaration',
+  description:
+    'What a service declares about its own recurring runs. The wrapper re-asserts every record '
+    + 'at boot as a `scheduler.request` of kind `recurring`.',
+  type: 'object',
+  additionalProperties: false,
+  required: ['recurrences'],
+  properties: {
+    recurrences: {
+      description:
+        'Every recurrence this service owns. An empty list is a valid declaration of nothing, '
+        + 'and a service with no recurrences may answer one.',
+      type: 'array',
+      items: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['id', 'cookbook_ref', 'cron', 'timezone'],
+        properties: {
+          id: {
+            description:
+              'Stable id of THIS schedule; it travels as `idempotency_key`, so re-registration '
+              + 'upserts instead of creating a second schedule.',
+            type: 'string',
+            minLength: 1,
+            maxLength: 255,
+            pattern: ID_PATTERN
+          },
+          cookbook_ref: {
+            description:
+              'Id of the cookbook to run. Its `triggers` must name this service and the kind '
+              + '`recurring`, or the scheduler refuses the request (confirmation scheduler 004).',
+            type: 'string',
+            minLength: 1,
+            maxLength: 255
+          },
+          cron: {
+            description: 'Cron expression, five fields.',
+            type: 'string',
+            pattern: CRON_PATTERN
+          },
+          timezone: {
+            description: 'IANA zone, explicit. No implicit zone exists (scheduler.md §4).',
+            type: 'string',
+            minLength: 1,
+            maxLength: 64
+          },
+          input: {
+            description:
+              'Input handed to the cookbook unchanged. Present only where the run needs one — '
+              + 'a scheduled import that writes says so here, while the same cookbook run by hand '
+              + 'can be given a different input.',
+            type: 'object'
+          },
+          catch_up: {
+            description:
+              'Whether a missed window runs once when the scheduler comes back. Absent means '
+              + 'false, and the scheduler materialises that default — this file does not.',
+            type: 'boolean'
+          }
+        }
+      }
+    }
+  }
+};
+
+module.exports = { recurrencesSchema, CRON_PATTERN, ID_PATTERN };

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