@onlineapps/service-wrapper 2.1.109 → 2.1.110

package/README.md

@@ -29,7 +29,8 @@ This package provides the infrastructure layer that sits between:
 - **Service registration** - Auto-registers with service registry
 - **API-to-Cookbook mapping** - Converts workflow steps to API calls
 - **Error handling** - Retry logic, DLQ routing
-- **Health checks** - Automatic health endpoint
+- **Health checks** - Automatic health endpoint (`GET /health`)
+- **Info endpoint** - Runtime version, validation, and standard level info (`GET /info`)
 
 ## Architecture
 
@@ -234,6 +235,21 @@ describe('My Service', () => {
 });
 ```
 
+## Info Endpoint
+
+ServiceWrapper automatically registers `GET /info` on every business service. No implementation needed.
+
+Returns runtime information:
+- **Service & wrapper versions** + all `@onlineapps/*` dependency versions
+- **Validation status** — contract fingerprint, proof age, test results
+- **Infrastructure fingerprint** — library manifest hash from Redis
+- **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).
+
+---
+
 ## Migration from Embedded Infrastructure
 
 If your service currently has workflow code:

package/config/runtime-defaults.json

@@ -43,9 +43,8 @@
       "validation": {
         "enabled": true
       },
-      "accountContext": {
+      "tenantContext": {
         "enabled": true,
-        "headerName": "account-id",
         "requirePathPrefixes": ["/api/"],
         "excludePathPrefixes": ["/api/v1/specification", "/api/health"]
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/service-wrapper",
-  "version": "2.1.109",
+  "version": "2.1.110",
   "description": "Thin orchestration layer for microservices - delegates all infrastructure concerns to specialized connectors",
   "main": "src/index.js",
   "scripts": {
@@ -28,9 +28,9 @@
     "@onlineapps/conn-base-monitoring": "1.0.9",
     "@onlineapps/conn-infra-error-handler": "1.0.8",
     "@onlineapps/conn-infra-mq": "1.1.67",
-    "@onlineapps/conn-orch-api-mapper": "1.0.29",
+    "@onlineapps/conn-orch-api-mapper": "1.0.30",
     "@onlineapps/conn-orch-cookbook": "2.0.35",
-    "@onlineapps/conn-orch-orchestrator": "1.0.101",
+    "@onlineapps/conn-orch-orchestrator": "1.0.102",
     "@onlineapps/conn-orch-registry": "1.1.52",
     "@onlineapps/conn-orch-validator": "2.0.28",
     "@onlineapps/monitoring-core": "1.0.20",

package/src/ServiceWrapper.js

@@ -24,6 +24,10 @@ const ErrorHandlerConnector = require('@onlineapps/conn-infra-error-handler');
 const { ValidationOrchestrator } = require('@onlineapps/conn-orch-validator');
 const runtimeCfg = require('./config');
 
+const REVALIDATION_FAST_BACKOFF_MS = [30000, 60000, 120000, 300000, 600000, 1800000];
+const REVALIDATION_DAILY_MS = 86400000;
+const REVALIDATION_STATE = { IDLE: 'idle', FAST_BACKOFF: 'fast_backoff', DAILY_BACKOFF: 'daily_backoff', SUCCEEDED: 'succeeded' };
+
 const INFRA_QUEUE_OWNERS = {
   'workflow.init': 'Gateway (api_gateway)',
   'workflow.control': 'Gateway (api_gateway)',
@@ -72,6 +76,12 @@ class ServiceWrapper {
 
     // State
     this.isInitialized = false;
+
+    // Revalidation state (Phases 3-6: infra invalidation + auto re-validation)
+    this._revalidationState = REVALIDATION_STATE.IDLE;
+    this._revalidationAttempt = 0;
+    this._revalidationTimer = null;
+    this._infraInvalidationConsumerTag = null;
   }
 
   /**
@@ -91,9 +101,14 @@ class ServiceWrapper {
   async _startWorkflowListenersIfReady(registrationResult, serviceName) {
     // Condition 1: Service must be validated and registered (certificate required)
     if (!(registrationResult?.success && registrationResult.certificate)) {
-      this.logger?.warn('⚠ Registration succeeded but no certificate received - workflow listeners NOT started');
-      this.logger?.warn('⚠ Business queues will NOT be created until certificate is received');
-      return;
+      const reason = !registrationResult?.success
+        ? `success=${registrationResult?.success}, message=${registrationResult?.message || 'none'}`
+        : 'certificate missing from registration result';
+      throw new Error(
+        `[ServiceWrapper][Registration] Service ${serviceName} did not receive certificate - ${reason}. ` +
+        'Service cannot start workflow listeners without valid certificate. ' +
+        'Docker will restart the service to retry registration.'
+      );
     }
 
     this.logger?.info('✓ Certificate validated (service is validated and registered), verifying infrastructure readiness...');
@@ -146,6 +161,15 @@ class ServiceWrapper {
       });
       throw new Error(`Failed to start workflow listeners for ${serviceName}: ${listenerError.message}`);
     }
+
+    // Phase 0.10: Subscribe to infrastructure invalidation events
+    try {
+      await this._subscribeToInfraInvalidation(serviceName);
+    } catch (subErr) {
+      this.logger?.warn('[ServiceWrapper][infra.invalidation] Failed to subscribe to invalidation events (non-critical)', {
+        error: subErr.message
+      });
+    }
   }
 
   /**
@@ -405,6 +429,11 @@ class ServiceWrapper {
       this.workflowInitConsumerTag = null;
       this.workflowControlConsumerTag = null;
       this.serviceWorkflowConsumerTag = null;
+      this._infraInvalidationConsumerTag = null;
+      if (this._revalidationTimer) {
+        clearTimeout(this._revalidationTimer);
+        this._revalidationTimer = null;
+      }
       this.isInitialized = false;
 
       console.log(`[CLEANUP] ✓ Cleanup completed`);
@@ -1056,6 +1085,150 @@ class ServiceWrapper {
     });
 
     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
+   */
+  _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();
+
+      // Infrastructure fingerprint from Redis (if cache available)
+      info.infraFingerprint = await this._getInfraFingerprint();
+
+      // Standard level (determined from filesystem, not from validation proof)
+      info.standardLevel = this._getStandardLevel();
+
+      // Revalidation state
+      info.revalidation = {
+        state: this._revalidationState,
+        attempt: this._revalidationAttempt
+      };
+
+      res.json(info);
+    });
+
+    this.logger?.info('Info endpoint registered at /info');
+  }
+
+  /**
+   * Collect validation proof info for /info endpoint.
+   * @private
+   * @returns {Object} Validation status summary
+   */
+  _getValidationInfo() {
+    const fs = require('fs');
+    const path = require('path');
+
+    if (!this.serviceRoot) {
+      return { status: 'no_service_root' };
+    }
+
+    const proofPath = path.join(this.serviceRoot, 'conn-runtime', 'validation-proof.json');
+
+    if (!fs.existsSync(proofPath)) {
+      return { status: 'no_proof' };
+    }
+
+    try {
+      const raw = JSON.parse(fs.readFileSync(proofPath, 'utf8'));
+      const data = raw.validationData || {};
+
+      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 };
+    }
+  }
+
+  /**
+   * Determine the implementation standard level from the filesystem.
+   * Uses ServiceStructureValidator's standard level checks.
+   * @private
+   * @returns {{ level: string|null, details: Array }}
+   */
+  _getStandardLevel() {
+    if (!this.serviceRoot) {
+      return { level: null, details: [] };
+    }
+
+    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 };
+    }
   }
 
   /**
@@ -1424,6 +1597,262 @@ class ServiceWrapper {
     });
   }
 
+  /**
+   * Subscribe to infra.invalidation events on the infrastructure.health.events fanout exchange.
+   * When received, deletes local validation proof and triggers re-validation with backoff.
+   * @private
+   */
+  async _subscribeToInfraInvalidation(serviceName) {
+    if (!this.mqClient?._transport?.channel) {
+      this.logger?.debug('[ServiceWrapper][infra.invalidation] No MQ channel available — skipping subscription');
+      return;
+    }
+
+    const channel = this.mqClient._transport.channel;
+    const exchangeName = 'infrastructure.health.events';
+
+    await channel.assertExchange(exchangeName, 'fanout', { durable: true });
+
+    const q = await channel.assertQueue('', { exclusive: true, autoDelete: true });
+
+    await channel.bindQueue(q.queue, exchangeName, '');
+
+    const { consumerTag } = await channel.consume(q.queue, async (msg) => {
+      if (!msg) return;
+
+      try {
+        const event = JSON.parse(msg.content.toString());
+
+        if (event.type !== 'infra.invalidation') {
+          channel.ack(msg);
+          return;
+        }
+
+        this.logger?.info('[ServiceWrapper][infra.invalidation] Infrastructure change detected, scheduling re-validation', {
+          fingerprint: event.fingerprint?.substring(0, 16) + '...',
+          timestamp: event.timestamp
+        });
+
+        // Delete local validation proof
+        const fs = require('fs');
+        const path = require('path');
+        if (this.serviceRoot) {
+          const proofPath = path.join(this.serviceRoot, 'conn-runtime', 'validation-proof.json');
+          if (fs.existsSync(proofPath)) {
+            fs.unlinkSync(proofPath);
+            this.logger?.info('[ServiceWrapper][infra.invalidation] Deleted local validation proof', { proofPath });
+          }
+        }
+
+        this._revalidateWithBackoff();
+
+      } catch (parseErr) {
+        this.logger?.warn('[ServiceWrapper][infra.invalidation] Failed to parse event', { error: parseErr.message });
+      }
+
+      channel.ack(msg);
+    });
+
+    this._infraInvalidationConsumerTag = consumerTag;
+    this.logger?.info('[ServiceWrapper][infra.invalidation] Subscribed to infrastructure invalidation events', {
+      exchange: exchangeName,
+      queue: q.queue,
+      consumerTag
+    });
+  }
+
+  /**
+   * Trigger re-validation with exponential backoff.
+   * Only one cycle is active at a time — duplicate calls while a cycle is running are ignored.
+   * @private
+   */
+  _revalidateWithBackoff() {
+    if (this._revalidationState === REVALIDATION_STATE.FAST_BACKOFF ||
+        this._revalidationState === REVALIDATION_STATE.DAILY_BACKOFF) {
+      this.logger?.info('[ServiceWrapper][revalidation] Ignoring duplicate invalidation — re-validation cycle already active', {
+        state: this._revalidationState,
+        attempt: this._revalidationAttempt
+      });
+      return;
+    }
+
+    this._revalidationState = REVALIDATION_STATE.FAST_BACKOFF;
+    this._revalidationAttempt = 0;
+    this._scheduleRevalidationAttempt();
+  }
+
+  /**
+   * Schedule the next re-validation attempt based on current state and attempt count.
+   * @private
+   */
+  _scheduleRevalidationAttempt() {
+    let delayMs;
+
+    if (this._revalidationState === REVALIDATION_STATE.DAILY_BACKOFF) {
+      delayMs = REVALIDATION_DAILY_MS;
+    } else if (this._revalidationAttempt < REVALIDATION_FAST_BACKOFF_MS.length) {
+      delayMs = REVALIDATION_FAST_BACKOFF_MS[this._revalidationAttempt];
+    } else {
+      this._revalidationState = REVALIDATION_STATE.DAILY_BACKOFF;
+      delayMs = REVALIDATION_DAILY_MS;
+      this.logger?.warn(`[ServiceWrapper][revalidation] Fast retries exhausted (${this._revalidationAttempt} attempts) - switching to daily retry`);
+    }
+
+    this.logger?.info(`[ServiceWrapper][revalidation] Next attempt in ${delayMs}ms`, {
+      attempt: this._revalidationAttempt + 1,
+      state: this._revalidationState,
+      delayMs
+    });
+
+    this._revalidationTimer = setTimeout(() => this._executeRevalidation(), delayMs);
+  }
+
+  /**
+   * Execute a single re-validation attempt.
+   * @private
+   */
+  async _executeRevalidation() {
+    this._revalidationAttempt++;
+    const maxFast = REVALIDATION_FAST_BACKOFF_MS.length;
+    const startTime = Date.now();
+
+    this.logger?.info(`[ServiceWrapper][revalidation] Attempt ${this._revalidationAttempt}/${maxFast} starting`);
+
+    try {
+      const serviceName = this.config.service?.name;
+      const serviceVersion = this.config.service?.version;
+      const serviceUrl = this.config.service?.url;
+
+      const orchestrator = this._injectedValidationOrchestrator || new ValidationOrchestrator({
+        serviceRoot: this.serviceRoot,
+        serviceName,
+        serviceVersion,
+        serviceUrl,
+        logger: this.logger
+      });
+
+      const result = await orchestrator.validate();
+
+      if (!result.success) {
+        throw new Error(`Validation failed: ${result.errors.join(', ')}`);
+      }
+
+      this.validationProof = result.proof;
+
+      // Re-register with fresh proof
+      if (this.registryClient) {
+        const serviceInfo = {
+          name: serviceName,
+          url: serviceUrl,
+          operations: this.operations?.operations || {},
+          metadata: {
+            version: serviceVersion,
+            description: this.config.service?.description || ''
+          }
+        };
+        await this.registryClient.register(serviceInfo);
+      }
+
+      const elapsed = Date.now() - startTime;
+      this._revalidationState = REVALIDATION_STATE.SUCCEEDED;
+      this._revalidationTimer = null;
+      this.logger?.info(`[ServiceWrapper][revalidation] Success after ${this._revalidationAttempt} attempts (${elapsed}ms)`);
+
+      // Clean up failure tracking file
+      this._clearValidationFailureFile();
+
+    } catch (error) {
+      const elapsed = Date.now() - startTime;
+      const nextDelay = this._revalidationState === REVALIDATION_STATE.DAILY_BACKOFF
+        ? REVALIDATION_DAILY_MS
+        : (this._revalidationAttempt < maxFast
+            ? REVALIDATION_FAST_BACKOFF_MS[this._revalidationAttempt]
+            : REVALIDATION_DAILY_MS);
+
+      if (this._revalidationState === REVALIDATION_STATE.DAILY_BACKOFF) {
+        this.logger?.warn(`[ServiceWrapper][revalidation] Daily retry attempt ${this._revalidationAttempt} - ${error.message}`);
+      } else {
+        this.logger?.warn(`[ServiceWrapper][revalidation] Attempt ${this._revalidationAttempt} failed: ${error.message} - next retry in ${nextDelay}ms`, {
+          attempt: this._revalidationAttempt,
+          elapsed,
+          error: error.message
+        });
+      }
+
+      this._scheduleRevalidationAttempt();
+    }
+  }
+
+  /**
+   * Read restart-aware validation failure tracking file.
+   * Used at startup to detect if the service has been failing validation across restarts.
+   * @private
+   * @returns {object|null} Failure data or null if no file exists
+   */
+  _readValidationFailureFile() {
+    const fs = require('fs');
+    const path = require('path');
+
+    if (!this.serviceRoot) return null;
+
+    const failurePath = path.join(this.serviceRoot, 'conn-runtime', 'validation-failure.json');
+    try {
+      if (!fs.existsSync(failurePath)) return null;
+      return JSON.parse(fs.readFileSync(failurePath, 'utf8'));
+    } catch (err) {
+      return null;
+    }
+  }
+
+  /**
+   * Write validation failure tracking file before process exit.
+   * @private
+   * @param {Error} error
+   * @param {number} attemptCount
+   * @param {string} firstFailure
+   */
+  _writeValidationFailureFile(error, attemptCount, firstFailure) {
+    const fs = require('fs');
+    const path = require('path');
+
+    if (!this.serviceRoot) return;
+
+    const runtimeDir = path.join(this.serviceRoot, 'conn-runtime');
+    if (!fs.existsSync(runtimeDir)) {
+      fs.mkdirSync(runtimeDir, { recursive: true });
+    }
+
+    const failurePath = path.join(runtimeDir, 'validation-failure.json');
+    const data = {
+      lastAttempt: new Date().toISOString(),
+      attemptCount,
+      lastError: error.message,
+      firstFailure: firstFailure || new Date().toISOString()
+    };
+
+    fs.writeFileSync(failurePath, JSON.stringify(data, null, 2));
+  }
+
+  /**
+   * Delete the validation failure tracking file (on successful validation).
+   * @private
+   */
+  _clearValidationFailureFile() {
+    const fs = require('fs');
+    const path = require('path');
+
+    if (!this.serviceRoot) return;
+
+    const failurePath = path.join(this.serviceRoot, 'conn-runtime', 'validation-failure.json');
+    try {
+      if (fs.existsSync(failurePath)) {
+        fs.unlinkSync(failurePath);
+      }
+    } catch (err) {
+      this.logger?.warn('[ServiceWrapper][startup] Failed to clear validation failure file', { error: err.message });
+    }
+  }
+
   /**
    * Shutdown wrapper and cleanup resources
    * @async
@@ -1438,6 +1867,12 @@ class ServiceWrapper {
         clearInterval(this.heartbeatTimer);
       }
 
+      // Clear revalidation timer
+      if (this._revalidationTimer) {
+        clearTimeout(this._revalidationTimer);
+        this._revalidationTimer = null;
+      }
+
       // Unregister from registry
       if (this.registryClient) {
         await this.registryClient.unregister(serviceName);
@@ -1509,25 +1944,38 @@ class ServiceWrapper {
     if (!this.config.service?.version) {
       throw new Error('Service version is required for validation');
     }
-    // Logger není povinný - validace může běžet i bez něj (použije console)
 
     const { name: serviceName, version: serviceVersion, port: servicePort } = this.config.service;
 
-    // Validate service port is configured
     if (!servicePort) {
       throw new Error('Service port is required for validation (config.service.port)');
     }
 
-    // Build service URL for validation (HTTP calls to running server)
-    // Fail-fast: do not guess hostnames (no topology defaults). Service URL must be explicit in ServiceConfig.
     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)');
     }
 
+    // Phase 5: Check restart-aware failure tracking
+    const failureData = this._readValidationFailureFile();
+    if (failureData && failureData.attemptCount >= REVALIDATION_FAST_BACKOFF_MS.length) {
+      const lastAttempt = new Date(failureData.lastAttempt).getTime();
+      const sinceLastAttempt = Date.now() - lastAttempt;
+
+      if (sinceLastAttempt < REVALIDATION_DAILY_MS) {
+        const remainingMs = REVALIDATION_DAILY_MS - sinceLastAttempt;
+        const remainingMin = Math.round(remainingMs / 60000);
+        this.logger?.info(
+          `[ServiceWrapper][startup] Previous validation failures detected (${failureData.attemptCount} attempts since ${failureData.firstFailure}) - waiting ${remainingMin}min before retry`
+        );
+        await new Promise(resolve => setTimeout(resolve, Math.min(remainingMs, 300000)));
+      } else {
+        this.logger?.info('[ServiceWrapper][startup] Previous failures detected, but 24h elapsed - retrying fresh');
+      }
+    }
+
     this.logger?.info('[ServiceWrapper] Checking validation proof...');
 
-    // Use injected orchestrator (for testing) or create new one (production)
     const orchestrator = this._injectedValidationOrchestrator || new ValidationOrchestrator({
       serviceRoot: this.serviceRoot,
       serviceName,
@@ -1536,20 +1984,47 @@ class ServiceWrapper {
       logger: this.logger
     });
 
-    const result = await orchestrator.validate();
+    // Startup retry loop with fast backoff
+    let lastError = null;
+    for (let attempt = 0; attempt < REVALIDATION_FAST_BACKOFF_MS.length; attempt++) {
+      try {
+        const result = await orchestrator.validate();
 
-    if (!result.success) {
-      throw new Error(`Validation failed: ${result.errors.join(', ')}`);
-    }
+        if (!result.success) {
+          throw new Error(`Validation failed: ${result.errors.join(', ')}`);
+        }
 
-    if (result.skipped) {
-      this.logger?.info('[ServiceWrapper] ✓ Using existing validation proof');
-    } else {
-      this.logger?.info('[ServiceWrapper] ✓ Validation completed successfully');
+        if (result.skipped) {
+          this.logger?.info('[ServiceWrapper] ✓ Using existing validation proof');
+        } else {
+          this.logger?.info('[ServiceWrapper] ✓ Validation completed successfully');
+        }
+
+        this.validationProof = result.proof;
+        this._clearValidationFailureFile();
+        return;
+      } catch (error) {
+        lastError = error;
+        const delayMs = REVALIDATION_FAST_BACKOFF_MS[attempt];
+
+        this.logger?.warn(`[ServiceWrapper][revalidation] Startup attempt ${attempt + 1}/${REVALIDATION_FAST_BACKOFF_MS.length} failed: ${error.message} - next retry in ${delayMs}ms`, {
+          attempt: attempt + 1,
+          delayMs,
+          error: error.message
+        });
+
+        if (attempt < REVALIDATION_FAST_BACKOFF_MS.length - 1) {
+          await new Promise(resolve => setTimeout(resolve, delayMs));
+        }
+      }
     }
 
-    // Store proof for registration
-    this.validationProof = result.proof;
+    // All startup retries exhausted — write failure file and exit
+    const firstFailure = failureData?.firstFailure || new Date().toISOString();
+    const totalAttempts = (failureData?.attemptCount || 0) + REVALIDATION_FAST_BACKOFF_MS.length;
+    this._writeValidationFailureFile(lastError, totalAttempts, firstFailure);
+
+    throw lastError;
   }
 
   /**

package/src/createTenantContextMiddleware.js

@@ -0,0 +1,127 @@
+'use strict';
+
+/**
+ * Tenant context middleware — requires x-tenant-id + x-workspace-id headers.
+ *
+ * Sets on req: tenant_id, workspace_id, person_id
+ *
+ * @param {Object} options
+ * @param {string} options.serviceName
+ * @param {Object} options.tenantContext
+ * @param {boolean} options.tenantContext.enabled
+ * @param {string[]} options.tenantContext.requirePathPrefixes
+ * @param {string[]} options.tenantContext.excludePathPrefixes
+ * @returns {Function} Express middleware
+ */
+function createTenantContextMiddleware(options = {}) {
+  const serviceName = options.serviceName;
+  const tenantContext = options.tenantContext || {};
+
+  if (!serviceName || typeof serviceName !== 'string') {
+    throw new Error('[service-wrapper][TenantContext] Missing dependency - Expected serviceName (string)');
+  }
+  if (typeof tenantContext !== 'object' || Array.isArray(tenantContext)) {
+    throw new Error('[service-wrapper][TenantContext] Invalid configuration - Expected tenantContext to be an object');
+  }
+
+  const {
+    enabled,
+    requirePathPrefixes,
+    excludePathPrefixes
+  } = tenantContext;
+
+  if (typeof enabled !== 'boolean') {
+    throw new Error(`[service-wrapper][TenantContext] Invalid configuration - tenantContext.enabled must be boolean, got: ${typeof enabled}`);
+  }
+  if (!Array.isArray(requirePathPrefixes) || requirePathPrefixes.some(p => typeof p !== 'string')) {
+    throw new Error('[service-wrapper][TenantContext] Invalid configuration - tenantContext.requirePathPrefixes must be string[]');
+  }
+  if (!Array.isArray(excludePathPrefixes) || excludePathPrefixes.some(p => typeof p !== 'string')) {
+    throw new Error('[service-wrapper][TenantContext] Invalid configuration - tenantContext.excludePathPrefixes must be string[]');
+  }
+
+  const requirePrefixes = requirePathPrefixes;
+  const excludePrefixes = excludePathPrefixes;
+
+  function parsePositiveInt(raw, label) {
+    if (raw === undefined || raw === null || raw === '') return null;
+    const num = Number.parseInt(String(raw), 10);
+    if (!Number.isInteger(num) || num <= 0) {
+      return { error: `[${serviceName}][TenantContext] Invalid ${label} - Expected positive integer, got: ${raw}` };
+    }
+    return num;
+  }
+
+  function sendJson(res, statusCode, payload) {
+    if (!res || typeof res.status !== 'function' || typeof res.json !== 'function') {
+      throw new Error('[service-wrapper][TenantContext] Invalid response object - Expected Express res with res.status().json()');
+    }
+    return res.status(statusCode).json(payload);
+  }
+
+  return function tenantContextMiddleware(req, res, next) {
+    if (!enabled) {
+      return next();
+    }
+
+    const rawUrl =
+      (req && typeof req.originalUrl === 'string' && req.originalUrl) ||
+      (req && typeof req.url === 'string' && req.url) ||
+      (req && typeof req.path === 'string' && req.path) ||
+      '';
+    const path = rawUrl.split('?')[0];
+
+    if (!requirePrefixes.some(prefix => path.startsWith(prefix))) {
+      return next();
+    }
+    if (excludePrefixes.some(prefix => path.startsWith(prefix))) {
+      return next();
+    }
+
+    const headers = req.headers || {};
+    const rawTenantId = headers['x-tenant-id'];
+    const rawWorkspaceId = headers['x-workspace-id'];
+
+    if (rawTenantId === undefined || rawWorkspaceId === undefined) {
+      return sendJson(res, 400, {
+        error: `[${serviceName}][TenantContext] Missing tenant context - Expected 'x-tenant-id' + 'x-workspace-id' headers`
+      });
+    }
+
+    const tenantId = parsePositiveInt(rawTenantId, 'x-tenant-id');
+    if (tenantId && tenantId.error) {
+      return sendJson(res, 400, { error: tenantId.error });
+    }
+    if (!tenantId) {
+      return sendJson(res, 400, {
+        error: `[${serviceName}][TenantContext] Missing tenant context - Expected header 'x-tenant-id' (positive INT)`
+      });
+    }
+
+    const workspaceId = parsePositiveInt(rawWorkspaceId, 'x-workspace-id');
+    if (workspaceId && workspaceId.error) {
+      return sendJson(res, 400, { error: workspaceId.error });
+    }
+    if (!workspaceId) {
+      return sendJson(res, 400, {
+        error: `[${serviceName}][TenantContext] Missing workspace context - Expected header 'x-workspace-id' (positive INT)`
+      });
+    }
+
+    const rawPersonId = headers['x-person-id'];
+    let personId = null;
+    if (rawPersonId !== undefined) {
+      personId = parsePositiveInt(rawPersonId, 'x-person-id');
+      if (personId && personId.error) {
+        return sendJson(res, 400, { error: personId.error });
+      }
+    }
+
+    req.tenant_id = tenantId;
+    req.workspace_id = workspaceId;
+    req.person_id = personId;
+    return next();
+  };
+}
+
+module.exports = { createTenantContextMiddleware };

