@onlineapps/conn-orch-validator 3.3.1 → 4.0.0

package/src/mocks/MockMQClient.js

@@ -3,12 +3,22 @@
 /**
  * MockMQClient - Simulates RabbitMQ for testing
  * Provides in-memory message queue simulation
+ *
+ * The surface mirrors `@onlineapps/mq-client-core` `BaseClient` — that is the
+ * client every service actually holds, so a divergence here does not merely make
+ * a test unrealistic: it teaches whoever codes against this mock to write the
+ * wrong call. Method names, argument shapes, defaults and error wording are kept
+ * in step with `shared/mq-client-core/src/BaseClient.js` and the RabbitMQ
+ * transport it delegates to.
+ *
+ * @see ../../../../mq-client-core/src/BaseClient.js
+ * @see ../../../../mq-client-core/src/transports/rabbitmqClient.js
  */
 class MockMQClient {
   constructor() {
     this.queues = {};
     this.consumers = {};
-    this.isConnected = false;
+    this._connected = false;
     this.publishedMessages = [];
     this.acknowledgedMessages = [];
     this.rejectedMessages = [];
@@ -18,7 +28,7 @@ class MockMQClient {
    * Simulate connection
    */
   async connect() {
-    this.isConnected = true;
+    this._connected = true;
     return Promise.resolve();
   }
 
@@ -26,17 +36,33 @@ class MockMQClient {
    * Simulate disconnection
    */
   async disconnect() {
-    this.isConnected = false;
+    this._connected = false;
     this.consumers = {};
     return Promise.resolve();
   }
 
+  /**
+   * Connection status.
+   *
+   * A METHOD, matching `BaseClient.isConnected()`. It used to be a boolean
+   * property of the same name, which is the more dangerous kind of mismatch:
+   * `if (client.isConnected)` written against that mock reads a function object
+   * on the real client — always truthy — so the guard never fires and nothing
+   * fails loudly.
+   *
+   * @returns {boolean}
+   */
+  isConnected() {
+    return this._connected === true;
+  }
+
   /**
    * Publish message to queue
    */
   async publish(queue, message, options = {}) {
-    if (!this.isConnected) {
-      throw new Error('Not connected to MQ');
+    if (!this._connected) {
+      // Wording per BaseClient.publish (ConnectionError).
+      throw new Error('Cannot publish: client is not connected');
     }
 
     if (!this.queues[queue]) {
@@ -95,8 +121,9 @@ class MockMQClient {
    * Consume messages from queue
    */
   async consume(queue, callback, options = {}) {
-    if (!this.isConnected) {
-      throw new Error('Not connected to MQ');
+    if (!this._connected) {
+      // Wording per BaseClient.consume (ConnectionError).
+      throw new Error('Cannot consume: client is not connected');
     }
 
     this.consumers[queue] = {
@@ -118,36 +145,94 @@ class MockMQClient {
   }
 
   /**
-   * Acknowledge message
+   * Acknowledge message.
+   *
+   * Signature and idempotence per `BaseClient.ack(msg)` → transport
+   * `rabbitmqClient.js:2286`: a delivery already settled (marked
+   * `_mqProcessed`) is silently skipped rather than settled twice.
+   *
+   * @param {Object} message - Broker message object
+   * @returns {Promise<void>}
    */
   async ack(message) {
+    if (message && message._mqProcessed) {
+      return; // Already acked/nacked — idempotent, as in the real transport
+    }
+
     this.acknowledgedMessages.push({
       message,
       timestamp: Date.now()
     });
-    return Promise.resolve();
+
+    if (message) {
+      message._mqProcessed = true;
+    }
   }
 
   /**
-   * Reject message
+   * Negative-acknowledge a message.
+   *
+   * Signature and semantics per `BaseClient.nack(msg, options)` → transport
+   * `rabbitmqClient.js:2313`:
+   *
+   *   const requeue = options.requeue !== undefined ? options.requeue : true;
+   *
+   * `requeue` therefore defaults to TRUE. This mock previously carried the raw
+   * amqplib positional form `nack(message, allUpTo, requeue)` with `requeue`
+   * defaulting to FALSE — the exact opposite — so code written against it
+   * either dropped messages it meant to retry or retried forever what it meant
+   * to drop. Neither `BaseClient` nor the transport exposes `allUpTo`; it is
+   * pinned to `false` inside the transport and is not part of the contract.
+   *
+   * @param {Object} message - Broker message object
+   * @param {Object} [options] - { requeue: boolean } — requeue defaults to true
+   * @returns {Promise<void>}
    */
-  async nack(message, allUpTo = false, requeue = false) {
+  async nack(message, options = {}) {
+    if (message && message._mqProcessed) {
+      return; // Already acked/nacked — idempotent, as in the real transport
+    }
+
+    const requeue = options.requeue !== undefined ? options.requeue : true;
+
+    if (requeue && !(message && message.fields && message.fields.routingKey)) {
+      throw new Error(
+        '[MockMQClient] Cannot requeue: message has no fields.routingKey - ' +
+        'a broker delivery always carries one. Fix: nack a message obtained from ' +
+        'consume(), or pass { requeue: false } to discard it.'
+      );
+    }
+
     this.rejectedMessages.push({
       message,
-      allUpTo,
       requeue,
       timestamp: Date.now()
     });
 
-    if (requeue && message.fields) {
+    if (message) {
+      message._mqProcessed = true;
+    }
+
+    if (requeue) {
       const queue = message.fields.routingKey;
       if (!this.queues[queue]) {
         this.queues[queue] = [];
       }
+      // A requeued message comes back as a NEW delivery with a new delivery tag,
+      // so it is settleable again. Keeping it marked would cap the retry loop at
+      // one round and hide the very behaviour this mock has to reproduce.
+      message._mqProcessed = false;
       this.queues[queue].push(message);
-    }
 
-    return Promise.resolve();
+      // The broker hands that redelivery straight to the live consumer. Skipping
+      // it is what would hide an always-failing handler's infinite retry loop.
+      if (this.consumers[queue]) {
+        const consumer = this.consumers[queue];
+        setImmediate(() => {
+          consumer.callback(message);
+        });
+      }
+    }
   }
 
   /**

package/src/utils/bizCiGateContract.js

@@ -4,6 +4,8 @@ const fs = require('fs');
 const path = require('path');
 const net = require('net');
 const { execSync } = require('child_process');
+const { readIntegrationRunArtefact } = require('./integrationRun');
+const { normalizeEnvDeclaration, collectEnvCoverage } = require('./envContract');
 
 const CONNECTOR_KEYS = ['db', 'redis', 'mq', 'minio'];
 const DEFAULT_CONTRACT_RELATIVE_PATH = path.join('config', 'service', 'integration-contract.json');
@@ -37,7 +39,78 @@ function assertBoolean(value, fieldName) {
   }
 }
 
-function normalizeIntegrationContract(rawContract, contractPath) {
+// The service declares WHAT its database is; the library implements HOW it is
+// built (see docs/biz/00-model/uniformity-principle.md). Everything the six
+// per-repo ci-setup-db.js scripts used to decide for themselves — client,
+// ordering, foreign-key handling — is a platform property and lives in the
+// library; only these four values legitimately differ per service.
+const SCHEMA_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const ENGINE_DECLARATION = /^(mariadb|mysql):[0-9][0-9.]*$/;
+
+/** A declared path must stay inside the repository — it is resolved against the service root. */
+function assertRepoRelativePath(value, fieldName) {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new Error(`[BizCiGate] Invalid ${fieldName} - Expected a non-empty path relative to the service root. `
+      + 'Fix: e.g. "migrations/*.sql".');
+  }
+  if (path.isAbsolute(value) || value.split('/').includes('..')) {
+    throw new Error(`[BizCiGate] Invalid ${fieldName} - "${value}" points outside the service root. `
+      + 'Fix: use a path relative to the repository, without ".." or a leading "/".');
+  }
+}
+
+function normalizeDatabaseDeclaration(database, connectors) {
+  // Absent means "this service has no database". Null rather than {} so callers
+  // distinguish that from an empty declaration and skip the steps explicitly.
+  if (database === undefined || database === null) return null;
+
+  if (typeof database !== 'object' || Array.isArray(database)) {
+    throw new Error('[BizCiGate] Invalid database - Expected an object with engine, schema and migrations. '
+      + 'Fix: omit the key entirely if the service has no database.');
+  }
+
+  if (!connectors.db) {
+    throw new Error('[BizCiGate] Contradictory contract - database is declared but requiredConnectors.db is false. '
+      + 'Fix: set requiredConnectors.db to true, or remove the database declaration.');
+  }
+
+  if (!ENGINE_DECLARATION.test(database.engine ?? '')) {
+    throw new Error(`[BizCiGate] Invalid database.engine - "${database.engine}" is not <mariadb|mysql>:<version>. `
+      + 'Fix: declare the engine AND its version, e.g. "mariadb:10.5" — CI runs exactly this image, '
+      + 'and testing on a different one proves nothing about the service SQL.');
+  }
+
+  if (!SCHEMA_IDENTIFIER.test(database.schema ?? '')) {
+    throw new Error(`[BizCiGate] Invalid database.schema - "${database.schema}" is not a plain identifier. `
+      + 'Fix: use the real schema name, e.g. "oagen_emailer"; it is interpolated into CREATE DATABASE and USE.');
+  }
+
+  assertRepoRelativePath(database.migrations, 'database.migrations');
+
+  const seeds = database.seeds ?? [];
+  if (!Array.isArray(seeds)) {
+    throw new Error('[BizCiGate] Invalid database.seeds - Expected an array of paths. '
+      + 'Fix: use ["scripts/seed/system.seed.sql"], or omit the key.');
+  }
+  seeds.forEach((seed, i) => assertRepoRelativePath(seed, `database.seeds[${i}]`));
+
+  return {
+    engine: database.engine,
+    schema: database.schema,
+    migrations: database.migrations,
+    seeds
+  };
+}
+
+/**
+ * @param {object} rawContract parsed integration-contract.json
+ * @param {string} contractPath for error messages
+ * @param {object} [options]
+ * @param {Map<string,string>} [options.envCoverage] what M1/M2 already cover; supplied by
+ *   loadAndValidateIntegrationContract, which is the caller that can read the repository.
+ *   Mandatory only when the contract carries an env block — see utils/envContract.js.
+ */
+function normalizeIntegrationContract(rawContract, contractPath, options = {}) {
   if (!rawContract || typeof rawContract !== 'object' || Array.isArray(rawContract)) {
     throw new Error(`[BizCiGate] Invalid contract root - Expected object in ${contractPath}`);
   }
@@ -64,12 +137,17 @@ function normalizeIntegrationContract(rawContract, contractPath) {
     throw new Error('[BizCiGate] Invalid integrationMinimum.minTestFiles - Expected integer >= 1');
   }
 
+  const database = normalizeDatabaseDeclaration(rawContract.database, normalizedConnectors);
+  const env = normalizeEnvDeclaration(rawContract.env, { coverage: options.envCoverage });
+
   return {
     serviceName: rawContract.serviceName || null,
     requiredConnectors: normalizedConnectors,
     integrationMinimum: {
       minTestFiles,
     },
+    database,
+    env,
     setup: rawContract.setup || {},
     raw: rawContract,
   };
@@ -79,7 +157,15 @@ function loadAndValidateIntegrationContract(serviceRoot, contractPath) {
   const resolvedServiceRoot = resolveServiceRoot(serviceRoot);
   const resolvedContractPath = resolveContractPath(resolvedServiceRoot, contractPath);
   const rawContract = readJsonFile(resolvedContractPath);
-  const normalizedContract = normalizeIntegrationContract(rawContract, resolvedContractPath);
+
+  // Coverage is collected from the repository, so only this entry point can
+  // supply it. The env block is rejected outright without it rather than
+  // validated halfway (automation-gates.md §5).
+  const envCoverage = collectEnvCoverage({
+    serviceRoot: resolvedServiceRoot,
+    requiredConnectors: rawContract?.requiredConnectors
+  });
+  const normalizedContract = normalizeIntegrationContract(rawContract, resolvedContractPath, { envCoverage });
 
   return {
     serviceRoot: resolvedServiceRoot,
@@ -214,17 +300,6 @@ function formatEnvironmentOutput(env, format) {
   throw new Error(`[BizCiGate] Unsupported output format - ${format}`);
 }
 
-function parseIntegerOrNull(value) {
-  if (value === undefined || value === null || value === '') {
-    return null;
-  }
-  const parsed = Number.parseInt(String(value), 10);
-  if (!Number.isFinite(parsed)) {
-    return null;
-  }
-  return parsed;
-}
-
 function buildIntegrationSignalSummary(options) {
   const contractInfo = loadAndValidateIntegrationContract(options.serviceRoot, options.contractPath);
   const unitTestFiles = getUnitTestFiles(contractInfo.serviceRoot);
@@ -239,10 +314,27 @@ function buildIntegrationSignalSummary(options) {
     gateReason = options.gateReason || error.message;
   }
 
-  const unitExecuted = parseIntegerOrNull(options.unitExecuted || process.env.OA_CI_UNIT_EXECUTED);
-  const integrationExecuted = parseIntegerOrNull(options.integrationExecuted || process.env.OA_CI_INTEGRATION_EXECUTED);
-  const resolvedUnitExecuted = unitExecuted === null ? unitTestFiles.length : unitExecuted;
-  const resolvedIntegrationExecuted = integrationExecuted === null ? integrationTestFiles.length : integrationExecuted;
+  // Executed figures come from the run artefact or from nowhere. The previous
+  // version fell back to the number of test FILES on disk, which reported tests
+  // as executed that had never run — the exact fake-green this gate exists to
+  // stop. No repo ever supplied the override it fell back from, so the artefact
+  // has always stated a fabricated number.
+  const runArtefact = readIntegrationRunArtefact(contractInfo.serviceRoot);
+  const executed = runArtefact
+    ? {
+      source: 'runner',
+      integrationTests: runArtefact.artefact.executedTests ?? null,
+      notExecutedTests: runArtefact.artefact.notExecutedTests ?? null,
+      verdict: runArtefact.artefact.verdict ?? null,
+      artefactPath: runArtefact.artefactPath,
+    }
+    : {
+      source: 'unknown',
+      integrationTests: null,
+      notExecutedTests: null,
+      verdict: null,
+      artefactPath: null,
+    };
 
   return {
     generatedAt: new Date().toISOString(),
@@ -255,10 +347,7 @@ function buildIntegrationSignalSummary(options) {
       unitTestFiles: unitTestFiles.length,
       integrationTestFiles: integrationTestFiles.length,
     },
-    executed: {
-      unitSuites: resolvedUnitExecuted,
-      integrationSuites: resolvedIntegrationExecuted,
-    },
+    executed,
     gate: {
       verdict: gateVerdict,
       reason: gateReason,

package/src/utils/connectorContract.js

@@ -0,0 +1,96 @@
+'use strict';
+
+/**
+ * Connector contract check — validation step "connectors".
+ *
+ * Replaces a step that printed "PASS (via cookbook tests)" and returned
+ * valid:true without evaluating anything. A step reporting a guarantee it never
+ * checked is worse than no step, because the log then reads as evidence.
+ *
+ * Tier-1 runs in phase 0.2, before the wrapper opens any connector, so nothing
+ * live can be probed here. What can be checked is that the service's two
+ * declarations of the same fact agree, and that the environment backs them:
+ *
+ *   config/service/config.json               wrapper.<connector> sections
+ *   config/service/integration-contract.json requiredConnectors
+ *
+ * biz-converter shipped with requiredConnectors.db=false while owning a schema —
+ * six migrations, DB_HOST set, a database service in CI. Nothing caught it: the
+ * only consequence was that ci:gate:wait never waited for the database, so the
+ * suite raced it. It was found by hand during the F4 switchover. This step
+ * exists so that class of contradiction is found by the machine instead.
+ *
+ * Pure: takes the two declarations and an environment, returns a result. No
+ * filesystem, no network, no process exit.
+ */
+
+/**
+ * How a required connector shows up in config.json's wrapper section, and which
+ * environment variable has to back it.
+ *
+ * `configSections` lists the wrapper keys that imply the connector, empty when
+ * none does. `cache` and `state` are both Redis-backed, so either satisfies
+ * redis. `db` and `minio` have no wrapper section — services reach their schema
+ * and object storage directly — so they are declared by the contract and
+ * evidenced only by the environment.
+ *
+ * The mapping was corrected on 2026-08-22 by running it against all eight
+ * services: an assumed wrapper.storage section for MinIO exists nowhere, and
+ * guessing it would have failed emailer and pdfgen for a configuration neither
+ * was ever meant to have.
+ */
+const CONNECTORS = {
+  db: { configSections: [], env: ['DB_HOST'] },
+  redis: { configSections: ['cache', 'state'], env: ['REDIS_URL'] },
+  mq: { configSections: ['mq'], env: ['RABBITMQ_URL'] },
+  // MinIO, like the database, has no wrapper section: services reach it through
+  // @onlineapps/conn-base-storage directly. Verified 2026-08-22 — no service on
+  // the platform declares wrapper.storage. So it is declared by the contract and
+  // evidenced only by the environment.
+  minio: { configSections: [], env: ['MINIO_ENDPOINT', 'MINIO_ACTUAL_HOST'] }
+};
+
+/**
+ * @param {object} args
+ * @param {object} args.config parsed config/service/config.json
+ * @param {object} args.requiredConnectors from the integration contract
+ * @param {object} args.env environment to check against
+ * @returns {{valid: boolean, checked: string[], errors: string[]}}
+ */
+function verifyConnectorContract({ config, requiredConnectors, env }) {
+  const errors = [];
+  const checked = [];
+  const wrapper = config?.wrapper ?? {};
+
+  for (const [name, spec] of Object.entries(CONNECTORS)) {
+    const required = requiredConnectors?.[name] === true;
+    const configured = spec.configSections.some((section) => wrapper[section] !== undefined);
+
+    if (required) {
+      checked.push(name);
+
+      if (spec.configSections.length > 0 && !configured) {
+        errors.push(`Connector "${name}" is required by the integration contract but no `
+          + `wrapper.${spec.configSections.join('/wrapper.')} section configures it in config/service/config.json.\n`
+          + `       Fix: configure it, or set requiredConnectors.${name} to false if the service does not use it.`);
+      }
+
+      const satisfied = spec.env.some((key) => env?.[key]);
+      if (!satisfied) {
+        errors.push(`Connector "${name}" is required but ${spec.env.join(' / ')} is not set.\n`
+          + '       Fix: set it in the CI job or config/env-active/*.env — a required connector without its '
+          + 'endpoint fails later, inside the connector, where the cause is harder to see.');
+      }
+    } else if (configured) {
+      errors.push(`config/service/config.json configures wrapper.${spec.configSections.find((s) => wrapper[s] !== undefined)} `
+        + `but the integration contract says "${name}" is not required.\n`
+        + '       The two declarations describe the same fact and must agree; while they disagree, '
+        + 'ci:gate:wait does not wait for this connector and the suite races it.\n'
+        + `       Fix: set requiredConnectors.${name} to true, or remove the wrapper section.`);
+    }
+  }
+
+  return { valid: errors.length === 0, checked, errors };
+}
+
+module.exports = { verifyConnectorContract, CONNECTORS };

package/src/utils/cookbookFormat.js

@@ -0,0 +1,95 @@
+'use strict';
+
+/**
+ * Cookbook format rule — the single place in this package that decides which
+ * cookbook format version the platform accepts.
+ *
+ * The rule itself is owned by the biz doc tree, not by this file:
+ * api/docs/biz/40-cookbooks/format.md § "Required fields" — `version` is a
+ * REQUIRED string, `"2.1.0"` or higher. This module only implements that
+ * sentence so both entry points enforce the same thing:
+ *
+ *   - `CookbookTestRunner.validateCookbook()` — the Tier-1 gate every biz
+ *     service runs at boot (mandatory, no per-repo opt-in);
+ *   - `CookbookTestUtils.validateCookbook()` — the readiness-wrapper path
+ *     three repos still call from `tests/bootstrap/service-readiness.test.js`.
+ *
+ * Returned messages carry the `Problem - Expected/Fix` part of the error
+ * format (architecture-principles §5); the `[Context]` prefix belongs to the
+ * caller, which is the one that knows whether it read a file or was handed an
+ * object.
+ *
+ * @see api/docs/biz/40-cookbooks/format.md
+ * @see api/docs/biz/40-cookbooks/test-runner-flow.md
+ */
+
+/** Minimum accepted cookbook format version — format.md § Required fields. */
+const MIN_COOKBOOK_FORMAT_VERSION = '2.1.0';
+
+/** `major[.minor[.patch]]`, digits only — the shape format.md documents. */
+const VERSION_PATTERN = /^\d+(\.\d+){0,2}$/;
+
+const DOC_REFERENCE = 'api/docs/biz/40-cookbooks/format.md § Required fields';
+
+/**
+ * @param {string} version numeric version string, already pattern-checked
+ * @returns {number[]} exactly three components, missing ones are 0
+ */
+function toComponents(version) {
+  const parts = version.split('.').map((part) => parseInt(part, 10));
+  while (parts.length < 3) {
+    parts.push(0);
+  }
+  return parts;
+}
+
+/**
+ * @param {string} a numeric version string
+ * @param {string} b numeric version string
+ * @returns {number} negative when a < b, 0 when equal, positive when a > b
+ */
+function compareVersions(a, b) {
+  const left = toComponents(a);
+  const right = toComponents(b);
+
+  for (let i = 0; i < 3; i++) {
+    if (left[i] !== right[i]) {
+      return left[i] - right[i];
+    }
+  }
+  return 0;
+}
+
+/**
+ * Check a cookbook's `version` field against the documented format rule.
+ *
+ * @param {*} version the raw value of the cookbook's top-level `version`
+ * @returns {string|null} `null` when the version satisfies the rule, otherwise
+ *   the problem in `Problem - Expected/Fix` form
+ */
+function checkCookbookFormatVersion(version) {
+  if (version === undefined || version === null || version === '') {
+    return `cookbook format version is missing - Expected top-level "version": "${MIN_COOKBOOK_FORMAT_VERSION}" or higher. `
+      + `Fix: add "version": "${MIN_COOKBOOK_FORMAT_VERSION}" to the cookbook (${DOC_REFERENCE}).`;
+  }
+
+  if (typeof version !== 'string' || !VERSION_PATTERN.test(version)) {
+    return `cookbook format version ${JSON.stringify(version)} is not a version string - `
+      + `Expected numeric "<major>.<minor>.<patch>", "${MIN_COOKBOOK_FORMAT_VERSION}" or higher. `
+      + `Fix: write the version as "${MIN_COOKBOOK_FORMAT_VERSION}" (${DOC_REFERENCE}).`;
+  }
+
+  if (compareVersions(version, MIN_COOKBOOK_FORMAT_VERSION) < 0) {
+    return `cookbook format version "${version}" is below the required minimum ${MIN_COOKBOOK_FORMAT_VERSION} - `
+      + `Expected "${MIN_COOKBOOK_FORMAT_VERSION}" or higher. `
+      + `Fix: migrate the cookbook to the v2.1 format and set "version": "${MIN_COOKBOOK_FORMAT_VERSION}" (${DOC_REFERENCE}).`;
+  }
+
+  return null;
+}
+
+module.exports = {
+  MIN_COOKBOOK_FORMAT_VERSION,
+  checkCookbookFormatVersion,
+  compareVersions
+};