@onlineapps/conn-orch-registry 6.0.3 → 8.0.0

package/src/registryClient.js

@@ -35,6 +35,20 @@ const { queueConfig } = require('@onlineapps/mq-client-core');
 const DEFAULTS = require('./defaults');
 const { assertLogger } = require('@onlineapps/logger-contract');
 
+/**
+ * The two ways a discovery read can fail that say nothing about the answer — the
+ * projection did not answer in time, or the client already knows Redis is gone. Both
+ * are typed HERE, where the failure is known, as `TRANSIENT` (d.1093; the pattern
+ * mq-client-core uses since d.683: a bare error from the transport is typed by the
+ * site that receives it, `src/utils/publishErrors.js` `TransientPublishError`). The
+ * L1 classifier reads `type` and never learns what Redis is; cookbook-router carries
+ * `type` from `cause` onto `SERVICE_DISCOVERY_FAILED`.
+ */
+const DISCOVERY_FAILURE_CODES = Object.freeze({
+  timeout: 'REGISTRY_DISCOVERY_TIMEOUT',
+  unavailable: 'REGISTRY_DISCOVERY_UNAVAILABLE'
+});
+
 /**
  * Keys `register()` REFUSES, with the reason the caller needs to act on
  * (d.562, extended by d.592).
@@ -68,6 +82,38 @@ const RETIRED_SERVICE_INFO_KEYS = Object.freeze({
     + 'destructure it, so deployability is read from that CI job and never from a registration message'
 });
 
+/**
+ * The keys `register()` ACCEPTS — the whole input contract of the call (d.702).
+ *
+ * It is the caller's half of `api/docs/biz/30-operations/registration-wire.md`
+ * §2.1: the five register-message fields a CALLER supplies, plus `timeout`, which
+ * is this call's own response budget and reaches no message. The rest of §2.1
+ * (`id`, `type`, `serviceName`, `version`, `specificationEndpoint`,
+ * `responseQueue`, `timestamp`, `validationProof`, `validationData`) is client
+ * state bound in the constructor, never caller input — a caller cannot set it and
+ * this table must not invite one to try.
+ *
+ * Any other key is refused BY NAME, for the same reason the table above exists:
+ * until d.702 `register()` refused six retired keys and dropped everything else in
+ * silence, so `helth`, `current_step` or `name` bought a confirmed registration
+ * whose message never carried the value. A key silently dropped leaves the caller
+ * believing something travelled, and a typo in an optional key is exactly the
+ * shape nobody notices (`architecture-principles.md` §3 no fallbacks, §4
+ * fail-fast).
+ *
+ * `RETIRED_SERVICE_INFO_KEYS` is the subset that can still say WHY the key went;
+ * ONE membership check reads both tables, so there is no second list to drift
+ * (`.claude/rules/change-discipline.md` § One rail per concern).
+ */
+const ACCEPTED_SERVICE_INFO_KEYS = Object.freeze({
+  endpoints: 'the `endpoints` array of the register message (§2.1); `[]` for every v3 service',
+  operations: 'the complete `operations` map the registry validates (§3)',
+  metadata: 'the `{ version, description }` object stored beside the spec (§2.1)',
+  health: 'the legacy health path of the register message; liveness travels by heartbeat (§2.2)',
+  workspaceScoped: 'the boolean emitted only when the service declares it (§2.1)',
+  timeout: 'how long THIS call waits for the registry verdict; it reaches no message'
+});
+
 
 class ServiceRegistryClient extends EventEmitter {
   /**
@@ -82,12 +128,19 @@ class ServiceRegistryClient extends EventEmitter {
    * @param {number} opts.heartbeatInterval - Milliseconds between heartbeats. REQUIRED: the
    *   cadence has ONE owner and it is not a library default (owner confirmation
    *   docs/governance/confirmations/biz-health-freshness.md 001 point 3); ServiceWrapper
-   *   passes `wrapper.registry.heartbeatInterval`, itself fed from BIZ_HEARTBEAT_INTERVAL_MS.
+   *   reads it from the environment key BIZ_HEARTBEAT_INTERVAL_MS and passes it here. The
+   *   config key `wrapper.registry.heartbeatInterval` is retired and the wrapper refuses it.
    * @param {string} [opts.apiQueue='api_services_queuer'] - Queue name for heartbeat and API traffic
    * @param {string} [opts.registryQueue='registry.register'] - Queue name for registry messages
    * @param {Object} [opts.validationProof=null] - Validation proof object {hash, data} (injected from outside)
    * @param {number} [opts.registrationTimeoutMs] - How long register() waits for the registry response
    *   before rejecting. Default comes from ./defaults.js (30000 ms); never read from the environment here.
+   * @param {number} opts.discoveryTimeoutMs - How long ONE discovery read (`getService()`)
+   *   may wait for the registry projection before it is refused as `TRANSIENT`. REQUIRED,
+   *   no module default: the value belongs to the platform (ServiceWrapper reads it from
+   *   the platform env) and bounds how long a workflow step can hang on a Redis that is
+   *   down or half-open (d.1090, d.1093). Enforced as a race beside the command, never as
+   *   node-redis' `AbortSignal` (see `getService()` for why).
    * @param {Object} opts.logger - Logger with info/warn/error/debug. Required and validated here:
    *   registration, heartbeat and revalidation events are what this client exists to report, and
    *   until 2026-09-05 they went to stdout through bare printing while this parameter was accepted
@@ -95,7 +148,7 @@ class ServiceRegistryClient extends EventEmitter {
    *   docs/governance/confirmations/connector-logger-contract.md 001 + 002.
    */
   constructor({ amqpUrl, serviceName, version, specificationEndpoint,
-                heartbeatInterval, apiQueue = 'api_services_queuer', registryQueue = 'registry.register',
+                heartbeatInterval, discoveryTimeoutMs, instanceId, apiQueue = 'api_services_queuer', registryQueue = 'registry.register',
                 redis = null, storageConfig = {}, validationProof = null, logger,
                 registryKeyPrefix = DEFAULTS.registryKeyPrefix,
                 registrationTimeoutMs = DEFAULTS.registrationTimeoutMs }) {
@@ -118,6 +171,32 @@ class ServiceRegistryClient extends EventEmitter {
         + `(module default ${DEFAULTS.registrationTimeoutMs}).`
       );
     }
+    // WHICH RUNNING COPY. The service NAME says which service; until d.817 nothing said
+    // which copy, so a short-lived foreign instance deregistered the live one and three
+    // services then beat into `unknown` for nine hours (INFRA batch 398, from production
+    // logs; owner decision `registry-instance-identity` 001).
+    //
+    // INJECTED, never made here (§1 DI, §3 no fallback): the wrapper makes ONE value per
+    // process at boot and hands the same one to `monitoring-core` as `serviceInstanceId`,
+    // so a second birthplace here would give one running copy two identities. Rule 11 —
+    // no default, no `|| uuidv4()`, no transition period.
+    if (typeof instanceId !== 'string' || instanceId === '') {
+      throw new Error(
+        `[RegistryClient] ${serviceName}: Missing instanceId - got ${JSON.stringify(instanceId)}. `
+        + 'Expected: a non-empty string naming THIS running copy of the service, the same value for the '
+        + 'whole process; the service name says which service, this says which copy. '
+        + 'Fix: pass the instance id the wrapper made once at boot (SERVICE_INSTANCE_ID when the '
+        + 'deployment gives one, otherwise a UUID v4) - this client never makes one, because the same '
+        + 'value also reaches monitoring-core as serviceInstanceId.'
+      );
+    }
+    this.instanceId = instanceId;
+    // Where the registry answers THIS copy's registration (conf
+    // `registry-instance-identity` 001 (c), d.817c) — carried as `responseQueue`.
+    // The shared `<service>.registry` (`serviceRegistryQueue`, set in `init()`)
+    // carries the registry's own prompts to every copy.
+    this.instanceResponseQueue = `${serviceName}.registry.${instanceId}`;
+
     this.registrationTimeoutMs = registrationTimeoutMs;
     this.serviceName = serviceName;
     this.version = version;
@@ -136,7 +215,8 @@ class ServiceRegistryClient extends EventEmitter {
         `[RegistryClient] ${serviceName}: Missing constructor option - heartbeatInterval is required. `
         + 'Expected: the cadence its one owner decided (docs/governance/confirmations/biz-health-freshness.md 001 '
         + 'point 3), passed as a positive number of milliseconds. '
-        + 'Fix: pass wrapper.registry.heartbeatInterval (ServiceWrapper reads it from BIZ_HEARTBEAT_INTERVAL_MS).'
+        + 'Fix: pass heartbeatInterval; ServiceWrapper reads it from env BIZ_HEARTBEAT_INTERVAL_MS '
+        + '(the config key wrapper.registry.heartbeatInterval is retired and refused).'
       );
     }
     if (typeof heartbeatInterval !== 'number' || !Number.isFinite(heartbeatInterval) || heartbeatInterval <= 0) {
@@ -145,8 +225,23 @@ class ServiceRegistryClient extends EventEmitter {
         + `got ${JSON.stringify(heartbeatInterval)}. Fix: pass the cadence as a number; a string is not parsed here.`
       );
     }