package/src/index.js

@@ -16,7 +16,7 @@ const ServiceWrapper = require('./ServiceWrapper');
 const { ConfigLoader } = require('./ConfigLoader');
 const runtimeCfg = require('./config');
 const pkg = require('../package.json');
-const { createAccountContextMiddleware } = require('./createAccountContextMiddleware');
+const { createTenantContextMiddleware } = require('./createTenantContextMiddleware');
 
 // Note: WorkflowProcessor and ApiCaller functionality has been moved to connectors:
 // - WorkflowProcessor -> @onlineapps/conn-orch-orchestrator
@@ -59,21 +59,20 @@ async function bootstrap(serviceRoot, options = {}) {
 
   console.log(`Starting ${config.service.name} v${config.service.version}...`);
 
-  // 0. Apply shared request context middleware (account context for multitenancy)
-  // Enforced centrally for all business services: /api/** must have account-id (except /api/v1/specification).
-  const accountContextMw = createAccountContextMiddleware({
+  // 0. Apply shared tenant context middleware (x-tenant-id + x-workspace-id + x-person-id)
+  const tenantContextMw = createTenantContextMiddleware({
     serviceName: config.service.name,
-    accountContext: config.wrapper?.accountContext
+    tenantContext: config.wrapper?.tenantContext
   });
-  app.use(accountContextMw);
+  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 account context BEFORE routes: move our middleware to the beginning of the router stack.
+  // 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][AccountContext] Cannot enforce account context - Express router stack not available. ` +
+      `[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.`
     );
   }
@@ -84,12 +83,12 @@ async function bootstrap(serviceRoot, options = {}) {
     lastLayer &&
     lastLayer.handle &&
     typeof lastLayer.handle === 'function' &&
-    lastLayer.handle.name === accountContextMw.name;
+    lastLayer.handle.name === tenantContextMw.name;
 
   if (!isOurMiddleware) {
     throw new Error(
-      `[service-wrapper][AccountContext] Cannot enforce account context - middleware placement is not deterministic. ` +
-      `Fix: ensure bootstrap registers account context middleware before routes, or update service to export app factory.`
+      `[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.`
     );
   }
 
@@ -155,6 +154,6 @@ module.exports = ServiceWrapper;
 module.exports.ServiceWrapper = ServiceWrapper;
 module.exports.ConfigLoader = ConfigLoader;
 module.exports.bootstrap = bootstrap;
-module.exports.createAccountContextMiddleware = createAccountContextMiddleware;
+module.exports.createTenantContextMiddleware = createTenantContextMiddleware;
 module.exports.default = ServiceWrapper;
 module.exports.VERSION = pkg.version;

package/src/createAccountContextMiddleware.js

@@ -1,103 +0,0 @@
-'use strict';
-
-/**
- * Create an Express middleware that enforces required account context for business APIs.
- *
- * Rules:
- * - Applies only for paths that match `requirePathPrefixes` and do NOT match `excludePathPrefixes`.
- * - Requires header `headerName` to be a positive integer.
- * - Sets `req.account_id` as integer.
- *
- * @param {Object} options
- * @param {string} options.serviceName
- * @param {Object} options.accountContext
- * @param {boolean} options.accountContext.enabled
- * @param {string} options.accountContext.headerName
- * @param {string[]} options.accountContext.requirePathPrefixes
- * @param {string[]} options.accountContext.excludePathPrefixes
- * @returns {Function} Express middleware
- */
-function createAccountContextMiddleware(options = {}) {
-  const serviceName = options.serviceName;
-  const accountContext = options.accountContext || {};
-
-  if (!serviceName || typeof serviceName !== 'string') {
-    throw new Error('[service-wrapper][AccountContext] Missing dependency - Expected serviceName (string)');
-  }
-  if (typeof accountContext !== 'object' || Array.isArray(accountContext)) {
-    throw new Error('[service-wrapper][AccountContext] Invalid configuration - Expected accountContext to be an object');
-  }
-
-  const {
-    enabled,
-    headerName,
-    requirePathPrefixes,
-    excludePathPrefixes
-  } = accountContext;
-
-  if (typeof enabled !== 'boolean') {
-    throw new Error(`[service-wrapper][AccountContext] Invalid configuration - wrapper.accountContext.enabled must be boolean, got: ${typeof enabled}`);
-  }
-  if (typeof headerName !== 'string' || headerName.trim() === '') {
-    throw new Error(`[service-wrapper][AccountContext] Invalid configuration - wrapper.accountContext.headerName must be non-empty string, got: ${headerName}`);
-  }
-  if (!Array.isArray(requirePathPrefixes) || requirePathPrefixes.some(p => typeof p !== 'string')) {
-    throw new Error('[service-wrapper][AccountContext] Invalid configuration - wrapper.accountContext.requirePathPrefixes must be string[]');
-  }
-  if (!Array.isArray(excludePathPrefixes) || excludePathPrefixes.some(p => typeof p !== 'string')) {
-    throw new Error('[service-wrapper][AccountContext] Invalid configuration - wrapper.accountContext.excludePathPrefixes must be string[]');
-  }
-
-  const requirePrefixes = requirePathPrefixes;
-  const excludePrefixes = excludePathPrefixes;
-
-  function sendJson(res, statusCode, payload) {
-    // Fail-fast: this middleware must run in Express.
-    if (!res || typeof res.status !== 'function' || typeof res.json !== 'function') {
-      throw new Error('[service-wrapper][AccountContext] Invalid response object - Expected Express res with res.status().json()');
-    }
-    return res.status(statusCode).json(payload);
-  }
-
-  return function accountContextMiddleware(req, res, next) {
-    if (!enabled) {
-      return next();
-    }
-
-    // Prefer originalUrl because req.path may be relative inside mounted routers (e.g. '/documents')
-    // while originalUrl keeps the full path (e.g. '/api/v1/documents').
-    const rawUrl =
-      (req && typeof req.originalUrl === 'string' && req.originalUrl) ||
-      (req && typeof req.url === 'string' && req.url) ||
-      (req && typeof req.path === 'string' && req.path) ||
-      '';
-    const path = rawUrl.split('?')[0];
-    if (!requirePrefixes.some(prefix => path.startsWith(prefix))) {
-      return next();
-    }
-    if (excludePrefixes.some(prefix => path.startsWith(prefix))) {
-      return next();
-    }
-
-    const rawAccountId = req.headers ? req.headers[headerName] : undefined;
-    if (!rawAccountId) {
-      return sendJson(res, 400, {
-        error: `[${serviceName}][Multitenancy] Missing account context - Expected request header '${headerName}' (INT)`
-      });
-    }
-
-    const accountId = Number.parseInt(String(rawAccountId), 10);
-    if (!Number.isInteger(accountId) || accountId <= 0) {
-      return sendJson(res, 400, {
-        error: `[${serviceName}][Multitenancy] Invalid account context - Expected '${headerName}' to be a positive integer`
-      });
-    }
-
-    req.account_id = accountId;
-    return next();
-  };
-}
-
-module.exports = { createAccountContextMiddleware };
-
-