@onlineapps/service-wrapper 4.0.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.0.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": "3.3.2",
-    "@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/ErrorMapper.js

@@ -9,6 +9,8 @@
  * modules, no third-party deps. Logger is injected via constructor (DI).
  *
  * Exports:
+ *   - BUSINESS_ERROR_BRAND   — Symbol.for('onlineapps.businessError'), the mark.
+ *   - isBusinessError(err)   — brand + shape predicate (the contract itself).
  *   - ErrorMapper            — maps exceptions to { status, error: {...} } envelopes.
  *   - BusinessError          — base class for handler-authored errors (code + status required).
  *   - ValidationError        — 400 VALIDATION_FAILED. Thrown by SchemaValidator
@@ -22,6 +24,32 @@
  *   - UnknownOperationError  — thrown by HandlerRegistry for unregistered ops.
  *   - AbortError             — thrown when ctx.abortSignal aborts the invocation.
  *
+ * THE CONTRACT IS A BRAND PLUS A SHAPE, NOT A CLASS IDENTITY (DÁVKA 50).
+ * Owner decision: api/docs/governance/confirmations/business-error-contract.md
+ * (20260829-1500-business-error-contract-001).
+ *
+ * An error is a business error when it carries ALL of:
+ *   - the brand `Symbol.for('onlineapps.businessError')` with value `true`
+ *     (a GLOBAL registry symbol, so it survives two copies of this package in
+ *     node_modules and can be claimed by a service's own class);
+ *   - `code`    — string matching /^[A-Z][A-Z0-9_]*$/;
+ *   - `status`  — number in [100, 599];
+ *   - `message` — non-empty string.
+ *
+ * `map()` therefore dispatches on `code`, never on `instanceof`. `instanceof`
+ * remains true for our own classes but is no longer what decides anything.
+ *
+ * The two outcomes for an error that is not a business error are deliberately
+ * different, and that difference is the point:
+ *   - BRANDED but malformed → OUR defect. 500 `MALFORMED_BUSINESS_ERROR` and an
+ *     `error` log naming the offending field. Loud, never anonymous.
+ *   - UNBRANDED            → a genuinely unknown error. 500 `INTERNAL_ERROR`,
+ *     message and details masked. Unchanged.
+ *
+ * A service may throw its own class as long as it declares the brand and the
+ * shape. Extending `BusinessError` is the easy way to get both; it is not the
+ * only permitted one.
+ *
  * Two constructor shapes, because the parameter sets genuinely differ:
  *   - `BusinessError` takes `{ code, status, message, details }` — the author
  *     must supply code + status, so they are named.
@@ -36,6 +64,88 @@
  * base class fail-fasts instead.
  */
 
+/**
+ * The business-error brand. `Symbol.for` puts it in the GLOBAL symbol registry,
+ * so two independently loaded copies of this file resolve to the SAME symbol —
+ * which is exactly the case `instanceof` used to lose.
+ */
+const BUSINESS_ERROR_BRAND = Symbol.for('onlineapps.businessError');
+
+/** `code` must be an uppercase SNAKE_CASE identifier. */
+const BUSINESS_ERROR_CODE_PATTERN = /^[A-Z][A-Z0-9_]*$/;
+
+const BUSINESS_ERROR_STATUS_MIN = 100;
+const BUSINESS_ERROR_STATUS_MAX = 599;
+
+/** Render a value for an operator-facing defect line: `"404" (string)`. */
+function describeValue(value) {
+  const rendered = typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean'
+    ? JSON.stringify(value)
+    : String(value);
+  return `${rendered} (${typeof value})`;
+}
+
+/**
+ * Does the error claim to be one of ours? Claiming is not being — see
+ * {@link describeBusinessErrorDefects}.
+ *
+ * @param {*} err
+ * @returns {boolean}
+ */
+function hasBusinessErrorBrand(err) {
+  return !!err && (typeof err === 'object' || typeof err === 'function') && err[BUSINESS_ERROR_BRAND] === true;
+}
+
+/**
+ * Every way a branded error breaks the shape, named field by field. Empty array
+ * = the contract holds.
+ *
+ * @param {Object} err
+ * @returns {string[]}
+ */
+function describeBusinessErrorDefects(err) {
+  const defects = [];
+
+  if (typeof err.code !== 'string' || !BUSINESS_ERROR_CODE_PATTERN.test(err.code)) {
+    defects.push(`code is ${describeValue(err.code)}, expected a string matching ${BUSINESS_ERROR_CODE_PATTERN.source}`);
+  }
+  if (typeof err.status !== 'number' || !Number.isFinite(err.status) ||
+      err.status < BUSINESS_ERROR_STATUS_MIN || err.status > BUSINESS_ERROR_STATUS_MAX) {
+    defects.push(`status is ${describeValue(err.status)}, expected a number between ${BUSINESS_ERROR_STATUS_MIN} and ${BUSINESS_ERROR_STATUS_MAX}`);
+  }
+  if (typeof err.message !== 'string' || err.message.length === 0) {
+    defects.push(`message is ${describeValue(err.message)}, expected a non-empty string`);
+  }
+
+  return defects;
+}
+
+/**
+ * THE contract. A service's own class passes this by declaring the brand and
+ * the three fields — it does not have to extend `BusinessError`.
+ *
+ * @param {*} err
+ * @returns {boolean}
+ */
+function isBusinessError(err) {
+  return hasBusinessErrorBrand(err) && describeBusinessErrorDefects(err).length === 0;
+}
+
+/**
+ * Stamp the brand on a class prototype: non-enumerable and non-writable, so it
+ * never reaches a JSON payload and cannot be unset by accident.
+ *
+ * @param {Function} Cls
+ */
+function brand(Cls) {
+  Object.defineProperty(Cls.prototype, BUSINESS_ERROR_BRAND, {
+    value: true,
+    enumerable: false,
+    writable: false,
+    configurable: false
+  });
+}
+
 class BusinessError extends Error {
   constructor({ code, status, message, details } = {}) {
     if (!code) {
@@ -163,6 +273,12 @@ class AbortError extends Error {
   }
 }
 
+// `UnknownOperationError` and `AbortError` do not extend `BusinessError` (their
+// constructor shape differs), so each is branded on its own prototype.
+brand(BusinessError);
+brand(UnknownOperationError);
+brand(AbortError);
+
 class ErrorMapper {
   /**
    * @param {Object} options
@@ -179,6 +295,10 @@ class ErrorMapper {
    * Map a handler exception to an MQ response envelope.
    * Never throws. Always returns `{ status, error: { code, message, [details], [correlation_id] } }`.
    *
+   * Recognition is by the brand + shape contract (see the file header), never by
+   * `instanceof`. Branded + malformed → 500 `MALFORMED_BUSINESS_ERROR` with the
+   * offending field named in the log; unbranded → 500 `INTERNAL_ERROR`, masked.
+   *
    * @param {Error} err
    * @param {Object} meta
    * @param {string} [meta.operation]
@@ -188,8 +308,34 @@ class ErrorMapper {
   map(err, meta = {}) {
     const { operation, correlation_id } = meta;
 
-    if (err instanceof ValidationError) {
-      if (err.phase === 'output') {
+    if (hasBusinessErrorBrand(err)) {
+      const defects = describeBusinessErrorDefects(err);
+      if (defects.length > 0) {
+        // Branded but malformed = a defect in OUR code (or in a service that
+        // claimed the brand and then broke the shape). It gets a named, loud
+        // 500 instead of the anonymous one an unknown error gets, so the log
+        // says which field is wrong rather than "something threw".
+        this._logger.error(
+          `[ErrorMapper] branded error has invalid shape - ${defects.join('; ')}. ` +
+          'Fix: a branded business error must carry code (' + BUSINESS_ERROR_CODE_PATTERN.source + '), ' +
+          `status (number ${BUSINESS_ERROR_STATUS_MIN}-${BUSINESS_ERROR_STATUS_MAX}) and a non-empty message.`,
+          {
+            err,
+            operation,
+            correlation_id,
+            code: 'MALFORMED_BUSINESS_ERROR',
+            status: 500,
+            stack: err && err.stack,
+            defects
+          }
+        );
+        return this._buildError(500, 'MALFORMED_BUSINESS_ERROR', 'An internal error occurred', undefined, correlation_id);
+      }
+
+      // From here on the shape is guaranteed. Branches key on `code`, so a
+      // class from a second copy of this package — or a service's own class
+      // declaring the same code — takes exactly the same branch as ours.
+      if (err.code === 'VALIDATION_FAILED' && err.phase === 'output') {
         this._logger.error(
           'output schema validation failed - server bug',
           { err, operation, correlation_id, code: 'INTERNAL_ERROR', status: 500 }
@@ -197,23 +343,7 @@ class ErrorMapper {
         return this._buildError(500, 'INTERNAL_ERROR', 'Internal validation error', undefined, correlation_id);
       }
 
-      this._logger.info(
-        'input schema validation failed',
-        { err, operation, correlation_id, code: 'VALIDATION_FAILED', status: 400 }
-      );
-      return this._buildError(400, 'VALIDATION_FAILED', err.message, err.details, correlation_id);
-    }
-
-    if (err instanceof UnknownOperationError) {
-      this._logger.warn(
-        'unknown operation requested',
-        { err, operation, correlation_id, code: 'UNKNOWN_OPERATION', status: 404 }
-      );
-      return this._buildError(404, 'UNKNOWN_OPERATION', err.message, undefined, correlation_id);
-    }
-
-    if (err instanceof BusinessError) {
-      // A BusinessError with a 5xx status is a server fault wearing a business
+      // A business error with a 5xx status is a server fault wearing a business
       // class. It is logged like one — `error` level WITH the stack — and the
       // caller gets the same neutral text as any other internal error, so the
       // original message (which may name a tenant, a column or a credential)
@@ -226,6 +356,30 @@ class ErrorMapper {
         return this._buildError(err.status, err.code, 'An internal error occurred', undefined, correlation_id);
       }
 
+      if (err.code === 'UNKNOWN_OPERATION') {
+        this._logger.warn(
+          'unknown operation requested',
+          { err, operation, correlation_id, code: err.code, status: err.status }
+        );
+        return this._buildError(err.status, err.code, err.message, undefined, correlation_id);
+      }
+
+      if (err.code === 'CLIENT_CANCELLED') {
+        this._logger.info(
+          'invocation aborted by client',
+          { err, operation, correlation_id, code: err.code, status: err.status }
+        );
+        return this._buildError(err.status, err.code, err.message, undefined, correlation_id);
+      }
+
+      if (err.code === 'VALIDATION_FAILED') {
+        this._logger.info(
+          'input schema validation failed',
+          { err, operation, correlation_id, code: err.code, status: err.status }
+        );
+        return this._buildError(err.status, err.code, err.message, err.details, correlation_id);
+      }
+
       this._logger.info(
         'handler raised BusinessError',
         { err, operation, correlation_id, code: err.code, status: err.status }
@@ -233,8 +387,11 @@ class ErrorMapper {
       return this._buildError(err.status, err.code, err.message, err.details, correlation_id);
     }
 
-    if (err instanceof AbortError || (err && err.name === 'AbortError')) {
-      const message = err && err.message ? err.message : 'Invocation aborted';
+    // Deliberately NOT the brand contract: an abort is a platform signal, not a
+    // business error, and the one we must recognise is Node's own DOMException
+    // from AbortController, which we do not construct and cannot brand.
+    if (err && err.name === 'AbortError') {
+      const message = err.message ? err.message : 'Invocation aborted';
       this._logger.info(
         'invocation aborted by client',
         { err, operation, correlation_id, code: 'CLIENT_CANCELLED', status: 499 }
@@ -265,6 +422,8 @@ class ErrorMapper {
 }
 
 module.exports = {
+  BUSINESS_ERROR_BRAND,
+  isBusinessError,
   ErrorMapper,
   BusinessError,
   ValidationError,

package/src/ServiceWrapper.js

@@ -326,7 +326,8 @@ class ServiceWrapper {
   /**
    * Fail-fast validation of naming conventions and workspaceScoped invariants.
    *
-   * Enforced rules (all normative — see OPERATIONS.md, biz-service-onboarding.md):
+   * Enforced rules (all normative — see api/docs/biz/30-operations/schema-v3.md and
+   * api/docs/biz/60-templates/onboarding-checklist.md):
    *   1. Every key in `operations.operations` matches kebab-case regex
    *      /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/ (no camelCase, snake_case, or PascalCase).
    *   2. `config.service.workspaceScoped` is an explicit boolean (no default).
@@ -379,12 +380,14 @@ class ServiceWrapper {
     }
 
     // Rules 3 & 4: workspaceScoped consistency with list-workspaces
+    // @see api/docs/biz/60-templates/onboarding-checklist.md §4 (workspace discovery convention)
+    // @see api/docs/biz/30-operations/schema-v3.md § Reserved operation names
     const hasListWorkspaces = Object.prototype.hasOwnProperty.call(opsMap, 'list-workspaces');
     if (ws === true && !hasListWorkspaces) {
       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/biz/60-templates/onboarding-checklist.md §4 and OPERATIONS.md §Reserved operation names.`
+          `Workspace-scoped services MUST expose list-workspaces (workspace discovery convention) - ` +
+          `Fix: declare a 'list-workspaces' operation in config/service/operations.json, or set service.workspaceScoped to false.`
       );
     }
     if (ws === false && hasListWorkspaces) {
@@ -1587,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();
 
@@ -2391,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) {
@@ -2442,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.
@@ -2486,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));
@@ -2614,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) {

package/src/index.js

@@ -124,6 +124,8 @@ const { OperationContext } = require('./OperationContext');
 const { ContextBuilder } = require('./ContextBuilder');
 const { SchemaValidator } = require('./SchemaValidator');
 const {
+  BUSINESS_ERROR_BRAND,
+  isBusinessError,
   ErrorMapper,
   BusinessError,
   ValidationError,
@@ -161,6 +163,18 @@ module.exports.ErrorMapper = ErrorMapper;
 // biz service throws; the retired @onlineapps/service-common hierarchy used the
 // same `(message, options)` signature, so migration is an import-line change.
 // Contract + per-class status/code: src/ErrorMapper.js header.
+//
+// The contract itself (DÁVKA 50, confirmation 20260829-1500-business-error-contract-001)
+// is the BRAND plus the SHAPE, not the class identity: an error is a business
+// error when it carries `BUSINESS_ERROR_BRAND` === true, a `code` matching
+// /^[A-Z][A-Z0-9_]*$/, a numeric `status` in [100, 599] and a non-empty
+// `message`. ErrorMapper dispatches on `code`, never on `instanceof`, so a
+// service may throw its OWN class as long as it declares the brand and the
+// shape — `isBusinessError()` is the predicate that decides. Branded but
+// malformed is a named 500 MALFORMED_BUSINESS_ERROR; unbranded stays a masked
+// 500 INTERNAL_ERROR.
+module.exports.BUSINESS_ERROR_BRAND = BUSINESS_ERROR_BRAND;
+module.exports.isBusinessError = isBusinessError;
 module.exports.BusinessError = BusinessError;
 module.exports.ValidationError = ValidationError;
 module.exports.NotFoundError = NotFoundError;