@onlineapps/service-wrapper 4.1.0 → 4.1.1

package/CHANGELOG.md

@@ -2,6 +2,107 @@
 
 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).
 
+## [Unreleased]
+
+**Patch.** No exported API moves: `BUSINESS_ERROR_BRAND`, `isBusinessError`, the
+error classes, `ServiceWrapper` and `bootstrap` are untouched. What changes is
+startup behaviour and one field inside `conn-runtime/validation-failure.json`,
+a runtime file this package writes and reads alone — not a contract any consumer
+compiles against.
+
+### Fixed — the restart cooldown is keyed on the CAUSE, not on time alone
+
+Measured on `api_service_emailer`, 2026-08-29: the cookbooks were repaired and
+the container restarted, but the failure file still said `attemptCount: 240`, so
+`_ensureValidationProof` slept `min(REVALIDATION_SLOW_MS - since, 300000)` — five
+minutes — before FÁZE 0.2. The boot looked wedged at 0.15, because the only
+announcement went to `this.logger?.info` and stdout said nothing.
+
+- `_writeValidationFailureFile` records `causeFingerprint`: the platform hash
+  (`FingerprintUtils.generateContentFingerprint`, never a new one) over every
+  `.json` under `config/service/` and `tests/cookbooks/` — what Tier-1
+  validation actually judges.
+- `_applyRestartCooldown` compares it at startup. Cause changed → the failure
+  file is deleted, no wait, and the attempt count starts from zero. Same cause →
+  the previous behaviour, unchanged.
+- **A file written before this version has no fingerprint, which is not the
+  current one, so it takes the "cause changed" branch.** There is no
+  compatibility branch and no migration: a missing fingerprint is a changed
+  cause (`architecture-principles.md` §11).
+- Both branches now print through `_logStartup`, which writes to the structured
+  log AND to stdout — the same two channels `_logPhase` uses for every
+  `[FÁZE …]` line. A five-minute wait that announces itself on a channel the
+  container does not show is not an announcement (`automation-gates.md` §5).
+- The failure file is re-read AFTER the cooldown. Reading it before carried the
+  old count into the write that follows, so a reset lifted the cooldown for
+  exactly one boot and then reinstated it.
+
+### Changed — one orchestrator factory, two callers
+
+`_executeRevalidation` built a `ValidationOrchestrator` per attempt;
+`_ensureValidationProof` built one and reused it across all six startup
+attempts. Both arrived in the same commit (`869a346a`, 2026-03-26) — the
+difference was a local convenience, not a design.
+
+The reuse was not free: dávka 49 had to add `resetResults()` to
+`CookbookTestRunner` because the shared runner accumulated failed cookbooks
+across those six attempts, so the verdict could never come back true inside one
+process. Nothing needs state between attempts, so `_createValidationOrchestrator()`
+is now the single construction site and every attempt gets a fresh instance. The
+injected orchestrator (`options._validationOrchestrator`) is still returned as-is
+— it is the test seam.
+
+### Added — `@onlineapps/service-validator-core` 1.0.14 as a declared dependency
+
+`FingerprintUtils` is required directly now. It was already installed
+transitively through `@onlineapps/conn-orch-validator`; requiring it without
+declaring it is the §20 defect the new G6 gate rejects.
+
+### Fixed — the heartbeat no longer invents an identity
+
+`startHealthHeartbeat()` defaulted the two facts that identify the service:
+`service.name || 'unnamed-service'` and `service.version || '1.0.0'`. Both are
+fallbacks (`architecture-principles.md` §3), and of the costly kind: a heartbeat
+published as `unnamed-service@1.0.0` is not a missing heartbeat but a WRONG one —
+the monitoring stack records a service that does not exist while the real one
+looks silent.
+
+Not dead branches either. `_ensureValidationProof` fail-fasts on both keys, but
+it runs only when `serviceRoot` is set and `wrapper.validation.enabled !== false`
+(`ServiceWrapper.js:831`), so a service with validation off arrived here with
+neither key ever checked. Both now fail fast with
+`[ServiceWrapper] Missing configuration - service.<key> is required`, in the
+shape `_registerService`already uses one method away.
+
+### Fixed — the guard test failed by hanging instead of failing
+
+The `_executeRevalidation` guard added above did catch a deleted local, but its
+`catch` scheduled the next attempt through a REAL `setTimeout` (30 s … 30 min).
+Jest then waited on the open handle, so the run froze instead of reporting the
+failure — measured by the lead: five minutes, no output. The test now records
+the scheduling instead of arming it, and asserts the success path never reaches
+the scheduler at all. Under the mutation it fails in 2 ms.
+
+### Tests
+
+`tests/unit/ServiceWrapper.validationFailureFile.test.js` — 18 cases: the
+fingerprint moves for a cookbook, for `operations.json` and for an added
+cookbook and NOT for an unrelated file; the three cooldown branches; the
+pre-fingerprint file; the reset that really starts from zero; no failure file;
+fewer failures than the fast backoff; an elapsed cooldown; the factory returning
+a new instance per call and the injected one unchanged; a single construction
+site in the source. Plus a guard for the class of defect 3.4.2 hot-fixed — a
+dangling local left by a cleanup pass — by driving `_executeRevalidation` far
+enough to register the service.
+
+`tests/unit/ServiceWrapper.heartbeatConfig.test.js` — 7 cases: each missing key
+by name, an absent `service` section, the publisher never constructed under a
+made-up identity, a complete identity starting it under its real name, the older
+`mqClient` guard still firing first, and the retired default absent from the
+source.
+
+Suite: 16 suites, 214 passed (was 189).
+
 ## [3.4.3] — 2026-08-17
 
 **Ajv config: `allowUnionTypes: true`.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/service-wrapper",
