@onlineapps/conn-orch-validator 9.0.0 → 11.0.0

package/src/ValidationOrchestrator.js

@@ -8,10 +8,13 @@ const { normalizeEnvDeclaration, collectEnvCoverage, verifyEnvPresence } = requi
 // called. It verified a cached proof before booting; the proof cache was
 // removed (see validate()) and the verifier's last call site went with it,
 // leaving a binding whose only remaining effect was to tell a reader that this
-// class still checks proofs. `ValidationProofCodec` stays — finalizeResults()
-// encodes the proof it writes.
-const { ValidationProofCodec } = require('@onlineapps/service-validator-core');
+// class still checks proofs. `ValidationProofCodec` went the same way in d.524:
+// finalizeResults() no longer encodes a proof of its own — it asks
+// `ValidationProofGenerator`, which is the one author of one, and the codec is
+// that generator's business.
 const FingerprintUtils = require('@onlineapps/service-validator-core').FingerprintUtils;
+const ValidationProofGenerator = require('./validators/ValidationProofGenerator');
+const { VALIDATOR_VERSION } = require('./validatorIdentity');
 const { ServiceStructureValidator } = require('./validators/ServiceStructureValidator');
 const { describeStepFailureWithContext } = require('./utils/stepFailure');
 const CookbookTestRunner = require('./CookbookTestRunner');
@@ -22,6 +25,7 @@ const { runManifest } = require('./manifest/runManifest');
 const { resolveWorkspaceRoot } = require('./manifest/workspaceRoot');
 const { renderBanner, describeFinding } = require('./manifest/report');
 const { buildDeployabilitySignal, writeDeployabilitySignal } = require('./manifest/deployabilitySignal');
+const { isGitCheckout, NOT_A_CHECKOUT } = require('./manifest/gitCheckout');
 
 /**
  * The manifest rows step 2 answers: the configuration documents a biz service is
@@ -38,6 +42,94 @@ const { buildDeployabilitySignal, writeDeployabilitySignal } = require('./manife
  */
 const CONFIG_STEP_ROWS = Object.freeze(['C-SERVICE', 'C-OPS', 'C-CONTRACT']);
 
