@onlineapps/service-wrapper 3.4.6 → 3.4.7

package/examples/README.md

@@ -166,5 +166,5 @@ curl -X POST http://localhost:33000/workflow \
 
 - [Operations Standard](/docs/OPERATIONS_STANDARD.md)
 - [Service Wrapper Configuration](../docs/CONFIGURATION_GUIDE.md)
-- [Workflow Module](/docs/modules/workflow.md)
+- [Workflow Architecture](/docs/architecture/workflow.md)
 - [Hello Service Examples](/services/hello-service/docs/WORKFLOW_EXECUTION.md)

package/jest.config.js

@@ -9,8 +9,16 @@ module.exports = {
   testMatch: [
     '**/tests/**/*.test.js'
   ],
+  // The integration tier owns its runner (jest.integration.config.js) because it
+  // needs a globalSetup that probes its live sidecar and env config that fails
+  // fast — and because it may not use the moduleNameMapper below, which points
+  // the connectors at mocks.
+  // Picked up by THIS config it ran without that setup, which is why it used to
+  // gate itself with `it.skip(...)` and report green while executing nothing.
+  // Run it with `npm run test:integration`.
   testPathIgnorePatterns: [
-    '/node_modules/'
+    '/node_modules/',
+    '/tests/integration/'
   ],
   coverageThresholds: {
     global: {
@@ -28,7 +36,12 @@ module.exports = {
     '@onlineapps/conn-orch-orchestrator': '<rootDir>/tests/mocks/connectors.js',
     '@onlineapps/conn-orch-orchestrator/package.json': '<rootDir>/tests/mocks/orchestrator-package-v2.js',
     '@onlineapps/conn-orch-cookbook': '<rootDir>/tests/mocks/connectors.js',
-    '@onlineapps/conn-base-state': '<rootDir>/tests/mocks/connectors.js'
+    // Anchored on purpose: moduleNameMapper keys are unanchored regexes, so the
+    // bare form also matches every absolute path containing the package name —
+    // including node_modules/@onlineapps/conn-base-state/src/index.js itself.
+    // That made the real connector unreachable from any test in this package.
+    // tests/integration/state-in-context.integration.test.js loads it by path.
+    '^@onlineapps/conn-base-state$': '<rootDir>/tests/mocks/connectors.js'
   },
   setupFilesAfterEnv: ['<rootDir>/tests/setup.js'],
   verbose: true

package/jest.integration.config.js

@@ -0,0 +1,29 @@
+'use strict';
+
+/**
+ * Separate Jest runner for the integration tier.
+ *
+ * It exists for two reasons, both of which the shared `jest.config.js` cannot
+ * serve:
+ *
+ *   1. `globalSetup` probes the live Redis and aborts the run when it is absent,
+ *     so the tier can never report a result on an environment that cannot serve
+ *     it (`tests/integration/setup.js`).
+ *   2. NO `moduleNameMapper`. The shared config maps the connectors to
+ *     `tests/mocks/connectors.js`, which is correct for the unit tier and wrong
+ *     here: an integration test that runs against mocks proves the call was
+ *     made, never the result (`architecture-principles.md` §10a — mocks are for
+ *     neighbours, never for the SUT).
+ *
+ * `tests/setup.js` is deliberately NOT loaded: it silences `console.error` and
+ * `console.warn`, which is exactly the output an integration failure needs.
+ */
+
+module.exports = {
+  testEnvironment: 'node',
+  testMatch: ['**/tests/integration/**/*.test.js'],
+  testTimeout: 30000,
+  globalSetup: './tests/integration/setup.js',
+  coverageDirectory: 'coverage-integration',
+  verbose: true
+};

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@onlineapps/service-wrapper",
-  "version": "3.4.6",
+  "version": "3.4.7",
   "description": "Thin orchestration layer for microservices - delegates all infrastructure concerns to specialized connectors",
   "main": "src/index.js",
   "scripts": {
     "test": "jest",
     "test:unit": "jest tests/unit",
     "test:component": "jest tests/component",
-    "test:integration": "jest tests/integration",
+    "test:integration": "jest --config=jest.integration.config.js",
     "test:coverage": "jest --coverage",
     "test:mocked": "node test/run-tests.js",
     "docs": "jsdoc2md --files src/**/*.js > API.md",
@@ -25,19 +25,19 @@
   "license": "MIT",
   "dependencies": {
     "@onlineapps/conn-base-cache": "1.0.9",
-    "@onlineapps/conn-base-monitoring": "1.0.14",
+    "@onlineapps/conn-base-monitoring": "1.0.15",
     "@onlineapps/conn-base-state": "1.0.1",
-    "@onlineapps/conn-infra-error-handler": "1.0.13",
+    "@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.6",
+    "@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.5",
-    "@onlineapps/monitoring-core": "1.0.25",
+    "@onlineapps/infrastructure-tools": "1.2.6",
+    "@onlineapps/monitoring-core": "1.0.26",
     "@onlineapps/runtime-config": "1.0.2",
-    "@onlineapps/service-common": "1.2.0",
+    "@onlineapps/service-common": "2.0.0",
     "ajv": "8.17.1",
     "ajv-formats": "3.0.1"
   },

package/src/ContextBuilder.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const { OperationContext } = require('./OperationContext');
+const { InvalidEnvelopeError } = require('./ErrorMapper');
 
 /**
  * ContextBuilder — assembles an OperationContext for a single invocation.
@@ -8,8 +9,11 @@ const { OperationContext } = require('./OperationContext');
  * Contract: RFC `api/docs/architecture/biz-service-invocation-model.md` §5.6 + §5.9.
  * Layer: L3 orchestration (see ARCHITECTURE_PRINCIPLES.md §7).
  *   - Depends on connectors (L1/L2) via constructor injection only.
- *   - Imports `./OperationContext` only. MUST NOT import HandlerRegistry,
- *     SchemaValidator, or ErrorMapper.
+ *   - Imports `./OperationContext` and the error CLASSES from `./ErrorMapper`
+ *     (L2 types, no behaviour — ErrorMapper itself imports nothing, so there is
+ *     no cycle; `./OperationContext` already depends on the same module).
+ *     MUST NOT import HandlerRegistry or SchemaValidator, and MUST NOT call
+ *     ErrorMapper.map() — mapping stays the wrapper's job.
  *   - Does NOT validate handler input/output schemas (SchemaValidator owns that).
  *   - Does NOT invoke handlers (ServiceWrapper owns that).
  *
@@ -20,14 +24,14 @@ const { OperationContext } = require('./OperationContext');
 class ContextBuilder {
   /**
    * @param {Object} deps
-   * @param {Object} deps.connectors - { storage, cache, http, secrets, monitoring, mq }
+   * @param {Object} deps.connectors - { storage, cache, http, secrets, state, monitoring, mq }
    * @param {Object} deps.config     - Read-only service config snapshot.
    * @param {Object} deps.logger     - Base logger (must expose `.child()` to be useful).
    */
   constructor({ connectors, config, logger } = {}) {
     if (!connectors) {
       throw new Error(
-        '[ContextBuilder] connectors is required - Expected { storage, cache, http, secrets, monitoring, mq }'
+        '[ContextBuilder] connectors is required - Expected { storage, cache, http, secrets, state, monitoring, mq }'
       );
     }
     if (!config) {
@@ -54,7 +58,7 @@ class ContextBuilder {
    *      Unset bundle_scope defaults to 'workspace' (strictest) per RFC §5.6 policy.
    *   3. Scoped logger (via base.child() when available; fall back to base logger
    *      only when the base does not implement .child — bunyan/pino both do).
-   *   4. Connector acquisition (db, cache, httpClient, secrets facade).
+   *   4. Connector acquisition (db, cache, httpClient, state, secrets facade).
    *   5. stream(chunk) -> mq.publishChunk (TODO P4.x biz-aiclient integration).
    *   6. abortSignal — external mqMessage.abortSignal wins; otherwise a no-op
    *      controller (plumbing for cancellation is intentionally out of scope here).
@@ -67,6 +71,8 @@ class ContextBuilder {
    */
   async build(mqMessage, operationSpec) {
     this._validateMqMessage(mqMessage);
+    // Untyped on purpose: a missing operationSpec means operations.json or the
+    // registry lookup is broken — our bug, so it must surface as a 500.
     if (!operationSpec || typeof operationSpec !== 'object') {
       throw new Error(
         '[ContextBuilder] operationSpec is required - Expected operations.json entry with bundle_scope'
@@ -90,6 +96,10 @@ class ContextBuilder {
     const { db, releaseDb } = await this._acquireDb();
     const cache = this._connectors.cache;
     const httpClient = this._connectors.http;
+    // Persistent Redis state (conn-base-state). Plain pass-through like `cache`:
+    // the connector namespaces its keys by `state:<serviceName>:` on its own, so
+    // there is no invocation scope for the builder to inject.
+    const state = this._connectors.state;
     const secretsAdapter = this._connectors.secrets;
     const secrets = {
       // Handlers call ctx.secrets.get(ref); the facade injects the invocation
@@ -136,6 +146,7 @@ class ContextBuilder {
       cache,
       httpClient,
       secrets,
+      state,
       stream,
       abortSignal,
       config: this._config
@@ -164,32 +175,41 @@ class ContextBuilder {
   }
 
   /**
+   * Validate the MQ envelope shape. Every field checked here is supplied by the
+   * caller, so every failure is InvalidEnvelopeError (400) naming the key.
    * @private
    */
   _validateMqMessage(mqMessage) {
     if (!mqMessage || typeof mqMessage !== 'object') {
-      throw new Error('[ContextBuilder] mqMessage is required - Expected parsed MQ message object');
+      throw new InvalidEnvelopeError('[ContextBuilder] mqMessage is required - Expected parsed MQ message object');
     }
     if (typeof mqMessage.operation !== 'string' || mqMessage.operation.length === 0) {
-      throw new Error('[ContextBuilder] mqMessage.operation is required - Expected non-empty string');
+      throw new InvalidEnvelopeError('[ContextBuilder] mqMessage.operation is required - Expected non-empty string');
     }
     if (!mqMessage.envelope || typeof mqMessage.envelope !== 'object') {
-      throw new Error(
+      throw new InvalidEnvelopeError(
         '[ContextBuilder] mqMessage.envelope is required - ' +
         'Expected object with tenant_id, workspace_id, optional person_id'
       );
     }
     if (typeof mqMessage.workflow_id !== 'string' || mqMessage.workflow_id.length === 0) {
-      throw new Error('[ContextBuilder] mqMessage.workflow_id is required - Expected uuid string');
+      throw new InvalidEnvelopeError('[ContextBuilder] mqMessage.workflow_id is required - Expected uuid string');
     }
     if (typeof mqMessage.correlation_id !== 'string' || mqMessage.correlation_id.length === 0) {
-      throw new Error('[ContextBuilder] mqMessage.correlation_id is required - Expected uuid string');
+      throw new InvalidEnvelopeError('[ContextBuilder] mqMessage.correlation_id is required - Expected uuid string');
     }
   }
 
   /**
    * Enforce bundle_scope tenancy requirements per RFC §5.6 + §6.3 Bug 1 mapping.
    * Tenancy is derived from the MQ envelope only — never from HTTP headers.
+   *
+   * Two fault owners, two statuses:
+   *   - `bundleScope` comes from OUR operations.json. An invalid value is a
+   *     packaging bug, stays an untyped Error and maps to 500.
+   *   - `envelope.*` comes from the caller / the cookbook author. A missing id
+   *     is their bug, is thrown as InvalidEnvelopeError and maps to 400 with
+   *     the missing key named.
    * @private
    */
   _validateTenancy(bundleScope, envelope) {
@@ -202,7 +222,7 @@ class ContextBuilder {
 
     if (bundleScope === 'tenant' || bundleScope === 'workspace') {
       if (envelope.tenant_id === undefined || envelope.tenant_id === null) {
-        throw new Error(
+        throw new InvalidEnvelopeError(
           `[ContextBuilder] mqMessage.envelope.tenant_id is required for bundle_scope="${bundleScope}" - ` +
           'tenancy must come from the MQ envelope (see RFC §6.3 Bug 1)'
         );
@@ -210,9 +230,10 @@ class ContextBuilder {
     }
     if (bundleScope === 'workspace') {
       if (envelope.workspace_id === undefined || envelope.workspace_id === null) {
-        throw new Error(
+        throw new InvalidEnvelopeError(
           '[ContextBuilder] mqMessage.envelope.workspace_id is required for bundle_scope="workspace" - ' +
-          'workspace-scoped ops must receive a workspace_id in the MQ envelope'
+          'workspace-scoped ops must receive a workspace_id in the MQ envelope. ' +
+          'Fix: set defaults.workspace_id (or the step-level workspace_id) in the cookbook'
         );
       }
     }

package/src/ErrorMapper.js

@@ -10,33 +10,32 @@
  *
  * Exports:
  *   - ErrorMapper            — maps exceptions to { status, error: {...} } envelopes.
- *   - ValidationError        — thrown by SchemaValidator (phase: 'input' | 'output').
- *   - UnknownOperationError  — thrown by HandlerRegistry for unregistered ops.
  *   - BusinessError          — base class for handler-authored errors (code + status required).
+ *   - ValidationError        — 400 VALIDATION_FAILED. Thrown by SchemaValidator
+ *                              (phase: 'input' | 'output') and by handlers.
+ *   - NotFoundError          — 404 RESOURCE_NOT_FOUND.
+ *   - ConflictError          — 409 DUPLICATE_RESOURCE.
+ *   - BusinessRuleError      — 422 BUSINESS_RULE_VIOLATED.
+ *   - AuthorizationError     — 403 FORBIDDEN.
+ *   - InvalidEnvelopeError   — 400 INVALID_ENVELOPE. Thrown by ContextBuilder when
+ *                              the MQ envelope from the caller is malformed.
+ *   - UnknownOperationError  — thrown by HandlerRegistry for unregistered ops.
  *   - AbortError             — thrown when ctx.abortSignal aborts the invocation.
+ *
+ * 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.
+ *   - every named subclass takes `(message, { details, operation })` — code and
+ *     status are the subclass's own identity and MUST NOT be author-supplied.
+ * The subclass shape is deliberately identical to the retired
+ * `@onlineapps/service-common` hierarchy so a biz service migrates by changing
+ * its import line only.
+ *
+ * ❌ No subclass carries a default status. A default (service-common used
+ * `statusCode = 500`) turns an unset field into a fabricated server error; the
+ * base class fail-fasts instead.
  */
 
-class ValidationError extends Error {
-  constructor({ message, details, phase, operation } = {}) {
-    super(message);
-    this.name = 'ValidationError';
-    this.code = 'VALIDATION_FAILED';
-    this.status = 400;
-    this.details = details;
-    this.phase = phase;
-    this.operation = operation;
-  }
-}
-
-class UnknownOperationError extends Error {
-  constructor(message) {
-    super(message);
-    this.name = 'UnknownOperationError';
-    this.code = 'UNKNOWN_OPERATION';
-    this.status = 404;
-  }
-}
-
 class BusinessError extends Error {
   constructor({ code, status, message, details } = {}) {
     if (!code) {
@@ -56,6 +55,105 @@ class BusinessError extends Error {
   }
 }
 
+/**
+ * 400. Input a caller (or a handler's own field check) rejected.
+ *
+ * `phase` is set only by SchemaValidator: 'input' means the caller's payload
+ * failed the operation schema, 'output' means the handler produced a payload
+ * that violates its own contract (a server bug — see map()). A handler-thrown
+ * ValidationError has no phase and maps to a plain 400.
+ *
+ * @param {string} message
+ * @param {Object} [options]
+ * @param {*} [options.details]
+ * @param {'input'|'output'} [options.phase]
+ * @param {string} [options.operation]
+ */
+class ValidationError extends BusinessError {
+  constructor(message, { details, phase, operation } = {}) {
+    super({ code: 'VALIDATION_FAILED', status: 400, message, details });
+    this.name = 'ValidationError';
+    if (phase !== undefined) {
+      this.phase = phase;
+    }
+    if (operation !== undefined) {
+      this.operation = operation;
+    }
+  }
+}
+
+/** 404. The addressed resource does not exist. */
+class NotFoundError extends BusinessError {
+  constructor(message, { details, operation } = {}) {
+    super({ code: 'RESOURCE_NOT_FOUND', status: 404, message, details });
+    this.name = 'NotFoundError';
+    if (operation !== undefined) {
+      this.operation = operation;
+    }
+  }
+}
+
+/** 409. The write collides with an existing resource or uniqueness constraint. */
+class ConflictError extends BusinessError {
+  constructor(message, { details, operation } = {}) {
+    super({ code: 'DUPLICATE_RESOURCE', status: 409, message, details });
+    this.name = 'ConflictError';
+    if (operation !== undefined) {
+      this.operation = operation;
+    }
+  }
+}
+
+/** 422. Shape is valid, a domain rule says no. */
+class BusinessRuleError extends BusinessError {
+  constructor(message, { details, operation } = {}) {
+    super({ code: 'BUSINESS_RULE_VIOLATED', status: 422, message, details });
+    this.name = 'BusinessRuleError';
+    if (operation !== undefined) {
+      this.operation = operation;
+    }
+  }
+}
+
+/** 403. The caller is authenticated but not entitled to this resource. */
+class AuthorizationError extends BusinessError {
+  constructor(message, { details, operation } = {}) {
+    super({ code: 'FORBIDDEN', status: 403, message, details });
+    this.name = 'AuthorizationError';
+    if (operation !== undefined) {
+      this.operation = operation;
+    }
+  }
+}
+
+/**
+ * 400. The MQ envelope the caller (or the cookbook author) sent is malformed —
+ * a missing tenant_id / workspace_id / workflow_id / correlation_id.
+ *
+ * Distinct from ValidationError on purpose: VALIDATION_FAILED means the
+ * operation's own input schema was violated, INVALID_ENVELOPE means the
+ * transport-level context never arrived, so a reader of the log can tell a
+ * broken cookbook from a broken payload without opening the message.
+ */
+class InvalidEnvelopeError extends BusinessError {
+  constructor(message, { details, operation } = {}) {
+    super({ code: 'INVALID_ENVELOPE', status: 400, message, details });
+    this.name = 'InvalidEnvelopeError';
+    if (operation !== undefined) {
+      this.operation = operation;
+    }
+  }
+}
+
+class UnknownOperationError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'UnknownOperationError';
+    this.code = 'UNKNOWN_OPERATION';
+    this.status = 404;
+  }
+}
+
 class AbortError extends Error {
   constructor(message) {
     super(message || 'Invocation aborted');
@@ -115,6 +213,19 @@ class ErrorMapper {
     }
 
     if (err instanceof BusinessError) {
+      // A BusinessError 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)
+      // never leaves the process. Details are dropped for the same reason.
+      if (err.status >= 500) {
+        this._logger.error(
+          'handler raised BusinessError with a server-fault status',
+          { err, operation, correlation_id, code: err.code, status: err.status, stack: err && err.stack }
+        );
+        return this._buildError(err.status, err.code, 'An internal error occurred', undefined, correlation_id);
+      }
+
       this._logger.info(
         'handler raised BusinessError',
         { err, operation, correlation_id, code: err.code, status: err.status }
@@ -155,8 +266,13 @@ class ErrorMapper {
 
 module.exports = {
   ErrorMapper,
+  BusinessError,
   ValidationError,
+  NotFoundError,
+  ConflictError,
+  BusinessRuleError,
+  AuthorizationError,
+  InvalidEnvelopeError,
   UnknownOperationError,
-  BusinessError,
   AbortError
 };

package/src/OperationContext.js

@@ -8,7 +8,7 @@ const { ValidationError } = require('./ErrorMapper');
  *
  * Contract: RFC `api/docs/architecture/biz-service-invocation-model.md` §5.6.
  *
- * Exactly 14 named fields, assembled by ContextBuilder.build() once per
+ * Exactly 15 named fields, assembled by ContextBuilder.build() once per
  * invocation and frozen before the handler runs:
  *
  *   Row-level scoping (from MQ envelope):
@@ -27,6 +27,8 @@ const { ValidationError } = require('./ErrorMapper');
  *     cache           — CacheAdapter (tenant-namespaced)
  *     httpClient      — axios instance
  *     secrets         — { get(name) => Promise<string> }
+ *     state           — StateConnector (persistent Redis state, no TTL,
+ *                       keys namespaced `state:<serviceName>:`) | null
  *     stream          — (chunk) => Promise<void>
  *     abortSignal     — AbortSignal
  *     config          — read-only service config snapshot
@@ -49,14 +51,14 @@ const { ValidationError } = require('./ErrorMapper');
  */
 class OperationContext {
   /**
-   * @param {Object} fields - The 14 fields listed above, fully populated.
+   * @param {Object} fields - The 15 fields listed above, fully populated.
    */
   constructor(fields) {
     if (!fields || typeof fields !== 'object') {
       throw new Error(
-        '[OperationContext] fields is required - Expected object with 14 named fields per RFC §5.6 ' +
+        '[OperationContext] fields is required - Expected object with 15 named fields per RFC §5.6 ' +
         '(tenant_id, workspace_id, person_id, operation_name, workflow_id, correlation_id, ' +
-        'logger, db, cache, httpClient, secrets, stream, abortSignal, config)'
+        'logger, db, cache, httpClient, secrets, state, stream, abortSignal, config)'
       );
     }
 
@@ -91,11 +93,10 @@ class OperationContext {
     const to = OperationContext._parseBoundary(dateTo, 'dateTo', 'end');
 
     if (to.getTime() < from.getTime()) {
-      throw new ValidationError({
-        message:
-          '[OperationContext.normalizeDateRange] dateTo is earlier than dateFrom - ' +
-          'Expected ISO date string (YYYY-MM-DD) or ISO datetime'
-      });
+      throw new ValidationError(
+        '[OperationContext.normalizeDateRange] dateTo is earlier than dateFrom - ' +
+        'Expected ISO date string (YYYY-MM-DD) or ISO datetime'
+      );
     }
 
     return { from, to };
@@ -110,27 +111,24 @@ class OperationContext {
    */
   static _parseBoundary(value, field, mode) {
     if (value === null || value === undefined) {
-      throw new ValidationError({
-        message:
-          `[OperationContext.normalizeDateRange] ${field} is null or undefined - ` +
-          'Expected ISO date string (YYYY-MM-DD) or ISO datetime'
-      });
+      throw new ValidationError(
+        `[OperationContext.normalizeDateRange] ${field} is null or undefined - ` +
+        'Expected ISO date string (YYYY-MM-DD) or ISO datetime'
+      );
     }
     if (typeof value !== 'string') {
-      throw new ValidationError({
-        message:
-          `[OperationContext.normalizeDateRange] ${field} is not a string - ` +
-          'Expected ISO date string (YYYY-MM-DD) or ISO datetime'
-      });
+      throw new ValidationError(
+        `[OperationContext.normalizeDateRange] ${field} is not a string - ` +
+        'Expected ISO date string (YYYY-MM-DD) or ISO datetime'
+      );
     }
 
     const trimmed = value.trim();
     if (trimmed.length === 0) {
-      throw new ValidationError({
-        message:
-          `[OperationContext.normalizeDateRange] ${field} is empty - ` +
-          'Expected ISO date string (YYYY-MM-DD) or ISO datetime'
-      });
+      throw new ValidationError(
+        `[OperationContext.normalizeDateRange] ${field} is empty - ` +
+        'Expected ISO date string (YYYY-MM-DD) or ISO datetime'
+      );
     }
 
     const isoDate = /^\d{4}-\d{2}-\d{2}$/;
@@ -143,19 +141,17 @@ class OperationContext {
     } else if (isoDateTime.test(trimmed)) {
       d = new Date(trimmed);
     } else {
-      throw new ValidationError({
-        message:
-          `[OperationContext.normalizeDateRange] ${field} is unparseable - ` +
-          'Expected ISO date string (YYYY-MM-DD) or ISO datetime'
-      });
+      throw new ValidationError(
+        `[OperationContext.normalizeDateRange] ${field} is unparseable - ` +
+        'Expected ISO date string (YYYY-MM-DD) or ISO datetime'
+      );
     }
 
     if (isNaN(d.getTime())) {
-      throw new ValidationError({
-        message:
-          `[OperationContext.normalizeDateRange] ${field} is unparseable - ` +
-          'Expected ISO date string (YYYY-MM-DD) or ISO datetime'
-      });
+      throw new ValidationError(
+        `[OperationContext.normalizeDateRange] ${field} is unparseable - ` +
+        'Expected ISO date string (YYYY-MM-DD) or ISO datetime'
+      );
     }
 
     return d;

package/src/SchemaValidator.js

@@ -145,8 +145,7 @@ class SchemaValidator {
     }
 
     const errors = fn.errors || [];
-    throw new ValidationError({
-      message: _summariseAjvError('input', errors),
+    throw new ValidationError(_summariseAjvError('input', errors), {
       phase: 'input',
       operation,
       details: errors
@@ -180,8 +179,7 @@ class SchemaValidator {
     }
 
     const errors = fn.errors || [];
-    throw new ValidationError({
-      message: _summariseAjvError('output', errors),
+    throw new ValidationError(_summariseAjvError('output', errors), {
       phase: 'output',
       operation,
       details: errors

package/src/index.js

@@ -17,6 +17,7 @@ const { ConfigLoader } = require('./ConfigLoader');
 const runtimeCfg = require('./config');
 const pkg = require('../package.json');
 const { createTenantContextMiddleware } = require('./createTenantContextMiddleware');
+const { setLogger: setSharedLogger, getLogger: getSharedLogger } = require('./logger');
 
 // Note: WorkflowProcessor functionality has been moved to
 // @onlineapps/conn-orch-orchestrator. The former ApiCaller /
@@ -124,9 +125,14 @@ const { ContextBuilder } = require('./ContextBuilder');
 const { SchemaValidator } = require('./SchemaValidator');
 const {
   ErrorMapper,
+  BusinessError,
   ValidationError,
+  NotFoundError,
+  ConflictError,
+  BusinessRuleError,
+  AuthorizationError,
+  InvalidEnvelopeError,
   UnknownOperationError,
-  BusinessError,
   AbortError
 } = require('./ErrorMapper');
 
@@ -135,6 +141,12 @@ module.exports.ServiceWrapper = ServiceWrapper;
 module.exports.ConfigLoader = ConfigLoader;
 module.exports.bootstrap = bootstrap;
 module.exports.createTenantContextMiddleware = createTenantContextMiddleware;
+
+// Shared logger proxy (F15 step 1). Single owner of the late-binding
+// setLogger/getLogger pair that every biz service used to keep as its own
+// `src/lib/logger.js` copy. See src/logger.js for the contract.
+module.exports.setLogger = setSharedLogger;
+module.exports.getLogger = getSharedLogger;
 module.exports.default = ServiceWrapper;
 module.exports.VERSION = pkg.version;
 
@@ -144,7 +156,17 @@ module.exports.OperationContext = OperationContext;
 module.exports.ContextBuilder = ContextBuilder;
 module.exports.SchemaValidator = SchemaValidator;
 module.exports.ErrorMapper = ErrorMapper;
+
+// Error hierarchy (DÁVKA 29). Single owner of the business-error classes every
+// 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.
+module.exports.BusinessError = BusinessError;
 module.exports.ValidationError = ValidationError;
+module.exports.NotFoundError = NotFoundError;
+module.exports.ConflictError = ConflictError;
+module.exports.BusinessRuleError = BusinessRuleError;
+module.exports.AuthorizationError = AuthorizationError;
+module.exports.InvalidEnvelopeError = InvalidEnvelopeError;
 module.exports.UnknownOperationError = UnknownOperationError;
-module.exports.BusinessError = BusinessError;
 module.exports.AbortError = AbortError;

package/src/logger.js

@@ -0,0 +1,116 @@
+'use strict';
+
+/**
+ * @module @onlineapps/service-wrapper/logger
+ * @description Shared logger proxy for business services.
+ *
+ * Handlers, services and controllers are `require`d at module load time, long
+ * before `wrapper.initialize()` has produced a real logger. This module is the
+ * late-binding indirection between the two: bootstrap calls `setLogger()` once,
+ * every consumer calls `getLogger()` whenever it actually logs.
+ *
+ * Fail-fast, no fallback. If `getLogger()` is reached before `setLogger()`, that
+ * is a wiring defect and it throws — it does NOT hand back a console-shaped
+ * substitute. A silent console fallback makes a service that lost its real
+ * logger look healthy: the log lines still appear on stdout, while nothing
+ * reaches the monitoring connector, the log files or the correlation context.
+ * See `architecture-principles.md` §3 (No Fallbacks) and §4 (Fail-Fast).
+ *
+ * Consumers call `getLogger()` at call time, never at module scope — binding
+ * the result into a module-level constant would capture the state before
+ * bootstrap and defeat the indirection.
+ *
+ * @example
+ * // bootstrap, once, after wrapper.initialize()
+ * const { setLogger } = require('@onlineapps/service-wrapper');
+ * setLogger(wrapper.logger);
+ *
+ * @example
+ * // any consumer
+ * const { getLogger } = require('@onlineapps/service-wrapper');
+ * function handle() {
+ *   getLogger().info('Message', { data: 'value' });
+ * }
+ */
+
+/**
+ * Methods a logger instance must expose. This is the contract every consumer
+ * of `getLogger()` relies on, so it is validated at injection time rather than
+ * discovered at the first `logger.debug(...)` in an error path.
+ * @type {string[]}
+ */
+const REQUIRED_METHODS = ['info', 'warn', 'error', 'debug'];
+
+const FIX_HINT =
+  'Fix: pass wrapper.logger to setLogger() once during bootstrap, after wrapper.initialize().';
+
+/** @type {Object|null} */
+let _logger = null;
+
+/**
+ * Inject the logger instance. Called once during bootstrap; a later call
+ * replaces the instance (tests wire an in-memory logger this way).
+ *
+ * @param {Object} logger - Logger exposing info/warn/error/debug as functions.
+ * @throws {Error} If `logger` is not an object exposing all four methods. The
+ *   previously stored instance is left untouched when validation fails.
+ * @returns {void}
+ */
+function setLogger(logger) {
+  if (logger === null || typeof logger !== 'object' || Array.isArray(logger)) {
+    throw new Error(
+      `[Logger] setLogger() received ${describe(logger)} - expected an object exposing ` +
+        `${REQUIRED_METHODS.join('/')}. ${FIX_HINT}`
+    );
+  }
+
+  const missing = REQUIRED_METHODS.filter((method) => typeof logger[method] !== 'function');
+  if (missing.length > 0) {
+    throw new Error(
+      `[Logger] setLogger() received an incomplete logger - missing callable method(s): ` +
+        `${missing.join(', ')}. Expected an object exposing ${REQUIRED_METHODS.join('/')}. ${FIX_HINT}`
+    );
+  }
+
+  _logger = logger;
+}
+
+/**
+ * Return the injected logger.
+ *
+ * @throws {Error} If `setLogger()` has not run yet. There is no console
+ *   fallback — an uninitialised logger is a bootstrap defect, not a degraded
+ *   mode to be papered over.
+ * @returns {Object} The logger passed to `setLogger()`.
+ */
+function getLogger() {
+  if (_logger === null) {
+    throw new Error(
+      '[Logger] Logger not initialized - getLogger() was called before setLogger(wrapper.logger). ' +
+        'Fix: call setLogger(wrapper.logger) once during bootstrap, after wrapper.initialize(), ' +
+        'before any consumer runs.'
+    );
+  }
+
+  return _logger;
+}
+
+/**
+ * Name the rejected value in the error message, so the caller sees what it
+ * actually passed rather than a bare type name.
+ *
+ * @param {*} value - The rejected argument.
+ * @returns {string} Human-readable description.
+ * @private
+ */
+function describe(value) {
+  if (value === null) {
+    return 'null';
+  }
+  if (Array.isArray(value)) {
+    return 'an array';
+  }
+  return `a value of type "${typeof value}"`;
+}
+
+module.exports = { setLogger, getLogger };