-  "version": "4.1.0",
+  "version": "4.1.1",
   "description": "Thin orchestration layer for microservices - delegates all infrastructure concerns to specialized connectors",
   "main": "src/index.js",
   "scripts": {
@@ -24,20 +24,20 @@
   "author": "OA Drive Team",
   "license": "MIT",
   "dependencies": {
-    "@onlineapps/conn-base-cache": "1.0.9",
-    "@onlineapps/conn-base-monitoring": "1.0.15",
-    "@onlineapps/conn-base-state": "1.0.1",
-    "@onlineapps/conn-infra-error-handler": "1.0.14",
-    "@onlineapps/conn-infra-mq": "1.1.70",
-    "@onlineapps/conn-infra-secrets": "1.0.0",
-    "@onlineapps/conn-orch-cookbook": "2.1.4",
-    "@onlineapps/conn-orch-orchestrator": "2.1.7",
-    "@onlineapps/conn-orch-registry": "1.2.2",
-    "@onlineapps/conn-orch-validator": "4.0.0",
-    "@onlineapps/infrastructure-tools": "1.2.6",
-    "@onlineapps/monitoring-core": "1.0.26",
-    "@onlineapps/runtime-config": "1.0.2",
+    "@onlineapps/conn-base-cache": "1.0.10",
+    "@onlineapps/conn-base-monitoring": "1.0.16",
+    "@onlineapps/conn-base-state": "1.0.2",
+    "@onlineapps/conn-infra-error-handler": "1.0.15",
+    "@onlineapps/conn-infra-mq": "2.0.0",
+    "@onlineapps/conn-infra-secrets": "1.1.0",
+    "@onlineapps/conn-orch-cookbook": "2.1.5",
+    "@onlineapps/conn-orch-orchestrator": "2.1.8",
+    "@onlineapps/conn-orch-registry": "2.0.0",
+    "@onlineapps/conn-orch-validator": "4.0.1",
+    "@onlineapps/infrastructure-tools": "1.2.7",
+    "@onlineapps/runtime-config": "1.0.3",
     "@onlineapps/service-common": "2.0.0",
+    "@onlineapps/service-validator-core": "1.0.15",
     "ajv": "8.17.1",
     "ajv-formats": "3.0.1"
   },

package/src/ServiceWrapper.js

@@ -1590,9 +1590,25 @@ class ServiceWrapper {
       throw new Error('[ServiceWrapper] mqClient is required to start heartbeat publisher');
     }
 
+    // Identity is required, never defaulted. A heartbeat published as
+    // `unnamed-service@1.0.0` is not a missing heartbeat, it is a WRONG one:
+    // the monitoring stack records a service that does not exist while the real
+    // one looks silent (architecture-principles.md §3).
+    //
+    // Not a dead branch either. `_ensureValidationProof` fail-fasts on both keys
+    // (below), but it runs only when serviceRoot is set and
+    // wrapper.validation.enabled !== false — a service with validation off used
+    // to arrive here with neither key ever checked.
+    const serviceName = this.config.service?.name;
+    if (!serviceName) {
+      throw new Error('[ServiceWrapper] Missing configuration - service.name is required');
+    }
+    const serviceVersion = this.config.service?.version;
+    if (!serviceVersion) {
+      throw new Error('[ServiceWrapper] Missing configuration - service.version is required');
+    }
+
     const { createBaseClientAdapter } = require('@onlineapps/infrastructure-tools');
-    const serviceName = this.config.service?.name || 'unnamed-service';
-    const serviceVersion = this.config.service?.version || '1.0.0';
 
     const getHealthData = () => this._collectHeartbeatComponents();
 
@@ -2394,16 +2410,7 @@ class ServiceWrapper {
       const serviceVersion = this.config.service?.version;
       const serviceUrl = this.config.service?.url;
 
-      // INTENTIONAL FALLBACK: bootstrap logger — see docs/standards/FALLBACKS_INVENTORY.md §5.1
-      const validationLogger = this.logger || console;
-      const orchestrator = this._injectedValidationOrchestrator || new ValidationOrchestrator({
-        serviceRoot: this.serviceRoot,
-        serviceName,
-        serviceVersion,
-        serviceUrl,
-        logger: validationLogger
-      });
-
+      const orchestrator = this._createValidationOrchestrator();
       const result = await orchestrator.validate();
 
       if (!result.success) {
@@ -2445,6 +2452,160 @@ class ServiceWrapper {
     }
   }
 
+  /**
+   * One place the startup path waits, so a test can watch it and a reader can
+   * find it. Never inlined as `new Promise(setTimeout)` again — an invisible
+   * five-minute sleep is what made a healthy boot look wedged.
+   *
+   * @private
+   * @param {number} ms
+   */
+  _sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+
+  /**
+   * A startup line on BOTH channels — structured log and stdout — exactly as
+   * `_logPhase` does for the `[FÁZE …]` lines.
+   *
+   * The five-minute cooldown announced itself only through `this.logger?.info`.
+   * On a container whose logger writes elsewhere that is no announcement at
+   * all: the boot stops after FÁZE 0.15 and says nothing for five minutes
+   * (automation-gates.md §5 — silence is a defect).
+   *
+   * @private
+   * @param {string} message
+   * @param {Object} [data]
+   */
+  _logStartup(message, data = {}) {
+    this.logger?.info(message, data);
+    console.log(message);
+  }
+
+  /**
+   * Fingerprint of everything Tier-1 validation judges: the service's own
+   * declaration files and its cookbooks.
+   *
+   * This is what the restart cooldown is keyed on. Time alone is the wrong key:
+   * biz-emailer was repaired and restarted on 2026-08-29 and still waited five
+   * minutes, because the file remembered 240 failures of a cause that no longer
+   * existed.
+   *
+   * Uses the platform hash (`FingerprintUtils`), never a new one.
+   *
+   * @private
+   * @returns {string|null} null when there is no service root to read
+   */
+  _computeValidationCauseFingerprint() {
+    const fs = require('fs');
+    const path = require('path');
+
+    if (!this.serviceRoot) return null;
+
+    const FingerprintUtils = require('@onlineapps/service-validator-core/src/utils/FingerprintUtils');
+
+    const contents = {};
+    const collect = (dir) => {
+      let entries;
+      try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+      } catch {
+        return; // an absent directory is a fact about the tree, not an error
+      }
+      for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        const abs = path.join(dir, entry.name);
+        if (entry.isDirectory()) { collect(abs); continue; }
+        if (!entry.isFile() || !entry.name.endsWith('.json')) continue;
+        try {
+          contents[path.relative(this.serviceRoot, abs)] = fs.readFileSync(abs, 'utf8');
+        } catch {
+          contents[path.relative(this.serviceRoot, abs)] = '<unreadable>';
+        }
+      }
+    };
+
+    collect(path.join(this.serviceRoot, 'config', 'service'));
+    collect(path.join(this.serviceRoot, 'tests', 'cookbooks'));
+
+    return FingerprintUtils.generateContentFingerprint(contents);
+  }
+
+  /**
+   * The restart-aware cooldown, applied ONLY to the same cause.
+   *
+   * Three outcomes, and each one says which on stdout:
+   *   - cause changed → no wait, the failure file is dropped so the attempt
+   *     count starts from zero. A file written before fingerprints existed has
+   *     none, which is not the current one, so it takes this branch: a missing
+   *     fingerprint is a changed cause, not a compatibility case
+   *     (architecture-principles.md §11).
+   *   - same cause, cooldown not elapsed → wait, as before.
+   *   - same cause, cooldown elapsed → no wait.
+   *
+   * @private
+   */
+  async _applyRestartCooldown() {
+    const failureData = this._readValidationFailureFile();
+    if (!failureData || failureData.attemptCount < REVALIDATION_FAST_BACKOFF_MS.length) {
+      return;
+    }
+
+    const currentCause = this._computeValidationCauseFingerprint();
+    if (failureData.causeFingerprint !== currentCause) {
+      this._logStartup(
+        '[ServiceWrapper][startup] Validation cause changed since the last failure - retrying fresh',
+        { previousAttempts: failureData.attemptCount, firstFailure: failureData.firstFailure }
+      );
+      this._clearValidationFailureFile();
+      return;
+    }
+
+    const sinceLastAttempt = Date.now() - new Date(failureData.lastAttempt).getTime();
+    if (sinceLastAttempt >= REVALIDATION_SLOW_MS) {
+      this._logStartup('[ServiceWrapper][startup] Previous failures detected, but cooldown elapsed - retrying fresh');
+      return;
+    }
+
+    const remainingMs = REVALIDATION_SLOW_MS - sinceLastAttempt;
+    const waitMs = Math.min(remainingMs, 300000);
+    this._logStartup(
+      `[ServiceWrapper][startup] Previous validation failures detected (${failureData.attemptCount} attempts since ${failureData.firstFailure}, same cause) - waiting ${Math.round(waitMs / 60000)}min before retry`,
+      { attemptCount: failureData.attemptCount, waitMs }
+    );
+    await this._sleep(waitMs);
+  }
+
+  /**
+   * The ONE place a ValidationOrchestrator is built.
+   *
+   * Both validation paths arrived in the same commit (869a346a, 2026-03-26) and
+   * ended up different by accident, not by design: `_executeRevalidation` builds
+   * one per attempt because the whole function IS one attempt, while
+   * `_ensureValidationProof` hoisted the construction out of its retry loop and
+   * reused a single instance across six attempts. That reuse was not free —
+   * dávka 49 had to add `resetResults()` to `CookbookTestRunner` because the
+   * shared runner accumulated failures across those attempts and the verdict
+   * could never come back true inside one process.
+   *
+   * Nothing needs state between attempts, so every attempt gets a fresh
+   * orchestrator. The injected one (tests) is still returned as-is: it is the
+   * seam, and a seam that behaved differently per call would test nothing.
+   *
+   * @private
+   */
+  _createValidationOrchestrator() {
+    if (this._injectedValidationOrchestrator) return this._injectedValidationOrchestrator;
+
+    // INTENTIONAL FALLBACK: bootstrap logger — see docs/standards/FALLBACKS_INVENTORY.md §5.1
+    return new ValidationOrchestrator({
+      serviceRoot: this.serviceRoot,
+      serviceName: this.config.service?.name,
+      serviceVersion: this.config.service?.version,
+      serviceUrl: this.config.service?.url || '',
+      logger: this.logger || console
+    });
+  }
+
   /**
    * Read restart-aware validation failure tracking file.
    * Used at startup to detect if the service has been failing validation across restarts.
@@ -2489,7 +2650,10 @@ class ServiceWrapper {
       lastAttempt: new Date().toISOString(),
       attemptCount,
       lastError: error.message,
-      firstFailure: firstFailure || new Date().toISOString()
+      firstFailure: firstFailure || new Date().toISOString(),
+      // What validation was judging when it failed. The restart cooldown is
+      // keyed on this, not on time alone.
+      causeFingerprint: this._computeValidationCauseFingerprint()
     };
 
     fs.writeFileSync(failurePath, JSON.stringify(data, null, 2));
@@ -2617,49 +2781,28 @@ class ServiceWrapper {
       throw new Error('Service version is required for validation');
     }
 
-    const { name: serviceName, version: serviceVersion } = this.config.service;
+    // ADR 0005: biz services have no HTTP surface — no port to bind, no URL to
+    // advertise. The two guards above are the contract; the values themselves
+    // are read by _createValidationOrchestrator() straight from this.config, so
+    // there is nothing left to hold in a local (change-discipline.md § Removing
+    // something removes its declaration).
 
-    // 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. Kept as a
-    // local var so downstream ValidationOrchestrator can still receive it
-    // (accepts empty string; only used for telemetry / log annotation).
-    const serviceUrl = this.config.service?.url || '';
+    // Phase 5: restart-aware failure tracking, keyed on the CAUSE.
+    await this._applyRestartCooldown();
 
-    // Phase 5: Check restart-aware failure tracking
+    // Read AFTER the cooldown: a changed cause deletes the file, and the run
+    // that follows must start from zero attempts. Reading before would carry
+    // the old count into the write below and reinstate the very cooldown the
+    // reset just lifted.
     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_SLOW_MS) {
-        const remainingMs = REVALIDATION_SLOW_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 cooldown elapsed - retrying fresh');
-      }
-    }
 
     this.logger?.info('[ServiceWrapper] Checking validation proof...');
 
-    // INTENTIONAL FALLBACK: bootstrap logger — see docs/standards/FALLBACKS_INVENTORY.md §5.1
-    const revalidationLogger = this.logger || console;
-    const orchestrator = this._injectedValidationOrchestrator || new ValidationOrchestrator({
-      serviceRoot: this.serviceRoot,
-      serviceName,
-      serviceVersion,
-      serviceUrl,
-      logger: revalidationLogger
-    });
-
     // Startup retry loop with fast backoff
     let lastError = null;
     for (let attempt = 0; attempt < REVALIDATION_FAST_BACKOFF_MS.length; attempt++) {
       try {
+        const orchestrator = this._createValidationOrchestrator();
         const result = await orchestrator.validate();
 
         if (!result.success) {