@onlineapps/service-wrapper 3.3.5 → 3.4.1

package/CHANGELOG.md

@@ -0,0 +1,69 @@
+# Changelog — @onlineapps/service-wrapper
+
+All notable changes to this package. Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format and semantic versioning within the internal-monorepo convention (all biz-service consumers ship matching changes in the same session).
+
+## [3.4.1] — 2026-08-17
+
+**Patch: drop stale port/url/specificationEndpoint guards left over from A2.2.**
+
+Under 3.4.0 the wrapper still refused to start when `config.service.port`, `config.service.url`, or `config.service.specificationEndpoint` were absent — legacy checks from `_ensureValidationProof` and `_initializeRegistry` that predated ADR 0005 and were not removed together with the Express init in A2.2. Live rollout hit the failure on first biz restart (biz-property Phase 0.2: "Service port is required for validation").
+
+Removed:
+- Port + URL guard in `_ensureValidationProof` (before Tier-1 validation runs).
+- Port + URL guard in `_initializeRegistry` (before Registry registration).
+- specificationEndpoint guard in `_initializeRegistry`.
+
+Behaviour changes:
+- `serviceInfo.url` sent to Registry is now the empty string (was: required non-empty).
+- `specificationEndpoint` sent to RegistryClient is `''` when absent (was: throw).
+- Consumers: none — Registry stores the ops spec directly from the register payload; the URL and endpoint fields have had no live reader since 3.4.0 A2.
+
+Fully compatible with 3.4.0 tests (98/98 GREEN) and with 3.4.0 biz configs that still declare `port`/`url`/`specificationEndpoint` in `config/service/config.json` — they're just no longer required.
+
+## [3.4.0] — 2026-08-17
+
+**Zero-HTTP shape for biz services** (ADR 0005 landed). See `api/docs/biz/80-decisions/0005-no-http-in-biz-containers.md`.
+
+### BREAKING
+
+- **Constructor:** `options.app` and `options.server` no longer required. Passed values are accepted for transitional callers but IGNORED — the wrapper never binds an Express app or HTTP server.
+- **`bootstrap()`:** signature `bootstrap(serviceRoot, options)` no longer reads `options.app`, no longer resolves `require('./src/app')`, no longer calls `app.listen(PORT)`. Return value shape changed from `{wrapper, server}` to `{wrapper}` (no server exists).
+- **Removed HTTP endpoints:** `GET /`, `GET /health`, `GET /info`, `GET /status`, `GET /specification`. These no longer mount on any Express app. Consumers relying on HTTP-polling `/health` (e.g. Registry `businessReadinessChecker` pre-3.4.0) MUST switch to reading `infrastructureHealthTracker` state populated from the MQ heartbeat.
+- **Removed methods** (were private, listed for grep-completeness): `_setupHealthChecks`, `_setupInfoEndpoint`, `_getValidationInfo`, `_getStandardLevel`, `_getInfraFingerprint`, `_extractExpressRoutes`.
+- **Removed test suites**: `tests/unit/ServiceWrapper.healthDependencies.test.js` (whole file tested the retired HTTP `/health` handler). `tests/unit/ServiceWrapper.test.js` describes `/info endpoint` and `Operations-Routes Alignment` deleted (tested removed methods).
+
+### Added
+
+- **`wrapper.startHealthHeartbeat()`** — new public method. Wires the biz service into the existing MQ heartbeat mechanism (`createBaseClientAdapter` from `@onlineapps/infrastructure-tools`). First heartbeat is emitted synchronously by publisher `start()`.
+- **`wrapper.stopHealthHeartbeat()`** — cleanup counterpart; called from `_cleanupBeforeRestart`.
+- **`wrapper.refreshDependencyHealth()`** — periodic refresh of cached `_lastDbHealth` / `_lastRedisHealth` (was a side effect of `_setupHealthChecks`; now standalone).
+- **`wrapper._collectHeartbeatComponents()`** — private helper returning `{mq, redis, db, cache} → 'healthy'|'unhealthy'|'unknown'` map, matching the shape `infrastructureHealth.listener` validates.
+- **Bootstrap phase 0.10** — Health Heartbeat Publisher startup (documented in `api/docs/biz/50-lifecycle/tier1-validation.md`).
+- **New standard level v1.3** — Zero-HTTP Shape (documented in `api/docs/biz/00-model/service-shape.md`).
+
+### Dependencies
+
+- New: `@onlineapps/infrastructure-tools@1.2.4` (exact, provides the `createHealthPublisher` factory this version wires into).
+
+### Migration for biz services
+
+Every biz service under `api_biz/*/` has also been updated in the same session:
+- `docker-compose.yml` / `docker-compose.production.yml`: removed `ports:` section
+- `Dockerfile`: removed `EXPOSE` and `HEALTHCHECK`
+- No changes needed to handlers (they never touched Express directly)
+- `src/app.js` remains in each biz repo for now (bootstrap doesn't read it; deletion is a follow-up cleanup)
+
+Rollout order:
+1. `npm publish @onlineapps/service-wrapper@3.4.0`
+2. In each `api_biz/*/package.json`: exact `"@onlineapps/service-wrapper": "3.4.0"` + `npm install`
+3. Restart containers; verify `docker port <biz>` empty and `redis-cli KEYS 'infrastructure:health:*'` shows entries.
+
+### Rationale
+
+- Removes the last HTTP surface in biz containers. `_probeServiceHealth` (Registry) was the sole automated consumer; replaced by tracker reads.
+- Reduces service-wrapper code by ~950 lines net.
+- Unifies biz + infra service liveness path (same queue, same tracker, same Redis projection).
+
+## [3.3.5] — Pre-3.4.0 baseline
+
+Last version with Express-mounted health/info/status endpoints. No changelog for versions prior to 3.4.0.

package/README.md

@@ -246,7 +246,7 @@ Returns runtime information:
 - **Implementation standard level** — highest cumulative level satisfied (v1.0, v1.1, v1.2, ...)
 - **Revalidation state** — current backoff cycle status
 
-Standard levels are determined by `ServiceStructureValidator` from `@onlineapps/conn-orch-validator`. See [Implementation Standard Levels](/docs/standards/SERVICE_ENDPOINTS.md#implementation-standard-levels) and [Validator README](/shared/connector/conn-orch-validator/README.md#implementation-standard-levels).
+Standard levels are determined by `ServiceStructureValidator` from `@onlineapps/conn-orch-validator`. See [Implementation Standard Levels](/docs/biz/00-model/service-shape.md#implementation-standard-levels) and [Validator README](/shared/connector/conn-orch-validator/README.md#implementation-standard-levels).
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/service-wrapper",
-  "version": "3.3.5",
+  "version": "3.4.1",
   "description": "Thin orchestration layer for microservices - delegates all infrastructure concerns to specialized connectors",
   "main": "src/index.js",
   "scripts": {
@@ -34,6 +34,7 @@
     "@onlineapps/conn-orch-orchestrator": "2.1.3",
     "@onlineapps/conn-orch-registry": "1.2.2",
     "@onlineapps/conn-orch-validator": "3.2.3",
+    "@onlineapps/infrastructure-tools": "1.2.4",
     "@onlineapps/monitoring-core": "1.0.24",
     "@onlineapps/runtime-config": "1.0.2",
     "@onlineapps/service-common": "1.1.3",
@@ -46,6 +47,7 @@
     "jsdoc": "^4.0.2",
     "jsdoc-to-markdown": "^8.0.0"
   },
+  "//_express_devDep": "Express remains in devDependencies solely because a few legacy unit tests (ServiceWrapper.test.js, orchestrator-contract-v1.test.js) still construct Express apps for tests that were written before ADR 0005. Runtime never imports Express. The dep will be dropped when those tests migrate.",
   "engines": {
     "node": ">=14.0.0"
   }

package/src/ServiceWrapper.js

@@ -99,20 +99,22 @@ class ServiceWrapper {
   /**
    * Create a new ServiceWrapper instance
    * @param {Object} options - Configuration options
-   * @param {Object} options.app - Express application instance
-   * @param {Object} options.server - HTTP server instance
    * @param {Object} options.config - Service and wrapper configuration
    * @param {Object} options.operations - Operations schema
    * @param {string} [options.serviceRoot] - Service root directory (for validation)
    * @param {Object} [options.validationProof=null] - Optional validation proof {hash, data}
    * @param {Object} [options._validationOrchestrator=null] - Optional ValidationOrchestrator for testing
+   * @param {Object} [options.app] - IGNORED (transitional; ADR 0005 removed Express)
+   * @param {Object} [options.server] - IGNORED (transitional; ADR 0005 removed Express)
    */
   constructor(options = {}) {
     this._validateOptions(options);
 
     // Store configuration
-    this.app = options.app;
-    this.server = options.server;
+    // Zero-HTTP shape (ADR 0005): biz services do not own an Express app
+    // or HTTP server. `options.app` / `options.server` are accepted for
+    // transitional compatibility with callers still passing them, but the
+    // wrapper does not read them anywhere.
     this.config = this._processConfig(options.config);
     this.operations = options.operations;
     this.serviceRoot = options.serviceRoot;
@@ -137,7 +139,7 @@ class ServiceWrapper {
     this._errorMapper = null;
 
     // Fail-fast: enforce naming conventions and workspaceScoped invariants.
-    // See api/docs/standards/OPERATIONS.md and biz-service-onboarding.md §3.1 / §4.
+    // See api/docs/biz/30-operations/schema-v3.md and biz-service-onboarding.md §3.1 / §4.
     // Rejection here keeps the contract authoritative at the earliest possible
     // point (before MQ listeners, registry client, or any I/O is touched).
     this._validateNamingAndWorkspaceScoped();
@@ -309,12 +311,10 @@ class ServiceWrapper {
    * @private
    */
   _validateOptions(options) {
-    if (!options.app) {
-      throw new Error('Express app instance is required');
-    }
-    if (!options.server) {
-      throw new Error('HTTP server instance is required');
-    }
+    // Zero-HTTP shape (ADR 0005): biz services no longer own an Express app
+    // or HTTP server. `app` and `server` options are accepted but no longer
+    // required — they exist only as a transitional hint for callers still
+    // passing them. They MUST NOT be used inside the wrapper.
     if (!options.config) {
       throw new Error('Configuration is required');
     }
@@ -354,7 +354,7 @@ class ServiceWrapper {
         : null;
     if (!opsMap || typeof opsMap !== 'object') {
       throw new Error(
-        `[ServiceWrapper][${serviceName}] operations schema is invalid - expected object with 'operations' map of operation definitions; see api/docs/standards/OPERATIONS.md`
+        `[ServiceWrapper][${serviceName}] operations schema is invalid - expected object with 'operations' map of operation definitions; see api/docs/biz/30-operations/schema-v3.md`
       );
     }
     const offenders = Object.keys(opsMap).filter((key) => !kebabRegex.test(key));
@@ -362,7 +362,7 @@ class ServiceWrapper {
       throw new Error(
         `[ServiceWrapper][${serviceName}] operation key(s) violate kebab-case convention: ` +
           `${offenders.map((k) => `'${k}'`).join(', ')} - must match /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/. ` +
-          `See api/docs/standards/OPERATIONS.md §Best Practices - Naming Convention. ` +
+          `See api/docs/biz/30-operations/schema-v3.md §Best Practices - Naming Convention. ` +
           `Rename the key(s) in operations.json plus every cookbook/test/Admin UI literal; there is no alias layer.`
       );
     }
@@ -372,7 +372,7 @@ class ServiceWrapper {
     if (typeof ws !== 'boolean') {
       throw new Error(
         `[ServiceWrapper][${serviceName}] service.workspaceScoped is required and MUST be an explicit boolean in config.json (got ${ws === undefined ? 'undefined' : JSON.stringify(ws)}). ` +
-          `See api/docs/standards/biz-service-onboarding.md §3.1. ` +
+          `See api/docs/biz/60-templates/onboarding-checklist.md §3.1. ` +
           `true = service stores data keyed by workspace_id and implements list-workspaces operation; ` +
           `false = stateless or cross-workspace.`
       );
@@ -384,14 +384,14 @@ class ServiceWrapper {
       throw new Error(
         `[ServiceWrapper][${serviceName}] service.workspaceScoped is true but 'list-workspaces' operation is not declared. ` +
           `Workspace-scoped services MUST expose list-workspaces (workspace discovery convention). ` +
-          `See api/docs/standards/biz-service-onboarding.md §4 and OPERATIONS.md §Reserved operation names.`
+          `See api/docs/biz/60-templates/onboarding-checklist.md §4 and OPERATIONS.md §Reserved operation names.`
       );
     }
     if (ws === false && hasListWorkspaces) {
       throw new Error(
         `[ServiceWrapper][${serviceName}] service.workspaceScoped is false but 'list-workspaces' operation is declared. ` +
           `Stateless / cross-workspace services MUST NOT declare list-workspaces - the flag is the authoritative signal. ` +
-          `See api/docs/standards/biz-service-onboarding.md §4.`
+          `See api/docs/biz/60-templates/onboarding-checklist.md §4.`
       );
     }
   }
@@ -650,8 +650,11 @@ class ServiceWrapper {
   async _cleanupBeforeRestart() {
     const serviceName = this.config.service?.name || 'unnamed-service';
     console.log(`[CLEANUP] Starting cleanup for ${serviceName} before restart...`);
-    
+
     try {
+      // 0. Stop heartbeat publisher (Phase 0.10)
+      this.stopHealthHeartbeat();
+
       // 1. Cancel all consumers
       if (this.registryClient?.queueManager?.channel) {
         try {
@@ -919,10 +922,8 @@ class ServiceWrapper {
       // cache, monitoring, mq) and BEFORE MQ messages are dispatched.
       this._initializeInvocationPipeline();
 
-      // Setup health checks
-      if (this.config.wrapper?.health?.enabled !== false) {
-        this._setupHealthChecks();
-      }
+      // Legacy HTTP /health and /info endpoints — RETIRED per ADR 0005.
+      // Health surface flows via Phase 0.10 heartbeat below. No HTTP mount.
 
       // Initialize orchestrator for workflow processing
       // NOTE: Orchestrator is prepared but workflow listeners will be started
@@ -931,6 +932,26 @@ class ServiceWrapper {
         await this._initializeOrchestrator();
       }
 
+      // FÁZE 0.10: Health heartbeat publisher (ADR 0005 — replaces HTTP /health).
+      // Wires biz service into the existing infrastructure heartbeat mechanism
+      // used by gateway / validator / delivery_endpoint. First heartbeat is
+      // emitted synchronously by createHealthPublisher.start() so Registry can
+      // flip readiness immediately on boot.
+      if (this.mqClient && this.config.wrapper?.heartbeat?.enabled !== false) {
+        const heartbeatStartTime = Date.now();
+        try {
+          await this.startHealthHeartbeat();
+          this._logPhase('0.10', 'Health Heartbeat Publisher', 'PASSED', null, Date.now() - heartbeatStartTime);
+        } catch (error) {
+          // Transient: heartbeat failure should not block service operation.
+          // Registry will mark the service stale until heartbeats arrive.
+          this._logPhase('0.10', 'Health Heartbeat Publisher', 'FAILED', error, Date.now() - heartbeatStartTime);
+          this.logger?.warn('[ServiceWrapper] Heartbeat publisher failed to start; service continues without heartbeat', {
+            error: error.message
+          });
+        }
+      }
+
       this.isInitialized = true;
       this._logPhase('INIT', 'ServiceWrapper Initialization', 'PASSED', null, Date.now() - startTime);
       this.logger?.info(`ServiceWrapper initialized successfully for ${serviceName}`);
@@ -1213,15 +1234,11 @@ class ServiceWrapper {
       throw new Error('[ServiceWrapper] Missing configuration - service.name is required');
     }
 
-    const servicePort = this.config.service?.port;
-    if (!servicePort) {
-      throw new Error('[ServiceWrapper] Missing configuration - service.port is required');
-    }
-
-    const serviceUrl = this.config.service?.url;
-    if (!serviceUrl) {
-      throw new Error('[ServiceWrapper] Missing configuration - service.url is required');
-    }
+    // ADR 0005: biz has no HTTP — no port, no URL. Kept in serviceInfo
+    // payload as empty string for Registry-side backward compat with
+    // pre-3.4.1 consumers that may still expect the field.
+    const servicePort = null;
+    const serviceUrl = '';
 
     const mqUrl = this.config.wrapper?.mq?.url;
     if (!mqUrl) {
@@ -1232,14 +1249,11 @@ class ServiceWrapper {
     // FÁZE 0.5 a 0.6: Vytvoření front a spuštění konzumerů se provádí v registryClient.init()
     // FÁZE 0.7: Registrace u Registry
 
-    // FAIL-FAST: specificationEndpoint MUST be in config, no fallbacks
-    const specificationEndpoint = this.config.service?.specificationEndpoint;
-    if (!specificationEndpoint) {
-      throw new Error(
-        `[ServiceWrapper] Missing required configuration - service.specificationEndpoint is required. ` +
-        `Fix: Add "specificationEndpoint": "/api/v1/specification" to conn-config/config.json under "service" section.`
-      );
-    }
+    // ADR 0005: no HTTP surface → specificationEndpoint has no consumer.
+    // Registry receives full operations spec in the register payload
+    // itself. Field kept optional for pre-3.4.1 config files that may
+    // still declare it; ignored if absent.
+    const specificationEndpoint = this.config.service?.specificationEndpoint || '';
 
     // Logger may not be initialized yet at this point - RegistryClient handles null gracefully
     this.registryClient = new RegistryConnector.ServiceRegistryClient({
@@ -1507,236 +1521,180 @@ class ServiceWrapper {
   }
 
   /**
-   * Setup health check endpoint
-   * @private
+   * Refresh cached component health signals for the heartbeat.
+   *
+   * The heartbeat itself is fire-and-forget on a short interval; we do not
+   * probe DB/Redis on every heartbeat. Instead, this helper is invoked
+   * periodically (or on demand) to keep `_lastDbHealth` / `_lastRedisHealth`
+   * fresh so the next heartbeat carries meaningful status.
+   *
+   * Ties into `_checkDatabaseDependency` / `_checkRedisDependency` which
+   * remain the single source of truth for what "healthy" means.
+   *
+   * @returns {Promise<void>}
    */
-  _setupHealthChecks() {
-    const healthEndpoint = this.config.wrapper?.health?.endpoint || '/health';
-
-    const healthHandler = async (req, res) => {
-      const dependencyIssues = [];
-      const health = {
-        status: 'healthy',
-        service: this.config.service?.name || 'unnamed-service',
-        timestamp: new Date().toISOString(),
-        requiredConnectors: this.requiredConnectors || null,
-        components: {
-          http: 'healthy',
-          mq: 'disabled',
-          registry: this.registryClient ? 'healthy' : 'disabled',
-          cache: this.cacheConnector ? 'healthy' : 'disabled',
-          state: this.stateConnector ? 'healthy' : 'disabled',
-          database: this.requiredConnectors?.db === true ? 'unknown' : 'not_required',
-          redis: this.requiredConnectors?.redis === true ? 'unknown' : 'not_required'
-        }
-      };
-
-      if (this.mqClient) {
-        const transport = this.mqClient._transport;
-        if (transport && typeof transport.performHealthCheck === 'function') {
-          try {
-            const mqHealth = await transport.performHealthCheck();
-            health.components.mq = mqHealth.healthy ? 'healthy' : 'unhealthy';
-            if (!mqHealth.healthy) {
-              health.mqIssues = mqHealth.issues;
-            }
-          } catch (e) {
-            health.components.mq = 'unhealthy';
-            health.mqIssues = [e.message];
-          }
-        } else {
-          health.components.mq = this.mqClient.isConnected() ? 'healthy' : 'unhealthy';
-        }
-      }
-
-      if (!this.requiredConnectors) {
-        health.components.database = 'unhealthy';
-        health.components.redis = 'unhealthy';
-        dependencyIssues.push(
-          'Integration contract was not loaded - expected config/service/integration-contract.json during initialization'
-        );
-      } else {
+  async refreshDependencyHealth() {
+    if (!this.requiredConnectors) {
+      // Integration contract not loaded — dependency state is unknown.
+      this._lastDbHealth = 'unknown';
+      this._lastRedisHealth = 'unknown';
+      return;
+    }
+    if (this.requiredConnectors.db === true) {
+      try {
         const dbDependency = await this._checkDatabaseDependency();
-        health.components.database = dbDependency.status;
-        if (dbDependency.status === 'unhealthy' && dbDependency.reason) {
-          dependencyIssues.push(`[db] ${dbDependency.reason}`);
-        }
-
-        const redisDependency = await this._checkRedisDependency();
-        health.components.redis = redisDependency.status;
-        if (redisDependency.status === 'unhealthy' && redisDependency.reason) {
-          dependencyIssues.push(`[redis] ${redisDependency.reason}`);
-        }
+        this._lastDbHealth = dbDependency.status;
+      } catch (_) {
+        this._lastDbHealth = 'unhealthy';
       }
-
-      if (dependencyIssues.length > 0) {
-        health.dependencyIssues = dependencyIssues;
-      }
-
-      const statuses = Object.values(health.components);
-      if (statuses.includes('unhealthy')) {
-        health.status = 'unhealthy';
-        res.status(503);
-      } else {
-        res.status(200);
+    }
+    if (this.requiredConnectors.redis === true) {
+      try {
+        const redisDependency = await this._checkRedisDependency();
+        this._lastRedisHealth = redisDependency.status;
+      } catch (_) {
+        this._lastRedisHealth = 'unhealthy';
       }
-
-      res.json(health);
-    };
-
-    // Health route must be registered BEFORE catch-all 404/error handlers.
-    // Services register routes (including 404) in app.js before ServiceWrapper initializes.
-    // We use _healthHandler reference that bootstrap() registered early in the stack.
-    if (this._healthRouteRegistered) {
-      this._healthImpl = healthHandler;
-    } else {
-      this.app.get(healthEndpoint, healthHandler);
     }
-
-    this.logger?.info(`Health check endpoint registered at ${healthEndpoint}`);
-
-    this._setupInfoEndpoint();
   }
 
   /**
-   * Setup /info endpoint exposing versions, fingerprint, and validation status.
-   * Registered alongside /health — always available once wrapper is initialized.
-   * @private
+   * Start the health heartbeat publisher (ADR 0005, Phase 0.10).
+   *
+   * Wires this biz service into the existing infrastructure heartbeat
+   * mechanism at `@onlineapps/infrastructure-tools` — the same mechanism
+   * already used in production by api_gateway, api_services_validator,
+   * api_delivery_endpoint. Registry's `infrastructureHealth.listener`
+   * consumes the messages and `infrastructureHealthTracker` maintains
+   * the state.
+   *
+   * Payload shape follows the validated infra format:
+   *   { serviceName, version, status, timestamp,
+   *     components: { mq, redis, db, cache }, correlationId }
+   *
+   * First heartbeat is emitted synchronously by publisher.start().
+   * On publish failure, the shared publisher logs and continues — the
+   * service is not crashed by a heartbeat glitch.
+   *
+   * @returns {Promise<void>}
    */
-  _setupInfoEndpoint() {
-    const fs = require('fs');
-    const path = require('path');
-    const wrapperPkg = require('../package.json');
-
-    this.app.get('/info', async (req, res) => {
-      const serviceName = this.config.service?.name || 'unnamed-service';
-      const serviceVersion = this.config.service?.version || 'unknown';
-
-      const info = {
-        service: serviceName,
-        serviceVersion,
-        serviceWrapper: wrapperPkg.version,
-        timestamp: new Date().toISOString()
-      };
-
-      // Collect @onlineapps/* dependency versions from service package.json
-      info.dependencies = {};
-      if (this.serviceRoot) {
-        try {
-          const svcPkgPath = path.join(this.serviceRoot, 'package.json');
-          const svcPkg = JSON.parse(fs.readFileSync(svcPkgPath, 'utf8'));
-          const deps = svcPkg.dependencies || {};
-          for (const [name, version] of Object.entries(deps)) {
-            if (name.startsWith('@onlineapps/')) {
-              info.dependencies[name] = version;
-            }
-          }
-        } catch (e) {
-          info.dependencies._error = e.message;
-        }
-      }
-
-      // Validation proof and contract fingerprint
-      info.validation = this._getValidationInfo();
+  async startHealthHeartbeat() {
+    if (this._heartbeatPublisher) {
+      this.logger?.warn('[ServiceWrapper] Heartbeat publisher already started');
+      return;
+    }
+    if (!this.mqClient) {
+      throw new Error('[ServiceWrapper] mqClient is required to start heartbeat publisher');
+    }
 
-      // Infrastructure fingerprint from Redis (if cache available)
-      info.infraFingerprint = await this._getInfraFingerprint();
+    const { createBaseClientAdapter } = require('@onlineapps/infrastructure-tools');
+    const serviceName = this.config.service?.name || 'unnamed-service';
+    const serviceVersion = this.config.service?.version || '1.0.0';
 
-      // Standard level (determined from filesystem, not from validation proof)
-      info.standardLevel = this._getStandardLevel();
+    const getHealthData = () => this._collectHeartbeatComponents();
 
-      // Revalidation state
-      info.revalidation = {
-        state: this._revalidationState,
-        attempt: this._revalidationAttempt
-      };
+    // createBaseClientAdapter builds a publisher that uses BaseClient.publish;
+    // our mqClient exposes .publish so this is a direct fit.
+    this._heartbeatPublisher = createBaseClientAdapter(
+      this.mqClient,
+      serviceName,
+      getHealthData,
+      { ...(this.config.wrapper?.heartbeat || {}) },
+      this.logger
+    );
 
-      res.json(info);
-    });
+    // Some downstream consumers of createBaseClientAdapter attach the
+    // service version onto messages via the publisher constructor;
+    // createHealthPublisher accepts version only via options — we can
+    // rely on the tracker's `version: 'unknown'` default when absent.
+    void serviceVersion;
+
+    // Prime the cached dependency signals so the first heartbeat has
+    // meaningful component state instead of 'unknown' placeholders.
+    await this.refreshDependencyHealth();
+
+    // Periodic dependency refresh so subsequent heartbeats stay fresh
+    // without probing DB/Redis inside the sync getHealthData callback.
+    const refreshInterval = this.config.wrapper?.heartbeat?.dependencyRefreshMs || 10000;
+    this._heartbeatRefreshInterval = setInterval(() => {
+      this.refreshDependencyHealth().catch((e) => {
+        this.logger?.warn('[ServiceWrapper] Dependency refresh failed', { error: e.message });
+      });
+    }, refreshInterval);
 
-    this.logger?.info('Info endpoint registered at /info');
+    await this._heartbeatPublisher.start();
+    this.logger?.info(`[ServiceWrapper] Heartbeat publisher started for ${serviceName}`);
   }
 
   /**
-   * Collect validation proof info for /info endpoint.
+   * Snapshot of connector-oriented component health for the heartbeat
+   * `components` map. Values are one of 'healthy' | 'unhealthy' | 'unknown',
+   * matching what `infrastructureHealth.listener` accepts.
+   *
+   * The connector-orientation (mq/redis/db/cache) matches what the legacy
+   * HTTP /health handler already computes via _checkDatabaseDependency /
+   * _checkRedisDependency; here we produce the same signals in the shape
+   * the shared listener validates.
+   *
    * @private
-   * @returns {Object} Validation status summary
+   * @returns {Object<string, 'healthy'|'unhealthy'|'unknown'>}
    */
-  _getValidationInfo() {
-    const fs = require('fs');
-    const path = require('path');
+  _collectHeartbeatComponents() {
+    const components = {
+      mq: 'unknown',
+      redis: 'unknown',
+      db: 'unknown',
+      cache: 'unknown'
+    };
 
-    if (!this.serviceRoot) {
-      return { status: 'no_service_root' };
+    // MQ — mqClient is the transport; if isConnected() returns true it is up.
+    if (this.mqClient && typeof this.mqClient.isConnected === 'function') {
+      try {
+        components.mq = this.mqClient.isConnected() ? 'healthy' : 'unhealthy';
+      } catch (_) {
+        components.mq = 'unhealthy';
+      }
+    } else if (this.mqClient) {
+      components.mq = 'healthy';
     }
 
-    const proofPath = path.join(this.serviceRoot, PROOF_RELATIVE_PATH);
-
-    if (!fs.existsSync(proofPath)) {
-      return { status: 'no_proof' };
+    // Redis / DB / cache — heartbeat is fire-and-forget so we only sample
+    // the last known state; the full async probe belongs to the periodic
+    // dependency checks, not to every 5-second heartbeat.
+    if (!this.requiredConnectors) {
+      // Integration contract not loaded — treat DB/redis as not required.
+      components.db = 'unknown';
+      components.redis = 'unknown';
+    } else {
+      components.db = this.requiredConnectors.db === true
+        ? (this._lastDbHealth || 'unknown')
+        : 'unknown';
+      components.redis = this.requiredConnectors.redis === true
+        ? (this._lastRedisHealth || 'unknown')
+        : 'unknown';
     }
 
-    try {
-      const raw = JSON.parse(fs.readFileSync(proofPath, 'utf8'));
-      const data = raw.validationData || {};
+    components.cache = this.cacheConnector ? 'healthy' : 'unknown';
 
-      const validatedAt = data.validatedAt ? new Date(data.validatedAt) : null;
-      const ageMs = validatedAt ? Date.now() - validatedAt.getTime() : null;
-
-      return {
-        status: 'valid',
-        contractFingerprint: data.contractFingerprint || null,
-        validatedAt: data.validatedAt || null,
-        proofAge: ageMs !== null ? `${Math.round(ageMs / 60000)}m` : null,
-        validatorVersion: data.validatorVersion || null,
-        testsRun: data.testsRun ?? null,
-        testsPassed: data.testsPassed ?? null
-      };
-    } catch (e) {
-      return { status: 'error', error: e.message };
-    }
+    return components;
   }
 
   /**
-   * Determine the implementation standard level from the filesystem.
-   * Uses ServiceStructureValidator's standard level checks.
-   * @private
-   * @returns {{ level: string|null, details: Array }}
+   * Stop the heartbeat publisher (used in cleanup paths).
+   * @returns {void}
    */
-  _getStandardLevel() {
-    if (!this.serviceRoot) {
-      return { level: null, details: [] };
+  stopHealthHeartbeat() {
+    if (this._heartbeatRefreshInterval) {
+      clearInterval(this._heartbeatRefreshInterval);
+      this._heartbeatRefreshInterval = null;
     }
-
-    try {
-      const { ServiceStructureValidator } = require('@onlineapps/conn-orch-validator/src/validators/ServiceStructureValidator');
-      const validator = new ServiceStructureValidator(this.serviceRoot);
-      return validator.determineStandardLevel();
-    } catch (e) {
-      return { level: null, error: e.message };
-    }
-  }
-
-  /**
-   * Read infra:fingerprint from Redis (if cache connector is available).
-   * @private
-   * @returns {Promise<Object|null>}
-   */
-  async _getInfraFingerprint() {
-    if (!this.cacheConnector) {
-      return null;
-    }
-
-    try {
-      const raw = await this.cacheConnector.get('infra:fingerprint');
-      if (!raw) return null;
-      const parsed = typeof raw === 'string' ? JSON.parse(raw) : raw;
-      return {
-        hash: parsed.hash || null,
-        timestamp: parsed.timestamp || null
-      };
-    } catch (e) {
-      return { error: e.message };
+    if (this._heartbeatPublisher) {
+      try {
+        this._heartbeatPublisher.stop();
+      } catch (e) {
+        this.logger?.warn('[ServiceWrapper] Heartbeat stop() threw', { error: e.message });
+      }
+      this._heartbeatPublisher = null;
     }
   }
 
@@ -2162,49 +2120,6 @@ class ServiceWrapper {
     throw err;
   }
 
-  /**
-   * Extract all registered Express routes from the app router stack.
-   * Handles nested Router instances (e.g. app.use('/api', router)).
-   * Compatible with Express 4 (app._router) and Express 5 (app.router).
-   * @private
-   * @returns {Array<{method: string, path: string}>}
-   */
-  _extractExpressRoutes() {
-    const routes = [];
-    const stack = this.app._router?.stack || this.app.router?.stack || [];
-
-    const extractFromStack = (layers, prefix) => {
-      for (const layer of layers) {
-        if (layer.route) {
-          for (const method of Object.keys(layer.route.methods)) {
-            routes.push({ method: method.toUpperCase(), path: `${prefix}${layer.route.path}` });
-          }
-        } else if (layer.name === 'router' && layer.handle?.stack) {
-          let mountPath = '';
-
-          // Express 4: extract prefix from regexp
-          // Multi-segment paths like /api/v1 produce regexp source ^\/api\/v1\/?...
-          // Each path segment is escaped as \/segment, so we capture all segments.
-          if (layer.regexp?.source) {
-            const match = layer.regexp.source.match(/^\^((?:\\\/[a-zA-Z0-9_.~-]+)+)/);
-            if (match) mountPath = match[1].replace(/\\\//g, '/');
-          }
-
-          // Express 5: probe the matcher to discover mount prefix
-          if (!mountPath && layer.matchers?.[0]) {
-            const probe = layer.matchers[0]('/api');
-            if (probe && probe.path) mountPath = probe.path;
-          }
-
-          extractFromStack(layer.handle.stack, `${prefix}${mountPath}`);
-        }
-      }
-    };
-
-    extractFromStack(stack, '');
-    return routes;
-  }
-
   /**
    * Instantiate the v3 invocation pipeline (HandlerRegistry, SchemaValidator,
    * ContextBuilder, ErrorMapper, HandlerLoader). Called from initialize()
@@ -2699,16 +2614,11 @@ class ServiceWrapper {
       throw new Error('Service version is required for validation');
     }
 
-    const { name: serviceName, version: serviceVersion, port: servicePort } = this.config.service;
-
-    if (!servicePort) {
-      throw new Error('Service port is required for validation (config.service.port)');
-    }
+    const { name: serviceName, version: serviceVersion } = this.config.service;
 
-    const serviceUrl = this.config.service?.url;
-    if (!serviceUrl) {
-      throw new Error('[ServiceWrapper] Missing configuration - config.service.url is required for validation (set SERVICE_URL in conn-config/config.json placeholder)');
-    }
+    // ADR 0005: biz services have no HTTP surface — no port to bind, no
+    // URL to advertise. Prior versions of this method required both;
+    // dropped in 3.4.1 because they had no consumer post-A2.
 
     // Phase 5: Check restart-aware failure tracking
     const failureData = this._readValidationFailureFile();

package/src/createTenantContextMiddleware.js

@@ -1,6 +1,6 @@
 'use strict';
 
-// See: docs/standards/tenant-context-contract.md
+// See: docs/biz/20-tenancy/tenant-context.md
 /**
  * Tenant context middleware — requires x-tenant-id + x-workspace-id headers.
  *

package/src/index.js

@@ -22,136 +22,60 @@ const { createTenantContextMiddleware } = require('./createTenantContextMiddlewa
 // @onlineapps/conn-orch-orchestrator. The former ApiCaller /
 // @onlineapps/conn-orch-api-mapper was retired 2026-04-21 (ADR-0001);
 // per-operation dispatch happens in-process via HandlerRegistry.
-
-// Note: HTTP logging middleware is now in each service's middlewares/httpLogging.js
-// It uses lazy logger access via lib/logger.js (set after wrapper.initialize())
+//
+// ADR 0005 (2026-08-17): biz containers run zero HTTP. bootstrap() does
+// not create or listen on any Express app. Status flows via the MQ
+// heartbeat mechanism at @onlineapps/infrastructure-tools, consumed by
+// Registry's infrastructureHealth.listener. See docs/biz/80-decisions/0005-.
 
 /**
- * Bootstrap a business service with standard configuration
- * Eliminates boilerplate code in service index.js
- * 
+ * Bootstrap a business service with standard configuration.
+ * Eliminates boilerplate code in service index.js.
+ *
+ * Zero-HTTP shape (ADR 0005): no Express app is created, no port is bound.
+ * Business operations flow via MQ + in-process HandlerRegistry dispatch.
+ * Health flows via MQ heartbeat (Phase 0.10 inside wrapper.initialize()).
+ *
  * @param {string} serviceRoot - Service root directory (__dirname from index.js)
  * @param {Object} [options] - Optional overrides
- * @param {Object} [options.app] - Express app (default: require('./src/app'))
  * @param {Object} [options.config] - Config (default: require('./src/config'))
  * @param {Function} [options.setLogger] - Logger setter (default: require('./src/lib/logger').setLogger)
- * @returns {Promise<{wrapper: ServiceWrapper, server: Object}>}
- * 
+ * @param {string} [options.serviceBaseDir] - Handler base dir (default: <serviceRoot>/src)
+ * @returns {Promise<{wrapper: ServiceWrapper}>}
+ *
  * @example
  * // index.js (minimal)
  * require('@onlineapps/service-wrapper').bootstrap(__dirname);
  */
 async function bootstrap(serviceRoot, options = {}) {
-  // Load app, config, and logger from service
-  const app = options.app || require(path.join(serviceRoot, 'src', 'app'));
   const config = options.config || require(path.join(serviceRoot, 'src', 'config'));
-  
-  // Logger setter is optional - some services may not have it
+
+  // Logger setter is optional — some services may not have one.
   let setLogger = options.setLogger;
   if (!setLogger) {
     try {
       const loggerModule = require(path.join(serviceRoot, 'src', 'lib', 'logger'));
       setLogger = loggerModule.setLogger;
     } catch (e) {
-      // No logger module - that's OK
       setLogger = () => {};
     }
   }
 
   console.log(`Starting ${config.service.name} v${config.service.version}...`);
 
-  // 0. Apply shared tenant context middleware (x-tenant-id + x-workspace-id + x-person-id)
-  const tenantContextMw = createTenantContextMiddleware({
-    serviceName: config.service.name,
-    tenantContext: config.wrapper?.tenantContext
-  });
-  app.use(tenantContextMw);
-
-  // Express routes are processed in registration order.
-  // Services usually register routes inside src/app BEFORE bootstrap runs, so app.use() here would be too late.
-  // We must enforce tenant context BEFORE routes: move our middleware to the beginning of the router stack.
-  // Fail-fast if we cannot guarantee correct order.
-  if (!app || !app._router || !Array.isArray(app._router.stack) || app._router.stack.length === 0) {
-    throw new Error(
-      `[service-wrapper][TenantContext] Cannot enforce tenant context - Express router stack not available. ` +
-      `Fix: ensure the service exports an Express app instance with registered routes before bootstrap.`
-    );
-  }
-
-  const stack = app._router.stack;
-  const lastLayer = stack[stack.length - 1];
-  const isOurMiddleware =
-    lastLayer &&
-    lastLayer.handle &&
-    typeof lastLayer.handle === 'function' &&
-    lastLayer.handle.name === tenantContextMw.name;
-
-  if (!isOurMiddleware) {
-    throw new Error(
-      `[service-wrapper][TenantContext] Cannot enforce tenant context - middleware placement is not deterministic. ` +
-      `Fix: ensure bootstrap registers tenant context middleware before routes, or update service to export app factory.`
-    );
-  }
-
-  stack.pop();
-  // Insert AFTER expressInit (which sets up res.status/res.json via setPrototypeOf).
-  // Position 0 = query, 1 = expressInit. Tenant context must run after both.
-  const expressInitIdx = stack.findIndex(l => l.name === 'expressInit');
-  if (expressInitIdx === -1) {
-    throw new Error(
-      '[service-wrapper][TenantContext] Express stack missing expressInit layer - ' +
-      'cannot guarantee tenant context runs after Express initialization'
-    );
-  }
-  stack.splice(expressInitIdx + 1, 0, lastLayer);
-
-  // Register /health route BEFORE service's 404 handler.
-  // ServiceWrapper._setupHealthChecks() will later set _healthImpl with actual MQ checks.
-  // Until then, this returns a basic healthy response (service is starting up).
-  let wrapperRef = null;
-  const healthEndpoint = config.wrapper?.health?.endpoint || '/health';
-  app.get(healthEndpoint, async (req, res) => {
-    if (wrapperRef && wrapperRef._healthImpl) {
-      return wrapperRef._healthImpl(req, res);
-    }
-    res.json({ status: 'starting', service: config.service.name, timestamp: new Date().toISOString() });
-  });
-
-  // Move health route before 404/error handlers (same stack technique as tenant context)
-  const healthLayer = stack.pop();
-  if (healthLayer) {
-    const catchAllIdx = stack.findIndex((layer, i) =>
-      i > 0 && !layer.route && !['query', 'expressInit', 'tenantContextMiddleware', 'jsonParser', 'urlencodedParser'].includes(layer.name)
-    );
-    if (catchAllIdx > 0) {
-      stack.splice(catchAllIdx, 0, healthLayer);
-    } else {
-      stack.push(healthLayer);
-    }
-  }
-
-  // 1. Start HTTP server
-  const PORT = config.service.port;
-  const server = app.listen(PORT, () => {
-    console.log(`✓ HTTP server listening on port ${PORT}`);
-    console.log(`✓ Health check: /health`);
-  });
-
-  // 2. Initialize Service Wrapper (MQ, Registry, Monitoring, etc.)
-  // v3 invocation model: HandlerLoader requires the service's src/ as base
-  // dir for resolving handler refs (RFC §5.9). Biz services may override by
-  // passing options.serviceBaseDir via bootstrap().
+  // v3 invocation model: HandlerLoader requires the service's src/ as the
+  // base dir for resolving handler refs (RFC §5.9). Biz services may
+  // override via options.serviceBaseDir.
   const serviceBaseDir = options.serviceBaseDir || path.join(serviceRoot, 'src');
+
   const wrapper = new ServiceWrapper({
-    app,
-    server,
     serviceRoot,
     serviceBaseDir,
     config: {
       service: {
         name: config.service.name,
         version: config.service.version,
-        port: config.service.port,
+        // `port` intentionally omitted — no HTTP surface in biz containers.
         url: config.service.url,
         specificationEndpoint: config.service.specificationEndpoint,
         description: config.service.description,
@@ -164,33 +88,31 @@ async function bootstrap(serviceRoot, options = {}) {
     validationProof: config.validationProof
   });
 
-  wrapper._healthRouteRegistered = true;
   await wrapper.initialize();
-  wrapperRef = wrapper;
 
-  // Initialize centralized logger for use throughout the service
   if (setLogger && wrapper.logger) {
     setLogger(wrapper.logger);
   }
 
-  console.log(`✓ Service Wrapper initialized (MQ, Registry, Monitoring)`);
+  console.log(`✓ Service Wrapper initialized (MQ, Registry, Monitoring, Heartbeat)`);
   console.log(`✓ Local logs: logs/app.{date}.log`);
   console.log(`✓ ${config.service.name} ready\n`);
 
-  // 3. Setup graceful shutdown
+  // Graceful shutdown — no HTTP server to close, just tear down the wrapper.
   const shutdown = async () => {
     console.log('\nShutting down gracefully...');
-    await wrapper.shutdown();
-    server.close(() => {
-      console.log('Server closed');
-      process.exit(0);
-    });
+    if (typeof wrapper.shutdown === 'function') {
+      await wrapper.shutdown();
+    } else if (typeof wrapper.stopHealthHeartbeat === 'function') {
+      wrapper.stopHealthHeartbeat();
+    }
+    process.exit(0);
   };
 
   process.on('SIGTERM', shutdown);
   process.on('SIGINT', shutdown);
 
-  return { wrapper, server };
+  return { wrapper };
 }
 
 // v3 invocation-model components (RFC §5.9): exported for biz services
@@ -225,4 +147,4 @@ module.exports.ErrorMapper = ErrorMapper;
 module.exports.ValidationError = ValidationError;
 module.exports.UnknownOperationError = UnknownOperationError;
 module.exports.BusinessError = BusinessError;
-module.exports.AbortError = AbortError;
+module.exports.AbortError = AbortError;