+/**
+ * One number a step MEASURED — or a refusal.
+ *
+ * The run's `totalTests`/`passedTests`/`failedTests` used to be summed with
+ * `|| 0`, so a step that measured nothing contributed a zero and the aggregate
+ * could not tell "no tests ran" from "the step did not say". The proof's author
+ * refuses an unmeasured field (`ValidationProofGenerator.readMeasurement`,
+ * d.524), but it never saw one: the fallback had already turned it into a
+ * number. That is `.claude/rules/architecture-principles.md` §3 (No Fallbacks)
+ * standing exactly where §4 wants a refusal, and the far end paid for it —
+ * `ValidationProofCodec.decode()` rejects the resulting proof as NO_TESTS, days
+ * later and nowhere near the cause.
+ *
+ * A measured 0 is untouched: zero failures is the ordinary case. What is
+ * refused is the ABSENCE of a measurement.
+ *
+ * @param {Object} step the step result the aggregate is summing
+ * @param {string} field `total`, `passed` or `failed`
+ * @param {string} stepName the step's name, for the refusal
+ * @returns {number} the measured value
+ */
+function readStepMeasurement(step, field, stepName) {
+  const value = step === null || step === undefined ? undefined : step[field];
+
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    throw new Error(`[ValidationOrchestrator] Missing measurement - step "${stepName}" reported `
+      + `${JSON.stringify(value) === undefined ? 'undefined' : JSON.stringify(value)} for "${field}", `
+      + 'and the run counts measured values only - a zero standing in for an absent measurement is '
+      + 'what makes a proof of nothing look like a passing validation. '
+      + `Fix: return a finite number as "${field}" from step "${stepName}".`);
+  }
+
+  return value;
+}
+
+/**
+ * The step that produced a finding, carried ON the finding.
+ *
+ * `results.errors` is one flat array: step 1 pushes objects
+ * `{ type, path, message, fix }` and steps 2-7 push sentences they have already
+ * written in the `[Context] Problem - Expected/Fix` shape. Nothing in it said
+ * WHICH step a finding came from, so the only reader that needs to know — the
+ * wrapper, which retries a transient step and refuses a static one — had to read
+ * `results.steps` instead and could say nothing about an individual finding.
+ *
+ * The marker is ADDED, never substituted: a sentence stays the same sentence and
+ * an object keeps every field it had, because `describeValidationFinding()` of
+ * `@onlineapps/service-wrapper` 9.0.x renders a string verbatim and an object
+ * only when it carries `type` and `message` — anything else reaches the operator
+ * as raw JSON. Rewriting the sentences into `{ step, message }` objects would
+ * therefore break the released wrapper, so the sentences keep their shape until
+ * a wrapper that reads `step` is published (d.602; the report to BIZ-general).
+ *
+ * The findings are COPIED rather than stamped in place: the step's own
+ * `results.steps.<step>.errors` is its answer and stays untouched.
+ *
+ * @param {Array<(string|object)>} findings what a step reported
+ * @param {string} step the step's key in `results.steps`
+ * @returns {Array<(string|object)>} the same findings, objects carrying `step`
+ */
+function attributeToStep(findings, step) {
+  if (!Array.isArray(findings)) {
+    // The TypeError this replaces reported itself instead of the finding: step 6
+    // spread a field the step does not have and aborted the whole run with
+    // "results.steps.connectors.warnings is not iterable" (F12, 2026-08-22).
+    throw new Error(`[ValidationOrchestrator] Step "${step}" reported findings that are not an array - `
+      + `got ${JSON.stringify(findings)}, expected an array. `
+      + `Fix: return "errors" as an array from step "${step}".`);
+  }
+
+  return findings.map((finding) => (
+    finding !== null && typeof finding === 'object' ? { ...finding, step } : finding
+  ));
+}
+
+/**
+ * The finding of a step whose body THREW — an object, so that it carries `step`,
+ * and with `type` so the released wrapper renders it as a sentence rather than
+ * as JSON.
+ *
+ * @param {string} step the step's key in `results.steps`
+ * @param {string} message the failure, in the `[Context] Problem - Fix` shape
+ * @returns {{type: string, step: string, message: string}}
+ */
+function stepThrewFinding(step, message) {
+  return { type: 'STEP_THREW', step, message };
+}
+
 /**
  * ValidationOrchestrator
  *
@@ -345,22 +437,27 @@ class ValidationOrchestrator {
 
     try {
       // Step 1: Service Structure
-      this.logger.info('[ValidationOrchestrator] Step 1/7: Service Structure');
-      results.steps.structure = await this.validateStructure();
-      if (!results.steps.structure.valid) {
+      const structureFailed = await this.runStep(results, 'structure', async () => {
+        this.logger.info('[ValidationOrchestrator] Step 1/7: Service Structure');
+        results.steps.structure = await this.validateStructure();
+        if (results.steps.structure.valid) return false;
+
         results.success = false;
-        results.errors.push(...results.steps.structure.errors);
-        // Fail fast - can't continue without proper structure
-        return this.finalizeResults(results, startTime);
-      }
+        results.errors.push(...attributeToStep(results.steps.structure.errors, 'structure'));
+        return true;
+      });
+      // Fail fast - can't continue without proper structure
+      if (structureFailed) return this.finalizeResults(results, startTime);
 
       // Step 2: Config Files
-      this.logger.info('[ValidationOrchestrator] Step 2/7: Config Files');
-      results.steps.config = await this.validateConfig();
-      if (!results.steps.config.valid) {
+      await this.runStep(results, 'config', async () => {
+        this.logger.info('[ValidationOrchestrator] Step 2/7: Config Files');
+        results.steps.config = await this.validateConfig();
+        if (results.steps.config.valid) return;
+
         results.success = false;
-        results.errors.push(...results.steps.config.errors);
-      }
+        results.errors.push(...attributeToStep(results.steps.config.errors, 'config'));
+      });
 
       // Step 3: Environment Contract
       //
@@ -369,40 +466,53 @@ class ValidationOrchestrator {
       // 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).
-      this.logger.info('[ValidationOrchestrator] Step 3/7: Environment Contract');
-      results.steps.env = this.validateEnvContract();
-      if (!results.steps.env.valid) {
+      const envFailed = await this.runStep(results, 'env', () => {
+        this.logger.info('[ValidationOrchestrator] Step 3/7: Environment Contract');
+        results.steps.env = this.validateEnvContract();
+        if (results.steps.env.valid) return false;
+
         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);
-      }
+        results.errors.push(...attributeToStep(results.steps.env.errors, 'env'));
+        return true;
+      });
+      // Fail fast — running handlers without the environment they declared
+      // produces a second, less honest error somewhere further in.
+      if (envFailed) return this.finalizeResults(results, startTime);
 
       // Step 4: Operations Compliance
-      this.logger.info('[ValidationOrchestrator] Step 4/7: Operations Compliance');
-      results.steps.operations = await this.validateOperations();
-      results.warnings.push(...(results.steps.operations.warnings || []));
-      if (!results.steps.operations.valid) {
+      await this.runStep(results, 'operations', async () => {
+        this.logger.info('[ValidationOrchestrator] Step 4/7: Operations Compliance');
+        results.steps.operations = await this.validateOperations();
+        results.warnings.push(...attributeToStep(results.steps.operations.warnings || [], 'operations'));
+        if (results.steps.operations.valid) return;
+
         results.success = false;
-        results.errors.push(...results.steps.operations.errors);
-      }
+        results.errors.push(...attributeToStep(results.steps.operations.errors, 'operations'));
+      });
 
       // Step 5: Cookbook Tests
-      this.logger.info('[ValidationOrchestrator] Step 5/7: Cookbook Tests');
-      results.steps.cookbooks = await this.runCookbookTests();
-      results.totalTests += results.steps.cookbooks.total || 0;
-      results.passedTests += results.steps.cookbooks.passed || 0;
-      results.failedTests += results.steps.cookbooks.failed || 0;
-      if (!results.steps.cookbooks.success) {
+      await this.runStep(results, 'cookbooks', async () => {
+        this.logger.info('[ValidationOrchestrator] Step 5/7: Cookbook Tests');
+        results.steps.cookbooks = await this.runCookbookTests();
+        // Measured values only — see readStepMeasurement() for why `|| 0` here
+        // was the reason the generator's refusal never fired. The refusal now
+        // fails THIS step by name instead of surfacing as a step-less
+        // "Validation error" (d.602).
+        results.totalTests += readStepMeasurement(results.steps.cookbooks, 'total', 'cookbooks');
+        results.passedTests += readStepMeasurement(results.steps.cookbooks, 'passed', 'cookbooks');
+        results.failedTests += readStepMeasurement(results.steps.cookbooks, 'failed', 'cookbooks');
+        if (results.steps.cookbooks.success) return;
+
         results.success = false;
-        results.errors.push(...(results.steps.cookbooks.errors || []));
-      }
+        results.errors.push(...attributeToStep(results.steps.cookbooks.errors || [], 'cookbooks'));
+      });
 
       // Step 6: Connector Integration
-      this.logger.info('[ValidationOrchestrator] Step 6/7: Connector Integration');
-      results.steps.connectors = this.validateConnectors();
-      if (!results.steps.connectors.valid) {
+      await this.runStep(results, 'connectors', () => {
+        this.logger.info('[ValidationOrchestrator] Step 6/7: Connector Integration');
+        results.steps.connectors = this.validateConnectors();
+        if (results.steps.connectors.valid) return;
+
         // Severity is unchanged: the connector contract stays non-critical and
         // its findings are reported as warnings, not as validation errors.
         //
@@ -413,8 +523,8 @@ class ValidationOrchestrator {
         // — 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);
-      }
+        results.warnings.push(...attributeToStep(results.steps.connectors.errors, 'connectors'));
+      });
 
       // Step 7: Manifest conformance
       //
@@ -427,15 +537,17 @@ class ValidationOrchestrator {
       // the service running and marks it undeployable — the banner says so at
       // the end of this log and `ci/deployability.json` says so to
       // `deploy-production`.
-      this.logger.info('[ValidationOrchestrator] Step 7/7: Manifest conformance');
-      results.steps.manifest = this.validateManifestConformance();
-      results.deployable = results.steps.manifest.deployable;
-      results.deployFindings = results.steps.manifest.deployFindings;
-      results.notRun = results.steps.manifest.notRun;
-      if (!results.steps.manifest.valid) {
+      await this.runStep(results, 'manifest', () => {
+        this.logger.info('[ValidationOrchestrator] Step 7/7: Manifest conformance');
+        results.steps.manifest = this.validateManifestConformance();
+        results.deployable = results.steps.manifest.deployable;
+        results.deployFindings = results.steps.manifest.deployFindings;
+        results.notRun = results.steps.manifest.notRun;
+        if (results.steps.manifest.valid) return;
+
         results.success = false;
-        results.errors.push(...results.steps.manifest.errors);
-      }
+        results.errors.push(...attributeToStep(results.steps.manifest.errors, 'manifest'));
+      });
 
       // Finalize and generate proof if successful
       return await this.finalizeResults(results, startTime);
@@ -443,11 +555,74 @@ class ValidationOrchestrator {
     } catch (error) {
       this.logger.error(`[ValidationOrchestrator] Validation failed: ${error.message}`);
       results.success = false;
-      results.errors.push(`Validation error: ${error.message}`);
+      // A failure that belongs to NO step — `finalizeResults` is the only code
+      // left out here. Everything raised inside a step is already recorded under
+      // that step's name by runStep(), which marks the error on its way out, so
+      // adding this sentence as well would report one failure twice and the
+      // second copy would carry no step at all (d.602).
+      if (typeof error.validationStep !== 'string') {
+        results.errors.push(`Validation error: ${error.message}`);
+      }
       return this.finalizeResults(results, startTime);
     }
   }
 
+  /**
+   * Run one step of the validation and GUARANTEE its record in `results.steps`.
+   *
+   * Each step method catches what its own work raises and answers
+   * `{ valid: false, … }` by its own name. This is the net under all of them: an
+   * exception from the logger, from the aggregate that reads a step's
+   * measurements, or from a step's findings being something other than an array
+   * used to escape to the catch of runFullValidation(), which pushed
+   * `Validation error: <message>` and left `results.steps.<step>` ABSENT.
+   *
+   * That absence is not a cosmetic gap. `@onlineapps/service-wrapper` 9.0.x
+   * decides whether a failed FÁZE 0.2 may be retried by reading
+   * `result.steps.<step>.valid` (its `STATIC_VALIDATION_STEPS`), and a step with
+   * no record reads as "the validator threw" — transient — so a structural
+   * defect bought the full six-attempt budget: 18,5 minutes of a boot that
+   * cannot succeed (measured on biz-converter, W591).
+   *
+   * The run still STOPS where it stopped before: the error is re-thrown, marked,
+   * and the outer catch finalizes exactly as it did.
+   *
+   * @param {object} results the run being assembled
+   * @param {string} step the step's key in `results.steps`
+   * @param {function(): *} block the step, its harvest included
+   * @returns {Promise<*>} whatever the block returned
+   */
+  async runStep(results, step, block) {
+    try {
+      return await block();
+    } catch (error) {
+      const finding = stepThrewFinding(step,
+        `[ValidationOrchestrator] Step "${step}" threw - ${error.message} `
+        + `Fix: repair what that message names; step "${step}" reached no verdict of its own.`);
+
+      // What the step had already measured is KEPT: a throw during the harvest
+      // must not erase the counts or findings the step did produce.
+      const measured = results.steps[step];
+      const partial = measured !== null && typeof measured === 'object' ? measured : {};
+
+      results.steps[step] = {
+        ...partial,
+        // Both fields, because this net does not know which one the step
+        // answers with: steps 1-4, 6 and 7 report `valid`, step 5 reports
+        // `success`, and a reader of either must see the failure.
+        valid: false,
+        success: false,
+        threw: true,
+        errors: [...(Array.isArray(partial.errors) ? partial.errors : []), finding]
+      };
+      results.success = false;
+      results.errors.push(finding);
+
+      error.validationStep = step;
+      throw error;
+    }
+  }
+
   /**
    * Step 1: Validate service structure
    */
