@onlineapps/conn-orch-validator 3.3.2 → 4.0.0

package/src/ValidationOrchestrator.js

@@ -2,35 +2,45 @@
 
 const fs = require('fs');
 const path = require('path');
+const { verifyConnectorContract } = require('./utils/connectorContract');
+const { normalizeEnvDeclaration, collectEnvCoverage, verifyEnvPresence } = require('./utils/envContract');
 const { ValidationProofCodec, ValidationProofVerifier } = require('@onlineapps/service-validator-core');
 const FingerprintUtils = require('@onlineapps/service-validator-core').FingerprintUtils;
 const { ServiceStructureValidator } = require('./validators/ServiceStructureValidator');
-const ServiceReadinessValidator = require('./ServiceReadinessValidator');
+const { describeStepFailureWithContext } = require('./utils/stepFailure');
 const CookbookTestRunner = require('./CookbookTestRunner');
 
 /**
  * ValidationOrchestrator
  *
  * Orchestrates complete service validation (Tier 1 Pre-Validation)
- * Runs 6-step validation process and generates validation proof.
+ * Runs a 6-step validation process and generates validation proof.
  *
  * Called automatically by ServiceWrapper during initialization.
+ *
+ * The steps are not the same six it ran before 2026-08-22. The readiness step
+ * is gone — its removal, and why nothing was lost with it, is explained above
+ * runFullValidation() — and the environment contract (step 3, F16) took a
+ * different place: a service now fails on a variable it declared it needs
+ * before any handler runs, instead of several layers later inside the wrapper.
+ *
+ * `options.serviceUrl` is accepted-and-ignored: existing callers
+ * (ServiceWrapper, the biz `scripts/run-pre-validation.js`) still pass one.
+ * It is not stored and not required. It fed the readiness step's
+ * `fetch(url + '/health')`, retired in 3.3.1 under ADR 0005; after that it was
+ * a *required* constructor option no line of code read, so a service whose
+ * SERVICE_URL was unset failed to boot on account of a value nobody wanted.
  */
 class ValidationOrchestrator {
   constructor(options = {}) {
     this.serviceRoot = options.serviceRoot;
     this.serviceName = options.serviceName;
     this.serviceVersion = options.serviceVersion;
-    this.serviceUrl = options.serviceUrl; // NEW: Service URL for HTTP calls
     if (!options.logger || typeof options.logger.warn !== 'function') {
       throw new Error('[ValidationOrchestrator] Logger is required — Expected object with warn() method');
     }
     this.logger = options.logger;
 
-    if (!this.serviceUrl) {
-      throw new Error('[ValidationOrchestrator] serviceUrl is required');
-    }
-
     // Paths — prefer new config/service/ layout, fall back to legacy conn-config/
     const newConfigDir = path.join(this.serviceRoot, 'config', 'service');
     const legacyConfigDir = path.join(this.serviceRoot, 'conn-config');
@@ -41,7 +51,6 @@ class ValidationOrchestrator {
 
     // Validators
     this.structureValidator = new ServiceStructureValidator(this.serviceRoot);
-    this.readinessValidator = new ServiceReadinessValidator({ logger: this.logger });
     this.cookbookRunner = new CookbookTestRunner({
       servicePath: this.serviceRoot,
       serviceName: this.serviceName,
@@ -58,78 +67,25 @@ class ValidationOrchestrator {
     console.log('[ValidationOrchestrator] Starting validation...');
 
     // Check if proof exists and is valid
-    const existingProof = await this.loadExistingProof();
-    if (existingProof && await this.isProofValid(existingProof)) {
-      console.log('[ValidationOrchestrator] ✓ Valid proof found, skipping validation');
-      return {
-        success: true,
-        proofExists: true,
-        proof: existingProof,
-        skipped: true
-      };
-    }
-
+    // No proof cache. It skipped steps 1-3 and 5-6 — measured at 6 ms in total
+    // against 1 ms to compute the fingerprint that decided it, so it bought five
+    // milliseconds. It cost a window of up to seven days in which validation
+    // asserted something no longer true, which is how biz-converter's
+    // fresh-database failure stayed hidden for days.
+    //
+    // And it never worked: FingerprintUtils.generate() serialised with a
+    // replacer array, so the fingerprint only ever covered serviceVersion and
+    // never invalidated on a change to operations.json, config.json or the
+    // Dockerfile either. Removing it gives up no capability.
+    //
+    // Its original justification — an HTTP probe with retries in step 5 — was
+    // removed in 3.3.1 under ADR 0005. Audit: docs/archive/validation-proof-audit-2026-08.md
     // Run full validation
     console.log('[ValidationOrchestrator] No valid proof, running validation...');
     return await this.runFullValidation();
   }
 
-  /**
-   * Load existing validation proof from conn-runtime/
-   */
-  async loadExistingProof() {
-    try {
-      if (!fs.existsSync(this.proofPath)) {
-        return null;
-      }
-
-      const content = fs.readFileSync(this.proofPath, 'utf8');
-      const proof = JSON.parse(content);
-
-      return proof;
-    } catch (error) {
-      console.warn(`[ValidationOrchestrator] Failed to load proof: ${error.message}`);
-      return null;
-    }
-  }
-
-  /**
-   * Check if proof is still valid
-   * Valid = correct signature + fingerprint + not expired
-   */
-  async isProofValid(proof) {
-    try {
-      if (!proof) {
-        return false;
-      }
-
-      // Verify proof integrity + age using the shared core verifier defaults.
-      // This MUST match what Tier-2 validator enforces to avoid PROOF_EXPIRED drift.
-      const verifier = new ValidationProofVerifier();
-      const verificationResult = verifier.verifyProof(proof);
-
-      if (!verificationResult.valid) {
-        console.log(`[ValidationOrchestrator] Proof validation failed: ${verificationResult.reason}`);
-        return false;
-      }
-
-      // Calculate current fingerprint
-      const currentFingerprint = await this.calculateFingerprint();
 
-      // Check if fingerprint matches (stored in validationData.contractFingerprint)
-      if (proof.validationData?.contractFingerprint !== currentFingerprint) {
-        console.log('[ValidationOrchestrator] Fingerprint mismatch (service changed)');
-        return false;
-      }
-
-      return true;
-    } catch (error) {
-      if (this.logger && typeof this.logger.error === 'function') {
-        this.logger.error(`[ValidationOrchestrator] Proof validation error: ${error.message}`);
-      }
-      return false;
-    }
-  }
 
   /**
    * Calculate service fingerprint
@@ -164,6 +120,34 @@ class ValidationOrchestrator {
         infra.envTemplate = fs.readFileSync(envTemplateFile, 'utf8');
       }
 
+      // Cookbooks and seeds are validation INPUTS. Leaving them out let a proof
+      // outlive the very thing it attests to: editing a cookbook, or breaking
+      // the fixtures one depends on, kept a cached proof valid for up to seven
+      // days while the service booted green. That masked biz-converter's
+      // fresh-database boot failure for days. Step 4 now also runs every boot
+      // regardless (see validate()); this covers the cached structural steps.
+      // A missing directory means the service has none of these, which is
+      // legitimate. Any other read failure is not, and must reach the caller
+      // rather than silently reducing what the fingerprint covers.
+      const hashDirectory = (dir, extension) => {
+        let names;
+        try {
+          names = fs.readdirSync(dir);
+        } catch (err) {
+          if (err.code === 'ENOENT') return undefined;
+          throw err;
+        }
+        const files = names.filter((name) => name.endsWith(extension)).sort();
+        if (files.length === 0) return undefined;
+        return files.map((name) => `${name}:${fs.readFileSync(path.join(dir, name), 'utf8')}`).join('\n');
+      };
+
+      const cookbooks = hashDirectory(path.join(this.serviceRoot, 'tests', 'cookbooks'), '.json');
+      if (cookbooks !== undefined) infra.cookbooks = cookbooks;
+
+      const seeds = hashDirectory(path.join(this.serviceRoot, 'scripts', 'seed'), '.sql');
+      if (seeds !== undefined) infra.seeds = seeds;
+
       // Extract @onlineapps/* dependencies
       const deps = {};
       if (pkg.dependencies) {
@@ -190,7 +174,40 @@ class ValidationOrchestrator {
   }
 
   /**
-   * Run full 6-step validation process
+   * Run the full 6-step validation process.
+   *
+   * There were six steps until 2026-08-22. Step 5, "Service Readiness",
+   * delegated to `ServiceReadinessValidator.validateReadiness({name, url,
+   * operations})` and reported a sixth-of-the-run verdict it never
+   * independently reached:
+   *
+   *   - Its per-operation rules were the same set as step 3's, rule for rule
+   *     (handler presence and shape, bundle_scope, input, output, the retired
+   *     v2 fields) — the two loops were textual copies of one another.
+   *   - Its only two extra guards, "operations must be an object" and "no
+   *     operations defined", are step 2's `operations.json has no operations
+   *     defined`.
+   *   - Run against a valid baseline plus 13 mutations covering every rule,
+   *     its verdict equalled `step2 && step3` in all 14 cases. Against the
+   *     eight live biz services it emitted one check, scored 80 out of a
+   *     maxScore of 100 that this call path could never reach (the 15-point
+   *     cookbook and 5-point registry checks need arguments the orchestrator
+   *     never passed), and compared that 80 against a `score >= 60` threshold
+   *     the single remaining weight had made decorative. It measured 0 ms.
+   *
+   * So it could not fail a service that steps 2 and 3 passed. A step that
+   * announces PASS without evaluating anything of its own is the defect the
+   * connector step was fixed for in F12 (`dcddb862`); this is the same defect
+   * one step earlier, and the honest repair is removal, not a smaller lie.
+   *
+   * Its one non-duplicate signal — a warning for an operation with no
+   * `description` — never reached anyone: the step returned `{valid, errors}`
+   * and dropped `warnings` on the floor. That signal now lives in step 3 and
+   * is surfaced in `results.warnings`, so removal costs nothing.
+   *
+   * `ServiceReadinessValidator` itself stays: its cookbook and registry checks
+   * are used by `helpers/createServiceReadinessTests`, and through it by the
+   * `tests/bootstrap/` suites of the biz repos.
    */
   async runFullValidation() {
     const startTime = Date.now();
@@ -223,16 +240,34 @@ class ValidationOrchestrator {
         results.errors.push(...results.steps.config.errors);
       }
 
-      // Step 3: Operations Compliance
-      console.log('[ValidationOrchestrator] Step 3/6: Operations Compliance');
+      // Step 3: Environment Contract
+      //
+      // Before the cookbook tests run a single handler and long before the
+      // wrapper opens a connector: a variable the service declared it cannot
+      // start without must fail here, where its name and the reason it exists
+      // are both at hand. SECRETS_MASTER_KEY used to fail after MQ
+      // registration, several layers away from the declaration (defect D2).
+      console.log('[ValidationOrchestrator] Step 3/6: Environment Contract');
+      results.steps.env = this.validateEnvContract();
+      if (!results.steps.env.valid) {
+        results.success = false;
+        results.errors.push(...results.steps.env.errors);
+        // Fail fast — running handlers without the environment they declared
+        // produces a second, less honest error somewhere further in.
+        return this.finalizeResults(results, startTime);
+      }
+
+      // Step 4: Operations Compliance
+      console.log('[ValidationOrchestrator] Step 4/6: Operations Compliance');
       results.steps.operations = await this.validateOperations();
+      results.warnings.push(...(results.steps.operations.warnings || []));
       if (!results.steps.operations.valid) {
         results.success = false;
         results.errors.push(...results.steps.operations.errors);
       }
 
-      // Step 4: Cookbook Tests
-      console.log('[ValidationOrchestrator] Step 4/6: Cookbook Tests');
+      // Step 5: Cookbook Tests
+      console.log('[ValidationOrchestrator] Step 5/6: Cookbook Tests');
       results.steps.cookbooks = await this.runCookbookTests();
       results.totalTests += results.steps.cookbooks.total || 0;
       results.passedTests += results.steps.cookbooks.passed || 0;
@@ -242,20 +277,21 @@ class ValidationOrchestrator {
         results.errors.push(...(results.steps.cookbooks.errors || []));
       }
 
-      // Step 5: Service Readiness
-      console.log('[ValidationOrchestrator] Step 5/6: Service Readiness');
-      results.steps.readiness = await this.validateReadiness();
-      if (!results.steps.readiness.valid) {
-        results.success = false;
-        results.errors.push(...results.steps.readiness.errors);
-      }
-
       // Step 6: Connector Integration
       console.log('[ValidationOrchestrator] Step 6/6: Connector Integration');
       results.steps.connectors = this.validateConnectors();
       if (!results.steps.connectors.valid) {
-        // Non-critical - just warnings
-        results.warnings.push(...results.steps.connectors.warnings);
+        // Severity is unchanged: the connector contract stays non-critical and
+        // its findings are reported as warnings, not as validation errors.
+        //
+        // The field they are read from is what changed. F12 (`dcddb862`) gave
+        // this step a real check returning {valid, errors}; this line still
+        // spread `.warnings`, which that shape does not have. So the only case
+        // the step exists to catch — a service that actually fails the contract
+        // — threw "results.steps.connectors.warnings is not iterable", aborted
+        // the whole run, and reported that TypeError in place of every finding.
+        // Reproduced against biz-pdfgen and biz-property on 2026-08-22.
+        results.warnings.push(...results.steps.connectors.errors);
       }
 
       // Finalize and generate proof if successful
@@ -331,18 +367,26 @@ class ValidationOrchestrator {
    * Step 3: Validate operations compliance (v3 — handler registry dispatch).
    * Required per operation: handler ('handlers/<path>#<export>'), bundle_scope, input, output.
    * Forbidden (v2): endpoint, method, path.
+   * Warned about: a missing `description` — inherited from the removed
+   * readiness step, which was the only place that noticed it and then threw
+   * the notice away.
    */
   async validateOperations() {
     try {
       const operationsFile = path.join(this.configPath, 'operations.json');
       const operations = JSON.parse(fs.readFileSync(operationsFile, 'utf8'));
       const errors = [];
+      const warnings = [];
 
       const validScopes = ['platform', 'tenant', 'workspace'];
       const handlerPattern = /^handlers\/[a-zA-Z0-9_\/-]+#[a-zA-Z_][a-zA-Z0-9_]*$/;
       const forbiddenV2Fields = ['endpoint', 'method', 'path'];
 
       for (const [opName, opDef] of Object.entries(operations.operations || {})) {
+        if (!opDef.description) {
+          warnings.push(`Operation ${opName}: missing description`);
+        }
+
         if (!opDef.handler) {
           errors.push(`Operation ${opName}: missing handler (v3 — 'handlers/<path>#<export>')`);
         } else if (!handlerPattern.test(opDef.handler)) {
@@ -369,15 +413,18 @@ class ValidationOrchestrator {
         }
       }
 
-      console.log(`[ValidationOrchestrator] ✓ Operations compliance: ${errors.length === 0 ? 'PASS' : 'FAIL'}`);
+      console.log(`[ValidationOrchestrator] ✓ Operations compliance: ${errors.length === 0 ? 'PASS' : 'FAIL'}`
+        + `${warnings.length > 0 ? ` (${warnings.length} warning(s))` : ''}`);
       return {
         valid: errors.length === 0,
-        errors: errors
+        errors: errors,
+        warnings: warnings
       };
     } catch (error) {
       return {
         valid: false,
-        errors: [`Operations validation failed: ${error.message}`]
+        errors: [`Operations validation failed: ${error.message}`],
+        warnings: []
       };
     }
   }
@@ -406,12 +453,24 @@ class ValidationOrchestrator {
       const result = await this.cookbookRunner.runCookbooks(cookbooksPath);
 
       console.log(`[ValidationOrchestrator] ✓ Cookbook tests: ${result.passed}/${result.total} passed`);
+
+      // `N cookbook test(s) failed` was the whole error list until 2026-08-29:
+      // the count without a single name, so `Validation failed: 1 cookbook
+      // test(s) failed` was all the wrapper, the registry and the reader ever
+      // got. Every failing step now names itself and its reason
+      // (utils/stepFailure.js) — automation-gates.md §5.
+      const failedSteps = (result.steps || []).filter((step) => step.passed === false);
+      const details = failedSteps.map(describeStepFailureWithContext);
+      for (const detail of details) {
+        console.error(`[ValidationOrchestrator]   ✗ ${detail}`);
+      }
+
       return {
         success: result.failed === 0,
         total: result.total,
         passed: result.passed,
         failed: result.failed,
-        errors: result.failed > 0 ? [`${result.failed} cookbook test(s) failed`] : []
+        errors: result.failed > 0 ? [`${result.failed} cookbook test(s) failed`, ...details] : []
       };
     } catch (error) {
       return {
@@ -425,52 +484,86 @@ class ValidationOrchestrator {
   }
 
   /**
-   * Step 5: Validate service readiness
+   * Step 3: Verify the environment contract — PRESENCE.
+   *
+   * The service declares the variables it needs in the same file where it
+   * declares its connectors and its database; this step checks that every name
+   * declared `required` is actually set. CI checks the other direction —
+   * COMPLETENESS, that nothing the repo reads is undeclared — because that one
+   * needs the repository, not the running environment.
+   * Rules and rationale: utils/envContract.js.
+   *
+   * A contract with no `env` block is skipped OUT LOUD. That state is
+   * legitimate until every repo adopts the declaration, but a step that says
+   * nothing about what it did not check reads as a guarantee it never gave
+   * (automation-gates.md §5).
+   *
+   * @returns {{valid: boolean, skipped?: boolean, errors: string[]}}
    */
-  async validateReadiness() {
-    try {
-      // Load operations.json
-      const operationsFile = path.join(this.configPath, 'operations.json');
-      const operations = JSON.parse(fs.readFileSync(operationsFile, 'utf8'));
+  validateEnvContract() {
+    const contractFile = path.join(this.serviceRoot, 'config', 'service', 'integration-contract.json');
 
-      const result = await this.readinessValidator.validateReadiness({
-        name: this.serviceName,
-        url: this.serviceUrl,
-        operations: operations.operations
+    let declaration;
+    try {
+      const rawContract = JSON.parse(fs.readFileSync(contractFile, 'utf8'));
+      declaration = normalizeEnvDeclaration(rawContract.env, {
+        coverage: collectEnvCoverage({
+          serviceRoot: this.serviceRoot,
+          requiredConnectors: rawContract.requiredConnectors
+        })
       });
-
-      console.log(`[ValidationOrchestrator] ✓ Service readiness: ${result.ready ? 'PASS' : 'FAIL'}`);
-      return {
-        valid: result.ready,
-        errors: result.ready ? [] : result.errors || ['Service not ready']
-      };
     } catch (error) {
-      return {
-        valid: false,
-        errors: [`Readiness validation failed: ${error.message}`]
-      };
+      // A missing or unreadable contract file is already reported by the
+      // connector step; what is new here is a declaration that exists and is
+      // wrong, and that must stop the boot rather than be worked around.
+      if (error.code === 'ENOENT') {
+        console.log('[ValidationOrchestrator] ⊘ Environment contract: SKIPPED — '
+          + `no ${path.relative(this.serviceRoot, contractFile)} in this service`);
+        return { valid: true, skipped: true, errors: [] };
+      }
+      return { valid: false, errors: [error.message] };
     }
+
+    if (declaration === null) {
+      console.log('[ValidationOrchestrator] ⊘ Environment contract: SKIPPED — '
+        + 'config/service/integration-contract.json declares no "env" block '
+        + '(F16 adoption pending; nothing is being checked here)');
+      return { valid: true, skipped: true, errors: [] };
+    }
+
+    const result = verifyEnvPresence({ declaration, env: process.env });
+    console.log(`[ValidationOrchestrator] ${result.valid ? '✓' : '✗'} Environment contract: `
+      + `${result.valid ? 'PASS' : 'FAIL'} (${result.checked.length} required name(s) checked: `
+      + `${result.checked.join(', ') || 'none'})`);
+    return { valid: result.valid, errors: result.errors };
   }
 
   /**
    * Step 6: Validate connector integration
    */
+  /**
+   * Verify the connector contract. Tier-1 runs in phase 0.2, before the wrapper
+   * opens anything, so nothing live can be probed — what is checked is that the
+   * service's two declarations agree and that the environment backs them.
+   * Rules and rationale: utils/connectorContract.js.
+   */
   validateConnectors() {
-    try {
-      // This is validated implicitly through cookbook tests
-      // which test ServiceWrapper + all connectors
+    const configFile = path.join(this.configPath, 'config.json');
+    const contractFile = path.join(this.serviceRoot, 'config', 'service', 'integration-contract.json');
 
-      console.log('[ValidationOrchestrator] ✓ Connector integration: PASS (via cookbook tests)');
-      return {
-        valid: true,
-        warnings: []
-      };
+    let config = {};
+    let requiredConnectors = {};
+    try {
+      config = JSON.parse(fs.readFileSync(configFile, 'utf8'));
+      requiredConnectors = JSON.parse(fs.readFileSync(contractFile, 'utf8')).requiredConnectors || {};
     } catch (error) {
-      return {
-        valid: false,
-        warnings: [`Connector validation warning: ${error.message}`]
-      };
+      return { valid: false, errors: [`[ConnectorContract] Cannot read the connector declarations - ${error.message}`] };
     }
+
+    const result = verifyConnectorContract({ config, requiredConnectors, env: process.env });
+    console.log(`[ValidationOrchestrator] ${result.valid ? '✓' : '✗'} Connector contract: `
+      + `${result.valid ? 'PASS' : 'FAIL'} (${result.checked.length} checked: ${result.checked.join(', ') || 'none'})`);
+    return { valid: result.valid, errors: result.errors };
   }
 
   /**
@@ -515,7 +608,11 @@ class ValidationOrchestrator {
       }
     } else {
       console.error(`[ValidationOrchestrator] ❌ Validation FAILED (${duration}ms)`);
-      console.error(`[ValidationOrchestrator] Errors: ${JSON.stringify(results.errors, null, 2)}(', ')}`);
+      // The trailing `(', ')}` was a leftover from a half-finished edit to a
+      // template literal: it printed on every failed validation as if it were
+      // part of the data. Found while reading this line for the biz-hello
+      // diagnosis (2026-08-29).
+      console.error(`[ValidationOrchestrator] Errors: ${JSON.stringify(results.errors, null, 2)}`);
     }
 
     return results;