@onlineapps/conn-orch-registry 3.0.1 → 4.0.0

package/src/registryClient.js

@@ -22,15 +22,16 @@
  * @see api/docs/biz/30-operations/registration-wire.md §2 MQ wire format
  * @see api/docs/biz/30-operations/schema-v3.md
  *
- * @module @onlineapps/connector-registry-client/src/registryClient
+ * @module @onlineapps/conn-orch-registry/src/registryClient
  */
 
 const EventEmitter = require('events');
 const QueueManager = require('./queueManager');
 const RegistryEventConsumer = require('./registryEventConsumer');
 const { v4: uuidv4 } = require('uuid');
-const queueConfig = require('@onlineapps/mq-client-core/src/config/queueConfig');
+const { queueConfig } = require('@onlineapps/mq-client-core');
 const DEFAULTS = require('./defaults');
+const { assertLogger } = require('@onlineapps/logger-contract');
 
 
 class ServiceRegistryClient extends EventEmitter {
@@ -39,23 +40,42 @@ class ServiceRegistryClient extends EventEmitter {
    * @param {string} opts.amqpUrl - AMQP URI for connecting to RabbitMQ
    * @param {string} opts.serviceName - Name of the service (e.g., 'invoicing')
    * @param {string} opts.version - Version of the service (e.g., '1.2.0')
-   * @param {string} [opts.specificationEndpoint='/api/v1/specification'] - Endpoint where API specification is available
-   * @param {number} [opts.heartbeatInterval=10000] - Heartbeat interval in milliseconds
+   * @param {string} opts.specificationEndpoint - Path the `register` and `heartbeat` messages
+   *   carry. REQUIRED: the wire format declares it required
+   *   (api/docs/biz/30-operations/registration-wire.md §2.1) and the registry stores what it
+   *   is sent, so a default here would write a path nobody configured into `registry:services`.
+   * @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.
    * @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 {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
+   *   and never read. Owner confirmation:
+   *   docs/governance/confirmations/connector-logger-contract.md 001 + 002.
    */
-  constructor({ amqpUrl, serviceName, version, specificationEndpoint = '/api/v1/specification',
-                heartbeatInterval = 10000, apiQueue = 'api_services_queuer', registryQueue = 'registry.register',
-                registryUrl = null, redis = null, storageConfig = {}, validationProof = null,
+  constructor({ amqpUrl, serviceName, version, specificationEndpoint,
+                heartbeatInterval, apiQueue = 'api_services_queuer', registryQueue = 'registry.register',
+                redis = null, storageConfig = {}, validationProof = null, logger,
                 registryKeyPrefix = DEFAULTS.registryKeyPrefix,
                 registrationTimeoutMs = DEFAULTS.registrationTimeoutMs }) {
     super();
     if (!amqpUrl || !serviceName || !version) {
-      throw new Error('amqpUrl, serviceName, and version are required');
+      throw new Error(
+        '[RegistryClient] Missing constructor options - amqpUrl, serviceName, and version are required. '
+        + 'Fix: pass all three to new ServiceRegistryClient({ amqpUrl, serviceName, version, logger }).'
+      );
     }
+    this.logger = assertLogger(
+      'RegistryClient',
+      logger,
+      'registration, heartbeat and revalidation events reach the service log'
+    );
     if (typeof registrationTimeoutMs !== 'number' || !Number.isFinite(registrationTimeoutMs) || registrationTimeoutMs <= 0) {
       throw new Error(
         `[RegistryClient] ${serviceName}: Invalid registrationTimeoutMs - expected a positive number of milliseconds, `
@@ -66,13 +86,35 @@ class ServiceRegistryClient extends EventEmitter {
     this.registrationTimeoutMs = registrationTimeoutMs;
     this.serviceName = serviceName;
     this.version = version;
-    // Spec endpoint is still configurable, but defaults are module-owned and can be overridden via runtime config.
+    // Both of these were module defaults until d.278c, and both were statements this
+    // package had no standing to make (architecture-principles §3, no fallbacks).
+    if (typeof specificationEndpoint !== 'string' || specificationEndpoint === '') {
+      throw new Error(
+        `[RegistryClient] ${serviceName}: Missing constructor option - specificationEndpoint is required, `
+        + `got ${JSON.stringify(specificationEndpoint)}. Expected: the path the register message must carry `
+        + '(api/docs/biz/30-operations/registration-wire.md §2.1 declares it required). '
+        + 'Fix: pass service.specificationEndpoint from the service configuration; nothing may substitute a path for it.'
+      );
+    }
+    if (heartbeatInterval === undefined) {
+      throw new Error(
+        `[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).'
+      );
+    }
+    if (typeof heartbeatInterval !== 'number' || !Number.isFinite(heartbeatInterval) || heartbeatInterval <= 0) {
+      throw new Error(
+        `[RegistryClient] ${serviceName}: Invalid heartbeatInterval - expected a positive number of milliseconds, `
+        + `got ${JSON.stringify(heartbeatInterval)}. Fix: pass the cadence as a number; a string is not parsed here.`
+      );
+    }
     this.specificationEndpoint = specificationEndpoint;
     this.heartbeatInterval = heartbeatInterval;
     this.apiQueue = apiQueue;
     this.registryQueue = registryQueue;
-    this.registryUrl = registryUrl;
-    this.queueManager = new QueueManager(amqpUrl, serviceName);
+    this.queueManager = new QueueManager(amqpUrl, serviceName, this.logger);
     this.heartbeatTimer = null;
 
     // Event consumer (optional, activated via subscribeToChanges)
@@ -93,119 +135,131 @@ class ServiceRegistryClient extends EventEmitter {
   async init() {
     await this.queueManager.init();
 
-    // Validation proof is now injected via constructor (not loaded here)
+    // Validation proof is now injected via constructor (not loaded here).
+    // One line either way: a proof is the normal case (info), its absence means the
+    // registry falls back to Tier 2 validation, which is a degraded mode (warn).
     if (this.validationProof) {
-      console.log(`[RegistryClient] ${this.serviceName}: ✅ Validation proof provided via constructor`);
-      console.log(`[RegistryClient] ${this.serviceName}:    Proof hash: ${this.validationProof.validationProof.substring(0, 32)}...`);
+      this.logger.info('[RegistryClient] Validation proof provided via constructor', {
+        serviceName: this.serviceName,
+        hasValidationProof: true,
+        proofHash: this.validationProof.validationProof.substring(0, 32)
+      });
     } else {
-      console.log(`[RegistryClient] ${this.serviceName}: ⚠️  No validation proof - will use Tier 2 validation`);
+      this.logger.warn('[RegistryClient] No validation proof - registry will run Tier 2 validation', {
+        serviceName: this.serviceName,
+        hasValidationProof: false
+      });
     }
 
-    // FÁZE 0.5: Vytvoření service-specific front
-    const queueCreationStartTime = Date.now();
+    // FÁZE 0.5 + 0.6: the response queue and its consumer, in one step.
+    //
+    // The queue is NOT asserted here any more. `consume()` in the core declares a
+    // business queue itself, with the arguments `queueConfig` owns
+    // (`transports/rabbitmqClient.js` § _prepareQueueForConsume), so a separate
+    // `ensureQueues()` call ahead of it was a second declaration of one queue —
+    // 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();
     this.serviceRegistryQueue = `${this.serviceName}.registry`;
-    console.log(`[FÁZE 0.5] Service Queue Creation - STARTING`);
-    
-    try {
-      // Ensure existence of service-specific queue only (infrastructure queues must already exist)
-      await this.queueManager.ensureQueues([this.serviceRegistryQueue]);
-      console.log(`[FÁZE 0.5] Service Queue Creation - PASSED (${Date.now() - queueCreationStartTime}ms)`);
-    } catch (error) {
-      console.error(`[FÁZE 0.5] Service Queue Creation - FAILED: ${error.message}`);
-      throw error;
-    }
 
-    // FÁZE 0.6: Spuštění konzumerů
-    const consumerStartTime = Date.now();
-    console.log(`[FÁZE 0.6] Consumer Startup - STARTING`);
-    
-    // CRITICAL: Before consume(), we must assertQueue with correct parameters
-    // amqplib's channel.consume() may internally call assertQueue() WITHOUT parameters
-    // This causes 406 PRECONDITION-FAILED if queue exists with different arguments
-    console.log(`[RegistryClient] [CONSUMER] About to consume from ${this.serviceRegistryQueue}`);
-    console.log(`[RegistryClient] [CONSUMER] ⚠ WARNING: amqplib's channel.consume() may internally call assertQueue() WITHOUT parameters`);
-    console.log(`[RegistryClient] [CONSUMER] ⚠ WARNING: Queue should already be asserted by ensureQueues() above with correct parameters from queueConfig.js`);
-    
-    // Start consuming service registry queue for registry responses and events
     const CONSUME_TIMEOUT = 5000; // 5 seconds
-    const consumeRegistryPromise = this.queueManager.channel.consume(
+    // `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
+    // hand-written `nack(msg, false, false)` this replaces asked the broker to drop
+    // the message, while the policy rejects it into `<service>.dlq` and publishes a
+    // `message_dlq` event. The handler reports failure by THROWING; it settles
+    // nothing itself (@onlineapps/mq-client-core README § consume() — the delivery
+    // contract).
+    const consumeRegistryPromise = this.queueManager.consume(
       this.serviceRegistryQueue,
-      msg => {
-        // Handle null message (queue deleted, connection closed, consumer canceled)
-        if (!msg) {
-          console.warn(`[RegistryClient] ${this.serviceName}: Received null message from ${this.serviceRegistryQueue} (queue may be deleted or connection closed)`);
-          return;
-        }
-        try {
-          this._handleRegistryMessage(msg);
-        } catch (error) {
-          console.error(`[RegistryClient] ${this.serviceName}: Error in consume callback:`, error);
-          // Nack message on error
-          try {
-            this.queueManager.channel.nack(msg, false, false);
-          } catch (nackErr) {
-            console.error(`[RegistryClient] ${this.serviceName}: Failed to nack message:`, nackErr);
-          }
-        }
-      },
-      { noAck: false }
+      msg => this._handleRegistryMessage(msg),
+      { requeueOnError: false }
     );
     let consumeRegistryTimeout;
     const consumeRegistryTimeoutPromise = new Promise((_, reject) => {
       consumeRegistryTimeout = setTimeout(() => {
-        reject(new Error(`consume() timeout for ${this.serviceRegistryQueue} after ${CONSUME_TIMEOUT}ms`));
+        reject(new Error(
+          `[RegistryClient] consume() timeout for ${this.serviceRegistryQueue} after ${CONSUME_TIMEOUT}ms - `
+          + 'the broker never confirmed the consumer. Fix: check RabbitMQ responsiveness and that the queue exists.'
+        ));
       }, CONSUME_TIMEOUT);
     });
 
     try {
       await Promise.race([consumeRegistryPromise, consumeRegistryTimeoutPromise]);
-      console.log(`[FÁZE 0.6] Consumer Startup - PASSED (${Date.now() - consumerStartTime}ms)`);
     } catch (consumeErr) {
-      console.error(`[FÁZE 0.6] Consumer Startup - FAILED: ${consumeErr.message}`);
-      throw new Error(`[RegistryClient] ${this.serviceName}: Failed to start consumer on ${this.serviceRegistryQueue}: ${consumeErr.message}`);
+      // Not logged before throwing: the thrown message already names the service,
+      // the queue and the cause.
+      throw 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 }
+      );
     } 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
+    });
   }
 
   /**
    * Internal handler for incoming messages from the registry queue.
    * Handles registration responses and revalidation requests.
+   *
+   * Settling is NOT this method's business (d.198b-3). A return means "handled"
+   * and the core acks once; a THROW means "not handled" and the core applies the
+   * delivery policy the consumer was registered with — one attempt, then
+   * `<service>.dlq` with a `message_dlq` event. The hand-written
+   * `channel.ack` / `channel.nack(msg, false, false)` that used to end this method
+   * asked the broker to DROP a message it could not read.
+   *
    * @param {Object} msg - AMQP message
+   * @returns {Promise<void>}
+   * @throws {Error} If the payload is not readable as a registry message
    * @private
    */
-  _handleRegistryMessage(msg) {
-    // CRITICAL: Handle null message (queue deleted, connection closed, consumer canceled)
-    if (!msg) {
-      console.warn(`[RegistryClient] ${this.serviceName}: Received null message (queue may be deleted or connection closed)`);
-      return; // Don't try to parse or ack null message
-    }
-    
-    // Log which queue this message came from (if available in msg properties)
+  async _handleRegistryMessage(msg) {
+    // Which queue this message came from (if available in msg properties)
     const queueName = msg.fields?.routingKey || msg.fields?.exchange || 'unknown';
-    console.log(`[RegistryClient] ${this.serviceName}: [MESSAGE] Processing message from queue: ${queueName}`);
-    
+
     let payload;
     try {
       payload = JSON.parse(msg.content.toString());
-      console.log(`[RegistryClient] ${this.serviceName}: [MESSAGE] Parsed payload type: ${payload.type}, requestId: ${payload.requestId}`);
+      // One line per inbound message, after parsing: the "processing from queue"
+      // line that used to precede it said nothing this one does not.
+      this.logger.debug('[RegistryClient] Registry message received', {
+        serviceName: this.serviceName,
+        queue: queueName,
+        type: payload.type,
+        requestId: payload.requestId
+      });
     } catch (err) {
-      console.error(`[RegistryClient] ${this.serviceName}: [MESSAGE] Failed to parse message:`, err);
-      this.emit('error', err);
-      // Only nack if message is not null
-      if (msg) {
-        try {
-          this.queueManager.channel.nack(msg, false, false);
-        } catch (nackErr) {
-          console.error(`[RegistryClient] ${this.serviceName}: Failed to nack message:`, nackErr.message);
-        }
-      }
-      return;
+      // Not logged before throwing, and NOT emitted as an 'error' event either: an
+      // EventEmitter with no 'error' listener RETHROWS what is emitted, which would
+      // turn a delivery the core knows how to reject into an uncatchable crash of the
+      // service. The rejection below is the one report, and the core turns it into a
+      // dead-letter plus a `message_dlq` event (connector-logger-contract 003).
+      throw new Error(
+        `[RegistryClient] Failed to parse registry message from ${queueName} - ${err.message}. `
+        + 'Expected: JSON written by api_services_registry. '
+        + 'Fix: the message is rejected into the dead-letter queue unread; read it there '
+        + 'through the DLQ dashboard to see what was published.',
+        { cause: err }
+      );
     }
 
     // Handle revalidation request from registry (infra version change)
     if (payload.type === 'revalidate') {
-      console.log(`[RegistryClient] ${this.serviceName}: Received revalidation request`, {
+      this.logger.info('[RegistryClient] Revalidation requested by the registry', {
+        serviceName: this.serviceName,
         reason: payload.reason,
         infraFingerprint: payload.infraFingerprint?.substring(0, 16)
       });
@@ -215,17 +269,16 @@ class ServiceRegistryClient extends EventEmitter {
     // Handle registration response from registry
     // Registry sends 'register.confirmed' after validation
     if ((payload.type === 'registerResponse' || payload.type === 'register.confirmed') && payload.requestId) {
-      console.log(`[RegistryClient] ${this.serviceName}: [REGISTRATION] Received ${payload.type} message`, {
+      this.logger.info('[RegistryClient] Registration response received', {
+        serviceName: this.serviceName,
+        type: payload.type,
         requestId: payload.requestId,
-        hasPendingRegistrations: !!(this.pendingRegistrations),
+        queue: queueName,
         pendingCount: this.pendingRegistrations ? this.pendingRegistrations.size : 0,
-        hasMatchingRequest: !!(this.pendingRegistrations && this.pendingRegistrations.has(payload.requestId)),
-        pendingKeys: this.pendingRegistrations ? Array.from(this.pendingRegistrations.keys()) : [],
-        queueName
+        matched: !!(this.pendingRegistrations && this.pendingRegistrations.has(payload.requestId))
       });
 
       if (this.pendingRegistrations && this.pendingRegistrations.has(payload.requestId)) {
-        console.log(`[RegistryClient] ${this.serviceName}: [REGISTRATION] Found matching pending registration, extracting resolve function...`);
         const { resolve } = this.pendingRegistrations.get(payload.requestId);
         
         // Clear associated timeout
@@ -235,18 +288,20 @@ class ServiceRegistryClient extends EventEmitter {
         }
         
         this.pendingRegistrations.delete(payload.requestId);
-        console.log(`[RegistryClient] ${this.serviceName}: [REGISTRATION] ✓ Resolve function extracted, pending registration removed`);
-
-        // CRITICAL: Resolve promise synchronously to ensure it's called before any async operations
-        console.log(`[RegistryClient] ${this.serviceName}: [RESOLVE] Starting resolve process for requestId: ${payload.requestId}`);
-        console.log(`[RegistryClient] ${this.serviceName}: [RESOLVE] Payload keys:`, Object.keys(payload));
-        console.log(`[RegistryClient] ${this.serviceName}: [RESOLVE] Payload.success:`, payload.success);
-        console.log(`[RegistryClient] ${this.serviceName}: [RESOLVE] Payload.validated:`, payload.validated);
-        console.log(`[RegistryClient] ${this.serviceName}: [RESOLVE] Payload.hasCertificate:`, !!payload.certificate);
-        if (payload.certificate) {
-          console.log(`[RegistryClient] ${this.serviceName}: [RESOLVE] Payload.certificate.id:`, payload.certificate.id);
-          console.log(`[RegistryClient] ${this.serviceName}: [RESOLVE] Payload.certificate.serviceName:`, payload.certificate.serviceName);
-        }
+
+        // What the registry actually answered, in one structured record. Nine
+        // stdout lines printed these same fields one per line.
+        this.logger.debug('[RegistryClient] Registry verdict payload', {
+          serviceName: this.serviceName,
+          requestId: payload.requestId,
+          payloadKeys: Object.keys(payload),
+          success: payload.success,
+          validated: payload.validated,
+          errorCode: payload.errorCode,
+          hasCertificate: !!payload.certificate,
+          certificateId: payload.certificate?.id,
+          certificateServiceName: payload.certificate?.serviceName
+        });
 
         // Resolve the registration promise with the response
         const registrationResult = {
@@ -256,50 +311,71 @@ class ServiceRegistryClient extends EventEmitter {
           version: this.version,
           registrationId: payload.registrationId,
           validated: payload.validated || payload.success, // Consider successful registration as validated
-          certificate: payload.certificate || null // Include certificate from Registry
+          certificate: payload.certificate || null, // Include certificate from Registry
+          // WHY the registry decided as it did, in a stable machine code the caller
+          // can branch on instead of matching the message text. Passed through
+          // verbatim - no default, no fallback (architecture-principles §3): the
+          // explicit `null` the registry sends on a confirmed registration stays
+          // null, and a payload carrying no code at all leaves this undefined.
+          // @see api/docs/biz/30-operations/registration-wire.md §8
+          errorCode: payload.errorCode,
+          // The parked registration of §2.5 — "you have not pre-validated yet" — is
+          // not a refusal and carries no errorCode; what it carries is the state and
+          // what to run about it. Both were read off the wire and dropped here until
+          // d.278c, so a caller saw `success: false` and nothing that explained it.
+          // Verbatim, like errorCode: a confirmed registration sends neither key and
+          // this leaves both undefined rather than inventing a status.
+          // @see api/docs/biz/30-operations/registration-wire.md §2.5
+          validationStatus: payload.validationStatus,
+          instructions: payload.instructions
         };
-        
-        console.log(`[RegistryClient] ${this.serviceName}: [RESOLVE] Created registrationResult:`, JSON.stringify({
-          success: registrationResult.success,
-          validated: registrationResult.validated,
-          hasCertificate: !!registrationResult.certificate,
-          certificateId: registrationResult.certificate?.id || 'none',
-          serviceName: registrationResult.serviceName,
-          version: registrationResult.version
-        }));
-        
-        console.log(`[RegistryClient] ${this.serviceName}: [RESOLVE] About to call resolve() function...`);
-        console.log(`[RegistryClient] ${this.serviceName}: [RESOLVE] resolve function type:`, typeof resolve);
-        console.log(`[RegistryClient] ${this.serviceName}: [RESOLVE] resolve function exists:`, !!resolve);
-        
+
         try {
           // CRITICAL: Call resolve synchronously - this must happen immediately
           resolve(registrationResult);
-          console.log(`[RegistryClient] ${this.serviceName}: [RESOLVE] ✓ resolve() called successfully`);
-          console.log(`[RegistryClient] ${this.serviceName}: [RESOLVE] Promise should now be resolved`);
+          this.logger.info('[RegistryClient] Registration resolved', {
+            serviceName: this.serviceName,
+            requestId: payload.requestId,
+            success: registrationResult.success,
+            validated: registrationResult.validated,
+            hasCertificate: !!registrationResult.certificate,
+            certificateId: registrationResult.certificate?.id || null
+          });
         } catch (resolveError) {
-          console.error(`[RegistryClient] ${this.serviceName}: [RESOLVE] ✗ Error calling resolve():`, resolveError);
-          console.error(`[RegistryClient] ${this.serviceName}: [RESOLVE] Error stack:`, resolveError.stack);
+          this.logger.error('[RegistryClient] Resolving the registration promise threw', {
+            serviceName: this.serviceName,
+            requestId: payload.requestId,
+            error: resolveError.message,
+            stack: resolveError.stack
+          });
           throw resolveError;
         }
       } else {
-        console.warn(`[RegistryClient] ${this.serviceName}: ⚠️  Received ${payload.type} with requestId ${payload.requestId}, but no matching pending registration found`);
+        this.logger.warn('[RegistryClient] Registration response has no matching pending request', {
+          serviceName: this.serviceName,
+          type: payload.type,
+          requestId: payload.requestId
+        });
       }
     }
 
-    // Acknowledge all messages (only if message is not null)
-    if (msg) {
-      try {
-        this.queueManager.channel.ack(msg);
-      } catch (ackErr) {
-        console.error(`[RegistryClient] ${this.serviceName}: Failed to ack message:`, ackErr.message);
-      }
-    }
+    // No ack here: returning IS the ack (d.198b-3). The core settles the delivery
+    // once the handler resolves, on the channel that delivered it.
   }
 
   /**
-   * Ensure an infrastructure queue exists without mutating it.
-   * Uses a temporary channel so failures don't kill the primary channel.
+   * Confirms an infrastructure queue exists, without creating it.
+   *
+   * A consumer never creates an infrastructure queue: it is brought into being by
+   * the infrastructure service that owns it (`api/docs/standards/queue-ownership.md`),
+   * with the arguments the central `queueConfig` declares. What this client may do
+   * is ask whether it is there, so a publish that would otherwise vanish into the
+   * default exchange fails fast and says which queue is missing.
+   *
+   * The check goes through the core's queue channel (d.198b-3). Until then it opened
+   * a raw amqplib channel of its own, precisely because a 404 kills the channel it
+   * arrives on — the core owns that recreation now.
+   *
    * @param {string} queueName
    * @returns {Promise<void>}
    * @private
@@ -309,7 +385,7 @@ class ServiceRegistryClient extends EventEmitter {
       return;
     }
 
-    if (!queueConfig?.isInfrastructureQueue(queueName)) {
+    if (!queueConfig.isInfrastructureQueue(queueName)) {
       return;
     }
 
@@ -317,62 +393,28 @@ class ServiceRegistryClient extends EventEmitter {
       return;
     }
 
-    if (!this.queueManager?.conn) {
-      throw new Error(`[RegistryClient] ${this.serviceName}: MQ connection not ready, cannot verify infrastructure queue ${queueName}. Ensure RabbitMQ is accessible.`);
+    if (!this.queueManager.isConnected()) {
+      throw new Error(
+        `[RegistryClient] ${this.serviceName}: MQ connection not ready - cannot verify infrastructure queue ${queueName}. `
+        + 'Fix: complete init() first and check that RabbitMQ is accessible.'
+      );
     }
 
-    // Add timeout to prevent hanging
-    const QUEUE_VERIFY_TIMEOUT = 10000; // 10 seconds
-    const verifyPromise = (async () => {
-      let verificationChannel;
-      let channelTimeout;
-
-      try {
-        // Wrapped createChannel with timeout
-        const createChannelPromise = this.queueManager.conn.createChannel();
-        const createChannelTimeoutPromise = new Promise((_, reject) => {
-          channelTimeout = setTimeout(() => {
-            reject(new Error(`createChannel timeout after ${QUEUE_VERIFY_TIMEOUT / 2}ms`));
-          }, QUEUE_VERIFY_TIMEOUT / 2);
-        });
-
-        verificationChannel = await Promise.race([createChannelPromise, createChannelTimeoutPromise]);
-        if (channelTimeout) clearTimeout(channelTimeout);
-
-        await verificationChannel.checkQueue(queueName);
-        this._verifiedInfraQueues.add(queueName);
-      } catch (error) {
-        if (error.code === 404) {
-          throw new Error(`[RegistryClient] Infrastructure queue '${queueName}' is missing. Ensure the responsible infrastructure service has initialized it.`);
-        }
-        throw error;
-      } finally {
-        if (channelTimeout) clearTimeout(channelTimeout);
-        if (verificationChannel) {
-          try {
-            await verificationChannel.close();
-          } catch (closeErr) {
-            console.warn(`[RegistryClient] ${this.serviceName}: Failed to close verification channel for ${queueName}:`, closeErr.message);
-          }
-        }
-      }
-    })();
-
-    let verifyTimeout;
-    const timeoutPromise = new Promise((_, reject) => {
-      verifyTimeout = setTimeout(() => {
-        reject(new Error(`[RegistryClient] ${this.serviceName}: Timeout verifying infrastructure queue '${queueName}' after ${QUEUE_VERIFY_TIMEOUT}ms. Queue may not exist or RabbitMQ is unresponsive.`));
-      }, QUEUE_VERIFY_TIMEOUT);
-    });
-
     try {
-      await Promise.race([verifyPromise, timeoutPromise]);
+      await this.queueManager.checkQueue(queueName);
+      this._verifiedInfraQueues.add(queueName);
     } catch (error) {
-      // Clear verification cache on error so we can retry
+      // Cleared so the next call asks again: a queue that was missing a second ago
+      // may have been created by its owner since.
       this._verifiedInfraQueues.delete(queueName);
+      if (error.code === 404) {
+        throw new Error(
+          `[RegistryClient] Infrastructure queue '${queueName}' is missing - the broker answered 404 for it. `
+          + 'Fix: start the infrastructure service that owns this queue before this service registers.',
+          { cause: error }
+        );
+      }
       throw error;
-    } finally {
-      if (verifyTimeout) clearTimeout(verifyTimeout);
     }
   }
 
@@ -385,17 +427,27 @@ class ServiceRegistryClient extends EventEmitter {
    * @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.
    * @param {number} serviceInfo.timeout - Timeout for registration response (default: 30000ms)
-   * @returns {Promise<Object>} Registration result with success status
+   * @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
+   *   registry's machine reason for a refusal (`UNDECLARED_SERVICE`,
+   *   `INVALID_OPERATIONS_SCHEMA`, `VALIDATOR_UNAVAILABLE`, …) — branch on it rather
+   *   than on `message`, whose wording is not a contract. It is passed through
+   *   verbatim: `null` on a confirmed registration, `undefined` when the reply
+   *   carried no code at all.
+   * @see api/docs/biz/30-operations/registration-wire.md §8
    */
   async register(serviceInfo = {}) {
-    // DEBUG: Check validation proof status
-    console.log(`[RegistryClient] ${this.serviceName}: >>> REGISTER CALLED <<<`);
-    console.log(`[RegistryClient] ${this.serviceName}:     this.validationProof =`, this.validationProof);
-
     // Validate input
     if (serviceInfo.endpoints && !Array.isArray(serviceInfo.endpoints)) {
-      throw new Error('endpoints must be an array');
+      throw new Error(
+        '[RegistryClient] Invalid serviceInfo - endpoints must be an array. '
+        + 'Fix: pass endpoints as an array of endpoint descriptors, or omit the key entirely.'
+      );
     }
 
     // FAIL-FAST: a client that was never initialized, or that has been closed, is not
@@ -403,9 +455,9 @@ class ServiceRegistryClient extends EventEmitter {
     // channel WITHOUT restarting the response consumer started by init() - so the
     // registry answered into a queue nobody was reading and register() waited out the
     // full timeout. No fallbacks (architecture-principles §3), fail fast (§4).
-    if (!this.queueManager.channel) {
+    if (!this.queueManager.isConnected()) {
       throw new Error(
-        `[RegistryClient] ${this.serviceName}: Cannot register - the MQ channel is not open `
+        `[RegistryClient] ${this.serviceName}: Cannot register - the MQ connection is not open `
         + '(client not initialized or already closed). Expected: init() completed before register(). '
         + 'Fix: call init() on a fresh ServiceRegistryClient; a closed client is not reusable.'
       );
@@ -436,16 +488,31 @@ class ServiceRegistryClient extends EventEmitter {
       msg.workspaceScoped = serviceInfo.workspaceScoped;
     }
 
+    // The manifest-conformance verdict, verbatim from the caller: `true`, `false`,
+    // or `null` when validation stopped before step 7 measured it. The registry
+    // projects it into `infrastructure:health:<service>` beside `status`
+    // (owner confirmation `api/docs/governance/confirmations/biz-service-manifest.md`
+    // 001 §4), so `null` is a value this message must be able to carry — hence a
+    // presence check and not a truthiness one. A caller that sends no verdict
+    // (anything other than ServiceWrapper) puts no key on the wire; nothing is
+    // substituted for it.
+    if ('deployable' in serviceInfo) {
+      msg.deployable = serviceInfo.deployable;
+    }
+
     // Include validation proof if loaded
     // Structure: { validationProof: "hash", validationData: { ... } }
     // See: @onlineapps/service-validator-core/README.md#validation-proof-structure
     if (this.validationProof) {
       msg.validationProof = this.validationProof.validationProof;
       msg.validationData = this.validationProof.validationData;
-      console.log(`[RegistryClient] ${this.serviceName}: ✅ Including validation proof in registration message`);
-      console.log(`[RegistryClient] ${this.serviceName}:    Proof hash: ${this.validationProof.validationProof.substring(0, 32)}...`);
+      // The proof itself is reported on the "Registration message sent" line below;
+      // repeating it here would log the same fact twice per registration.
     } else {
-      console.log(`[RegistryClient] ${this.serviceName}: ⚠️  NO validation proof available - Registry will perform Tier 2 validation`);
+      this.logger.warn('[RegistryClient] Registering without a validation proof - registry will run Tier 2', {
+        serviceName: this.serviceName,
+        version: this.version
+      });
     }
 
     // Create promise to wait for registration response.
@@ -482,44 +549,56 @@ class ServiceRegistryClient extends EventEmitter {
     // Send registration message to registry
     // CRITICAL: Use queueConfig.js to get correct parameters (TTL, max-length, etc.)
     // This prevents 406 PRECONDITION-FAILED errors from TTL mismatches
-    console.log(`[RegistryClient] [PUBLISH] Preparing to publish to ${this.registryQueue}`);
-    
     try {
       await this._ensureInfrastructureQueue(this.registryQueue);
     } catch (queueError) {
-      const errorMsg = `[RegistryClient] ${this.serviceName}: Cannot register - infrastructure queue verification failed: ${queueError.message}`;
-      console.error(errorMsg);
-      throw this._abortPendingRegistration(msgId, new Error(errorMsg));
+      // Not logged before throwing: the rejection carries this exact message.
+      throw this._abortPendingRegistration(msgId, new Error(
+        `[RegistryClient] ${this.serviceName}: Cannot register - infrastructure queue verification failed: ${queueError.message}`
+      ));
     }
 
-    console.log(`[RegistryClient] ${this.serviceName}: Sending registration message to queue: ${this.registryQueue}`);
-    console.log(`[RegistryClient] ${this.serviceName}: Message type: ${msg.type}, serviceName: ${msg.serviceName}, version: ${msg.version}`);
-
-    // Send message synchronously (sendToQueue is synchronous, returns boolean).
-    // The channel existed when register() started; it can still have been closed while
-    // the infrastructure-queue check awaited above.
-    if (!this.queueManager.channel || this.queueManager.channel.closed) {
+    // The connection was open when register() started; it can still have been lost
+    // while the infrastructure-queue check awaited above.
+    if (!this.queueManager.isConnected()) {
       throw this._abortPendingRegistration(msgId, new Error(
-        `[RegistryClient] ${this.serviceName}: Cannot publish - the MQ channel closed before the registration `
-        + 'message was sent. Expected: an open channel for the whole register() call. '
+        `[RegistryClient] ${this.serviceName}: Cannot publish - the MQ connection closed before the registration `
+        + 'message was sent. Expected: an open connection for the whole register() call. '
         + 'Fix: re-create the client (init() + register()) once the MQ connection is back.'
       ));
     }
 
     try {
-      const sent = this.queueManager.channel.sendToQueue(
+      // The core's publish resolves or THROWS; there is no falsy return to read
+      // (@onlineapps/mq-client-core README § API — "publish() … failure is signalled
+      // by a thrown PublishError, never by a falsy return"). Serialisation is its
+      // job too, so the message travels as the object it is.
+      await this.queueManager.publish(
         this.registryQueue,
-        Buffer.from(JSON.stringify(msg)),
+        msg,
         { persistent: true }
       );
-      if (!sent) {
-        throw new Error(`[RegistryClient] ${this.serviceName}: sendToQueue returned false - queue may be full or channel backpressure active.`);
-      }
-      console.log(`[RegistryClient] ${this.serviceName}: ✓ Registration message sent, waiting for response...`);
+      // The one line per registration attempt: what was published, where, under
+      // which request id, and whether it carried a proof. Six stdout lines
+      // ("REGISTER CALLED", the proof pair, "Preparing to publish", "Sending
+      // registration message", "Message type") said this in pieces.
+      this.logger.info('[RegistryClient] Registration message sent', {
+        serviceName: this.serviceName,
+        version: this.version,
+        registryQueue: this.registryQueue,
+        responseQueue: this.serviceRegistryQueue,
+        requestId: msgId,
+        hasValidationProof: !!this.validationProof,
+        proofHash: this.validationProof
+          ? this.validationProof.validationProof.substring(0, 32)
+          : null,
+        timeoutMs: timeout
+      });
     } catch (sendError) {
-      const errorMsg = `[RegistryClient] ${this.serviceName}: Failed to send registration message: ${sendError.message}`;
-      console.error(errorMsg);
-      throw this._abortPendingRegistration(msgId, new Error(errorMsg));
+      // Not logged before throwing: the rejection carries this exact message.
+      throw this._abortPendingRegistration(msgId, new Error(
+        `[RegistryClient] ${this.serviceName}: Failed to send registration message: ${sendError.message}`
+      ));
     }
 
     this.emit('registerSent', msg);
@@ -529,16 +608,10 @@ class ServiceRegistryClient extends EventEmitter {
     // which is what a legitimate registry rejection looks like (e.g. missing
     // validation proof). The caller must be able to tell "the registry said no"
     // from "the registry never answered" (architecture-principles §3, §4).
-    console.log(`[RegistryClient] ${this.serviceName}: [AWAIT] Waiting for registration response promise...`);
-    const response = await responsePromise;
-    console.log(`[RegistryClient] ${this.serviceName}: [AWAIT] ✓ Promise resolved, response received:`, {
-      hasResponse: !!response,
-      responseType: typeof response,
-      responseKeys: response ? Object.keys(response) : [],
-      hasSuccess: !!response?.success,
-      hasCertificate: !!response?.certificate
-    });
-    return response;
+    // No log around the await: the same event is already reported once, from
+    // _handleRegistryMessage ("Registration resolved"), and a timeout or an abort
+    // rejects with a message of its own.
+    return responsePromise;
   }
 
   /**
@@ -566,7 +639,21 @@ class ServiceRegistryClient extends EventEmitter {
 
   /**
    * Deregisters the service from the registry.
-   * @returns {Promise<Object>} Deregistration result
+   *
+   * The registry sends NO reply to a `deregister`
+   * (api/docs/biz/30-operations/registration-wire.md §2.3 — `processDeregistration`
+   * removes the record and publishes `service.deregistered` to monitoring), so
+   * there is no verdict to report and none is invented. Until d.278c this method
+   * answered a hardcoded `{ success: true, message: 'Service deregistered
+   * successfully' }` whatever happened — a claim about the registry made by the
+   * one party that never heard from it.
+   *
+   * What this call knows, and therefore what it returns: the request it published,
+   * 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.
+   *
+   * @returns {Promise<{requestId: string, serviceName: string, version: string,
+   *   publishedTo: string, heartbeatStopped: boolean, publishedAt: string}>}
    */
   async deregister() {
     const msg = {
@@ -577,15 +664,18 @@ class ServiceRegistryClient extends EventEmitter {
       timestamp: new Date().toISOString()
     };
 
-    // Send deregistration message to registry
-    // CRITICAL: Use queueConfig.js to get correct parameters (TTL, max-length, etc.)
-    console.log(`[RegistryClient] [PUBLISH] Preparing to publish to ${this.registryQueue} (deregister)`);
     await this._ensureInfrastructureQueue(this.registryQueue);
-    this.queueManager.channel.sendToQueue(
+    await this.queueManager.publish(
       this.registryQueue,
-      Buffer.from(JSON.stringify(msg)),
+      msg,
       { persistent: true }
     );
+    this.logger.info('[RegistryClient] Deregistration request published', {
+      serviceName: this.serviceName,
+      version: this.version,
+      registryQueue: this.registryQueue,
+      requestId: msg.id
+    });
 
     this.emit('deregisterSent', msg);
 
@@ -593,10 +683,12 @@ class ServiceRegistryClient extends EventEmitter {
     this.stopHeartbeat();
 
     return {
-      success: true,
-      message: 'Service deregistered successfully',
+      requestId: msg.id,
       serviceName: this.serviceName,
-      version: this.version
+      version: this.version,
+      publishedTo: this.registryQueue,
+      heartbeatStopped: this.heartbeatTimer === null,
+      publishedAt: msg.timestamp
     };
   }
 
@@ -623,14 +715,19 @@ class ServiceRegistryClient extends EventEmitter {
       specificationEndpoint: this.specificationEndpoint,
       timestamp: new Date().toISOString()
     };
-    // CRITICAL: Use queueConfig.js to get correct parameters (TTL, max-length, etc.)
-    console.log(`[RegistryClient] [PUBLISH] Preparing to publish to ${this.registryQueue} (heartbeat)`);
     await this._ensureInfrastructureQueue(this.registryQueue);
-    this.queueManager.channel.sendToQueue(
+    await this.queueManager.publish(
       this.registryQueue,
-      Buffer.from(JSON.stringify(msg)),
+      msg,
       { persistent: true }
     );
+    // debug, not info: this repeats every heartbeatInterval, so at
+    // info it would bury every other line this client writes.
+    this.logger.debug('[RegistryClient] Heartbeat sent', {
+      serviceName: this.serviceName,
+      version: this.version,
+      registryQueue: this.registryQueue
+    });
     this.emit('heartbeatSent', msg);
   }
 
@@ -640,7 +737,10 @@ class ServiceRegistryClient extends EventEmitter {
   startHeartbeat() {
     // Send immediately after init
     this.sendHeartbeat().catch(err => {
-      console.error(`[RegistryClient] ${this.serviceName}: Initial heartbeat failed: ${err.message}`);
+      this.logger.error('[RegistryClient] Initial heartbeat failed', {
+        serviceName: this.serviceName,
+        error: err.message
+      });
     });
 
     // Repeat at the configured interval using a safe recursive timeout to avoid parallel runs
@@ -648,7 +748,10 @@ class ServiceRegistryClient extends EventEmitter {
       try {
         await this.sendHeartbeat();
       } catch (err) {
-        console.error(`[RegistryClient] ${this.serviceName}: Heartbeat failed: ${err.message}`);
+        this.logger.error('[RegistryClient] Heartbeat failed', {
+          serviceName: this.serviceName,
+          error: err.message
+        });
       } finally {
         // Schedule next heartbeat only after previous one finished (or failed)
         if (this.heartbeatTimer !== null) {
@@ -684,7 +787,8 @@ class ServiceRegistryClient extends EventEmitter {
         queueManager: this.queueManager,
         serviceName: this.serviceName,
         redis: this.redis,
-        storageConfig: this.storageConfig
+        storageConfig: this.storageConfig,
+        logger: this.logger
       });
 
       // Forward events from consumer
@@ -699,18 +803,6 @@ class ServiceRegistryClient extends EventEmitter {
     }
   }
 
-  /**
-   * Get service spec from event consumer (requires subscribeToChanges)
-   * @param {string} serviceName - Name of the service
-   * @returns {Promise<Object>} - Service specification
-   */
-  async getServiceSpec(serviceName) {
-    if (!this.eventConsumer) {
-      throw new Error('Event consumer not initialized. Call subscribeToChanges() first.');
-    }
-    return this.eventConsumer.getServiceSpec(serviceName);
-  }
-
   /**
    * Get basic service state for service discovery.
    *
@@ -731,8 +823,16 @@ class ServiceRegistryClient extends EventEmitter {
    * cookbook-router expects `{ status }`; the registry writes it lowercase
    * ('active'/'inactive') into the summary, so no normalization happens here.
    *
+   * @typedef {Object} ServiceSummary
+   * @property {string} serviceName
+   * @property {string} status - lowercase, as the registry writes it ('active'/'inactive')
+   * @property {string} [version]
+   * @property {string} [lastHeartbeatAt]
+   */
+
+  /**
    * @param {string} serviceName
-   * @returns {Promise<{serviceName: string, status: string, version?: string, lastHeartbeatAt?: string} | null>}
+   * @returns {Promise<ServiceSummary|null>}
    */
   async getService(serviceName) {
     if (!serviceName || typeof serviceName !== 'string') {
@@ -774,29 +874,6 @@ class ServiceRegistryClient extends EventEmitter {
     };
   }
 
-  /**
-   * Check if service is active (requires subscribeToChanges)
-   * @param {string} serviceName - Name of the service
-   * @returns {boolean}
-   */
-  isServiceActive(serviceName) {
-    if (!this.eventConsumer) {
-      throw new Error('Event consumer not initialized. Call subscribeToChanges() first.');
-    }
-    return this.eventConsumer.isServiceActive(serviceName);
-  }
-
-  /**
-   * Get list of active services (requires subscribeToChanges)
-   * @returns {Array<string>}
-   */
-  getActiveServices() {
-    if (!this.eventConsumer) {
-      return [];
-    }
-    return this.eventConsumer.getActiveServices();
-  }
-
   /**
    * Releases resources: stops heartbeat and closes connection.
    * @returns {Promise<void>}