@onlineapps/conn-orch-validator 3.0.1 → 3.1.2

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@onlineapps/conn-orch-validator",
-  "version": "3.0.1",
+  "version": "3.1.2",
   "description": "Validation orchestrator for OA Drive microservices - coordinates validation across all layers (base, infra, orch, business)",
   "main": "src/index.js",
+  "bin": {
+    "oa-biz-ci-gate": "src/cli/biz-ci-gate.js"
+  },
   "scripts": {
     "test": "jest",
     "test:unit": "jest tests/unit",

package/src/CookbookTestRunner.js

@@ -2,6 +2,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const crypto = require('crypto');
 const axios = require('axios');
 const MockMQClient = require('./mocks/MockMQClient');
 const MockRegistry = require('./mocks/MockRegistry');
@@ -10,6 +11,24 @@ const { resolveHeaders } = require('./utils/resolveHeaders');
 /**
  * CookbookTestRunner - Executes cookbook tests offline with mocked infrastructure
  *
+ * Dispatch strategy (D5, validator 3.1.0):
+ *   - v3 operations.json — operation has a `handler` field ("path#exportName")
+ *     → dispatch via `require()` + direct function call. HTTP is not involved.
+ *   - legacy operations.json — operation has `endpoint` + `method`
+ *     → dispatch via axios HTTP request against serviceUrl. Retained for
+ *       backward-compat with any pre-v3 services that still expose /api/v1/*.
+ *   - operation with neither `handler` nor `endpoint` → explicit error.
+ *
+ * The v3 handler dispatch builds a minimal real ctx:
+ *   { logger, tenant_id, workspace_id, correlation_id, db: null, cache: null,
+ *     httpClient: null, stream: null, abortSignal: null }
+ * — matching the shape ServiceWrapper.ContextBuilder produces in production
+ * (see api/docs/architecture/biz-service-invocation-model.md §5). Handlers
+ * that require DB access import sequelize directly from their own
+ * src/config/database.js module (see standards/biz-service-onboarding.md §9a);
+ * connector fields stay null and the handler surfaces its own failure if
+ * something it genuinely needs is missing.
+ *
  * Supports unified cookbook format for both testing (with expect) and production (without expect)
  */
 class CookbookTestRunner {
@@ -32,6 +51,10 @@ class CookbookTestRunner {
       throw new Error('[CookbookTestRunner] timeout is required — Expected positive number (ms)');
     }
     this.logger = options.logger;
+    this._servicePathByName = new Map();
+    if (this.servicePath) {
+      this._servicePathByName.set(this.serviceName, this.servicePath);
+    }
 
     // Initialize mocked infrastructure
     if (this.mockInfrastructure) {
@@ -166,50 +189,37 @@ class CookbookTestRunner {
     };
 
     try {
-      // Resolve operation endpoint from operations.json
-      const endpoint = await this.resolveOperation(step.service, step.operation);
+      // Resolve operation spec from operations.json — returns either
+      // { dispatchMode: 'handler', modulePath, exportName } (v3) or
+      // { dispatchMode: 'http', path, method, headers } (legacy).
+      const spec = await this.resolveOperation(step.service, step.operation);
 
       const validationTenantId = process.env.OA_VALIDATION_TENANT_ID;
       const validationWorkspaceId = process.env.OA_VALIDATION_WORKSPACE_ID;
       if (!validationTenantId || !validationWorkspaceId) {
         throw new Error('[CookbookTestRunner] Missing required environment variables OA_VALIDATION_TENANT_ID and/or OA_VALIDATION_WORKSPACE_ID');
       }
-      const request = {
-        method: endpoint.method,
-        url: `${this.serviceUrl}${endpoint.path}`,
-        data: step.input,
-        timeout: testConfig.timeout || this.timeout,
-        headers: {
-          'x-validation-request': 'true',
-          'x-tenant-id': validationTenantId,
-          'x-workspace-id': validationWorkspaceId,
-          ...resolveHeaders(endpoint.headers),
-          ...resolveHeaders(step.headers)
-        }
-      };
-
-      result.request = request;
-
-      // Execute request
-      const response = await axios(request);
-
-      result.response = {
-        status: response.status,
-        statusText: response.statusText,
-        data: response.data
-      };
 
-      result.actual = response.data;
-      result.duration = Date.now() - startTime;
-
-      // Validate expectations
-      if (step.expect) {
-        const validation = this.validateExpectations(step.expect, result);
-        result.passed = validation.passed;
-        result.validationErrors = validation.errors;
+      if (spec.dispatchMode === 'handler') {
+        await this._dispatchViaHandler({
+          step,
+          spec,
+          testConfig,
+          validationTenantId,
+          validationWorkspaceId,
+          result,
+          startTime
+        });
       } else {
-        // No expectations = just check if request succeeded
-        result.passed = response.status >= 200 && response.status < 300;
+        await this._dispatchViaHttp({
+          step,
+          spec,
+          testConfig,
+          validationTenantId,
+          validationWorkspaceId,
+          result,
+          startTime
+        });
       }
 
       this.logger.info(`Step ${step.id}: ${result.passed ? 'PASSED' : 'FAILED'} (${result.duration}ms)`);
@@ -225,6 +235,160 @@ class CookbookTestRunner {
     return result;
   }
 
+  /**
+   * v3 dispatch: require handler module, build minimal real ctx, call
+   * handler(input, ctx). Mirrors the production ContextBuilder shape
+   * (see api/docs/architecture/biz-service-invocation-model.md §5) with
+   * all connector slots set to null — handlers that need DB access use
+   * direct sequelize import per standards/biz-service-onboarding.md §9a.
+   */
+  async _dispatchViaHandler({ step, spec, testConfig, validationTenantId, validationWorkspaceId, result, startTime }) {
+    const stepTimeout = testConfig.timeout || this.timeout;
+    const correlationId = step.correlation_id || crypto.randomUUID();
+
+    const ctx = {
+      logger: this.logger,
+      tenant_id: validationTenantId,
+      workspace_id: validationWorkspaceId,
+      correlation_id: correlationId,
+      operation_name: step.operation,
+      service_name: step.service,
+      db: null,
+      cache: null,
+      httpClient: null,
+      secrets: null,
+      stream: null,
+      abortSignal: null,
+      headers: {
+        'x-validation-request': 'true',
+        'x-tenant-id': validationTenantId,
+        'x-workspace-id': validationWorkspaceId,
+        ...resolveHeaders(step.headers)
+      }
+    };
+
+    const request = {
+      mode: 'handler',
+      service: step.service,
+      operation: step.operation,
+      module: spec.modulePath,
+      export: spec.exportName,
+      input: step.input,
+      ctx: {
+        tenant_id: ctx.tenant_id,
+        workspace_id: ctx.workspace_id,
+        correlation_id: ctx.correlation_id
+      }
+    };
+    result.request = request;
+
+    let handlerFn;
+    try {
+      const mod = require(spec.modulePath);
+      handlerFn = mod[spec.exportName];
+      if (typeof handlerFn !== 'function') {
+        throw new Error(`[CookbookTestRunner] Handler ${spec.exportName} not exported from ${spec.modulePath}`);
+      }
+    } catch (error) {
+      throw new Error(`[CookbookTestRunner] Failed to load handler ${spec.exportName} from ${spec.modulePath}: ${error.message}`);
+    }
+
+    let timeoutId;
+    const timeoutPromise = new Promise((_, reject) => {
+      timeoutId = setTimeout(() => {
+        reject(new Error(`[CookbookTestRunner] Handler ${step.operation} exceeded timeout ${stepTimeout}ms`));
+      }, stepTimeout);
+      if (timeoutId.unref) timeoutId.unref();
+    });
+
+    let handlerError = null;
+    let handlerOutput = null;
+    try {
+      handlerOutput = await Promise.race([
+        Promise.resolve().then(() => handlerFn(step.input || {}, ctx)),
+        timeoutPromise
+      ]);
+    } catch (error) {
+      handlerError = error;
+    } finally {
+      clearTimeout(timeoutId);
+    }
+
+    result.duration = Date.now() - startTime;
+
+    if (handlerError) {
+      // Synthesize an HTTP-like response so existing expect validators
+      // continue to work (expect.status: 'error', expect.error.code, ...).
+      const errorCode = handlerError.code || handlerError.name || 'HANDLER_ERROR';
+      const statusCode = typeof handlerError.statusCode === 'number'
+        ? handlerError.statusCode
+        : 500;
+      result.response = {
+        status: statusCode,
+        statusText: errorCode,
+        data: { code: errorCode, message: handlerError.message }
+      };
+      result.actual = result.response.data;
+      result.error = { code: errorCode, message: handlerError.message };
+    } else {
+      result.response = {
+        status: 200,
+        statusText: 'OK',
+        data: handlerOutput
+      };
+      result.actual = handlerOutput;
+    }
+
+    if (step.expect) {
+      const validation = this.validateExpectations(step.expect, result);
+      result.passed = validation.passed;
+      result.validationErrors = validation.errors;
+    } else {
+      result.passed = !handlerError;
+    }
+  }
+
+  /**
+   * Legacy dispatch: HTTP request against serviceUrl + endpoint. Retained
+   * verbatim (modulo wrapping) for compatibility with pre-v3 services that
+   * still expose /api/v1/* business routes.
+   */
+  async _dispatchViaHttp({ step, spec, testConfig, validationTenantId, validationWorkspaceId, result, startTime }) {
+    const request = {
+      method: spec.method,
+      url: `${this.serviceUrl}${spec.path}`,
+      data: step.input,
+      timeout: testConfig.timeout || this.timeout,
+      headers: {
+        'x-validation-request': 'true',
+        'x-tenant-id': validationTenantId,
+        'x-workspace-id': validationWorkspaceId,
+        ...resolveHeaders(spec.headers),
+        ...resolveHeaders(step.headers)
+      }
+    };
+    result.request = request;
+
+    const response = await axios(request);
+
+    result.response = {
+      status: response.status,
+      statusText: response.statusText,
+      data: response.data
+    };
+
+    result.actual = response.data;
+    result.duration = Date.now() - startTime;
+
+    if (step.expect) {
+      const validation = this.validateExpectations(step.expect, result);
+      result.passed = validation.passed;
+      result.validationErrors = validation.errors;
+    } else {
+      result.passed = response.status >= 200 && response.status < 300;
+    }
+  }
+
   /**
    * Validate expectations against actual results
    */
@@ -373,33 +537,85 @@ class CookbookTestRunner {
   }
 
   /**
-   * Resolve operation to HTTP endpoint
+   * Resolve operation spec from operations.json. Returns a dispatch
+   * descriptor depending on which shape the operation declares:
+   *
+   *   v3 (handler-based, post-2026-04):
+   *     { dispatchMode: 'handler', modulePath, exportName }
+   *
+   *   legacy (HTTP endpoint, pre-v3):
+   *     { dispatchMode: 'http', path, method, headers }
+   *
+   * Throws if the operation declares neither.
    */
   async resolveOperation(serviceName, operationName) {
-    // Load operations.json — prefer config/service/, fall back to conn-config/
-    let operationsPath = null;
-    if (this.servicePath) {
-      const newPath = path.join(this.servicePath, 'config', 'service', 'operations.json');
-      const legacyPath = path.join(this.servicePath, 'conn-config', 'operations.json');
-      operationsPath = fs.existsSync(newPath) ? newPath : (fs.existsSync(legacyPath) ? legacyPath : null);
-    }
+    const serviceRoot = this._resolveServiceRoot(serviceName);
+    const newPath = path.join(serviceRoot, 'config', 'service', 'operations.json');
+    const legacyPath = path.join(serviceRoot, 'conn-config', 'operations.json');
+    const operationsPath = fs.existsSync(newPath) ? newPath : (fs.existsSync(legacyPath) ? legacyPath : null);
 
     if (!operationsPath) {
       throw new Error(`Operations file not found for service: ${serviceName} (checked config/service/ and conn-config/)`);
     }
 
     const operations = JSON.parse(fs.readFileSync(operationsPath, 'utf8'));
-    const operation = operations.operations[operationName];
+    const operation = operations.operations && operations.operations[operationName];
 
     if (!operation) {
       throw new Error(`Operation not found: ${operationName}`);
     }
 
-    return {
-      path: operation.endpoint,
-      method: operation.method,
-      headers: operation.headers || {}
-    };
+    if (operation.handler) {
+      const [modRel, exportName] = String(operation.handler).split('#');
+      if (!modRel || !exportName) {
+        throw new Error(`[CookbookTestRunner] Invalid handler spec "${operation.handler}" for ${serviceName}.${operationName}; expected "path#exportName"`);
+      }
+      const modulePath = require.resolve(path.join(serviceRoot, 'src', modRel));
+      return {
+        dispatchMode: 'handler',
+        modulePath,
+        exportName,
+        headers: operation.headers || {}
+      };
+    }
+
+    if (operation.endpoint && operation.method) {
+      return {
+        dispatchMode: 'http',
+        path: operation.endpoint,
+        method: operation.method,
+        headers: operation.headers || {}
+      };
+    }
+
+    throw new Error(`[CookbookTestRunner] Operation ${serviceName}.${operationName} declares neither "handler" (v3) nor "endpoint"+"method" (legacy) in ${operationsPath}`);
+  }
+
+  /**
+   * Resolve filesystem root for a service. The default resolver assumes
+   * every cookbook step targets the runner's own service (this.servicePath).
+   * Callers that need cross-service dispatch can subclass and override.
+   */
+  _resolveServiceRoot(serviceName) {
+    if (this._servicePathByName.has(serviceName)) {
+      return this._servicePathByName.get(serviceName);
+    }
+    if (!this.servicePath) {
+      throw new Error(`[CookbookTestRunner] No servicePath known for ${serviceName}; construct with servicePath or register via setServicePath(name, path)`);
+    }
+    // Cookbooks may reference this.serviceName under a different alias.
+    return this.servicePath;
+  }
+
+  /**
+   * Register a servicePath for a service name. Only needed when cookbooks
+   * dispatch to a service other than the runner's primary service.
+   */
+  setServicePath(serviceName, servicePath) {
+    if (!serviceName || !servicePath) {
+      throw new Error('[CookbookTestRunner] setServicePath requires both serviceName and servicePath');
+    }
+    this._servicePathByName.set(serviceName, servicePath);
   }
 
   /**

package/src/cli/biz-ci-gate.js

@@ -0,0 +1,221 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const {
+  DEFAULT_CONTRACT_RELATIVE_PATH,
+  loadAndValidateIntegrationContract,
+  verifyIntegrationMinimum,
+  buildCiEnvironment,
+  formatEnvironmentOutput,
+  buildIntegrationSignalSummary,
+  waitRequiredConnectors,
+  runConnectorSetup,
+  writeJsonFile,
+} = require('../utils/bizCiGateContract');
+
+function parseArgs(argv) {
+  const parsed = {
+    command: null,
+    options: {},
+  };
+
+  const args = [...argv];
+  parsed.command = args.shift() || null;
+
+  while (args.length > 0) {
+    const token = args.shift();
+    if (!token.startsWith('--')) {
+      continue;
+    }
+    const key = token.slice(2);
+    const next = args[0];
+    if (next && !next.startsWith('--')) {
+      parsed.options[key] = args.shift();
+    } else {
+      parsed.options[key] = 'true';
+    }
+  }
+
+  return parsed;
+}
+
+function printHelp() {
+  process.stdout.write(`
+Usage:
+  oa-biz-ci-gate <command> [--service-root <path>] [--contract <path>] [options]
+
+Commands:
+  verify-contract             Validate integration-contract.json schema and connector flags.
+  verify-integration-minimum Validate package scripts + fail on empty integration suite.
+  emit-ci-env                Emit connector-aware CI environment exports.
+  wait-connectors            Wait for required connector TCP endpoints.
+  run-setup                  Run optional connector setup commands from contract.
+  write-summary              Write normalized integration signal artifact JSON.
+
+Common options:
+  --service-root <path>      Service repository root. Default: current working directory.
+  --contract <path>          Contract path (absolute or relative to service root).
+                             Default: ${DEFAULT_CONTRACT_RELATIVE_PATH}
+
+emit-ci-env options:
+  --format <shell|dotenv|json>    Output format. Default: shell
+  --output <path>                 Optional output file path
+
+wait-connectors options:
+  --attempts <number>             Maximum connection attempts per connector (default: 60)
+  --interval-ms <number>          Delay between attempts in milliseconds (default: 1000)
+
+write-summary options:
+  --output <path>                 Summary artifact path. Default: <service-root>/ci/integration-signal.json
+  --gate-verdict <pass|fail>      Override gate verdict
+  --gate-reason <text>            Override gate reason
+  --unit-executed <number>        Executed unit suite count
+  --integration-executed <number> Executed integration suite count
+`);
+}
+
+function boolFromString(value) {
+  return value === true || value === 'true' || value === '1';
+}
+
+function resolveContractOptions(options) {
+  return {
+    serviceRoot: options['service-root'] || process.cwd(),
+    contractPath: options.contract || undefined,
+  };
+}
+
+function runVerifyContract(options) {
+  const contractInfo = loadAndValidateIntegrationContract(options.serviceRoot, options.contractPath);
+  process.stdout.write(`[BizCiGate] OK verify-contract\n`);
+  process.stdout.write(`${JSON.stringify({
+    serviceRoot: contractInfo.serviceRoot,
+    contractPath: contractInfo.contractPath,
+    serviceName: contractInfo.contract.serviceName,
+    requiredConnectors: contractInfo.contract.requiredConnectors,
+    integrationMinimum: contractInfo.contract.integrationMinimum,
+  }, null, 2)}\n`);
+}
+
+function runVerifyIntegrationMinimum(options) {
+  const result = verifyIntegrationMinimum(options.serviceRoot, options.contractPath);
+  process.stdout.write(`[BizCiGate] OK verify-integration-minimum\n`);
+  process.stdout.write(`${JSON.stringify({
+    serviceRoot: result.serviceRoot,
+    contractPath: result.contractPath,
+    discoveredIntegrationTests: result.discoveredCount,
+    requiredIntegrationTests: result.requiredCount,
+    packageJsonPath: result.packageScripts.packageJsonPath,
+  }, null, 2)}\n`);
+}
+
+function runEmitCiEnv(options) {
+  const contractInfo = loadAndValidateIntegrationContract(options.serviceRoot, options.contractPath);
+  const env = buildCiEnvironment(contractInfo);
+  const format = options.format || 'shell';
+  const output = formatEnvironmentOutput(env, format);
+  const outputPath = options.output;
+
+  if (outputPath) {
+    const resolvedOutputPath = path.resolve(options.serviceRoot, outputPath);
+    fs.mkdirSync(path.dirname(resolvedOutputPath), { recursive: true });
+    if (format === 'json') {
+      fs.writeFileSync(resolvedOutputPath, JSON.stringify(env, null, 2));
+    } else {
+      fs.writeFileSync(resolvedOutputPath, output);
+    }
+    process.stdout.write(`[BizCiGate] Wrote CI env output to ${resolvedOutputPath}\n`);
+    return;
+  }
+
+  process.stdout.write(output);
+}
+
+async function runWaitConnectors(options) {
+  const result = await waitRequiredConnectors(options.serviceRoot, options.contractPath, {
+    attempts: options.attempts,
+    intervalMs: options['interval-ms'],
+  });
+  process.stdout.write(`[BizCiGate] OK wait-connectors\n`);
+  process.stdout.write(`${JSON.stringify({
+    serviceRoot: result.serviceRoot,
+    connectorsChecked: result.checks,
+    waitPolicy: result.waitPolicy,
+  }, null, 2)}\n`);
+}
+
+function runSetup(options) {
+  const result = runConnectorSetup(options.serviceRoot, options.contractPath);
+  process.stdout.write(`[BizCiGate] OK run-setup\n`);
+  process.stdout.write(`${JSON.stringify({
+    serviceRoot: result.serviceRoot,
+    executed: result.executed,
+  }, null, 2)}\n`);
+}
+
+function runWriteSummary(options) {
+  const summary = buildIntegrationSignalSummary({
+    serviceRoot: options.serviceRoot,
+    contractPath: options.contractPath,
+    gateVerdict: options['gate-verdict'],
+    gateReason: options['gate-reason'],
+    unitExecuted: options['unit-executed'],
+    integrationExecuted: options['integration-executed'],
+  });
+
+  const outputPath = options.output
+    ? path.resolve(options.serviceRoot, options.output)
+    : path.join(path.resolve(options.serviceRoot), 'ci', 'integration-signal.json');
+
+  const writtenPath = writeJsonFile(outputPath, summary);
+  process.stdout.write(`[BizCiGate] Wrote integration summary to ${writtenPath}\n`);
+  process.stdout.write(`${JSON.stringify(summary, null, 2)}\n`);
+}
+
+async function main() {
+  const parsed = parseArgs(process.argv.slice(2));
+  if (!parsed.command || boolFromString(parsed.options.help)) {
+    printHelp();
+    process.exit(parsed.command ? 0 : 1);
+  }
+
+  const command = parsed.command;
+  const baseOptions = resolveContractOptions(parsed.options);
+  const options = { ...baseOptions, ...parsed.options };
+
+  try {
+    if (command === 'verify-contract') {
+      runVerifyContract(options);
+      return;
+    }
+    if (command === 'verify-integration-minimum') {
+      runVerifyIntegrationMinimum(options);
+      return;
+    }
+    if (command === 'emit-ci-env') {
+      runEmitCiEnv(options);
+      return;
+    }
+    if (command === 'wait-connectors') {
+      await runWaitConnectors(options);
+      return;
+    }
+    if (command === 'run-setup') {
+      runSetup(options);
+      return;
+    }
+    if (command === 'write-summary') {
+      runWriteSummary(options);
+      return;
+    }
+
+    throw new Error(`[BizCiGate] Unknown command - ${command}`);
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`);
+    process.exit(1);
+  }
+}
+
+main();

package/src/index.js

@@ -27,6 +27,7 @@ try {
   console.error('[conn-orch-validator] WARNING: Failed to load CookbookTestRunner:', error.message);
 }
 const WorkflowTestRunner = require('./WorkflowTestRunner');
+const BizCiGateContract = require('./utils/bizCiGateContract');
 
 const ServiceReadinessValidator = require('./ServiceReadinessValidator');
 const ValidationOrchestrator = require('./ValidationOrchestrator');
@@ -49,6 +50,7 @@ module.exports = {
 
   get createServiceReadinessTests() { return createServiceReadinessTests; },
   get createPreValidationTests() { return createPreValidationTests; },
+  get BizCiGateContract() { return BizCiGateContract; },
 
   createMockMQ: () => new MockMQClient(),
   createMockRegistry: () => new MockRegistry(),

package/src/utils/bizCiGateContract.js

@@ -0,0 +1,430 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const net = require('net');
+const { execSync } = require('child_process');
+
+const CONNECTOR_KEYS = ['db', 'redis', 'mq', 'minio'];
+const DEFAULT_CONTRACT_RELATIVE_PATH = path.join('config', 'service', 'integration-contract.json');
+
+function readJsonFile(filePath) {
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`[BizCiGate] Missing file - ${filePath}`);
+  }
+
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (error) {
+    throw new Error(`[BizCiGate] Invalid JSON - ${filePath}: ${error.message}`);
+  }
+}
+
+function resolveServiceRoot(serviceRoot) {
+  return path.resolve(serviceRoot || process.cwd());
+}
+
+function resolveContractPath(serviceRoot, contractPath) {
+  if (!contractPath) {
+    return path.join(serviceRoot, DEFAULT_CONTRACT_RELATIVE_PATH);
+  }
+  return path.isAbsolute(contractPath) ? contractPath : path.join(serviceRoot, contractPath);
+}
+
+function assertBoolean(value, fieldName) {
+  if (typeof value !== 'boolean') {
+    throw new Error(`[BizCiGate] Invalid contract field - ${fieldName} must be boolean`);
+  }
+}
+
+function normalizeIntegrationContract(rawContract, contractPath) {
+  if (!rawContract || typeof rawContract !== 'object' || Array.isArray(rawContract)) {
+    throw new Error(`[BizCiGate] Invalid contract root - Expected object in ${contractPath}`);
+  }
+
+  const requiredConnectors = rawContract.requiredConnectors;
+  if (!requiredConnectors || typeof requiredConnectors !== 'object' || Array.isArray(requiredConnectors)) {
+    throw new Error('[BizCiGate] Missing requiredConnectors - Expected object with db/redis/mq/minio booleans');
+  }
+
+  const normalizedConnectors = {};
+  for (const key of CONNECTOR_KEYS) {
+    const value = requiredConnectors[key];
+    assertBoolean(value, `requiredConnectors.${key}`);
+    normalizedConnectors[key] = value;
+  }
+
+  const integrationMinimum = rawContract.integrationMinimum;
+  if (!integrationMinimum || typeof integrationMinimum !== 'object' || Array.isArray(integrationMinimum)) {
+    throw new Error('[BizCiGate] Missing integrationMinimum - Expected object with minTestFiles');
+  }
+
+  const minTestFiles = integrationMinimum.minTestFiles;
+  if (!Number.isInteger(minTestFiles) || minTestFiles < 1) {
+    throw new Error('[BizCiGate] Invalid integrationMinimum.minTestFiles - Expected integer >= 1');
+  }
+
+  return {
+    serviceName: rawContract.serviceName || null,
+    requiredConnectors: normalizedConnectors,
+    integrationMinimum: {
+      minTestFiles,
+    },
+    setup: rawContract.setup || {},
+    raw: rawContract,
+  };
+}
+
+function loadAndValidateIntegrationContract(serviceRoot, contractPath) {
+  const resolvedServiceRoot = resolveServiceRoot(serviceRoot);
+  const resolvedContractPath = resolveContractPath(resolvedServiceRoot, contractPath);
+  const rawContract = readJsonFile(resolvedContractPath);
+  const normalizedContract = normalizeIntegrationContract(rawContract, resolvedContractPath);
+
+  return {
+    serviceRoot: resolvedServiceRoot,
+    contractPath: resolvedContractPath,
+    contract: normalizedContract,
+  };
+}
+
+function listFilesRecursive(rootDir) {
+  if (!fs.existsSync(rootDir)) {
+    return [];
+  }
+
+  const stack = [rootDir];
+  const files = [];
+
+  while (stack.length > 0) {
+    const current = stack.pop();
+    const entries = fs.readdirSync(current, { withFileTypes: true });
+    for (const entry of entries) {
+      const entryPath = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(entryPath);
+      } else if (entry.isFile()) {
+        files.push(entryPath);
+      }
+    }
+  }
+
+  return files;
+}
+
+function isTestFile(filePath) {
+  return /\.(test|spec)\.(js|cjs|mjs|ts|tsx)$/.test(filePath);
+}
+
+function getIntegrationTestFiles(serviceRoot) {
+  const candidateDirs = [
+    path.join(serviceRoot, 'tests', 'integration'),
+    path.join(serviceRoot, 'tests', 'db', 'integration'),
+  ];
+
+  const allFiles = [];
+  for (const dir of candidateDirs) {
+    allFiles.push(...listFilesRecursive(dir).filter(isTestFile));
+  }
+
+  return Array.from(new Set(allFiles));
+}
+
+function getUnitTestFiles(serviceRoot) {
+  const unitDir = path.join(serviceRoot, 'tests', 'unit');
+  return listFilesRecursive(unitDir).filter(isTestFile);
+}
+
+function validatePackageScriptsForIntegrationMinimum(serviceRoot) {
+  const packageJsonPath = path.join(serviceRoot, 'package.json');
+  const packageJson = readJsonFile(packageJsonPath);
+  const scripts = packageJson.scripts || {};
+
+  const testIntegration = scripts['test:integration'] || '';
+  if (!testIntegration) {
+    throw new Error('[BizCiGate] Missing package script - test:integration is required');
+  }
+
+  if (testIntegration.includes('--passWithNoTests')) {
+    throw new Error('[BizCiGate] Forbidden --passWithNoTests in test:integration');
+  }
+
+  const testAll = scripts['test:all'] || '';
+  if (!testAll) {
+    throw new Error('[BizCiGate] Missing package script - test:all is required');
+  }
+
+  if (!/test:integration/.test(testAll)) {
+    throw new Error('[BizCiGate] Invalid test:all - must include test:integration');
+  }
+
+  return {
+    packageJsonPath,
+    testIntegration,
+    testAll,
+  };
+}
+
+function verifyIntegrationMinimum(serviceRoot, contractPath) {
+  const contractInfo = loadAndValidateIntegrationContract(serviceRoot, contractPath);
+  const packageScripts = validatePackageScriptsForIntegrationMinimum(contractInfo.serviceRoot);
+  const integrationTestFiles = getIntegrationTestFiles(contractInfo.serviceRoot);
+  const discoveredCount = integrationTestFiles.length;
+  const requiredCount = contractInfo.contract.integrationMinimum.minTestFiles;
+
+  if (discoveredCount < requiredCount) {
+    throw new Error(`[BizCiGate] Integration minimum not met - Found ${discoveredCount}, required ${requiredCount}`);
+  }
+
+  return {
+    ...contractInfo,
+    packageScripts,
+    integrationTestFiles,
+    discoveredCount,
+    requiredCount,
+  };
+}
+
+function buildCiEnvironment(contractInfo) {
+  const { requiredConnectors } = contractInfo.contract;
+  return {
+    OA_CI_CONNECTOR_DB_REQUIRED: requiredConnectors.db ? '1' : '0',
+    OA_CI_CONNECTOR_REDIS_REQUIRED: requiredConnectors.redis ? '1' : '0',
+    OA_CI_CONNECTOR_MQ_REQUIRED: requiredConnectors.mq ? '1' : '0',
+    OA_CI_CONNECTOR_MINIO_REQUIRED: requiredConnectors.minio ? '1' : '0',
+    OA_CI_INTEGRATION_MIN_TEST_FILES: String(contractInfo.contract.integrationMinimum.minTestFiles),
+    OA_CI_CONNECTORS_JSON: JSON.stringify(requiredConnectors),
+  };
+}
+
+function formatEnvironmentOutput(env, format) {
+  const keys = Object.keys(env).sort();
+  if (format === 'json') {
+    return `${JSON.stringify(env, null, 2)}\n`;
+  }
+
+  if (format === 'dotenv') {
+    return `${keys.map((key) => `${key}=${env[key]}`).join('\n')}\n`;
+  }
+
+  if (format === 'shell') {
+    return `${keys.map((key) => `export ${key}=${JSON.stringify(env[key])}`).join('\n')}\n`;
+  }
+
+  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);
+  const integrationTestFiles = getIntegrationTestFiles(contractInfo.serviceRoot);
+
+  let gateVerdict = options.gateVerdict || 'pass';
+  let gateReason = options.gateReason || 'integration minimum satisfied';
+  try {
+    verifyIntegrationMinimum(contractInfo.serviceRoot, contractInfo.contractPath);
+  } catch (error) {
+    gateVerdict = options.gateVerdict || 'fail';
+    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;
+
+  return {
+    generatedAt: new Date().toISOString(),
+    serviceName: contractInfo.contract.serviceName,
+    serviceRoot: contractInfo.serviceRoot,
+    contractPath: contractInfo.contractPath,
+    connectors: contractInfo.contract.requiredConnectors,
+    integrationMinimum: contractInfo.contract.integrationMinimum,
+    discovered: {
+      unitTestFiles: unitTestFiles.length,
+      integrationTestFiles: integrationTestFiles.length,
+    },
+    executed: {
+      unitSuites: resolvedUnitExecuted,
+      integrationSuites: resolvedIntegrationExecuted,
+    },
+    gate: {
+      verdict: gateVerdict,
+      reason: gateReason,
+    },
+  };
+}
+
+function writeJsonFile(filePath, data) {
+  const resolvedFilePath = path.resolve(filePath);
+  const targetDir = path.dirname(resolvedFilePath);
+  fs.mkdirSync(targetDir, { recursive: true });
+  fs.writeFileSync(resolvedFilePath, JSON.stringify(data, null, 2));
+  return resolvedFilePath;
+}
+
+function waitForTcpService({ name, host, port, attempts, intervalMs }) {
+  return new Promise((resolve, reject) => {
+    let currentAttempt = 0;
+
+    function tryConnect() {
+      currentAttempt += 1;
+      const socket = net.createConnection({ host, port });
+      socket.setTimeout(intervalMs);
+
+      socket.on('connect', () => {
+        socket.destroy();
+        resolve({ name, host, port, attemptsUsed: currentAttempt });
+      });
+
+      socket.on('timeout', () => {
+        socket.destroy();
+      });
+
+      socket.on('error', () => {
+        socket.destroy();
+      });
+
+      socket.on('close', () => {
+        if (currentAttempt >= attempts) {
+          reject(new Error(`[BizCiGate] Connector not reachable - ${name} (${host}:${port}) after ${attempts} attempts`));
+          return;
+        }
+        setTimeout(tryConnect, intervalMs);
+      });
+    }
+
+    tryConnect();
+  });
+}
+
+function parseHostPortFromUrl(rawUrl, defaultPort, connectorName) {
+  try {
+    const parsed = new URL(rawUrl);
+    return {
+      host: parsed.hostname,
+      port: Number.parseInt(parsed.port || String(defaultPort), 10),
+    };
+  } catch (error) {
+    throw new Error(`[BizCiGate] Invalid URL for ${connectorName} - ${rawUrl}`);
+  }
+}
+
+async function waitRequiredConnectors(serviceRoot, contractPath, options = {}) {
+  const contractInfo = loadAndValidateIntegrationContract(serviceRoot, contractPath);
+  const { requiredConnectors } = contractInfo.contract;
+
+  const attempts = Number.parseInt(String(options.attempts || process.env.OA_CI_WAIT_ATTEMPTS || 60), 10);
+  const intervalMs = Number.parseInt(String(options.intervalMs || process.env.OA_CI_WAIT_INTERVAL_MS || 1000), 10);
+
+  const checks = [];
+
+  if (requiredConnectors.db) {
+    const host = process.env.DB_HOST;
+    const port = Number.parseInt(String(process.env.DB_PORT || '3306'), 10);
+    if (!host) {
+      throw new Error('[BizCiGate] Missing env for required connector db - DB_HOST');
+    }
+    checks.push(waitForTcpService({ name: 'db', host, port, attempts, intervalMs }));
+  }
+
+  if (requiredConnectors.redis) {
+    const redisUrl = process.env.REDIS_URL;
+    if (!redisUrl) {
+      throw new Error('[BizCiGate] Missing env for required connector redis - REDIS_URL');
+    }
+    const { host, port } = parseHostPortFromUrl(redisUrl, 6379, 'redis');
+    checks.push(waitForTcpService({ name: 'redis', host, port, attempts, intervalMs }));
+  }
+
+  if (requiredConnectors.mq) {
+    const mqUrl = process.env.RABBITMQ_URL;
+    if (!mqUrl) {
+      throw new Error('[BizCiGate] Missing env for required connector mq - RABBITMQ_URL');
+    }
+    const { host, port } = parseHostPortFromUrl(mqUrl, 5672, 'mq');
+    checks.push(waitForTcpService({ name: 'mq', host, port, attempts, intervalMs }));
+  }
+
+  if (requiredConnectors.minio) {
+    const host = process.env.MINIO_ACTUAL_HOST || process.env.MINIO_ENDPOINT || process.env.MINIO_HOST;
+    const port = Number.parseInt(String(process.env.MINIO_PORT || '9000'), 10);
+    if (!host) {
+      throw new Error('[BizCiGate] Missing env for required connector minio - MINIO_ENDPOINT or MINIO_ACTUAL_HOST');
+    }
+    checks.push(waitForTcpService({ name: 'minio', host, port, attempts, intervalMs }));
+  }
+
+  const results = await Promise.all(checks);
+  return {
+    ...contractInfo,
+    waitPolicy: { attempts, intervalMs },
+    checks: results,
+  };
+}
+
+function runConnectorSetup(serviceRoot, contractPath) {
+  const contractInfo = loadAndValidateIntegrationContract(serviceRoot, contractPath);
+  const { requiredConnectors } = contractInfo.contract;
+  const setup = contractInfo.contract.setup || {};
+  const executed = [];
+
+  const setupMap = [
+    { key: 'db', commandField: 'dbSetupCommand' },
+    { key: 'redis', commandField: 'redisSetupCommand' },
+    { key: 'mq', commandField: 'mqSetupCommand' },
+    { key: 'minio', commandField: 'minioSetupCommand' },
+  ];
+
+  for (const entry of setupMap) {
+    if (!requiredConnectors[entry.key]) {
+      continue;
+    }
+    const command = setup[entry.commandField];
+    if (!command) {
+      continue;
+    }
+    execSync(command, {
+      cwd: contractInfo.serviceRoot,
+      stdio: 'inherit',
+      env: process.env,
+    });
+    executed.push({
+      connector: entry.key,
+      commandField: entry.commandField,
+      command,
+    });
+  }
+
+  return {
+    ...contractInfo,
+    executed,
+  };
+}
+
+module.exports = {
+  CONNECTOR_KEYS,
+  DEFAULT_CONTRACT_RELATIVE_PATH,
+  loadAndValidateIntegrationContract,
+  normalizeIntegrationContract,
+  getIntegrationTestFiles,
+  getUnitTestFiles,
+  verifyIntegrationMinimum,
+  buildCiEnvironment,
+  formatEnvironmentOutput,
+  buildIntegrationSignalSummary,
+  waitRequiredConnectors,
+  runConnectorSetup,
+  writeJsonFile,
+};