@@ -460,7 +635,8 @@ class ValidationOrchestrator {
     } catch (error) {
       return {
         valid: false,
-        errors: [`Structure validation failed: ${error.message}`]
+        threw: true,
+        errors: [stepThrewFinding('structure', `Structure validation failed: ${error.message}`)]
       };
     }
   }
@@ -499,7 +675,8 @@ class ValidationOrchestrator {
       this.logger.error(`[ValidationOrchestrator] Step 2/7 could not run: ${error.message}`);
       return {
         valid: false,
-        errors: [error.message],
+        threw: true,
+        errors: [stepThrewFinding('config', error.message)],
         findings: []
       };
     }
@@ -582,7 +759,8 @@ class ValidationOrchestrator {
     } catch (error) {
       return {
         valid: false,
-        errors: [`Operations validation failed: ${error.message}`],
+        threw: true,
+        errors: [stepThrewFinding('operations', `Operations validation failed: ${error.message}`)],
         warnings: []
       };
     }
@@ -643,11 +821,12 @@ class ValidationOrchestrator {
     } catch (error) {
       return {
         success: false,
+        threw: true,
         total: 0,
         passed: 0,
         failed: 0,
         cookbooks: { total: 0, passed: 0, failed: 0 },
-        errors: [`Cookbook tests failed: ${error.message}`]
+        errors: [stepThrewFinding('cookbooks', `Cookbook tests failed: ${error.message}`)]
       };
     }
   }
