@onlineapps/conn-orch-registry 4.0.3 → 5.0.0

package/README.md

@@ -76,7 +76,15 @@ await client.register({
   health: '/health'
 });
 
-client.startHeartbeat();
+// The give-up budget is required: how many missed beats mean the service can no
+// longer prove it is alive, and what happens then. Neither is defaulted here.
+client.startHeartbeat({
+  maxFailures: 5,
+  onFatal: (err) => {
+    logger.error(err.message);
+    process.exit(1); // the restart policy boots it again and it re-registers
+  }
+});
 
 // Graceful shutdown
 process.on('SIGINT', async () => {

package/docs/REGISTRY_CLIENT_GUIDE.md

@@ -17,14 +17,14 @@ Microservice                Registry                  Backend
     |   (setup connection)      |                         |
     |                          |                         |
     |-- register() ----------->|                         |
-    |   (full spec: endpoints |                         |
-    |    + operations + meta) |-- validate() --------->|
+    |   (endpoints +          |                         |
+    |    operations + meta)   |-- validate() --------->|
     |                          |   (check if tested)    |
     |                          |<-- validation result --|
     |                          |                         |
     |<-- register.confirmed ---|                         |
     |                          |                         |
-    |-- startHeartbeat() ----->|                         |
+    |-- startHeartbeat({…}) -->|                         |
     |   (if validated OK)      |                         |
 ```
 
@@ -70,13 +70,15 @@ async function initializeService() {
       author: 'Development Team',
       documentation: 'https://docs.example.com/users'
     },
-    health: '/health',
-    spec: openApiSpec  // Optional: OpenAPI specification object
+    health: '/health'
   });
 
-  // Step 3: If registration successful, start heartbeat
+  // Step 3: If registration successful, start heartbeat with its give-up budget
   if (registrationResult.success) {
-    registryClient.startHeartbeat();
+    registryClient.startHeartbeat({
+      maxFailures: 5,
+      onFatal: (err) => { console.error(err.message); process.exit(1); }
+    });
     console.log('Service registered and activated');
   } else {
     console.error('Registration failed:', registrationResult.message);
@@ -135,11 +137,25 @@ against the Operations Registry contract and either confirms or rejects.
 
 **Returns:** Registration result object with `success` status
 
-#### `startHeartbeat()`
-Starts sending periodic heartbeat messages. Should only be called after successful registration.
+#### `startHeartbeat({ maxFailures, onFatal })`
+Starts sending periodic heartbeat messages at the cadence the constructor was given. Should only be called
+after successful registration.
+
+Both options are REQUIRED and neither is defaulted:
+
+- `maxFailures` — a positive whole number of **consecutive** failed beats. One success resets the count.
+- `onFatal(err)` — called once, with the error naming the count and the last cause, at the moment the budget
+  is spent. The loop is already stopped when it runs.
+
+A loop with no budget beats forever into a broker that refuses it, so the service keeps running while every
+reader of the registry sees it as stale. What a dead heartbeat MEANS (stop the process, page someone) is the
+caller's decision — this client counts and reports, it never decides.
+
+The cadence is not an argument here: it has one owner, the constructor option `heartbeatInterval`
+(owner confirmation `api/docs/governance/confirmations/biz-health-freshness.md` 001 point 3).
 
 #### `stopHeartbeat()`
-Stops the heartbeat timer.
+Stops the heartbeat timer. Idempotent: calling it twice, or before any `startHeartbeat()`, does nothing.
 
 #### `async subscribeToChanges()`
 Subscribes to registry change events (optional).
@@ -184,7 +200,10 @@ registryClient.startHeartbeat();  // Started immediately
 await registryClient.init();
 const result = await registryClient.register(serviceInfo);  // NEW: Registration required
 if (result.success) {
-  registryClient.startHeartbeat();  // Only after validation
+  registryClient.startHeartbeat({    // Only after validation
+    maxFailures: 5,
+    onFatal: (err) => { console.error(err.message); process.exit(1); }
+  });
 }
 ```
 

package/examples/basicUsage.js

@@ -71,7 +71,13 @@ registryClient.on(EVENTS.ERROR, (err) => {
     await registryClient.register(await loadServiceSpec());
     console.log('Register message published.');
 
-    registryClient.startHeartbeat();
+    registryClient.startHeartbeat({
+      maxFailures: 5,
+      onFatal: (err) => {
+        console.error(err.message);
+        process.exit(1); // the restart policy boots it again and it re-registers
+      }
+    });
     console.log('Heartbeat loop started.');
 
     const shutdown = async () => {

package/examples/event-consumer-example.js

@@ -63,7 +63,13 @@ async function main() {
   });
 
   // Start heartbeat
-  client.startHeartbeat();
+  client.startHeartbeat({
+    maxFailures: 5,
+    onFatal: (err) => {
+      console.error(err.message);
+      process.exit(1);
+    }
+  });
 
   // OPT-IN: Subscribe to registry changes
   console.log('Subscribing to registry changes...');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/conn-orch-registry",
-  "version": "4.0.3",
+  "version": "5.0.0",
   "license": "MIT",
   "description": "conn-orch-registry provides the core communication mechanism for microservices in this environment. It enables them to interact with a services_registry to receive and fulfill tasks by submitting heartbeats or their API descriptions.",
   "keywords": [
@@ -37,7 +37,7 @@
   },
   "dependencies": {
     "@onlineapps/logger-contract": "2.0.0",
-    "@onlineapps/mq-client-core": "3.2.0",
+    "@onlineapps/mq-client-core": "4.0.0",
     "uuid": "^9.0.1"
   },
   "devDependencies": {

package/src/queueManager.js

@@ -90,11 +90,25 @@ class QueueManager {
       // The core's refusal says "the configured host" without naming it — which
       // host is exactly what a reader of a boot failure needs, so it is added
       // here, redacted, with the core's error as the cause.
-      throw new Error(
+      //
+      // The CLASSIFICATION the source put on the failure travels with the rewrap.
+      // `@onlineapps/mq-client-core` owns the question "did the broker answer and
+      // refuse?" (`REFUSAL_REPLY_CODES`, `_isBrokerRefusal()`) and states the
+      // answer as `code: 'MQ_CONNECTION_FATAL'` / `reason: 'broker-refused'`;
+      // `new Error(msg, { cause })` carries neither, so the marker died here and
+      // `@onlineapps/service-wrapper` — which ends its boot on `error.code` — was
+      // left with an unclassified failure and called a refusal transient (d.532,
+      // measured on biz-meta). Nothing is classified HERE: what the source left
+      // unmarked stays unmarked, exactly as `@onlineapps/conn-infra-mq` does it
+      // in `ConnectorMQClient` (d.498b).
+      const refusal = new Error(
         `[QueueManager] Failed to connect to RabbitMQ at ${this.safeAmqpUrl} - ${error.message}. `
         + 'Fix: check broker health and the credentials in the AMQP URI.',
         { cause: error }
       );
+      refusal.code = error.code;
+      refusal.reason = error.reason;
+      throw refusal;
     }
   }
 
@@ -137,12 +151,30 @@ class QueueManager {
         await this.client.assertQueue(q);
       } catch (assertErr) {
         const errorMsg = assertErr.message || String(assertErr);
-        throw new Error(
+        // The CLASSIFICATION the source put on the failure travels with the
+        // rewrap, exactly as it does in `init()` a few methods up (d.532). This
+        // was the THIRD path and the one d.532 did not reach: FÁZE 0.8 declares
+        // the business queues, and `new Error(msg, { cause })` carries no own
+        // property, so whatever the core decided about this failure died here and
+        // `@onlineapps/service-wrapper` — which reads `error.code` — was handed an
+        // unclassified one (d.579).
+        //
+        // Nothing is classified HERE: what the source left unmarked stays
+        // unmarked. This package neither reads AMQP reply codes nor matches on
+        // message text; the question "did the broker answer and refuse?" belongs
+        // to `@onlineapps/mq-client-core` (`REFUSAL_REPLY_CODES`,
+        // `_isBrokerRefusal()`), and a second copy of that list here would be free
+        // to drift from the one the broker is actually talked to through
+        // (`change-discipline.md` § One rail per concern).
+        const refusal = new Error(
           `[QueueManager] Failed to assert queue ${q} - ${errorMsg} (code ${assertErr.code || 'N/A'}). `
           + 'Fix: a 406 PRECONDITION-FAILED means the queue exists with different arguments; '
           + 'align them or let its owner declare it.',
           { cause: assertErr }
         );
+        refusal.code = assertErr.code;
+        refusal.reason = assertErr.reason;
+        throw refusal;
       }
       this.logger.debug('[QueueManager] Queue asserted', {
         serviceName: this.serviceName,

package/src/registryClient.js

@@ -2,13 +2,15 @@
  * registryClient.js
  *
  * ServiceRegistryClient for communication between a microservice (via Agent)
- * and the central registry. Sends the full service specification in the
- * `register` message (including the `operations` map) and periodic heartbeat
- * messages. Receives registration responses (register.confirmed /
- * register.rejected) and revalidation requests from the registry.
+ * and the central registry. Sends the service's `operations` map in the
+ * `register` message and periodic heartbeat messages. Receives registration
+ * responses (register.confirmed / register.rejected) and revalidation requests
+ * from the registry.
  *
  * Legacy `apiDescription` / `apiDescriptionRequest` round-trips have been
- * removed — the full spec is part of the `register` message itself.
+ * removed — what the registry validates travels in the `register` message
+ * itself, as `operations` (schema-v3). The `spec` key that used to carry an
+ * OpenAPI document beside it left in d.562: nothing ever read it.
  *
  * Uses QueueManager to manage AMQP queues. Emits events through EventEmitter.
  *
@@ -33,6 +35,32 @@ const { queueConfig } = require('@onlineapps/mq-client-core');
 const DEFAULTS = require('./defaults');
 const { assertLogger } = require('@onlineapps/logger-contract');
 
+/**
+ * Keys `register()` REFUSES, with the reason the caller needs to act on (d.562).
+ *
+ * All three used to travel on every registration and nothing ever read them:
+ * `api/infra/api_services_registry/src/listeners/registry.listener.js`
+ * destructures the `register` message without them, and no other reader exists on
+ * the platform (`api/docs/biz/30-operations/registration-wire.md` §2.1).
+ *
+ * They are refused rather than ignored: a key silently dropped leaves the caller
+ * believing something travelled. And they are refused under BOTH spellings each
+ * was accepted by (`token` / `validationToken`, `secret` / `tokenSecret`) — two
+ * names for one field is the defect this table closes, not a compatibility list.
+ */
+const RETIRED_SERVICE_INFO_KEYS = Object.freeze({
+  spec: 'the OpenAPI document a registry used to dereference over HTTP; biz containers expose no HTTP '
+    + '(ADR 0005) and what the registry validates today is `operations` (registration-wire.md §3)',
+  token: 'part of the JWT token API that left @onlineapps/service-validator-core in d.344; a validation '
+    + 'run is proven by `validationProof` / `validationData` and the certificate the validator signs',
+  validationToken: 'part of the JWT token API that left @onlineapps/service-validator-core in d.344; a '
+    + 'validation run is proven by `validationProof` / `validationData` and the certificate the validator signs',
+  secret: 'the shared secret of that same token API, whose last reader (HTTP POST /validate) was deleted '
+    + '2026-08-22; nothing verifies a token with it, and a broker message is no place for a secret',
+  tokenSecret: 'the shared secret of that same token API, whose last reader (HTTP POST /validate) was '
+    + 'deleted 2026-08-22; nothing verifies a token with it, and a broker message is no place for a secret'
+});
+
 
 class ServiceRegistryClient extends EventEmitter {
   /**
@@ -190,11 +218,22 @@ class ServiceRegistryClient extends EventEmitter {
     } catch (consumeErr) {
       // Not logged before throwing: the thrown message already names the service,
       // the queue and the cause.
-      throw new Error(
+      //
+      // The CLASSIFICATION the source put on the failure travels with the rewrap,
+      // for the same reason it does in `QueueManager.init()`: a queue the broker
+      // refused with 406 PRECONDITION-FAILED is answered identically on every
+      // attempt, and `@onlineapps/service-wrapper` ends FÁZE 0.7 permanently on
+      // `error.code` rather than on this sentence (d.532). `new Error(msg,
+      // { 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} - `
         + `${consumeErr.message}. Fix: check RabbitMQ health; without this consumer no registry reply is ever read.`,
         { cause: consumeErr }
       );
+      refusal.code = consumeErr.code;
+      refusal.reason = consumeErr.reason;
+      throw refusal;
     } finally {
       if (consumeRegistryTimeout) clearTimeout(consumeRegistryTimeout);
     }
@@ -426,7 +465,6 @@ class ServiceRegistryClient extends EventEmitter {
    * @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 {Object} serviceInfo.spec - OpenAPI specification
    * @param {(boolean|null)} [serviceInfo.deployable] - Manifest-conformance verdict of the
    *   caller's last validation run: `true`, `false`, or `null` when the run never measured
    *   it. Emitted only when the caller states one; see the `deployable` block below.
@@ -450,6 +488,19 @@ 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.
+    for (const key of Object.keys(serviceInfo)) {
+      if (Object.prototype.hasOwnProperty.call(RETIRED_SERVICE_INFO_KEYS, key)) {
+        throw new Error(
+          `[RegistryClient] ${this.serviceName}: serviceInfo carries the retired key "${key}" - `
+          + `${RETIRED_SERVICE_INFO_KEYS[key]}. `
+          + `Fix: delete "${key}" from the object passed to register().`
+        );
+      }
+    }
+
     // FAIL-FAST: a client that was never initialized, or that has been closed, is not
     // usable. It used to silently call queueManager.init() here, which re-opened a
     // channel WITHOUT restarting the response consumer started by init() - so the
@@ -475,15 +526,13 @@ class ServiceRegistryClient extends EventEmitter {
       operations: serviceInfo.operations || {},
       metadata: serviceInfo.metadata || {},
       health: serviceInfo.health || '/health',
-      spec: serviceInfo.spec || null,
-      validationToken: serviceInfo.token || serviceInfo.validationToken,
-      tokenSecret: serviceInfo.secret || serviceInfo.tokenSecret,
       responseQueue: this.serviceRegistryQueue, // Queue for registry to send response
       timestamp: new Date().toISOString()
     };
 
     // Propagate workspaceScoped flag to the registry so consumers can discover
-    // which services are workspace-scoped. See biz-service-onboarding.md §4.
+    // which services are workspace-scoped.
+    // @see api/docs/biz/60-templates/onboarding-checklist.md §4
     if (typeof serviceInfo.workspaceScoped === 'boolean') {
       msg.workspaceScoped = serviceInfo.workspaceScoped;
     }
@@ -732,36 +781,115 @@ class ServiceRegistryClient extends EventEmitter {
   }
 
   /**
-   * Starts periodic heartbeat messages.
+   * Starts periodic heartbeat messages, and gives up after a budget of
+   * consecutive failures.
+   *
+   * 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
+   * (`.claude/rules/change-discipline.md` § One rail per concern).
+   *
+   * The cadence is NOT an argument here. It has one owner and it is the
+   * constructor's `heartbeatInterval` (owner confirmation
+   * docs/governance/confirmations/biz-health-freshness.md 001 point 3); taking it
+   * again per call would be the second number that confirmation refuses.
+   *
+   * Neither option is defaulted. How many missed beats mean death, and what death
+   * means, are decisions of the caller that owns the process — this client only
+   * counts and reports (`.claude/rules/architecture-principles.md` §3, §4).
+   *
+   * @param {Object} options
+   * @param {number} options.maxFailures - REQUIRED. Consecutive failed beats the
+   *   service may accumulate before it can no longer prove it is alive. A
+   *   positive whole number; one success resets the count to zero.
+   * @param {function(Error): void} options.onFatal - REQUIRED. Called exactly once,
+   *   with the §5 error naming the count and the last cause, at the moment the
+   *   budget is spent. The loop is already stopped when it is called.
    */
-  startHeartbeat() {
-    // Send immediately after init
-    this.sendHeartbeat().catch(err => {
-      this.logger.error('[RegistryClient] Initial heartbeat failed', {
-        serviceName: this.serviceName,
-        error: err.message
-      });
-    });
+  startHeartbeat(options) {
+    if (options === null || typeof options !== 'object' || Array.isArray(options)) {
+      throw new Error(
+        `[RegistryClient] ${this.serviceName}: Missing heartbeat options - startHeartbeat({ maxFailures, onFatal }) `
+        + `requires both, got ${JSON.stringify(options) === undefined ? 'undefined' : JSON.stringify(options)}. `
+        + 'Expected: an object naming the give-up budget and the handler that receives the fatal error. '
+        + 'Fix: call client.startHeartbeat({ maxFailures, onFatal }); this loop carries no default budget and '
+        + 'decides nothing about the service.'
+      );
+    }
 
-    // Repeat at the configured interval using a safe recursive timeout to avoid parallel runs
-    const heartbeatLoop = async () => {
+    const { maxFailures, onFatal } = options;
+
+    // Checked before the timer exists, so a wrong budget fails the boot naming the
+    // option rather than killing the service on beat one (§4, fail-fast).
+    if (!Number.isInteger(maxFailures) || maxFailures <= 0) {
+      throw new Error(
+        `[RegistryClient] ${this.serviceName}: Invalid maxFailures - expected a positive whole number of consecutive `
+        + `failed beats, got ${JSON.stringify(maxFailures) === undefined ? 'undefined' : JSON.stringify(maxFailures)}. `
+        + 'Expected: the budget its owner decided. Fix: pass the number of beats the service may miss before it is '
+        + 'no longer alive; at 0 the loop would give up on the first blip, which is the opposite of a budget.'
+      );
+    }
+
+    if (typeof onFatal !== 'function') {
+      throw new Error(
+        `[RegistryClient] ${this.serviceName}: Invalid onFatal - expected a function, got `
+        + `${JSON.stringify(onFatal) === undefined ? 'undefined' : JSON.stringify(onFatal)}. `
+        + 'Expected: the caller decides what a dead heartbeat means (stop the service, page someone); this client '
+        + 'only reports that the budget is spent. '
+        + 'Fix: pass onFatal: (err) => { /* shut the service down so it re-registers on restart */ }.'
+      );
+    }
+
+    let consecutiveFailures = 0;
+
+    // ONE accounting path for every beat, the immediate one included: a first beat
+    // counted outside the budget would make `maxFailures` mean "N + 1 for the first
+    // failure" — a number the caller did not set.
+    const beat = async () => {
       try {
         await this.sendHeartbeat();
+        consecutiveFailures = 0;
       } catch (err) {
+        consecutiveFailures += 1;
         this.logger.error('[RegistryClient] Heartbeat failed', {
           serviceName: this.serviceName,
-          error: err.message
+          error: err.message,
+          consecutiveFailures,
+          maxFailures
         });
-      } finally {
-        // Schedule next heartbeat only after previous one finished (or failed)
-        if (this.heartbeatTimer !== null) {
-          this.heartbeatTimer = setTimeout(heartbeatLoop, this.heartbeatInterval);
+
+        if (consecutiveFailures >= maxFailures) {
+          // Stopped BEFORE onFatal runs: the handler tears the process down, and a
+          // timer still armed would fire one more beat into a closing service.
+          this.stopHeartbeat();
+          onFatal(new Error(
+            `[RegistryClient] ${this.serviceName}: Registry heartbeat failed ${consecutiveFailures} times in a row - `
+            + `the service can no longer prove it is alive; last cause: ${err.message} `
+            + `Expected: a beat reaches ${this.registryQueue} within the budget of ${maxFailures}. `
+            + 'Fix: check the registry service and the queue it consumes, then restart this service so it '
+            + 'registers again.',
+            { cause: err }
+          ));
         }
       }
     };
 
-    // Use setTimeout instead of setInterval for better control
+    // Repeat at the configured cadence with a recursive timeout, so two beats can
+    // never run in parallel; `heartbeatTimer === null` is how a stop (from
+    // stopHeartbeat, or from the budget above) refuses the next schedule.
+    const heartbeatLoop = async () => {
+      await beat();
+      if (this.heartbeatTimer !== null) {
+        this.heartbeatTimer = setTimeout(heartbeatLoop, this.heartbeatInterval);
+      }
+    };
+
+    // Armed before the immediate beat is awaited, so the budget can clear it: the
+    // beat's rejection is handled in a microtask, i.e. after this line has run.
     this.heartbeatTimer = setTimeout(heartbeatLoop, this.heartbeatInterval);
+    beat();
   }
 
   /**