+    if (discoveryTimeoutMs === undefined) {
+      throw new Error(
+        `[RegistryClient] ${serviceName}: Missing constructor option - discoveryTimeoutMs is required. `
+        + 'Expected: how long (ms) one discovery read of the registry projection may wait before it is '
+        + 'refused as TRANSIENT, as a positive number. '
+        + 'Fix: pass discoveryTimeoutMs; ServiceWrapper reads it from the platform env (shared.env).'
+      );
+    }
+    if (typeof discoveryTimeoutMs !== 'number' || !Number.isFinite(discoveryTimeoutMs) || discoveryTimeoutMs <= 0) {
+      throw new Error(
+        `[RegistryClient] ${serviceName}: Invalid discoveryTimeoutMs - expected a positive number of milliseconds, `
+        + `got ${JSON.stringify(discoveryTimeoutMs)}. Fix: pass the deadline as a number; a string is not parsed here.`
+      );
+    }
     this.specificationEndpoint = specificationEndpoint;
     this.heartbeatInterval = heartbeatInterval;
+    this.discoveryTimeoutMs = discoveryTimeoutMs;
     this.apiQueue = apiQueue;
     this.registryQueue = registryQueue;
     this.queueManager = new QueueManager(amqpUrl, serviceName, this.logger);
@@ -195,8 +290,42 @@ class ServiceRegistryClient extends EventEmitter {
     // agreeing today, and 406 PRECONDITION-FAILED the day the two drift apart
     // (`.claude/rules/change-discipline.md` § One rail per concern).
     const consumerStartTime = Date.now();
+    // TWO queues, two jobs (conf `registry-instance-identity` 001 (c), d.817c):
+    //  - `<service>.registry`, shared by every copy — the registry's own prompts
+    //    (`revalidate`; `api_services_registry` `revalidationRequester.js` sends to
+    //    `<serviceName>.registry`);
+    //  - `<service>.registry.<instance_id>` — the answers to THIS copy's registration,
+    //    named in `register`'s `responseQueue`, so a live copy can no longer eat the
+    //    confirmation meant for another.
+    // Both have a dead-letter route in `queueConfig` (the per-instance template landed
+    // first, d.817b — the order conf 002 made binding), so `consume()` accepts both.
     this.serviceRegistryQueue = `${this.serviceName}.registry`;
 
+    for (const queue of [this.serviceRegistryQueue, this.instanceResponseQueue]) {
+      await this._startRegistryConsumer(queue);
+    }
+
+    // One line for the whole boot of this client: which queues it talks on, and how
+    // long the consumers took to attach. Replaces the four FÁZE 0.5/0.6 markers.
+    this.logger.info('[RegistryClient] Initialized', {
+      serviceName: this.serviceName,
+      version: this.version,
+      registryQueue: this.registryQueue,
+      promptQueue: this.serviceRegistryQueue,
+      responseQueue: this.instanceResponseQueue,
+      consumerStartupMs: Date.now() - consumerStartTime
+    });
+  }
+
+  /**
+   * Attach this client's handler to one registry queue, within a bounded wait.
+   *
+   * @param {string} queue - `<service>.registry` or `<service>.registry.<instance_id>`
+   * @returns {Promise<void>}
+   * @throws {Error} naming the queue, carrying the source's classification
+   * @private
+   */
+  async _startRegistryConsumer(queue) {
     const CONSUME_TIMEOUT = 5000; // 5 seconds
     // `requeueOnError: false` is the budget this consumer has always had, said in
     // the core's word: ONE attempt. The difference is where a failure goes — the
@@ -206,7 +335,7 @@ class ServiceRegistryClient extends EventEmitter {
     // nothing itself (@onlineapps/mq-client-core README § consume() — the delivery
     // contract).
     const consumeRegistryPromise = this.queueManager.consume(
-      this.serviceRegistryQueue,
+      queue,
       msg => this._handleRegistryMessage(msg),
       { requeueOnError: false }
     );
@@ -214,7 +343,7 @@ class ServiceRegistryClient extends EventEmitter {
     const consumeRegistryTimeoutPromise = new Promise((_, reject) => {
       consumeRegistryTimeout = setTimeout(() => {
         reject(new Error(
-          `[RegistryClient] consume() timeout for ${this.serviceRegistryQueue} after ${CONSUME_TIMEOUT}ms - `
+          `[RegistryClient] consume() timeout for ${queue} after ${CONSUME_TIMEOUT}ms - `
           + 'the broker never confirmed the consumer. Fix: check RabbitMQ responsiveness and that the queue exists.'
         ));
       }, CONSUME_TIMEOUT);
@@ -234,7 +363,7 @@ class ServiceRegistryClient extends EventEmitter {
       // { cause })` carries no own property, so the marker used to die here.
       // Nothing is classified HERE — what the source left unmarked stays unmarked.
       const refusal = new Error(
-        `[RegistryClient] ${this.serviceName}: Failed to start consumer on ${this.serviceRegistryQueue} - `
+        `[RegistryClient] ${this.serviceName}: Failed to start consumer on ${queue} - `
         + `${consumeErr.message}. Fix: check RabbitMQ health; without this consumer no registry reply is ever read.`,
         { cause: consumeErr }
       );
@@ -244,16 +373,6 @@ class ServiceRegistryClient extends EventEmitter {
     } finally {
       if (consumeRegistryTimeout) clearTimeout(consumeRegistryTimeout);
     }
-
-    // One line for the whole boot of this client: which queues it talks on, and how
-    // long the consumer took to attach. Replaces the four FÁZE 0.5/0.6 markers.
-    this.logger.info('[RegistryClient] Initialized', {
-      serviceName: this.serviceName,
-      version: this.version,
-      registryQueue: this.registryQueue,
-      responseQueue: this.serviceRegistryQueue,
-      consumerStartupMs: Date.now() - consumerStartTime
-    });
   }
 
   /**
@@ -468,11 +587,17 @@ class ServiceRegistryClient extends EventEmitter {
    * Registers the service with the registry.
    * Registry will validate if the service is properly tested and valid.
    * Upon successful validation, the service will be activated and can start heartbeats.
-   * @param {Object} serviceInfo - Service registration information
-   * @param {Array} serviceInfo.endpoints - API endpoints provided by the service
-   * @param {Object} serviceInfo.metadata - Additional service metadata
-   * @param {string} serviceInfo.health - Health check endpoint
-   * @param {number} serviceInfo.timeout - Timeout for registration response (default: 30000ms)
+   * @param {Object} serviceInfo - Service registration information. It accepts EXACTLY the keys
+   *   below (`ACCEPTED_SERVICE_INFO_KEYS`) — any other key is refused by name, and a retired one
+   *   (`RETIRED_SERVICE_INFO_KEYS`) with the reason it went. Nothing is dropped in silence: a key
+   *   this call ignored would leave the caller believing it travelled.
+   * @param {Array} [serviceInfo.endpoints] - API endpoints provided by the service; `[]` for v3 services
+   * @param {Object} [serviceInfo.operations] - The complete `operations` map the registry validates
+   * @param {Object} [serviceInfo.metadata] - `{ version, description }` stored beside the spec
+   * @param {string} [serviceInfo.health] - Legacy health path; liveness travels by heartbeat
+   * @param {boolean} [serviceInfo.workspaceScoped] - Emitted only when the service declares it
+   * @param {number} [serviceInfo.timeout] - How long THIS call waits for the registry verdict
+   *   (default: the constructor's registrationTimeoutMs). It reaches no message.
    * @returns {Promise<{success: boolean, message: string, serviceName: string, version: string,
    *   registrationId: (string|undefined), validated: boolean, certificate: (Object|null),
    *   errorCode: (string|null|undefined)}>} The registry verdict. `errorCode` is the
@@ -492,9 +617,12 @@ class ServiceRegistryClient extends EventEmitter {
       );
     }
 
-    // A retired key is refused BY NAME, before anything is published: dropping it
-    // in silence would leave the caller believing it travelled. The value is never
-    // echoed - two of these keys carried a secret.
+    // ONE membership check over the two tables above, before anything is published.
+    // A key the contract does not name is refused BY NAME: dropping it in silence
+    // would leave the caller believing it travelled. A retired key keeps its own
+    // reason - it is the subset that can still say what replaced it. Neither
+    // refusal echoes the value: two of the retired keys carried a secret, and an
+    // unknown key can carry anything.
     for (const key of Object.keys(serviceInfo)) {
       if (Object.prototype.hasOwnProperty.call(RETIRED_SERVICE_INFO_KEYS, key)) {
         throw new Error(
@@ -503,6 +631,15 @@ class ServiceRegistryClient extends EventEmitter {
           + `Fix: delete "${key}" from the object passed to register().`
         );
       }
+      if (!Object.prototype.hasOwnProperty.call(ACCEPTED_SERVICE_INFO_KEYS, key)) {
+        throw new Error(
+          `[RegistryClient] ${this.serviceName}: serviceInfo key "${key}" is not part of the registration `
+          + `contract - Expected one of: ${Object.keys(ACCEPTED_SERVICE_INFO_KEYS).join(', ')} `
+          + '(api/docs/biz/30-operations/registration-wire.md §2.1). '
+          + `Fix: delete "${key}" from the object passed to register(), or send the value under the key `
+          + 'the contract names for it.'
+        );
+      }
     }
 
     // FAIL-FAST: a client that was never initialized, or that has been closed, is not
@@ -519,9 +656,32 @@ class ServiceRegistryClient extends EventEmitter {
     }
 
     const msgId = uuidv4();
+
+    // FAIL-FAST: one request id, one pending registration. `pendingRegistrations` and
+    // `pendingTimeouts` are keyed by this id, and until d.760b a second call under an id
+    // that was still pending simply set() over both - which dropped the earlier timer's
+    // handle. Nothing could reach it afterwards: the registry's answer clears by id
+    // (_handleRegistryMessage), and close() walks the table, so both found only the newer
+    // handle and the older timer ran to its full 30 s. Cancelling the earlier registration
+    // here instead would be a fallback (§3): its caller is still awaiting an answer that
+    // belongs to it, and this class cannot know which of the two calls is the mistake.
+    if (this.pendingRegistrations && this.pendingRegistrations.has(msgId)) {
+      throw new Error(
+        `[RegistryClient] ${this.serviceName}: Duplicate request id "${msgId}" - a registration with this id `
+        + 'is still pending. Expected: one register() in flight per request id; it is settled by the registry '
+        + `answer, by the ${this.registrationTimeoutMs}ms timeout or by close(). `
+        + 'Fix: await the register() already in flight before starting another one, and - if the ids repeat '
+        + 'because uuid.v4 is stubbed - give each registration its own id.'
+      );
+    }
+
     // @see api/docs/biz/30-operations/registration-wire.md §2 MQ wire format
     const msg = {
       id: msgId,
+      // WHICH REQUEST (`id`, per call) and WHICH COPY (`instance_id`, per process) are
+      // two identities with two lifetimes — d.817, owner `registry-instance-identity` 001.
+      // snake_case is the one spelling the wire has (`workflow-message-aliases` 001).
+      instance_id: this.instanceId,
       type: 'register',
       serviceName: this.serviceName,
       version: this.version,
@@ -530,7 +690,7 @@ class ServiceRegistryClient extends EventEmitter {
       operations: serviceInfo.operations || {},
       metadata: serviceInfo.metadata || {},
       health: serviceInfo.health || '/health',
-      responseQueue: this.serviceRegistryQueue, // Queue for registry to send response
+      responseQueue: this.instanceResponseQueue, // THIS copy's answer queue (conf registry-instance-identity 001 (c))
       timestamp: new Date().toISOString()
     };
 
@@ -572,7 +732,7 @@ class ServiceRegistryClient extends EventEmitter {
           reject(new Error(
             `[RegistryClient] ${this.serviceName}: Registration timed out - no response from the registry `
             + `within ${timeout}ms. Expected: api_services_registry consumes '${this.registryQueue}' and answers `
-            + `on '${this.serviceRegistryQueue}'. Fix: start api_services_registry (docker compose up -d `
+            + `on '${this.instanceResponseQueue}'. Fix: start api_services_registry (docker compose up -d `
             + 'api_services_registry) or raise registrationTimeoutMs.'
           ));
         }
@@ -627,7 +787,7 @@ class ServiceRegistryClient extends EventEmitter {
         serviceName: this.serviceName,
         version: this.version,
         registryQueue: this.registryQueue,
-        responseQueue: this.serviceRegistryQueue,
+        responseQueue: this.instanceResponseQueue,
         requestId: msgId,
         hasValidationProof: !!this.validationProof,
         proofHash: this.validationProof
@@ -693,14 +853,25 @@ class ServiceRegistryClient extends EventEmitter {
    * where it published it, and that the heartbeat timer is stopped. A publish that
    * fails REJECTS; reaching the return means the broker took the message.
    *
+   * The heartbeat loop stops FIRST, before anything is published. A heartbeat is
+   * the claim "this copy is alive"; a caller that deregisters has decided it is
+   * leaving, and that decision does not wait for the broker. Until d.1083 the loop
+   * stopped only after a successful publish, so a rejected deregistration left it
+   * beating for a service on its way out.
+   *
    * @returns {Promise<{requestId: string, serviceName: string, version: string,
    *   publishedTo: string, heartbeatStopped: boolean, publishedAt: string}>}
    */
   async deregister() {
+    this.stopHeartbeat();
+
     const msg = {
       id: uuidv4(),
       type: 'deregister',
       serviceName: this.serviceName,
+      // The reason this key exists at all: the registry deletes only on a match, so a
+      // short-lived foreign copy can no longer deregister the live one (d.817).
+      instance_id: this.instanceId,
       version: this.version,
       timestamp: new Date().toISOString()
     };
@@ -720,9 +891,6 @@ class ServiceRegistryClient extends EventEmitter {
 
     this.emit('deregisterSent', msg);
 
-    // Stop heartbeat if running
-    this.stopHeartbeat();
-
     return {
       requestId: msg.id,
       serviceName: this.serviceName,
@@ -752,6 +920,9 @@ class ServiceRegistryClient extends EventEmitter {
       id: uuidv4(),
       type: 'heartbeat',
       serviceName: this.serviceName,
+      // The beat says which copy is alive, so the registry can keep its availability
+      // episodes per instance instead of per name (d.817, INFRA half).
+      instance_id: this.instanceId,
       version: this.version,
       specificationEndpoint: this.specificationEndpoint,
       timestamp: new Date().toISOString()
@@ -778,9 +949,10 @@ class ServiceRegistryClient extends EventEmitter {
    *
    * A heartbeat loop with no budget is worse than none: the beats stop reaching
    * the registry, the loop logs and reschedules forever, and the service keeps
-   * running while every consumer of `registry:services` reads it as stale. Until
-   * 2026-09-15 that budget lived in `@onlineapps/service-wrapper`, in a second
-   * loop around `sendHeartbeat()` — two loops for one cadence
+   * running while every consumer of `registry:services` reads it as stale. The
+   * budget lives here and nowhere else: `@onlineapps/service-wrapper` arms this
+   * loop and runs none of its own (service-wrapper d.1076, its CHANGELOG) — two
+   * loops for one cadence would be two rails for one concern
    * (`.claude/rules/change-discipline.md` § One rail per concern).
    *
    * The cadence is NOT an argument here. It has one owner and it is the
@@ -801,6 +973,24 @@ class ServiceRegistryClient extends EventEmitter {
    *   budget is spent. The loop is already stopped when it is called.
    */
   startHeartbeat(options) {
+    // FAIL-FAST: one client, one loop. Checked before the options, because the state
+    // of the receiver is the problem here whatever the arguments say. Until d.760c the
+    // line at the end of this method wrote the new handle over `heartbeatTimer` and the
+    // earlier loop lost the only reference to itself: it re-arms while that field is
+    // not null, and the field now belonged to the newer loop, so `stopHeartbeat()`
+    // cancelled one loop and the other went on beating for a service that had stopped.
+    // Replacing the running loop silently would be a fallback (§3) - the caller that
+    // started it is not asking for it to be discarded, and this class cannot know which
+    // of the two callers is the mistake.
+    if (this.heartbeatTimer) {
+      throw new Error(
+        `[RegistryClient] ${this.serviceName}: A heartbeat loop is already running - starting a second one would `
+        + 'overwrite the timer handle of the first, which would then beat on with nothing able to stop it. '
+        + 'Expected: one heartbeat loop per client; stop it with stopHeartbeat() first. '
+        + 'Fix: call client.stopHeartbeat() before starting a new loop, or keep the loop that is already running.'
+      );
+    }
+
     if (options === null || typeof options !== 'object' || Array.isArray(options)) {
       throw new Error(
         `[RegistryClient] ${this.serviceName}: Missing heartbeat options - startHeartbeat({ maxFailures, onFatal }) `
@@ -886,12 +1076,21 @@ class ServiceRegistryClient extends EventEmitter {
 
   /**
    * Stops periodic heartbeat messages.
+   *
+   * One scheduler, one cancel: `startHeartbeat()` arms the loop with a recursive
+   * `setTimeout` and nothing in this class has created an interval since that
+   * rewrite (d.503), so `clearTimeout` is the whole job. A `clearInterval` on the
+   * same handle stood beside it until d.752, under a comment offering to cancel
+   * "whether it's from setTimeout or setInterval" — a choice the class does not
+   * have, and one that told every reader the loop might be an interval.
+   *
+   * Setting `heartbeatTimer` to null is the second half and not a formality: the
+   * loop reads it before arming the next beat, so a beat already in flight sees
+   * the stop and schedules nothing.
    */
   stopHeartbeat() {
     if (this.heartbeatTimer) {
-      // Clear timeout regardless of whether it's from setTimeout or setInterval
       clearTimeout(this.heartbeatTimer);
-      clearInterval(this.heartbeatTimer);
       this.heartbeatTimer = null;
     }
   }
@@ -970,7 +1169,38 @@ class ServiceRegistryClient extends EventEmitter {
     }
 
     const key = `${this.registryKeyPrefix}services`;
-    const raw = await this.redis.hGet(key, serviceName);
+    // THE DEADLINE IS A RACE, NOT AN AbortSignal (d.1093). Without a deadline `hGet`
+    // never settles while Redis is down or half-open (d.1088, d.1090). node-redis 4.7.1
+    // does offer `commandOptions({ signal })`, but aborting a command the server has
+    // already received removes its queue node a second time (the abort listener stays
+    // attached after the command is sent), the queue length goes negative, and the next
+    // `flushAll` — a socket error with `disableOfflineQueue`, or `disconnect()` — throws
+    // `TypeError: Cannot read properties of undefined (reading 'reject')`; from the socket
+    // error handler that is an uncaught exception that ends the process (measured d.1093,
+    // fake RESP server). The race leaves the command in the queue: a late reply is still
+    // matched to it, and its late settlement is caught below, never unhandled.
+    const lookup = this.redis.hGet(key, serviceName);
+    let timer;
+    let timedOut = false;
+    const deadline = new Promise((resolve) => {
+      timer = setTimeout(() => { timedOut = true; resolve(); }, this.discoveryTimeoutMs);
+    });
+    let raw;
+    try {
+      raw = await Promise.race([lookup, deadline]);
+    } catch (err) {
+      throw this._typeDiscoveryFailure(err, { key, serviceName });
+    } finally {
+      clearTimeout(timer);
+    }
+    if (timedOut) {
+      lookup.then(() => {}, (late) => {
+        this.logger.debug(
+          `[RegistryClient] getService - abandoned lookup of "${serviceName}" settled after the deadline: ${late.message}`
+        );
+      });
+      throw this._discoveryTimeout({ key, serviceName });
+    }
     if (!raw) {
       return null;
     }
@@ -994,6 +1224,49 @@ class ServiceRegistryClient extends EventEmitter {
     };
   }
 
+  /**
+   * The lookup did not end within `discoveryTimeoutMs`. Nothing failed underneath, so
+   * the error carries no `cause`.
+   * @private
+   * @returns {Error}
+   */
+  _discoveryTimeout({ key, serviceName }) {
+    const failure = new Error(
+      `[RegistryClient] getService - Registry projection did not answer the lookup of "${serviceName}" `
+      + `within ${this.discoveryTimeoutMs} ms (key ${key}). Expected: a reply from the Redis the registry projects into. `
+      + 'Fix: make that Redis reachable to this service; the step is retried as TRANSIENT.'
+    );
+    failure.code = DISCOVERY_FAILURE_CODES.timeout;
+    failure.type = 'TRANSIENT';
+    failure.serviceName = serviceName;
+    return failure;
+  }
+
+  /**
+   * Types a rejected discovery read by what THIS client knows, never by the text of the
+   * rejection (node-redis errors carry no `code` and no `name`, measured d.1090): a client
+   * that reports it is not ready means Redis is gone (offline with `disableOfflineQueue`,
+   * socket closed under the command). Anything else — a reply error from a connected
+   * Redis — is not a transport verdict and passes unchanged.
+   * @private
+   * @returns {Error}
+   */
+  _typeDiscoveryFailure(err, { key, serviceName }) {
+    if (this.redis.isReady !== false) {
+      return err;
+    }
+    const failure = new Error(
+      `[RegistryClient] getService - Registry projection is unreachable for the lookup of "${serviceName}" `
+      + `(key ${key}) - ${err.message}. Expected: a connected client of the Redis the registry projects into. `
+      + 'Fix: make that Redis reachable to this service; the step is retried as TRANSIENT.',
+      { cause: err }
+    );
+    failure.code = DISCOVERY_FAILURE_CODES.unavailable;
+    failure.type = 'TRANSIENT';
+    failure.serviceName = serviceName;
+    return failure;
+  }
+
   /**
    * Releases resources: stops heartbeat and closes connection.
    * @returns {Promise<void>}

package/src/registryEventConsumer.js

@@ -10,6 +10,7 @@
 
 const EventEmitter = require('events');
 const { assertLogger } = require('@onlineapps/logger-contract');
+const { queueConfig } = require('@onlineapps/mq-client-core');
 
 // The storage connector arrives by INJECTION. There used to be an implicit
 // default here — `require('@onlineapps/connector-storage')` inside a try/catch
@@ -88,8 +89,19 @@ class RegistryEventConsumer extends EventEmitter {
     // Reusing it would cause 406 PRECONDITION_FAILED when different queue args (TTL/max-length) are applied.
     this.eventsQueueName = `${serviceName}.registry.events`;
 
-    // Exchange name for registry events
-    this.exchangeName = 'registry.changes';
+    // Exchange name for registry events - from the library that declares the whole
+    // registry section of the topology, never spelled here. Until d.809 this was the
+    // one wire name of this package written twice: a rename in `queueConfig` would
+    // have left this consumer subscribed to an exchange nobody publishes to, with
+    // nothing red anywhere (`change-discipline.md` § One rail per concern).
+    //
+    // Only the NAME. The pinned 4.0.1 declares `registry.changes` as
+    // `{ type: 'exchange', durable: true }` with no `exchangeType`; the tree has
+    // `exchangeType: 'fanout'` (d.712) and is unreleased, so reading the type from the
+    // library today would read `undefined` and defaulting it here would be a fallback
+    // (§3). The `'fanout'` in subscribeToChanges() therefore stays a literal until
+    // mq-client-core is released.
+    this.exchangeName = queueConfig.queueName('registry', 'changes');
   }
 
   /**