@@ -690,7 +869,7 @@ class ValidationOrchestrator {
           + `no ${path.relative(this.serviceRoot, contractFile)} in this service`);
         return { valid: true, skipped: true, errors: [] };
       }
-      return { valid: false, errors: [error.message] };
+      return { valid: false, threw: true, errors: [stepThrewFinding('env', error.message)] };
     }
 
     if (declaration === null) {
@@ -726,7 +905,12 @@ class ValidationOrchestrator {
       config = JSON.parse(fs.readFileSync(configFile, 'utf8'));
       requiredConnectors = JSON.parse(fs.readFileSync(contractFile, 'utf8')).requiredConnectors || {};
     } catch (error) {
-      return { valid: false, errors: [`[ConnectorContract] Cannot read the connector declarations - ${error.message}`] };
+      return {
+        valid: false,
+        threw: true,
+        errors: [stepThrewFinding('connectors',
+          `[ConnectorContract] Cannot read the connector declarations - ${error.message}`)]
+      };
     }
 
     const result = verifyConnectorContract({ config, requiredConnectors, env: process.env });
@@ -748,18 +932,59 @@ class ValidationOrchestrator {
    * the signal carries them (`automation-gates.md` §5). There is no switch that
    * skips this step and none that moves the signal: one path, unbypassable.
    *
+   * OUTSIDE A GIT CHECKOUT THE STEP DOES NOT MEASURE. Owner decision 2026-09-17
+   * (confirmation `biz-service-manifest` 011): a production image is not a
+   * checkout and carries neither `docker-compose.yml` nor `README.md`, so the
+   * uniform measured there reports absences that say nothing about the
+   * repository — 12 findings for a healthy service. A verdict reached that way
+   * is not a strict check, it is a wrong answer, and `NOT DEPLOYABLE` printed
+   * from it discredits the rows that ARE true. What proves deployability is the
+   * CI job `validate-uniform`, from every commit, over the checkout
+   * (confirmation 010); a running container cannot prove it and no longer
+   * pretends to. The step then says NOT RUN in one line and `deployable` stays
+   * `null` — NOT MEASURED, which is a different statement from `false` and is
+   * why that field has three states.
+   *
    * Order inside the step is deliberate: the banner is printed BEFORE the file
    * is written, so a service root that cannot be written to still leaves the
    * human-readable verdict in the log.
    *
    * @see api/docs/governance/confirmations/biz-service-manifest.md §4
-   * @returns {{valid: boolean, deployable: boolean, errors: string[], findings: object[],
+   * @returns {{valid: boolean, deployable: (boolean|null), errors: string[], findings: object[],
    *            deployFindings: object[], notRun: object[], signalPath: string|null}}
    */
   validateManifestConformance() {
     try {
+      // The run happens first and costs nothing extra: step 2 has already asked
+      // for it (`manifestRun()` is computed once per validation), and a service
+      // root that vanished must still fail by its own name rather than be
+      // reported as "not a checkout".
       const result = this.manifestRun();
 
+      if (!isGitCheckout(this.serviceRoot)) {
+        // One line, and no table: naming the findings of a tree this run cannot
+        // read would be the false guarantee of `automation-gates.md` §5 in
+        // reverse — a reader acting on `README.md missing` inside a container
+        // would go looking for a file the image is not supposed to carry.
+        this.logger.info(`[ValidationOrchestrator] NOT RUN  manifest conformance — ${NOT_A_CHECKOUT} `
+          + 'Deployability is proven per commit by the CI job `validate-uniform` over the checkout '
+          + '(confirmation biz-service-manifest 010).');
+
+        // No signal either: `ci/deployability.json` IS a verdict, and this run
+        // reached none. Writing one would hand `deploy-production` a file that
+        // looks like an answer. The checkout path writes it
+        // (`src/cli/oa-validate.js`), which is where the answer exists.
+        return {
+          valid: true,
+          deployable: null,
+          errors: [],
+          findings: [],
+          deployFindings: [],
+          notRun: [],
+          signalPath: null
+        };
+      }
+
       // The banner and `ci/deployability.json` describe the WHOLE uniform,
       // CONFIG_STEP_ROWS included: the verdict is about the tree, and a reader
       // (or `deploy-production`) must not conclude it is clean because the boot
@@ -773,7 +998,7 @@ class ValidationOrchestrator {
         serviceRoot: this.serviceRoot,
         signal: buildDeployabilitySignal({
           result,
-          validatorVersion: require('../package.json').version
+          validatorVersion: VALIDATOR_VERSION
         })
       });
 
@@ -804,8 +1029,9 @@ class ValidationOrchestrator {
       this.logger.error(`[ValidationOrchestrator] Step 7/7 could not run: ${error.message}`);
       return {
         valid: false,
+        threw: true,
         deployable: false,
-        errors: [error.message],
+        errors: [stepThrewFinding('manifest', error.message)],
         findings: [],
         deployFindings: [],
         notRun: [],
@@ -825,21 +1051,34 @@ class ValidationOrchestrator {
       try {
         // Generate validation proof
         const fingerprint = await this.calculateFingerprint();
-        const proof = {
+
+        // Through the generator, which is the ONE author of a proof. Built here
+        // by hand and handed straight to the codec, this proof escaped both of
+        // the generator's refusals: an unmeasured field (`readMeasurement`) and
+        // a run that executed nothing
+        // (`.claude/rules/change-discipline.md` § One rail per concern).
+        //
+        // The numbers reaching it are measured ones: the aggregate above sums
+        // through `readStepMeasurement()`, so an absent measurement fails the
+        // run here rather than arriving as a zero the generator cannot tell
+        // from a real one (d.576b).
+        const generator = new ValidationProofGenerator({
           serviceName: this.serviceName,
-          version: this.serviceVersion,
-          contractFingerprint: fingerprint, // Store contract fingerprint for subsequent starts
-          validator: '@onlineapps/conn-orch-validator',
-          validatorVersion: require('../package.json').version,
-          validatedAt: new Date().toISOString(),
-          testsRun: results.totalTests,
-          testsPassed: results.passedTests,
-          testsFailed: results.failedTests,
-          durationMs: duration
-        };
+          serviceVersion: this.serviceVersion
+        });
 
-        // Encode proof using ValidationProofCodec
-        const encodedProof = ValidationProofCodec.encode(proof);
+        const pkg = this.readServicePackageJson(path.join(this.serviceRoot, 'package.json'));
+
+        const encodedProof = generator.generateProof(
+          {
+            total: results.totalTests,
+            passed: results.passedTests,
+            failed: results.failedTests,
+            duration
+          },
+          pkg.dependencies || {},
+          { contractFingerprint: fingerprint }
+        );
 
         // Save proof to conn-runtime/
         await this.saveProof(encodedProof);