@onlineapps/conn-orch-validator 3.1.1 → 3.2.0

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@onlineapps/conn-orch-validator",
-  "version": "3.1.1",
+  "version": "3.2.0",
   "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",
@@ -26,7 +29,6 @@
     "ajv": "^8.12.0",
     "ajv-formats": "^2.1.1",
     "amqplib": "^0.10.9",
-    "axios": "^1.4.0",
     "joi": "^17.9.0"
   },
   "devDependencies": {

package/src/CookbookTestRunner.js

@@ -3,47 +3,39 @@
 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');
 const { resolveHeaders } = require('./utils/resolveHeaders');
 
 /**
- * CookbookTestRunner - Executes cookbook tests offline with mocked infrastructure
+ * 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.
+ * Dispatch is exclusively v3 handler-registry: each operation MUST declare
+ * `handler: "path#exportName"` in operations.json. The runner loads the
+ * module via `require()` and calls `handler(input, ctx)` directly in-process
+ * (no HTTP). Operations without a `handler` field are an explicit error.
  *
- * The v3 handler dispatch builds a minimal real ctx:
+ * The 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
+ *     httpClient: null, secrets: 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
+ * that need 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
+ * connector slots 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)
+ * Supports unified cookbook format for both testing (with expect) and production (without expect).
  */
 class CookbookTestRunner {
   constructor(options = {}) {
     if (!options.serviceName) {
       throw new Error('[CookbookTestRunner] serviceName is required');
     }
-    if (!options.serviceUrl) {
-      throw new Error('[CookbookTestRunner] serviceUrl is required');
-    }
     if (!options.logger || typeof options.logger.warn !== 'function') {
       throw new Error('[CookbookTestRunner] Logger is required — Expected object with warn() method');
     }
     this.serviceName = options.serviceName;
-    this.serviceUrl = options.serviceUrl;
     this.servicePath = options.servicePath;
     this.mockInfrastructure = options.mockInfrastructure !== false;
     this.timeout = options.timeout;
@@ -189,9 +181,8 @@ class CookbookTestRunner {
     };
 
     try {
-      // Resolve operation spec from operations.json — returns either
-      // { dispatchMode: 'handler', modulePath, exportName } (v3) or
-      // { dispatchMode: 'http', path, method, headers } (legacy).
+      // Resolve operation spec from operations.json — always returns
+      // { modulePath, exportName } (v3 handler dispatch is the only mode).
       const spec = await this.resolveOperation(step.service, step.operation);
 
       const validationTenantId = process.env.OA_VALIDATION_TENANT_ID;
@@ -200,27 +191,15 @@ class CookbookTestRunner {
         throw new Error('[CookbookTestRunner] Missing required environment variables OA_VALIDATION_TENANT_ID and/or OA_VALIDATION_WORKSPACE_ID');
       }
 
-      if (spec.dispatchMode === 'handler') {
-        await this._dispatchViaHandler({
-          step,
-          spec,
-          testConfig,
-          validationTenantId,
-          validationWorkspaceId,
-          result,
-          startTime
-        });
-      } else {
-        await this._dispatchViaHttp({
-          step,
-          spec,
-          testConfig,
-          validationTenantId,
-          validationWorkspaceId,
-          result,
-          startTime
-        });
-      }
+      await this._dispatchViaHandler({
+        step,
+        spec,
+        testConfig,
+        validationTenantId,
+        validationWorkspaceId,
+        result,
+        startTime
+      });
 
       this.logger.info(`Step ${step.id}: ${result.passed ? 'PASSED' : 'FAILED'} (${result.duration}ms)`);
 
@@ -236,7 +215,7 @@ class CookbookTestRunner {
   }
 
   /**
-   * v3 dispatch: require handler module, build minimal real ctx, call
+   * Handler 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
@@ -348,47 +327,6 @@ class CookbookTestRunner {
     }
   }
 
-  /**
-   * 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
    */
@@ -537,16 +475,9 @@ class CookbookTestRunner {
   }
 
   /**
-   * 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.
+   * Resolve operation spec from operations.json. Returns the handler
+   * dispatch descriptor: { modulePath, exportName, headers }.
+   * Throws if the operation does not declare a v3 `handler`.
    */
   async resolveOperation(serviceName, operationName) {
     const serviceRoot = this._resolveServiceRoot(serviceName);
@@ -565,30 +496,20 @@ class CookbookTestRunner {
       throw new Error(`Operation not found: ${operationName}`);
     }
 
-    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.handler) {
+      throw new Error(`[CookbookTestRunner] Operation ${serviceName}.${operationName} in ${operationsPath} is missing required v3 field "handler" ("path#exportName"). Fix: declare handler in operations.json per RFC §5.3.`);
     }
 
-    if (operation.endpoint && operation.method) {
-      return {
-        dispatchMode: 'http',
-        path: operation.endpoint,
-        method: operation.method,
-        headers: operation.headers || {}
-      };
+    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"`);
     }
-
-    throw new Error(`[CookbookTestRunner] Operation ${serviceName}.${operationName} declares neither "handler" (v3) nor "endpoint"+"method" (legacy) in ${operationsPath}`);
+    const modulePath = require.resolve(path.join(serviceRoot, 'src', modRel));
+    return {
+      modulePath,
+      exportName,
+      headers: operation.headers || {}
+    };
   }
 
   /**

package/src/ServiceReadinessValidator.js

@@ -197,17 +197,26 @@ class ServiceReadinessValidator {
   }
 
   /**
-   * Check health endpoint
+   * Check health endpoint via Node 18+ global fetch (no external HTTP client).
    */
   async checkHealth(healthUrl) {
     try {
-      const axios = require('axios');
-      const response = await axios.get(healthUrl, { timeout: 5000 });
+      const response = await fetch(healthUrl, {
+        method: 'GET',
+        signal: AbortSignal.timeout(5000)
+      });
+
+      let data = null;
+      try {
+        data = await response.json();
+      } catch (_) {
+        // health endpoint may return non-JSON; keep data null and rely on status.
+      }
 
       return {
         passed: response.status === 200,
         status: response.status,
-        data: response.data
+        data
       };
     } catch (error) {
       return {

package/src/ValidationOrchestrator.js

@@ -45,7 +45,6 @@ class ValidationOrchestrator {
     this.cookbookRunner = new CookbookTestRunner({
       servicePath: this.serviceRoot,
       serviceName: this.serviceName,
-      serviceUrl: this.serviceUrl,
       logger: this.logger,
       timeout: 30000
     });
@@ -384,12 +383,10 @@ class ValidationOrchestrator {
   }
 
   /**
-   * Step 4: Run cookbook tests
-   *
-   * v3 note: per-operation HTTP dispatch is retired. If operations.json is v3
-   * (schema_version "3.0" or any operation declares `handler`), cookbook runs
-   * are skipped here with a warning. Handler-registry-based cookbook dispatch
-   * is tracked separately (see RFC §5.3, §5.9).
+   * Step 4: Run cookbook tests via CookbookTestRunner (v3 handler dispatch).
+   * Operations must declare a `handler` in operations.json; the runner
+   * loads the module via `require()` and calls the exported function
+   * in-process. Failures fail this validation step.
    */
   async runCookbookTests() {
     try {
@@ -406,36 +403,6 @@ class ValidationOrchestrator {
         };
       }
 
-      const operationsFile = path.join(this.configPath, 'operations.json');
-      let isV3 = false;
-      try {
-        const ops = JSON.parse(fs.readFileSync(operationsFile, 'utf8'));
-        const opValues = Object.values(ops.operations || {});
-        isV3 = ops.schema_version === '3.0' || opValues.some(o => o && typeof o === 'object' && 'handler' in o);
-      } catch (_) { /* fall through to runner */ }
-
-      if (isV3) {
-        // v3 per-op HTTP dispatch is retired (RFC §5.3). Cookbook HTTP execution
-        // is skipped until CookbookTestRunner gains handler-registry dispatch.
-        // We still report each operation as a structural-validation "test" so
-        // the proof codec's `testsRun > 0` invariant is satisfied — structural
-        // validation of all operations has already passed at Steps 1 and 3.
-        let opCount = 0;
-        try {
-          const ops = JSON.parse(fs.readFileSync(operationsFile, 'utf8'));
-          opCount = Object.keys(ops.operations || {}).length;
-        } catch (_) { opCount = 0; }
-
-        console.warn(`[ValidationOrchestrator] Step 4: cookbook HTTP dispatch is v2-only. Skipping for v3; counting ${opCount} operation structural check(s) as tests.`);
-        return {
-          success: true,
-          total: opCount,
-          passed: opCount,
-          failed: 0,
-          warnings: ['Cookbook HTTP execution skipped — v3 handler-registry dispatch not yet implemented in CookbookTestRunner']
-        };
-      }
-
       const result = await this.cookbookRunner.runCookbooks(cookbooksPath);
 
       console.log(`[ValidationOrchestrator] ✓ Cookbook tests: ${result.passed}/${result.total} passed`);

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,
+};